Home / Docs / Specification / 29. Numerics
29.19 Complex[F64] and Complex[F32]
(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.
-
The types.
Complex[F64]andComplex[F32]are two built-in types, not instances of a generic kind. Each has the fieldsreandim, of its component type.ComplextakesF64orF32, unlabeled, in brackets; any other argument is U2002, and a label applies to the whole type, as insecret Complex[F64]. Both satisfyEq, and neither satisfiesOrdorInteger. A user kind, variant, capability or unit namedComplexis U1002 (§18 rule 1). -
Construction.
complex(re: x, im: y)builds a value. Its arguments are bothF64or bothF32; 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, andx.complex(im: y)is the same call. A complex type that the context expects gives its component type to both arguments, so inlet u: Complex[F32] = complex(re: 0.1, im: 0.2)both literals areF32.complexis 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 namedcomplexis the package's and keeps its meaning (spec/10 §11 rule 5). -
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,-xcomponentwise x * yre = a * c - b * d,im = a * d + b * cx / ySmith's algorithm: if c.abs().ieee_ge(other: d.abs()), witht = d / candn = c + d * t,re = (a + b * t) / nandim = (b - a * t) / n; otherwise, witht = c / dandn = c * t + d,re = (a * t + b) / nandim = (b * t - a) / nx.conj()complex(re: a, im: -b)x.scale(by: k)complex(re: a * k, im: b * k),kof the component typex.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 iscomplex(re: 1.0, im: 0.0). Whentord * tunderflows, 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 part0.0, where the exact quotient's is about1.0e-40. A NaN component of the divisor failsieee_geand 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)iscomplex(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 toscale(by:)for a product and tocomplex(re: x, im: 0.0)otherwise.Complex[F64]andComplex[F32]do not mix.<,<=,>,>=andmodare U2001. There is noabs,arg,exporsqrtof a complex value until the correctly rounded functions of ADR 0114 rule 18 land.
- Smith's limits. The bits are those of this short, published algorithm. Where it avoids it, no intermediate overflows:
-
Text.
to_text, interpolation and the Una form writecomplex(re: 1.0, im: -2.0), each component as §7 rule 1 writes anF64and §18 rule 8 anF32. -
Verification. A complex value is an element of an uninterpreted sort,
i!Complex_F64ori!Complex_F32, with the field functionsi!f!re!andi!f!im!intoFloat64orFloat32, and the field equations of a construction, as for a record (spec/12 §4). The refinement language gainsre,im,complex(re:, im:)and==and!=on complex values:x == yis the conjunction of SMT=on both pairs of components, a field ofcomplex(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. -
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, anF64handle or anF32word each. Every stored component is canonical (§6). -
Information flow is §11's: a complex value carries labels as
Intdoes;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. -
Cost. Construction, the fields,
==,conj,scale,norm_sqrand 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. -
Diagnostics. U1002 for a declaration named
Complex; U2002 forComplexof another type; U2001 for the arguments ofcomplex, mixed operands, an ordering,mod, andcomplexnamed as a value; U2014 for the arithmetic and the methods in a clause. -
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 * ywith a 1 × 1 matrix product wait for a later step of the dense values (§17). -
Units. A measured complex value has one unit for both components (ADR 0120 rule 64):
reandimhave it,+and-need it,*,/andscale(by:)multiply or divide units,conjkeeps it andnorm_sqr()squares it (spec/25 §9).