FFI-compatible std complex numbers

[SciMind2460]

Proposal

Problem statement

Currently, there is no stable counterpart to the C _Complex types, and a myriad of implementations exist on crates.io. Popular crates like num-complex exist, but more often there are implementations defined by the crates themselves, which, while compatible with the other types in having the exact same implementation, require a myriad of conversion functions to convert with each other. Additionally, there is no syntax supported like 1+2i or 1+2j for complex numbers. (This ACP doesn't cover this, but it does lay ground for future work in this area)

Motivating examples or use cases

A scientific computing library's functions (can be written in C):

// in comp
extern double _Complex computes_function(x: double _Complex);

can be represented in Rust without the need of complex structs and the like:

extern "C" {
  fn computes_function(x: c64) -> c64;
}
fn main() {
  let returned_value = computes_function(c32::new(3, 4))
}

with the special repr that only the standard library can provide.
(This would, however, require that the complex numbers become lang items.)

Solution sketch

Complex numbers will have a implementation similar to this:

// c16, c32, c64, c128 to be defined this way using f16, f32, f64 and f128 respectively
#[lang = "complex"] // to match C
#[repr(transparent)]
#[derive(Copy, Clone, PartialEq, Default)]
pub struct Complex<T>(Simd<T, 2>) where T: SimdElement + Float>> // can use the num_traits float; 

type c16 = Complex<f16>;
type c32 = Complex<f32>;
type c64 = Complex<f64>;
type c128 = Complex<f128>;

// smorgasbord of impls
impl<T> Complex<T> {
    fn re(self) ->  {
        self.0.into()[0]
    }
    fn im(self) {
        self.0.into()[1]
    }

    fn csin(self) {}
    fn ccos(self) {}
    fn ctan(self) {}
}

impl<T> Add for Complex<T> {}
impl<T> Sub for Complex<T> {}
impl<T> Mul for Complex<T> {}
impl<T> Div for Complex<T> {}

The complex numbers will serve as structs with SIMD reprs.

Alternatives

Don't put it into the std (status quo)

We could just not put complex numbers in the std and let the popular libraries work. This would be acceptable if not for improving FFI with C, as it already implements the _Complex types and adding them to Rust would significantly improve the FFI experience with libraries already in C. I do not recommend this yet.

Links and related work

Standard complex number in std library
C compatible complex types using traits

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[pitaj]

Recommend fixing your code blocks to specify rust for proper highlighting.

You might want to discuss c32, c64, etc vs Complex<f32>, Complex<f64>, etc

[SciMind2460]

Recommend fixing your code blocks to specify rust for proper highlighting.

You might want to discuss c32, c64, etc vs Complex<f32>, Complex<f64>, etc

Thanks! Added it as per your suggestion.

[tgross35]

I think complex numbers are definitely a topic that needs an RFC rather than an ACP, given the lang involvement.

// All the trait impls as per LLVM intrinsics

Does LLVM actually provide intrinsics for this? From a quick look it doesn't look like langref says anything about complex numbers and that Clang just emits calls to e.g. __mulsc3.

[SciMind2460]

// All the trait impls as per LLVM intrinsics

Does LLVM actually provide intrinsics for this? From a quick look it doesn't look like langref says anything about complex numbers and that Clang just emits calls to e.g. __mulsc3.

That was a holdover from an earlier concept. I just removed it.

I think complex numbers are definitely a topic that needs an RFC rather than an ACP, given the lang involvement.

From my point of view, the only lang involvement that would be required would be the special FFI with C, but otherwise I think it would work without much libs involvement.

[tgross35]

This still seems reversed: lang needs to decide whether or not we want an FFI-compatible complex type. If not, there isn't (IMO) any reason for anything related to complex numbers to live in std since it's a high-complexity interface that can, for now, be done just as well in an external crate.

Even aside from that, there are so many potential moving parts with complex numbers (FFI interop, possible new syntax, intrinsics, math library support, ecosystem impact). I don't think we should focus on library API without looking at the bigger picture, which an RFC would provide.

(Also, the basic math ops would be compiler intrinsics that may lower to libgcc calls (rather than libm calls), which lang technically owns as well.)

[kennytm]

#[lang = "complex"] // defines a special C-compatible repr which matches the ABI
struct c32 {

a lang-item can only be applied to one definition. perhaps you want something like #[repr(c_complex)] instead.

[SciMind2460]

a lang-item can only be applied to one definition. perhaps you want something like #[repr(c_complex)] instead.

Hmm... is it possible to do a special repr for only the complexes and make it unusable outside of std?
Or could we do something like this:

#[lang = "c32"]
struct c32 {..}
#[lang = "c64"]
struct c64 {..}

[kennytm]

why you want to make it unusable outside std? it's not like #[repr(simd)] is banned outside the standard library either. and making the feature perma-unstable is pretty close to "internal-use-only".

anyway as mentioned in #707 (comment) this change is beyond the scope of ACP.

[programmerjake]

it's not like #[repr(simd)] is banned outside the standard library either. and making the feature perma-unstable is pretty close to "internal-use-only".

iirc the plan is std::simd::Simd is what everything else will use instead of repr(simd) and repr(simd) will become perma-unstable or removed and converted to a lang item.

[kennytm]

iirc the plan is std::simd::Simd is what everything else will use instead of repr(simd) and repr(simd) will become perma-unstable or removed and converted to a lang item.

then it would still correspond here to a Complex<f32> (the "Complex as a generic struct" alternative) than distinct c32, c64 types (one could define type c32 = Complex<f32>), and only one lang item for the entire struct Complex<T>

[programmerjake]

then it would still correspond here to a Complex<f32> (the "Complex as a generic struct" alternative) than distinct c32, c64 types (one could define type c32 = Complex<f32>), and only one lang item for the entire struct Complex<T>

I think having a generic struct is better anyway since it makes it easier to be generic over the underlying floating-point type, and to maybe also support GCC's complex integers extension. Also, it seems as though all the other types in std are becoming generic over primitive types instead of having a separate independent type for each primitive, e.g. NonZero and Atomic (though Atomic is just a type alias for now due to issues with AtomicU128 still being unstable)

[SciMind2460]

I think having a generic struct is better anyway since it makes it easier to be generic over the underlying floating-point type, and to maybe also support GCC's complex integers extension. Also, it seems as though all the other types in std are becoming generic over primitive types instead of having a separate independent type for each primitive, e.g. NonZero and Atomic (though Atomic is just a type alias for now due to issues with AtomicU128 still being unstable)

That seems good. I've made an implementation based on it representing complex numbers as Simd floats and then implementing operations on them. Unfortunately, f16 and f128 support are blocked on #125440. Also, we'll need lang support for calling convention matching, but that can always be added later