Support Complex literals, arithmetic operations (#2709)

Co-authored-by: Scott Carda <[email protected]>

Author: swernli

library/core/core.qs

@@ -57,5 +57,19 @@ namespace Std.Core {
         output
     }
 
-    export Length, Repeated;
+    /// # Summary
+    /// Represents a complex number by its real and imaginary components.
+    /// The real component can be accessed via the `Real` field, and the imaginary
+    /// component via the `Imag` field. Complex literals can be written using the
+    /// form `a + bi`, where `a` is the Double literal for the real part and
+    /// `b` is the Double literal for the imaginary part.
+    ///
+    /// # Example
+    /// The following snippet defines the imaginary unit 𝑖 = 0 + 1𝑖:
+    /// ```qsharp
+    /// let imagUnit = 1.0i;
+    /// ```
+    struct Complex { Real : Double, Imag : Double }
+
+    export Length, Repeated, Complex;
 }

library/std/src/Std/Math.qs

@@ -1106,18 +1106,6 @@ function PNormalized(p : Double, array : Double[]) : Double[] {
 // Complex numbers
 //
 
-/// # Summary
-/// Represents a complex number by its real and imaginary components.
-/// The first element of the tuple is the real component,
-/// the second one - the imaginary component.
-///
-/// # Example
-/// The following snippet defines the imaginary unit 𝑖 = 0 + 1𝑖:
-/// ```qsharp
-/// let imagUnit = Complex(0.0, 1.0);
-/// ```
-struct Complex { Real : Double, Imag : Double }
-
 /// # Summary
 /// Represents a complex number in polar form.
 /// The polar representation of a complex number is c = r⋅𝑒^(t𝑖).
@@ -1218,7 +1206,7 @@ function ArgComplexPolar(input : ComplexPolar) : Double { input.Argument }
 /// # Output
 /// The unary negation of `input`.
 function NegationC(input : Complex) : Complex {
-    Complex(-input.Real, -input.Imag)
+    -input
 }
 
 /// # Summary
@@ -1246,7 +1234,7 @@ function NegationCP(input : ComplexPolar) : ComplexPolar {
 /// # Output
 /// The sum a + b.
 function PlusC(a : Complex, b : Complex) : Complex {
-    Complex(a.Real + b.Real, a.Imag + b.Imag)
+    a + b
 }
 
 /// # Summary
@@ -1261,12 +1249,7 @@ function PlusC(a : Complex, b : Complex) : Complex {
 /// # Output
 /// The sum a + b.
 function PlusCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar {
-    ComplexAsComplexPolar(
-        PlusC(
-            ComplexPolarAsComplex(a),
-            ComplexPolarAsComplex(b)
-        )
-    )
+    ComplexAsComplexPolar(ComplexPolarAsComplex(a) + ComplexPolarAsComplex(b))
 }
 
 /// # Summary
@@ -1281,7 +1264,7 @@ function PlusCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar {
 /// # Output
 /// The difference a - b.
 function MinusC(a : Complex, b : Complex) : Complex {
-    Complex(a.Real - b.Real, a.Imag - b.Imag)
+    a - b
 }
 
 /// # Summary
@@ -1311,10 +1294,7 @@ function MinusCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar {
 /// # Output
 /// The product a⋅b.
 function TimesC(a : Complex, b : Complex) : Complex {
-    Complex(
-        a.Real * b.Real - a.Imag * b.Imag,
-        a.Real * b.Imag + a.Imag * b.Real
-    )
+    a * b
 }
 
 /// # Summary
@@ -1335,33 +1315,6 @@ function TimesCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar {
     )
 }
 
-/// # Summary
-/// Internal. Since it is easiest to define the power of two complex numbers
-/// in Cartesian form as returning in polar form, we define that here, then
-/// convert as needed.
-/// Note that this is a multi-valued function, but only one value is returned.
-internal function PowCAsCP(base : Complex, power : Complex) : ComplexPolar {
-    let (a, b) = (base.Real, base.Imag);
-    let (c, d) = (power.Real, power.Imag);
-    let baseSqNorm = a * a + b * b;
-    let baseNorm = Sqrt(baseSqNorm);
-    let baseArg = ArgComplex(base);
-
-    // We pick the principal value of the multi-valued complex function ㏑ as
-    // ㏑(a+b𝑖) = ln(|a+b𝑖|) + 𝑖⋅arg(a+b𝑖) = ln(baseNorm) + 𝑖⋅baseArg
-    // Therefore
-    // base^power = (a+b𝑖)^(c+d𝑖) = 𝑒^( (c+d𝑖)⋅㏑(a+b𝑖) ) =
-    // = 𝑒^( (c+d𝑖)⋅(ln(baseNorm)+𝑖⋅baseArg) ) =
-    // = 𝑒^( (c⋅ln(baseNorm) - d⋅baseArg) + 𝑖⋅(c⋅baseArg + d⋅ln(baseNorm)) )
-    // magnitude = 𝑒^((c⋅ln(baseNorm) - d⋅baseArg)) = baseNorm^c / 𝑒^(d⋅baseArg)
-    // angle = d⋅ln(baseNorm) + c⋅baseArg
-
-    let magnitude = baseNorm^c / E()^(d * baseArg);
-    let angle = d * Log(baseNorm) + c * baseArg;
-
-    ComplexPolar(magnitude, angle)
-}
-
 /// # Summary
 /// Returns a number raised to a given power of type `Complex`.
 /// Note that this is a multi-valued function, but only one value is returned.
@@ -1375,7 +1328,7 @@ internal function PowCAsCP(base : Complex, power : Complex) : ComplexPolar {
 /// # Output
 /// The power a^b
 function PowC(a : Complex, power : Complex) : Complex {
-    ComplexPolarAsComplex(PowCAsCP(a, power))
+    a^power
 }
 
 /// # Summary
@@ -1391,7 +1344,7 @@ function PowC(a : Complex, power : Complex) : Complex {
 /// # Output
 /// The power a^b
 function PowCP(a : ComplexPolar, power : ComplexPolar) : ComplexPolar {
-    PowCAsCP(ComplexPolarAsComplex(a), ComplexPolarAsComplex(power))
+    ComplexAsComplexPolar(ComplexPolarAsComplex(a)^ComplexPolarAsComplex(power))
 }
 
 /// # Summary
@@ -1406,11 +1359,7 @@ function PowCP(a : ComplexPolar, power : ComplexPolar) : ComplexPolar {
 /// # Output
 /// The quotient a / b.
 function DividedByC(a : Complex, b : Complex) : Complex {
-    let sqNorm = b.Real * b.Real + b.Imag * b.Imag;
-    Complex(
-        (a.Real * b.Real + a.Imag * b.Imag) / sqNorm,
-        (a.Imag * b.Real - a.Real * b.Imag) / sqNorm
-    )
+    a / b
 }
 
 /// # Summary

source/compiler/qsc/src/interpret.rs

@@ -518,7 +518,7 @@ impl Interpreter {
             if matches!(&namespace[..], &["Std", "OpenQASM", "Angle"]) && &*udt.name == "Angle" {
                 *self.angle_ty_cache.borrow_mut() = Some(*item_id);
                 UdtKind::Angle
-            } else if matches!(&namespace[..], &["Std", "Math"]) && &*udt.name == "Complex" {
+            } else if matches!(&namespace[..], &["Std", "Core"]) && &*udt.name == "Complex" {
                 *self.complex_ty_cache.borrow_mut() = Some(*item_id);
                 UdtKind::Complex
             } else {

source/compiler/qsc_ast/src/ast.rs

@@ -1685,6 +1685,8 @@ pub enum Lit {
     Bool(bool),
     /// A floating-point literal.
     Double(f64),
+    /// A floating-point imaginary literal, e.g `1.0i`.
+    Imaginary(f64),
     /// An integer literal.
     Int(i64),
     /// A Pauli operator literal.
@@ -1701,6 +1703,7 @@ impl Display for Lit {
             Lit::BigInt(val) => write!(f, "BigInt({val})")?,
             Lit::Bool(val) => write!(f, "Bool({val})")?,
             Lit::Double(val) => write!(f, "Double({val})")?,
+            Lit::Imaginary(val) => write!(f, "Imaginary({val})")?,
             Lit::Int(val) => write!(f, "Int({val})")?,
             Lit::Pauli(val) => write!(f, "Pauli({val:?})")?,
             Lit::Result(val) => write!(f, "Result({val:?})")?,

source/compiler/qsc_codegen/src/qsharp.rs

@@ -693,6 +693,14 @@ impl<W: Write> Visitor<'_> for QSharpGen<W> {
                     };
                     self.write(&num_str);
                 }
+                Lit::Imaginary(value) => {
+                    let num_str = if value.fract() == 0.0 {
+                        format!("{value}.i")
+                    } else {
+                        format!("{value}i")
+                    };
+                    self.write(&num_str);
+                }
                 Lit::Int(value) => self.write(&value.to_string()),
                 Lit::Pauli(value) => match value {
                     Pauli::I => self.write("PauliI"),

source/compiler/qsc_codegen/src/qsharp/tests.rs

@@ -1049,3 +1049,17 @@ fn bases_and_readable_values() {
             }"#]],
     );
 }
+
+#[test]
+fn complex_literals() {
+    check(
+        "function Foo() : Complex { 3.0 + 4.0i }",
+        None,
+        &expect![[r#"
+            namespace test {
+                function Foo() : Complex {
+                    3. + 4.i
+                }
+            }"#]],
+    );
+}

source/compiler/qsc_doc_gen/src/generate_docs/tests.rs

@@ -181,6 +181,7 @@ fn index_file_generation() {
 
         | Name | Description |
         |------|-------------|
+        | [Complex](xref:Qdk.Std.Core.Complex) | Represents a complex number by its real and imaginary components. The real component can be accessed via the `Real` field, and the imaginary component via the `Imag` field. Complex literals can be written using the form `a + bi`, where `a` is the Double literal for the real part and `b` is the Double literal for the imaginary part. |
         | [Length](xref:Qdk.Std.Core.Length) | Returns the number of elements in the input array `a`. |
         | [Repeated](xref:Qdk.Std.Core.Repeated) | Creates an array of given `length` with all elements equal to given `value`. `length` must be a non-negative integer. |
     "#]]
@@ -267,6 +268,16 @@ fn generates_std_core_summary() {
     let combined_summary = core_summaries.join("\n\n");
 
     expect![[r#"
+        ## Complex
+
+        ```qsharp
+        struct Complex { Real : Double, Imag : Double }
+        ```
+
+        Represents a complex number by its real and imaginary components. The real component can be accessed via the `Real` field, and the imaginary component via the `Imag` field. Complex literals can be written using the form `a + bi`, where `a` is the Double literal for the real part and `b` is the Double literal for the imaginary part.
+
+
+
         ## Length
 
         ```qsharp