Complex numbers #3892

SciMind2460 · 2025-12-02T10:51:56Z

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

text/3892-complex-numbers.md

joshtriplett · 2025-12-02T18:15:12Z

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

text/3892-complex-numbers.md

clarfonthey · 2025-12-02T19:47:41Z

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 · 2025-12-02T20:06:06Z

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 · 2025-12-02T20:19:46Z

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.

text/3892-complex-numbers.md

SOF3 · 2025-12-03T07:54:04Z

text/3892-complex-numbers.md

+
+The definition of complex numbers in the C99 standard defines the _memory layout_ of a complex number but not its _calling convention_. 
+This makes crates like `num-complex` untenable for calling C FFI functions containing complex numbers without at least a level of indirection (`*const Complex`) or the like.
+Only in `std` is it possible to make an additional repr to match the calling convention that C uses across FFI boundaries. 


Why is FFI compatibility limited to std only? It's just like how we have all the types in crate@libc. What necessitates complex becominga type in something like crate@libc?

it's like va_list (core::ffi::va_list::VaListImpl) can only be implemented in libcore.

SciMind2460 · 2025-12-03T09:51:01Z

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.

text/3892-complex-numbers.md

tgross35 · 2025-12-03T09:55:05Z

text/3892-complex-numbers.md

+impl Complex<f64> {
+  fn angle(self) {
+    f32::atan2(self.re(), self.im())
+  }
+  fn from_polar(modulus: f32, angle: f32) -> Complex<f32> {
+    Complex::new(modulus * f32::cos(angle), modulus * f32::sin(angle))
+  }
+}


Probably want to return something here? And not use the f32 types for f64

That being said: I think polar conversions should be put into "future possibilities" since they aren't needed for basic support.

I was trying to write something to help with @clarfonthey's polar proposal, but if they are fine with this becoming a future possibility, then OK!

Agreed that they should be moved to "future possibilities" for now.

text/3892-complex-numbers.md

Clarified language regarding division and method descriptions for complex numbers. Expanded rationale for the complex number type and its implications for FFI.

text/3892-complex-numbers.md

programmerjake · 2025-12-09T19:58:14Z

text/3892-complex-numbers.md

+```
+that could help simplify the life of people who otherwise would have to keep writing `Complex::new()`?
+- Should we support Imaginary eventually? This RFC doesn't cover it, but I think we can do this later in another RFC.
+- Eventually we may support Gaussian integers (an extension of the real integers) which have a Euclidean division procedure with remainder. We could theoretically eventually support these integers?


I'll note GCC has integer complex numbers as a C extension, which I think Rust should eventually support FFI with.

Co-authored-by: Josh Triplett <[email protected]>

ComputerDruid · 2025-12-11T03:37:47Z

If the motivation for putting it in std is just for FFI, could the std one just be a struct with pub fields and no other API, and then have the nice complex type be provided by a crate which is a #[repr(transparent)] wrapper around that?

programmerjake · 2025-12-11T05:06:29Z

If the motivation for putting it in std is just for FFI, could the std one just be a struct with pub fields and no otger API, and then have the nice complex type be provided by a crate which is a #[repr(transparent)] wrapper around that?

that's technically possible, but I think we should support more than that -- it's not like it's some super weird type like PowerPC's 128-bit float that they used to use for long double that's really 2x f64 in disguise with some weird arithmetic.

SciMind2460 · 2025-12-11T08:27:28Z

If the motivation for putting it in std is just for FFI, could the std one just be a struct with pub fields and no otger API, and then have the nice complex type be provided by a crate which is a #[repr(transparent)] wrapper around that?

Another problem that this RFC aims to resolve, which @miikkas pointed out, is to unify the API of complex numbers. Providing the std type as just a complex number with no methods would go against that.

Clarify future support for Gaussian integers and floating point types in the RFC.

text/3892-complex-numbers.md

Co-authored-by: Kevin Reid <[email protected]>

Clarified the rationale for a unified API for complex numbers and addressed compatibility issues with C libraries. Updated examples and alternatives to improve understanding of complex number implementations.

Co-authored-by: Kevin Reid <[email protected]>

programmerjake · 2025-12-16T00:48:11Z

text/3892-complex-numbers.md

 [guide-level-explanation]: #guide-level-explanation

-`Complex<T>` numbers can be instantiated with any component type using `Complex::new(re, im)` where `re` and `im` are of the same type (this includes all numbers).
+`Complex<T>` numbers can be instantiated with any component type using `Complex::new(re, im)` where `re` and `im` are of the same type ( includes all numbers).


removing "this" here seems like an accidental change

text/3892-complex-numbers.md

Amanieu · 2025-12-16T18:31:45Z

I would like @cuviper (as the author of num-complex) to review the proposed API here.

text/3892-complex-numbers.md

Refactor Complex struct to have public fields and update methods for real and imaginary parts. Added notes on future considerations for polar conversions and arithmetic implementations.

Co-authored-by: Josh Triplett <[email protected]>

cuviper · 2025-12-17T01:44:07Z

text/3892-complex-numbers.md

+[rationale-and-alternatives]: #rationale-and-alternatives
+
+The rationale for this type is mostly FFI: C libraries that may be linked from Rust code currently cannot provide functions with direct struct implementations of Complex - they must be hidden under at least a layer of indirection. This is because of the undefined calling convention of complex numbers in C. For example: on powerpc64-linux-gnu, [returning double _Complex doesn't do the same thing as returning a struct with a field of type double[2].](https://gcc.godbolt.org/z/hh7zYcnK6) However, it is not always possible to write a C complex-valued function that wraps the first function in a pointer. Thus, FFI becomes a problem if such complex-valued functions are passed by value and not by reference.  
+Additionally, another issue this solves is to have a unified API for complex numbers. Right now, many crates are using their own implementation (`num-complex` could serve as a unifying factor, but other crates do not implement the same complex numbers, such as `nalgebra`, due to less care over incompatibility concerns), which makes it difficult to implement unifying interfaces without complicating the code with too many conversion functions. This serves a problem for crates that use different implementations of complex numbers for different tasks (`sprs` relying on `num-complex` and `nalgebra` implementing its own variation)


You're mistaken about nalgebra, at least -- it re-exports num_complex::Complex in its own API so you don't have to depend on num-complex yourself, but it is still the same unified type.

https://docs.rs/nalgebra/latest/src/nalgebra/lib.rs.html#169

https://github.com/dimforge/nalgebra/blob/96c5d876f49afbcb0c22748b4f548b654cfef4fe/src/lib.rs#L169

It appears I made a mistake, because these docs link back to nalgebra::Complex as its own struct, but it is actually there in the definition of num-complex. I'll rework the example.

cuviper

I apologise in advance to num-complex

No worries! There are definitely things that a compiler-integrated implementation can do better, especially with ABI as you've highlighted. A lot of the num-complex API is also limited by trying to be so generic, whereas the standard library can choose to keep all the implementation flexibility for itself.

cuviper · 2025-12-17T02:03:56Z

text/3892-complex-numbers.md

+  fn sub(self, other: Self) -> Self::Output;
+}
+```
+and then implementations of those functions which require external calls to C (`__mulsc3` etc.), which will be in `std` and not `core`:


This will require #[rustc_allow_incoherent_impl] or something like it, as we do for std floating-point methods. However, I think it would be the first time we put that on a trait impl, let alone on lang-item traits such as Mul and Div. We'd better be sure the compiler is ready and willing to support that!

By comparison, num-complex implements them generically (Mul, Div) using straightforward mathematical formulas, but this doesn't take any special care for precision or overflow issues.

We could do them genetically but IMO if we do it via LLVM we can guarantee that the implementation is the exact same. I do like the idea of doing it genetically though.

cuviper · 2025-12-17T02:07:26Z

text/3892-complex-numbers.md

+  fn div(self, other: Self) -> Self::Output;
+}
+```
+The floating point numbers shall have sine and cosine and tangent functions, their inverses, their hyperbolic variants, and their inverses defined as per the C standard and with Infinity and Nan values defined as per the C standard.


These will all forward from std to external libraries as well?
(the incoherent bit is ok for inherent methods though, just like we do for regular floats)

Yes, they will be forwarded from Std and not core (if that's what you mean)

cuviper · 2025-12-17T02:11:25Z

text/3892-complex-numbers.md

+```
+that could help simplify the life of people who otherwise would have to keep writing `Complex::new()`?
+- Should we support Imaginary eventually? This RFC doesn't cover it, but I think we can do this later in another RFC.
+- Eventually we may support Gaussian integers (an extension of the real integers) which have a Euclidean division procedure with remainder. GCC has these, and we could theoretically eventually support these integers alongside GCC FFI.


FWIW, a recent issue raised that num-complex's remainder is not ideal for their purpose: rust-num/num#445

Although as I commented there, it can be seen similarly to the Rem vs. rem_euclid methods for integers in the standard library.

We could do both a biggest check and a nearest check using different methods? Like you pointed out. It will be an issue to determine the canonical remainder though.

SciMind2460 added 2 commits December 2, 2025 18:50

Add complex numbers rfc

ba634bb

Change file name and pr to reflect current issue

0f4d922

SciMind2460 mentioned this pull request Dec 2, 2025

FFI-compatible std complex numbers rust-lang/libs-team#707

Closed

ehuss added the T-libs-api Relevant to the library API team, which will review and decide on the RFC. label Dec 2, 2025

tgross35 reviewed Dec 2, 2025

View reviewed changes

joshtriplett added the T-lang Relevant to the language team, which will review and decide on the RFC. label Dec 2, 2025

joshtriplett reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

joshtriplett reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

joshtriplett reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

joshtriplett reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

joshtriplett added the I-libs-api-nominated Indicates that an issue has been nominated for prioritizing at the next libs-api team meeting. label Dec 2, 2025

kennytm reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Show resolved Hide resolved

text/3892-complex-numbers.md Show resolved Hide resolved

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

clarfonthey reviewed Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

bluebear94 suggested changes Dec 2, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

SOF3 reviewed Dec 3, 2025

View reviewed changes

SciMind2460 added 2 commits December 3, 2025 17:42

Incorporate feedback into RFC

863794c

Fix errors

60465d0

tgross35 reviewed Dec 3, 2025

View reviewed changes

SciMind2460 added 2 commits December 3, 2025 18:53

Remove impls and replace with stubs

66b4a8e

Fix polars

e6a51ea

programmerjake reviewed Dec 3, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

tgross35 reviewed Dec 3, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

kennytm reviewed Dec 3, 2025

View reviewed changes

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

text/3892-complex-numbers.md Outdated Show resolved Hide resolved

SciMind2460 added 2 commits December 3, 2025 20:35

Add more future possibilities and fix typos

f63d8e6

Add associated consts and collapse functions

8033da5

Improve clarity and rationale in complex numbers documentation

c055e1a

Clarified language regarding division and method descriptions for complex numbers. Expanded rationale for the complex number type and its implications for FFI.

joshtriplett reviewed Dec 9, 2025

View reviewed changes