mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
Merge pull request #356 from stephentyrone/oct-2026-backport-main-to-1.1
Oct 2026 backport main to 1.1
This commit is contained in:
6 files changed
+400
-2
No files matched your search
@@ -1,5 +1,8 @@
|
||||
name: Pull request
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize]
|
||||
@@ -9,6 +12,8 @@ jobs:
|
||||
name: Test
|
||||
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
|
||||
with:
|
||||
enable_macos_checks: true
|
||||
windows_exclude_swift_versions: '[{"swift_version": "5.9"}]'
|
||||
enable_wasm_sdk_build: true
|
||||
wasm_sdk_build_command: swift build --target Numerics
|
||||
soundness:
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
# Notes on Complex Division
|
||||
|
||||
A discussion of the algorithms used to implement complex division
|
||||
|
||||
## Overview
|
||||
|
||||
How does compute the quotient of two complex numbers z/w? The naïve schoolbook
|
||||
answer is to turn it into complex multiplication by scaling both numerator and
|
||||
denominator by the conjugate of w: z/w = (zw̅)/(ww̅) = (zw̅)/|w|². Translated
|
||||
directly into swift, this expression would become:
|
||||
|
||||
```swift
|
||||
extension Complex {
|
||||
func naïveDivision(_ z: Complex, _ w: Complex) -> Complex {
|
||||
(z * w.conjugate).divded(by: w.lengthSquared)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If both z and w are both "well-scaled" (i.e. their exponents are neither very
|
||||
large nor very small), then this expression works reasonably well when
|
||||
evaluated in floating-point. Cancellation may occur in the computation of
|
||||
either the real or the imaginary part of the zw̅ term, but not in both
|
||||
simultaneously, so the relative error in any vector norm is bounded by a
|
||||
small multiple of machine epsilon.
|
||||
|
||||
However, if z or w is not well-scaled, then either zw̅ or |w|² or both may
|
||||
underflow or overflow, even when the actual quotient may be perfectly
|
||||
representable. For example, if we have
|
||||
|
||||
```swift
|
||||
let a: Float = 1.84467441E+19 // large, but not outrageously large
|
||||
let z = Complex(a, a)
|
||||
let w = z
|
||||
```
|
||||
|
||||
then both `(z * w.conjugate)` and `w.lengthSquared` overflow, and the result
|
||||
of `naïveDivision` is `(NaN, NaN)` even though the actual mathematical quotient
|
||||
is 1.
|
||||
|
||||
At least `(NaN, NaN)` is obviously wrong; when intermediate results underflow
|
||||
instead of overflow, we can instead get bogus results that are not obvious at
|
||||
all. For example:
|
||||
|
||||
```swift
|
||||
let z = Complex<Float>(imaginary: 6.6174449e-24)
|
||||
let w = Complex<Float>(5.29395592e-23, 3.97046694e-23)
|
||||
let q = naïveDivision(z, w)
|
||||
```
|
||||
|
||||
`q` is computed as `(0.666666686, 0.666666686)`, which looks like a reasonable
|
||||
result, but the exact `z/w` would be `(0.6, 0.8)`; both the phase and magnitude
|
||||
of the computed result have large errors, and there is no indication that
|
||||
anything went wrong.
|
||||
|
||||
## Complex division in Swift Numerics
|
||||
|
||||
### Goals
|
||||
|
||||
Programming languages and libraries have developed a variety of approaches to
|
||||
handle this problem. Swift Numerics' approach is somewhat novel, so I will
|
||||
first lay out the considerations that lead us to it.
|
||||
|
||||
1. Division should be reasonably fast, and permit compiler optimizations that
|
||||
make it faster. So long as all inputs are well-scaled, it should not be
|
||||
much slower than multiplication.
|
||||
|
||||
2. Division should have the same error characteristics as multiplication;
|
||||
componentwise error bounds and correct rounding are non-goals. Good error
|
||||
bounds in a complex norm are what matters.
|
||||
|
||||
3. Division should not be any more sensitive to undue overflow or underflow
|
||||
than multiplication is (i.e. it is OK for results very near the boundaries
|
||||
to overflow or underflow even though the exact result would be
|
||||
representable, but results that are far from those boundaries should always
|
||||
be computed with good accuracy).
|
||||
|
||||
### Fast path
|
||||
|
||||
These considerations lead us to a first draft of our implementation; since we
|
||||
want division to be roughly like multiplication, we will "simply" turn it into
|
||||
a multiplication via the naïve formula:
|
||||
|
||||
```swift
|
||||
public static func /(z: Complex, w: Complex) -> Complex {
|
||||
let lenSq = w.lengthSquared
|
||||
guard lenSq.isNormal else { /* naive formula will not work */ }
|
||||
return z * w.conjugate.divided(by: lenSq)
|
||||
}
|
||||
```
|
||||
|
||||
if `lenSq` can be computed without overflow or underflow, then
|
||||
`w.conjugate.divided(by: lenSq)` is a (rounded) reciprocal `1/w`, and so
|
||||
multiplying that by `z` satisfies the goals that we laid out above. Note
|
||||
in particular that if we are dividing multiple values by a single divisor,
|
||||
the reciprocal is a constant, and this check only has to happen once.
|
||||
|
||||
That leaves us just needing to figure out what to do when the reciprocal
|
||||
is not well-scaled.
|
||||
|
||||
### Slow path
|
||||
|
||||
When an approximate reciprocal for the divisor is not representable, we use
|
||||
a scaling algorithm adapted from Doug Priest's "Efficient Scaling for
|
||||
Complex Division". In hand-wavy form, Priest's idea is:
|
||||
|
||||
1. choose a scale factor s ~ |w|^(-¾)
|
||||
2. let wʹ ← sw
|
||||
2. let zʹ ← sz
|
||||
|
||||
Note that we _can_ compute a reciprocal for wʹ without overflow or underflow,
|
||||
because |wʹ| ~ |w|^(¼), so |wʹ²| ~ |w|^(½) and so |w̅ʹ/wʹ²| ~ |w|^(-¼).¹
|
||||
To compute z/w, we compute zʹ/wʹ. sz might overflow or underflow, but only
|
||||
if the final computation would overflow or underflow anyway. This is because
|
||||
division by w is a dilation combined with a rotation; because |w| is bounded
|
||||
away from 1, the multiplication by s is a dilation if and only if division
|
||||
by w is also dilation (this is where we diverge from Priest; because he
|
||||
doesn't have a fast-path for well-scaled w, he has to handle this case
|
||||
carefully).
|
||||
|
||||
Like Priest, we arrange for s to be a power of the radix with the desired
|
||||
scale, which makes the computation of wʹ and zʹ exact (unless zʹ over- or
|
||||
underflows). This achieves one more desirable property: barring underflow,
|
||||
rescaling both w and z by the radix does not change results when we move
|
||||
between the fast and slow algorithms.
|
||||
|
||||
Instead of `zʹ/wʹ = zʹ(w̅ʹ/|wʹ|²)`, Priest uses `(zw″)/|wʹ|²`. There isn't
|
||||
a strong reason to favor one or the other numerically, but our formulation
|
||||
lets us preserve `z/w = z * w.reciprocal` under scaling by powers of the
|
||||
radix (up to the underflow boundary), which is somewhat nice to have, and
|
||||
allows us to extract a little bit more ILP in some cases.
|
||||
|
||||
----
|
||||
### Notes
|
||||
|
||||
¹ This analysis fails for types like Float16 where the number of
|
||||
significand bits is on the order of the greatest exponent because the desired
|
||||
s may not be representable if w is subnormal. Note that the problem is _only_
|
||||
in the representation of s, so we can handle this case by rescaling in two
|
||||
steps.
|
||||
@@ -0,0 +1,228 @@
|
||||
# Approximate Equality
|
||||
|
||||
Test whether two values agree within a specified tolerance.
|
||||
|
||||
## Overview
|
||||
|
||||
In numerical computing, mathematical equality often diverges from computed
|
||||
equality. Rounding in floating-point arithmetic is one common cause, but many
|
||||
nontrivial numerical algorithms also have inherent truncation or discretization
|
||||
errors, and empirical measurements carry uncertainty to begin with. In these
|
||||
scenarios, exact equality (`==`) may be too strict or inappropriate, and an
|
||||
approximate equality comparison is needed instead. Conversely, exact equality
|
||||
remains entirely appropriate when checking for identical values, sentinel states,
|
||||
or integers.
|
||||
|
||||
`RealModule` provides a family of `isApproximatelyEqual` methods that test
|
||||
whether two values are within a tolerance of one another. They are available
|
||||
on any `Numeric` type whose `Magnitude` is a `FloatingPoint` type (including
|
||||
`Float`, `Double`, and `Complex`), and a more general form is available on any
|
||||
`AdditiveArithmetic` type for which you can supply a norm.
|
||||
|
||||
```swift
|
||||
import Numerics
|
||||
|
||||
let x = 0.1 + 0.2
|
||||
x == 0.3 // false
|
||||
x.isApproximatelyEqual(to: 0.3) // true
|
||||
```
|
||||
|
||||
### Comparing non-Numeric types with a custom norm
|
||||
|
||||
The approximate equality API is not limited to scalar numbers or `Numeric`
|
||||
types. Any type conforming to `AdditiveArithmetic` can be compared once you
|
||||
supply a suitable norm function mapping differences to a `FloatingPoint`
|
||||
magnitude.
|
||||
|
||||
For example, consider a 2D geometric vector or point type representing spatial
|
||||
displacements:
|
||||
|
||||
```swift
|
||||
struct Vector2D: AdditiveArithmetic, Equatable {
|
||||
var x: Double
|
||||
var y: Double
|
||||
|
||||
static var zero: Vector2D {
|
||||
Vector2D(x: 0, y: 0)
|
||||
}
|
||||
|
||||
static func + (lhs: Vector2D, rhs: Vector2D) -> Vector2D {
|
||||
Vector2D(x: lhs.x + rhs.x, y: lhs.y + rhs.y)
|
||||
}
|
||||
|
||||
static func - (lhs: Vector2D, rhs: Vector2D) -> Vector2D {
|
||||
Vector2D(x: lhs.x - rhs.x, y: lhs.y - rhs.y)
|
||||
}
|
||||
}
|
||||
|
||||
// Compare vectors using the Euclidean distance (L2 norm):
|
||||
let v1 = Vector2D(x: 1.0, y: 2.0)
|
||||
let v2 = Vector2D(x: 1.000000001, y: 1.999999999)
|
||||
|
||||
let areClose = v1.isApproximatelyEqual(
|
||||
to: v2,
|
||||
absoluteTolerance: 1e-6,
|
||||
norm: { v in (v.x * v.x + v.y * v.y).squareRoot() }
|
||||
)
|
||||
// areClose == true
|
||||
```
|
||||
|
||||
Because `Vector2D` is not `Numeric` (it does not define multiplication of
|
||||
vectors to produce a vector), it cannot use the standard `Numeric.isApproximatelyEqual`
|
||||
overload. However, because vector subtraction forms a difference vector in an
|
||||
additive space, the general `AdditiveArithmetic` overload evaluates the custom
|
||||
norm directly.
|
||||
|
||||
### Choosing a tolerance
|
||||
|
||||
The simplest method uses a _relative_ tolerance:
|
||||
|
||||
```swift
|
||||
public func isApproximatelyEqual(
|
||||
to other: Self,
|
||||
relativeTolerance: Magnitude = Magnitude.ulpOfOne.squareRoot(),
|
||||
norm: (Self) -> Magnitude = \.magnitude
|
||||
) -> Bool
|
||||
```
|
||||
|
||||
Two finite values compare equal when
|
||||
|
||||
```
|
||||
norm(self - other) <= relativeTolerance * scale
|
||||
```
|
||||
|
||||
where `scale` is `max(norm(self), norm(other), .leastNormalMagnitude)`.
|
||||
Because the bound grows with the size of the operands, a single relative
|
||||
tolerance works across a wide range of magnitudes.
|
||||
|
||||
The default tolerance is `.ulpOfOne.squareRoot()`, which corresponds to
|
||||
expecting about half of the available digits in the result to be correct. This
|
||||
is the usual rule of thumb in numerical analysis when you have no other
|
||||
information about the computation, but it is not appropriate for every use
|
||||
case, so you should pass an explicit value when you can estimate how much error
|
||||
your computation introduces.
|
||||
|
||||
#### Absolute versus relative tolerance
|
||||
|
||||
A relative tolerance scales with the magnitude of the operands, making it
|
||||
effective across numbers of very small or very large scale. However, a pure
|
||||
relative tolerance fails when comparing against zero or numbers much smaller
|
||||
than the surrounding computation, because `scale` approaches zero and shrinks
|
||||
the allowable difference to near zero.
|
||||
|
||||
To handle values near zero, use the overload that also accepts an _absolute_
|
||||
tolerance:
|
||||
|
||||
```swift
|
||||
public func isApproximatelyEqual(
|
||||
to other: Self,
|
||||
absoluteTolerance: Magnitude,
|
||||
relativeTolerance: Magnitude = 0
|
||||
) -> Bool
|
||||
```
|
||||
|
||||
Two finite values compare equal when _either_ the absolute or the relative
|
||||
bound is satisfied:
|
||||
|
||||
```
|
||||
(self - other).magnitude <= absoluteTolerance
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
(self - other).magnitude <= relativeTolerance * scale
|
||||
```
|
||||
|
||||
where `scale` is `max(self.magnitude, other.magnitude)`.
|
||||
|
||||
When choosing values:
|
||||
- Use **relative tolerance** when the allowed error is proportional to the
|
||||
magnitude of the values being computed (e.g. general floating-point arithmetic).
|
||||
- Use **absolute tolerance** when values can be near zero, or when the error
|
||||
is independent of the scale of the inputs (e.g. fixed measurement resolution).
|
||||
- Supplying both allows the absolute tolerance to govern comparisons near
|
||||
zero, while the relative tolerance takes over once values grow beyond
|
||||
`absoluteTolerance / relativeTolerance`.
|
||||
|
||||
Setting `absoluteTolerance == relativeTolerance` is typically appropriate only
|
||||
when values are expected to lie on an integral or unit-spaced grid due to
|
||||
algorithmic considerations (where `1.0` represents the base unit scale). For
|
||||
general computations, the two tolerances should be chosen independently based on
|
||||
the scale of the problem and the expected precision.
|
||||
|
||||
### Special values
|
||||
|
||||
The comparison follows the same conventions as `FloatingPoint`:
|
||||
|
||||
```swift
|
||||
Double.nan.isApproximatelyEqual(to: .nan) // false
|
||||
Double.infinity.isApproximatelyEqual(to: .infinity) // true
|
||||
(0.0).isApproximatelyEqual(to: -0.0) // true
|
||||
```
|
||||
|
||||
A NaN is never approximately equal to anything, including itself, and a finite
|
||||
value is never approximately equal to an infinity. Equal values always compare
|
||||
approximately equal regardless of the tolerance, so infinities compare equal to
|
||||
themselves and `+0` compares equal to `-0`.
|
||||
|
||||
### Comparing other types with a custom norm
|
||||
|
||||
The methods above measure the difference between two values using the
|
||||
`.magnitude` property. Sometimes you want to use a different
|
||||
[norm](https://en.wikipedia.org/wiki/Norm_(mathematics)). The most general
|
||||
overload, defined on `AdditiveArithmetic`, lets you supply one:
|
||||
|
||||
```swift
|
||||
public func isApproximatelyEqual<Magnitude>(
|
||||
to other: Self,
|
||||
absoluteTolerance: Magnitude,
|
||||
relativeTolerance: Magnitude = 0,
|
||||
norm: (Self) -> Magnitude
|
||||
) -> Bool
|
||||
where Magnitude: FloatingPoint
|
||||
```
|
||||
|
||||
#### Complex magnitude vs other norms
|
||||
|
||||
For complex numbers, the default norm is `\.magnitude`, which computes the
|
||||
infinity-norm (`max(abs(real), abs(imaginary))`).
|
||||
|
||||
A major numerical advantage of `\.magnitude` for complex values is that it is
|
||||
finite and non-zero for any finite non-zero value:
|
||||
- Unlike Euclidean length (`\.length`, $\sqrt{x^2 + y^2}$), which can overflow
|
||||
to infinity if $x^2 + y^2$ exceeds the maximum representable finite value or
|
||||
underflow if both components are tiny, `\.magnitude` never overflows or underflows
|
||||
for finite numbers.
|
||||
- It avoids intermediate squaring, square roots, or the complex scaling logic of
|
||||
`hypot`, making it robust even when handling very poorly scaled values.
|
||||
|
||||
If you specifically need to test whether a complex number lies inside a circular
|
||||
disk of radius `0.001` centered at `1 + 0i` rather than a square box, you can
|
||||
pass the Euclidean length as the norm:
|
||||
|
||||
```swift
|
||||
import ComplexModule
|
||||
|
||||
z.isApproximatelyEqual(
|
||||
to: 1,
|
||||
absoluteTolerance: 0.001,
|
||||
norm: \.length
|
||||
)
|
||||
```
|
||||
|
||||
## Mathematical properties
|
||||
|
||||
For any fixed tolerance, approximate equality is _reflexive_ on
|
||||
non-exceptional values and _symmetric_: if `a` is approximately equal to `b`,
|
||||
then `b` is approximately equal to `a`.
|
||||
|
||||
It is **not transitive**. `a` can be approximately equal to `b`, and `b` to
|
||||
`c`, while `a` and `c` differ by more than the tolerance. Approximate equality
|
||||
is therefore **not** an equivalence relation, even when restricted to
|
||||
non-exceptional values. For this reason you must not use it to implement a
|
||||
conformance to `Equatable`: doing so would violate the invariants that generic
|
||||
code written against `Equatable` relies on.
|
||||
|
||||
For any point `a`, the set of values that compare approximately equal to `a`
|
||||
is _convex_ (under the assumption that `norm` implements a valid norm).
|
||||
@@ -26,3 +26,7 @@ The Real protocol is a convenient name for the intersection of `FloatingPoint`,
|
||||
`RealFunctions`, and `AlgebraicField`; this is the protocol that you are most
|
||||
likely to want to constrain to when writing generic "math" code that works
|
||||
with floating-point types.
|
||||
|
||||
``RealModule`` also provides `isApproximatelyEqual` methods for comparing
|
||||
floating-point values up to a tolerance, which is almost always what you want
|
||||
instead of an exact `==` comparison. See <doc:ApproximateEquality> for details.
|
||||
@@ -68,9 +68,30 @@ This gives us an implementation that works for `Float`, `Double`, and `Float80`
|
||||
When new basic floating-point types are added to Swift, like `Float16` or `Float128`, it will work for them as well.
|
||||
Not having this protocol is a significant missing feature for numerical computing in Swift, and I'm really looking forward to seeing what people do with it.
|
||||
|
||||
## Approximate equality
|
||||
|
||||
`RealModule` provides a family of `isApproximatelyEqual` methods that test
|
||||
whether two values agree up to a relative or absolute tolerance:
|
||||
|
||||
```swift
|
||||
import Numerics
|
||||
|
||||
let x = 0.1 + 0.2
|
||||
x == 0.3 // false
|
||||
x.isApproximatelyEqual(to: 0.3) // true
|
||||
```
|
||||
|
||||
These methods are available on any `Numeric` type whose `Magnitude` is a
|
||||
`FloatingPoint` type, with a more general form on `AdditiveArithmetic` that
|
||||
takes a custom norm.
|
||||
See the [Approximate Equality][ApproximateEquality] article for a discussion of
|
||||
how to choose a tolerance, how special values are handled, and why approximate
|
||||
equality must not be used to implement `Equatable`.
|
||||
|
||||
### Dependencies:
|
||||
- The C standard math library (`libm`) via the `_NumericsShims` target.
|
||||
|
||||
[ApproximateEquality]: Documentation.docc/ApproximateEquality.md
|
||||
[ErrorFunction]: https://en.wikipedia.org/wiki/Error_function
|
||||
[GammaFunction]: https://en.wikipedia.org/wiki/Gamma_function
|
||||
[SE-0246]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0246-mathable.md
|
||||
|
||||
@@ -23,9 +23,9 @@ function(get_swift_host_arch result_var_name)
|
||||
else()
|
||||
set("${result_var_name}" "aarch64" PARENT_SCOPE)
|
||||
endif()
|
||||
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64")
|
||||
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64" OR "${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "powerpc64")
|
||||
set("${result_var_name}" "powerpc64" PARENT_SCOPE)
|
||||
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64le")
|
||||
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "ppc64le" OR "${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "powerpc64le")
|
||||
set("${result_var_name}" "powerpc64le" PARENT_SCOPE)
|
||||
elseif("${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "s390x")
|
||||
set("${result_var_name}" "s390x" PARENT_SCOPE)
|
||||
|
||||
Reference in new issue
Block a user