Complex Numbers (Pre-ACP)

language design
1

Continuing the discussion from Standard complex number in std library

Proposal

Problem statement

Currently, there is no stable counterpart to the C _Complex types, and a myriad of implementations exist on crates.io. LLVM has a intrinsic for this, but it is not used in Rust as yet. 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.

Motivating examples or use cases

(I'm looking to develop this a bit further with code, but my basic idea is scientific computing FFI with C will have a target FFI type on this end)

Solution sketch

Complex numbers will have a implementation similar to this:

// llvm-intrinsic primitive c32, c64, c128
// impls for all the types
impl c32 {
   fn re() { ... }
   fn im() { ... }
}
// All the trait impls as per LLVM intrinsics
impl Add for c32 {}
impl Sub for c32 {}
impl Mul for c32 {}
impl Div for c32 {}

// Syntax to be used like this: 1 + 2j
// in main.rs
fn main() {
  println!("{}", 1+2j); // prints 1 + 2j
}

The complex numbers will serve as primitives and all intrinsics will be defined as per MLIR intrinsics.

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. Additionally, with complex numbers being LLVM intrinsics, I suggest that we support it as part of the underlying backend. I do not recommend this yet.

Links and related work

Standard complex number in std library

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.

Request: Can anyone provide an example piece of code that they would like for this?

2 Likes
2

A problem i see for FFI is that in C a complex number is not always passed as a struct.

On GNU _Complex is sometimes passed in SSE registers, but sometimes also passed as two separate parameters, sometimes also like a normal struct.

But MSVC does not actually support _Complex Ms docs

1 Like
3

AFAIK it is a part of the C99 standard (Arithmetic types - cppreference.com) so I think that we can create a primitive that will have the implementation-specific FFI? MSVC does have _FComplex and the like so I think we can get away with doing FFI on that front.

4

This is not a problem — Rust itself also sometimes passes structs of two elements as separate values that may be in registers (a “scalar pair”). If compatibility with C is desired, the Complex struct can be given a special #[repr] which promises to match the C _Complex ABI when the generic parameter is a primitive float. It may technically be a new compiler feature, but all the pieces are (probably) already there.

2 Likes
5

This formula for complex multiplication doesn't handle "intermediate overflow" correctly; there are situations where the mathematically correct result (computed in infinite precision) would fit in T, but one or more of the intermediate products doesn't, so you don't get the right answer. Similar problems exist for division and complex norm. How do you plan to address this?

6

Answering out of turn, but is it by using the llvm intrinsics instead?

1 Like
7

Yep, that was my idea. It's just that I was wondering if we wanted this as a primitive or a struct so I left it like that. Edited my post to use LLVM intrinsics instead.

(BTW, since this adds a new primitive to rust, would this technically not come under the scope of an ACP?)