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 FF-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!

text/3892-complex-numbers.md

Co-authored-by: kennytm <kennytm@gmail.com>

text/3892-complex-numbers.md

Co-authored-by: Juniper Tyree <50025784+juntyr@users.noreply.github.com>

text/3892-complex-numbers.md

SciMind2460 · 2025-12-04T10:38:32Z

@clarfonthey one of the other reasons I don't agree with polar representation is that it makes it very hard to define complex integers (Gaussian integers) which I included as a future possibility and which are useful for dealing with discrete geometry.

dlight · 2025-12-04T16:31:14Z

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 FF-compatibility types is reasonable and this shouldn't prevent us from adding std::ffi::Complex which is orthogonal.

But std::num::Complex needs to have some in-memory representation in any case, and there isn't a way to make a global toggle that says "in my app, the most natural representation is polar". So the stdlib needs to pick one or another.

What the stdlib could do is to make this representation private, and reserve the right to change it without it being considered a breaking change. But why would this change ever happen? If changing the repr of this type realistically won't happen, it's useful to make this repr a public guarantee (not only it aids FFI, it also aids unsafe code, such as people writing inline asm to manipulate such a type without the need to pass through a conversion step)

clarfonthey · 2025-12-04T16:36:37Z

The conversion between a polar and orthogonal form isn't lossless, so, it effectively can't be done "automatically" or "as an implementation detail." You need trigonometric functions to do it, and while the conversion is algebraically closed, it's certainly more complicated to do exactly and most people prefer to just use floats instead.

My point here isn't that we need to decide; the issue is that the decision itself means that we shouldn't decide, and instead avoid having a standard Complex type for the standard library.

This doesn't preclude adding std::ffi::Complex which allows ABI-compatibility with C's _Complex, however, I don't think that such a type should be made standard for the language because of the fact that there are so many different ways to go about it.

SciMind2460 · 2025-12-04T22:45:55Z

@clarfonthey IMO if you consider the fact that complex integers are only really supported orthogonally, then it becomes clear that there is only really one choice. Though polar representations are more accurate, they simply wouldn't work with complex integers (Gaussian integers) which I proposed as a future possibility. Rust has to decide in favor of the orthogonal representation if we choose to support Gaussian integers.

…

On Fri, 5 Dec, 2025, 00:37 Clar Fon, ***@***.***> wrote: *clarfonthey* left a comment (rust-lang/rfcs#3892) <#3892 (comment)> The conversion between a polar and orthogonal form isn't lossless, so, it effectively can't be done "automatically" or "as an implementation detail." You need trigonometric functions to do it, and while the conversion is algebraically closed, it's certainly more complicated to do exactly and most people prefer to just use floats instead. My point here isn't that we need to decide; the issue is that the decision itself means that we *shouldn't* decide, and instead avoid having a standard Complex type for the standard library. This doesn't preclude adding std::ffi::Complex which allows ABI-compatibility with C's _Complex, however, I don't think that such a type should be made standard for the language *because* of the fact that there are so many different ways to go about it. — Reply to this email directly, view it on GitHub <#3892 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BLL7PYEKKLORP5MEG4D3QK34ABPK3AVCNFSM6AAAAACNY66HSWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMJTGEZTINZVGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

clarfonthey · 2025-12-05T00:52:13Z

Rust doesn't have to support them, though. Gaussian integers, however useful, are not a primitive that the language needs to offer to everyone and maintain.

tgross35 · 2025-12-05T01:21:53Z

text/3892-complex-numbers.md

+## Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+`Complex<T>` numbers can be instantiated as of any type using `Complex::new(re, im)` where `re` and `im` are of the same type (this includes all numbers).
+```rust
+let x = Complex::new(3.0, 4.0);
+```


Discussion: where should this type live?

(redirecting discussion from the main PR thread to keep things organized)

tgross35 · 2025-12-05T02:21:33Z

text/3892-complex-numbers.md

+## Rationale and alternatives
+[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. 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.


The C spec says that T _Complex gets treated as T[2] in memory. It is my understanding that most ABIs effectively say the same. Could you give some concrete examples of platforms where this isn't the case?

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

I'll add into the RFC

kennytm · 2025-12-05T06:32:42Z

I guess my main clarification here was that due to the polar-orthogonal discrepancy

[...]

My point here isn't that we need to decide; the issue is that the decision itself means that we shouldn't decide, and instead avoid having a standard Complex type for the standard library.

As binary floating point cannot represent $\pi$ exactly, you can't even accurately describe $i\;(= 1\angle\tfrac\pi2)$ in polar form. In terms of representation it can work if the angle unit uses turns (multiples of $2\pi$) rather than radians. Even so, addition and subtraction under polar form is extremely complicated ($\left(r_1\angle\theta_1\right) + \left(r_2\angle\theta_2\right) = \left(\sqrt{r_1^2+r_2^2+2r_1r_2\cos(\theta_1-\theta_2)}\right)\angle\left(\tan^{-1}\tfrac{r_1\sin\theta_1+r_2\sin\theta_2}{r_1\cos\theta_1+r_2\cos\theta_2}\right)$ ) which outweighs any slight advantages brought by multiplication ($(a_1 + b_1i)\times(a_2+b_2i) = (a_1a_2 - b_1b_2) + (a_1b_2 + a_2b_1)i$ isn't really that costly in comparison), so it does not make sense as default in terms of computation either.

So I don't see how this is a valid discrepancy in the first place, no sane library will only provide a Complex<T> type in polar form, it's going to be either always rectilinear, or having multiple convertible choices StandardComplex<T>, PolarComplex<T>, EinsensteinComplex<T> etc.

If we are going to have a std::num::Complex<T>, in additional to the above reasoning, because of easy interoperability with C, C++, etc the rectilinear form is basically the only choice. That is, the "polar form" question is a total distraction, the only decision we need to make is have it, or not.

This doesn't preclude adding std::ffi::Complex which allows ABI-compatibility with C's _Complex, however, I don't think that such a type should be made standard for the language because of the fact that there are so many different ways to go about it.

Providing only core::ffi::Complex but without any associated functions is like providing core::ffi::VaList type without the arg() method, or like providing core::arch::x86::__m128 type without all the SSE _mm_* functions.

So IMO we either:

Provide a Complex<T> type which is FFI-compatible with C's _Complex T at least for T = f32, f64, and exposes all methods available in C, or
Declare that [T; 2] is FFI-compatible with _Complex T and be done with it. I think it is correct for Clang and GCC, but seems not the case for MSVC.

Though polar representations are more accurate, they simply wouldn't work with complex integers (Gaussian integers) which I proposed as a future possibility.

Note that Gaussian integers are not the only type of complex integers.

programmerjake · 2025-12-05T07:45:27Z

Provide a Complex<T> type which is FFI-compatible with C's _Complex T at least for T = f32, f64, and exposes all methods available in C, or

Declare that [T; 2] is FFI-compatible with _Complex T and be done with it. I think it is correct for Clang and GCC, but seems not the case for MSVC.

Deciding the in-memory representation is the easy part, the hard part is how exactly complex numbers are passed by value in function arguments and return values -- I recall reading ABI specs that treat complex numbers specially such that they don't really match the ABI of any other single type (so it has to be handled specially by rustc and can't just be an existing type), though I can't currently recall which ABI specs.

SciMind2460 · 2025-12-05T08:00:17Z

@programmerjake you're right - the calling convention of complex numbers is really not defined very well, which is why in my opinion No. 2 seems untenable. Sometimes complex numbers are passed as a struct, sometimes SSE registers - it really is untenable for anything other than STD to match the calling convention. (I am not an AI - I use dashes to denote pauses very frequently.)

Added theoretical C code example and alternatives for complex number handling in FFI.

Clarified rationale for Complex type regarding FFI and C calling conventions.

Noratrieb · 2025-12-06T22:54:32Z

text/3892-complex-numbers.md

+## Drawbacks
+[drawbacks]: #drawbacks
+
+If there is suddenly a standard-library Complex type, people may rush to include it in their current implementations, which would leave people behind if they didn't know about it. I really don't think this is a drawback though, since similar things have happened in Rust before: the inclusion of `OnceCell` in Rust, for example.


I don't really understand what exactly this means. Who would want to rush to include complex numbers in their code? And who would be be left behind?
I think the biggest downside here is the increased complexity and API surface and implementation maintenance.

github put this reply in the wrong thread, afaict it was intended to be here.

SciMind2460 · 2025-12-06T23:12:25Z

No, what I was intending to say was that the fact that complex numbers would be introduced would make some libraries use the std complexes immediately whereas others would still use num-complex. I'll add implementation complexity though.

…

On Sun, 7 Dec, 2025, 06:54 nora, ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In text/3892-complex-numbers.md <#3892 (comment)>: > +impl Div for Complex<f32> { // calls to __divsc3 will be required here for implementation details and corresponding real types will also be implemented + type Output = Self; + + fn div(self, other: Self) -> Self::Output; +} +impl Div for Complex<f64> { // calls to __divdc3 will be required here for implementation details and corresponding real types will also be implemented + type Output = Self; + + 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. +## Drawbacks +[drawbacks]: #drawbacks + +If there is suddenly a standard-library Complex type, people may rush to include it in their current implementations, which would leave people behind if they didn't know about it. I really don't think this is a drawback though, since similar things have happened in Rust before: the inclusion of `OnceCell` in Rust, for example. I don't really understand what exactly this means. Who would want to rush to include complex numbers in their code? And who would be be left behind? I think the biggest downside here is the increased complexity and API surface and implementation maintenance. — Reply to this email directly, view it on GitHub <#3892 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BLL7PYAVAPV6XHQUYQJ6OO34ANND5AVCNFSM6AAAAACNY66HSWVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTKNBYGUYTOOJUGA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

Clarify potential drawbacks of a standard-library Complex type and its impact on implementation.

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 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 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

Apply suggestions from code review

d86a918

Co-authored-by: kennytm <kennytm@gmail.com>

juntyr reviewed Dec 3, 2025

View reviewed changes

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

juntyr reviewed Dec 3, 2025

View reviewed changes

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

juntyr reviewed Dec 3, 2025

View reviewed changes

SciMind2460 and others added 2 commits December 4, 2025 16:41

Add fixes in type signature

4add4e1

Co-authored-by: Juniper Tyree <50025784+juntyr@users.noreply.github.com>

Apply suggestions from code review

5aceb3e

Co-authored-by: Juniper Tyree <50025784+juntyr@users.noreply.github.com>

jdahlstrom reviewed Dec 4, 2025

View reviewed changes

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

jdahlstrom reviewed Dec 4, 2025

View reviewed changes

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

SciMind2460 added 2 commits December 4, 2025 18:35

Clarified some details regarding i

94dece5

Fix wording in complex numbers documentation

0cf423a

tgross35 reviewed Dec 5, 2025

View reviewed changes

SciMind2460 added 2 commits December 5, 2025 16:27

Add possible workaround

512a3be

Added theoretical C code example and alternatives for complex number handling in FFI.

Update rationale for Complex type in FFI context

ca8f9ba

Clarified rationale for Complex type regarding FFI and C calling conventions.

Noratrieb reviewed Dec 6, 2025

View reviewed changes

Update drawbacks section for Complex type proposal

23f1e67

Clarify potential drawbacks of a standard-library Complex type and its impact on implementation.

Complex numbers #3892

Are you sure you want to change the base?

Complex numbers #3892

Conversation

SciMind2460 commented Dec 2, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joshtriplett commented Dec 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clarfonthey commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tgross35 commented Dec 2, 2025

Uh oh!

clarfonthey commented Dec 2, 2025

Uh oh!

Uh oh!

Uh oh!

SOF3 Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SciMind2460 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SciMind2460 commented Dec 4, 2025

Uh oh!

dlight commented Dec 4, 2025

Uh oh!

clarfonthey commented Dec 4, 2025

Uh oh!

SciMind2460 commented Dec 4, 2025 via email

Uh oh!

clarfonthey commented Dec 5, 2025

Uh oh!

SciMind2460 commented Dec 2, 2025 •

edited by rustbot

Loading

clarfonthey commented Dec 2, 2025 •

edited

Loading

SOF3 Dec 3, 2025 •

edited

Loading

SciMind2460 commented Dec 3, 2025 •

edited

Loading

SciMind2460 commented Dec 5, 2025 •

edited

Loading