Swift Numerics

The ElementaryFunctions protocol provides access to a wide range of mathematical building blocks, including exponential, logarithmic, trigonometric, hyperbolic, and power/root functions. Any type conforming to ElementaryFunctions makes these functions available as static methods.

Note that ElementaryFunctions conformance implies AdditiveArithmetic, so standard addition, subtraction, and the zero property are also available on these types.

let x: Float = 1
let y = Float.sin(x) // 0.84147096

The NumericsShims module is an internal implementation detail used by other Swift Numerics modules. It provides access to Swift builtins and assembly by wrapping them in static inline C functions.

Note: This module provides no stable Swift API and is not intended for direct use by end-users.

Swift Numerics implements complex division (/) using a two-path approach to balance performance and numerical stability.

The Fast Path

When the divisor w is 'well-scaled' (meaning its squared length w.lengthSquared is a normal floating-point number), the library uses a simplified formula: z * w.conjugate / w.lengthSquared. This is computationally efficient and performs similarly to complex multiplication.

The Slow Path

If the divisor is not well-scaled (risking overflow or underflow in intermediate steps), the library switches to a scaling algorithm based on Doug Priest's 'Efficient Scaling for Complex Division'. It scales both the numerator and denominator by a factor s (a power of the radix) to ensure the reciprocal can be computed without losing precision or triggering premature overflow/underflow. This ensures that the division is as robust as multiplication.

The library prioritizes robust division and multiplication with small relative error in a complex norm, rather than guaranteeing small componentwise errors.

This approach allows the use of fast, naive formulas for the common case, with additional checks to prevent spurious overflow or underflow. While componentwise error bounds are not guaranteed, the implementation is designed to be as accurate as standard real-number multiplication.

When working with very large or very small complex numbers, a naive implementation of the Euclidean norm (sqrt(x*x + y*y)) can fail. For example, with Float, a value like 1e20 would cause x*x to overflow to infinity, even though the square root of the sum is representable.

Swift Numerics' .length property handles this automatically by using a robust two-step algorithm that avoids these spurious errors.

let z = Complex<Float>(1e20, 1e20)
z.length // 1.41421358E+20

let w = Complex<Float>(1e-24, 1e-24)
w.length // 1.41421362E-24

The Complex module does not provide heterogeneous arithmetic operators (e.g., adding a RealType to a Complex number like z + x).

This design choice avoids ambiguous type inference. For example, in a context where Complex is expected, an expression like 2 * a (where a is a RealType) could be interpreted as either a RealType or a Complex number, leading to unexpected behavior. To perform arithmetic between real and complex numbers, you should explicitly convert the real value to a Complex type.

Swift Numerics provides two ways to measure the size of a complex number:

1. magnitude: Returns the infinity norm (also known as the maximum norm or Chebyshev norm).
2. length: Returns the two-norm (also known as the Euclidean norm).

You can also use .lengthSquared to get the squared Euclidean norm.

All Complex numbers containing a non-finite component are treated as a single "point at infinity". This point has infinite magnitude and an indeterminate phase. Consequently, the real and imaginary parts of an infinity value are NaN.

let w = Complex<Double>.infinity
w == -w               // true
let re = w.real       // .nan
let im = w.imag       // .nan