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

kennytm · 2025-12-02T18:50:58Z

text/3892-complex-numbers.md

+```rust
+let y = Complex::from_array([3, 4]);
+```
+or as a tuple:
+```rust
+let z = Complex::from_tuple((3, 4));
+```


i think impl<T> From<(T, T)> for Complex<T> and impl<T> From<[T; 2]> for Complex<T> would be sufficient. it's like there is no SocketAddr::from_tuple.

This still exists. @scimind2460 please make sure you adequately address review concerns before marking topics as resolved, or leave them open for the the commenter to mark resolved themselves. If you're not sure, leave a comment.

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

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

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

text/3892-complex-numbers.md

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.

text/3892-complex-numbers.md

Co-authored-by: Jacob Lifshay <[email protected]>

text/3892-complex-numbers.md

tgross35 · 2026-01-06T21:42:58Z

text/3892-complex-numbers.md

+```rust
+let y = Complex::from_array([3, 4]);
+```
+or as a tuple:
+```rust
+let z = Complex::from_tuple((3, 4));
+```


This still exists. @scimind2460 please make sure you adequately address review concerns before marking topics as resolved, or leave them open for the the commenter to mark resolved themselves. If you're not sure, leave a comment.

text/3892-complex-numbers.md

joshtriplett · 2026-01-07T03:32:43Z

I'd love to see an FCP kicked off for this, as soon as the open comments are addressed on the RFC (extra functions that need to move to future possibilities, and the inaccurate background information on nalgebra).

text/3892-complex-numbers.md

Co-authored-by: Trevor Gross <[email protected]>

Removed redundant statement about overhead from libgcc calls and clarified the purpose of the Complex type.

scimind2460 · 2026-01-07T08:34:08Z

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

joshtriplett · 2026-01-13T16:34:03Z

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 · 2026-01-13T16:34:05Z

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

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.

text/3892-complex-numbers.md

Co-authored-by: kennytm <[email protected]>

text/3892-complex-numbers.md

Clarify the rationale behind complex number implementation alternatives.

Expanded on the limitations of polar complex numbers and the need for a standard type for FFI with C. Discussed alternatives to complex number representation and their implications.

text/3892-complex-numbers.md

Added a section discussing alternatives to complex number implementations, including polar layout and non-generic primitive types, while emphasizing the importance of FFI compatibility.

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

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

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

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

scimind2460 and others added 2 commits December 17, 2025 09:20

Refactor Complex struct and update methods

a1774ac

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.

Apply suggestions from code review

6851400

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

cuviper reviewed Dec 17, 2025

View reviewed changes

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

cuviper reviewed Dec 17, 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 Show resolved Hide resolved

scimind2460 and others added 2 commits December 30, 2025 11:44

Clarify reason for intrinsic calls

d7429f8

Apply suggestion from @programmerjake

be1092e

Co-authored-by: Jacob Lifshay <[email protected]>

joshtriplett reviewed Jan 6, 2026

View reviewed changes

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

Remove polar from the main body of the RFC

b28187b

tgross35 reviewed Jan 6, 2026

View reviewed changes

tgross35 reviewed Jan 7, 2026

View reviewed changes

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

scimind2460 and others added 4 commits January 7, 2026 16:18

Apply suggestions from code review

be027bb

Co-authored-by: Trevor Gross <[email protected]>

Update 3892-complex-numbers.md

b376ab9

Apply suggestions from code review

410b497

Co-authored-by: Trevor Gross <[email protected]>

Refine complex numbers documentation and remove redundancy

11a2bfa

Removed redundant statement about overhead from libgcc calls and clarified the purpose of the Complex type.

rust-rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. labels Jan 13, 2026

joshtriplett added I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. and removed I-libs-api-nominated Indicates that an issue has been nominated for prioritizing at the next libs-api team meeting. labels Jan 13, 2026

traviscross added the P-lang-drag-2 Lang team prioritization drag level 2. label Jan 14, 2026

kennytm reviewed Jan 14, 2026

View reviewed changes

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

Update text/3892-complex-numbers.md

a99270d

Co-authored-by: kennytm <[email protected]>

tmandry reviewed Jan 15, 2026

View reviewed changes

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

scimind2460 added 2 commits January 15, 2026 16:41

Revise alternatives section for complex numbers

5480bd4

Clarify the rationale behind complex number implementation alternatives.

Enhance discussion on complex number alternatives

9e3bacd

Expanded on the limitations of polar complex numbers and the need for a standard type for FFI with C. Discussed alternatives to complex number representation and their implications.

programmerjake reviewed Jan 16, 2026

View reviewed changes

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

Expand alternatives section for complex numbers

d773668

Added a section discussing alternatives to complex number implementations, including polar layout and non-generic primitive types, while emphasizing the importance of FFI compatibility.

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!

kennytm Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

tgross35 Jan 6, 2026

Choose a reason for hiding this comment

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

tgross35 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

scimind2460 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

joshtriplett Dec 9, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cuviper left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgross35 Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

scimind2460 commented Dec 2, 2025 •

edited by rustbot

Loading

clarfonthey commented Dec 2, 2025 •

edited

Loading

clarfonthey commented Dec 2, 2025 •

edited

Loading

scimind2460 commented Dec 3, 2025 •

edited

Loading

joshtriplett Dec 9, 2025 •

edited

Loading

rust-rfcbot commented Jan 13, 2026 •

edited by BurntSushi

Loading