Complex numbers

[scimind2460]

This RFC proposes FFI-compatible complex numbers to help scientific computing library authors use non-indirected complexes.

I apologise in advance to num-complex

Rendered

[joshtriplett]

Labeling this T-lang because the desire to make this FFI-compatible is a lang matter.

[clarfonthey]

It's worth pointing out another big issue with this is that the canonical a+bi is not actually the best representation of complex numbers in all cases, and so deciding on this is making a decision that might make life harder for external complex-numeric libraries out there.

In particular, while a+bi (orthogonal) representation is efficient for addition, r*(iθ).exp() is more efficient for multiplication, and depending on the equation you're using, it may be advantageous to switch between the two to reduce the number of arithmetic operations needed.

I'm not super compelled by the argument that C supports this, therefore the standard library needs to support this. I think that guaranteeing a std::ffi::Complex representation would be desirable, but there's no saying that we need to make this a canonical type in, say, std::num.

[tgross35]

It's worth pointing out another big issue with this is that the canonical a+bi is not actually the best representation of complex numbers in all cases, and so deciding on this is making a decision that might make life harder for external complex-numeric libraries out there.

In particular, while a+bi (orthogonal) representation is efficient for addition, r*(iθ).exp() is more efficient for multiplication, and depending on the equation you're using, it may be advantageous to switch between the two to reduce the number of arithmetic operations needed.

I think that polar form almost always is the more optimal form, at least in my experience. But the ABIs do use rectangular, e.g. from x86:

Arguments of complex T where T is one of the types float or double are treated as if they are implemented as:

struct complexT {
  T real;
  T imag;
};

so it makes sense that an interchange type matches that, and users can translate to/from a polar repr at the FFI boundary if needed. But this reasoning is definitely something to have in the RFC's rationale & alternatives.

[clarfonthey]

Right: I guess my main clarification here was that due to the polar-orthogonal discrepancy, it shouldn't be a canonical Rust type (e.g. std::num::Complex shouldn't be making a decision on which is more-canonical), but I do think that having extra FFI-compatibility types is reasonable and this shouldn't prevent us from adding std::ffi::Complex which is orthogonal.

[scimind2460]

Thanks everyone for the feedback! I have incorporated as much as I can into the RFC.
@clarfonthey I do think that the orthogonal representation is more "canonical", especially as it is the most commonly used one in crates.io and across languages. So I'm not sure if we can consider this an issue, especially as there are polar conversion methods in the RFC.

[scimind2460]

Hopefully I've cleared up everything to satisfaction. I suppose it's broadly reasonable to FCP?

[joshtriplett]

The current state of the RFC looks good, thank you!

This continues to be a lang/libs-api RFC, lang because of the FFI interoperability with C _Complex, and libs-api for everything else about the type.

@rfcbot merge libs-api,lang

[rust-rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @nikomatsakis
• @scottmcm
• @the8472
• @tmandry
• @traviscross

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[scimind2460]

Commenting on #793 as prior art (it wishes to achieve the same objective, but is largely dead)

[scottmcm]

Having something to match C99 _Complex seems entirely lang-reasonable to me. I'm happy to see this not proposing a new repr; if things outside core want something with that layout/ABI they can repr(transparent) the canonical one.

@rfcbot reviewed

(I didn't pay much attention to the API. I trust libs-api will handle that appropriately.)

[cuviper]

if things outside core want something with that layout/ABI they can repr(transparent) the canonical one.

I'm ok with this, but I do want to note that this is not seamless. For example, num_complex::Complex would not be able to keep its pub fields, only to pub expose that it's wrapping the core type that has pub fields itself.

(I probably won't bother with that at all -- just recommending the core type directly if you want C-ABI compatibility.)

[comex]

Will there be impls for fN: Mul<Complex<fN>>, fN: Add<Complex<fN>>, and the reverses of those? That would make it possible to write e.g. 1.0 + 2.0 * f32::i(). Seems like it should be either part of the RFC or a future possibility, or explicitly rejected.

[scimind2460]

Will there be impls for fN: Mul<Complex<fN>>, fN: Add<Complex<fN>>, and the reverses of those? That would make it possible to write e.g. 1.0 + 2.0 * f32::i(). Seems like it should be either part of the RFC or a future possibility, or explicitly rejected.

It was there in an earlier draft, but I decided to relegate it to a future possibility. However, you can see that a related possibility such as the fn i(self) was discussed.