Home / Docs / Specification / 29. Numerics

29.19 Complex[F64] and Complex[F32]

Release v0.4.0

(ADR 0120 rules 22 to 25 and V3.) Complex numbers whose components are F64 or F32, with every operation defined by the operations of the components. This section applies only to packages of edition 0.5; in earlier editions Complex and complex are ordinary names.

  1. The types. Complex[F64] and Complex[F32] are two built-in types, not instances of a generic kind. Each has the fields re and im, of its component type. Complex takes F64 or F32, unlabeled, in brackets; any other argument is U2002, and a label applies to the whole type, as in secret Complex[F64]. Both satisfy Eq, and neither satisfies Ord or Integer. A user kind, variant, capability or unit named Complex is U1002 (§18 rule 1).

  2. Construction. complex(re: x, im: y) builds a value. Its arguments are both F64 or both F32; otherwise it is U2001, with a repair that converts the second to the first one's type, and a missing argument is U2001. Its arguments bind as a function's do (spec/04 §3): the first by position, the second by its label or by punning, and x.complex(im: y) is the same call. A complex type that the context expects gives its component type to both arguments, so in let u: Complex[F32] = complex(re: 0.1, im: 0.2) both literals are F32. complex is not a function value, since its result's type is chosen at each call by its arguments' type: naming it as a value is U2001, with a repair to a lambda. A package's own declaration named complex is the package's and keeps its meaning (spec/10 §11 rule 5).

  3. Operations. Each is defined by the operations of §3 on the components, in this order, each rounded once, with no contraction: no engine fuses a product into a sum. With x = a + bi and y = c + di:

    Operation Definition
    x + y, x - y, -x componentwise
    x * y re = a * c - b * d, im = a * d + b * c
    x / y Smith's algorithm: if c.abs().ieee_ge(other: d.abs()), with t = d / c and n = c + d * t, re = (a + b * t) / n and im = (b - a * t) / n; otherwise, with t = c / d and n = c * t + d, re = (a * t + b) / n and im = (b * t - a) / n
    x.conj() complex(re: a, im: -b)
    x.scale(by: k) complex(re: a * k, im: b * k), k of the component type
    x.norm_sqr() a * a + b * b, of the component type
    ==, != both components by identity (§5 rule 1)
    • Smith's limits. The bits are those of this short, published algorithm. Where it avoids it, no intermediate overflows: complex(re: 1.0e300, im: 1.0e300) divided by itself is complex(re: 1.0, im: 0.0). When t or d * t underflows, the result loses accuracy, up to all of it: complex(re: 0.0, im: 1.0e300) / complex(re: 1.0e10, im: 1.0e-320) has the real part 0.0, where the exact quotient's is about 1.0e-40. A NaN component of the divisor fails ieee_ge and takes the second branch.
    • No recovery of infinities after a NaN result (C99 Annex G is not followed): complex(re: infinity(), im: 0.0) * complex(re: 1.0, im: 0.0) is complex(re: inf, im: nan), as the formula gives. Every result is a function of the operands, the same in both engines and on every target.
    • Mixed operands. A complex and a real operand of +, -, * or /, on either side, are U2001, with a repair to scale(by:) for a product and to complex(re: x, im: 0.0) otherwise. Complex[F64] and Complex[F32] do not mix. <, <=, >, >= and mod are U2001. There is no abs, arg, exp or sqrt of a complex value until the correctly rounded functions of ADR 0114 rule 18 land.
  4. Text. to_text, interpolation and the Una form write complex(re: 1.0, im: -2.0), each component as §7 rule 1 writes an F64 and §18 rule 8 an F32.

  5. Verification. A complex value is an element of an uninterpreted sort, i!Complex_F64 or i!Complex_F32, with the field functions i!f!re! and i!f!im! into Float64 or Float32, and the field equations of a construction, as for a record (spec/12 §4). The refinement language gains re, im, complex(re:, im:) and == and != on complex values: x == y is the conjunction of SMT = on both pairs of components, a field of complex(re: a, im: b) is that argument, and a construction is never a term of its own anywhere else. The arithmetic of rule 3 and the methods are code only, U2014 in a clause: a complex product already weighs more than the bound of §8 rule 6. A program states facts about the components it computes.

  6. Representation. The representation is not observable (spec/16 §4). Both engines hold a complex value as a record of its two components, and every operation is elaborated into the operations of the components, so both compute the same bits by the routines of §9 and §18 rule 11. The flat record of ADR 0108 rule 1, two raw cells in registers with no allocation, waits for the raw cells of ADR 0107, as §9 says for F64: until then native code holds a complex value as a record object of two cells, an F64 handle or an F32 word each. Every stored component is canonical (§6).

  7. Information flow is §11's: a complex value carries labels as Int does; complex(re:, im:), every operator and every method label their result with the join of the labels of their operands, and a field of a labeled complex value carries its label.

  8. Cost. Construction, the fields, ==, conj, scale, norm_sqr and every operator are O(1): a product is four multiplications and two additions, a quotient at most three divisions, three multiplications, three additions, two absolute values and one comparison. Rendering is O(1). Checking and elaborating each of them is O(1), and the verifier encodes each in O(1) terms.

  9. Diagnostics. U1002 for a declaration named Complex; U2002 for Complex of another type; U2001 for the arguments of complex, mixed operands, an ordering, mod, and complex named as a value; U2014 for the arithmetic and the methods in a clause.

  10. Not yet. The hash encoding of a complex value (ADR 0119 rule 9, as ADR 0120 amends it) waits for the keyed hashing of ADR 0119. Complex elements of dense values (ADR 0120 rules 25 and 46) and the comparison of x * y with a 1 × 1 matrix product wait for a later step of the dense values (§17).

  11. Units. A measured complex value has one unit for both components (ADR 0120 rule 64): re and im have it, + and - need it, *, / and scale(by:) multiply or divide units, conj keeps it and norm_sqr() squares it (spec/25 §9).