mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
docs: add dedicated documentation for ApproximateEquality (#153)
Add a comprehensive DocC guide for ApproximateEquality covering: - Background and motivation for approximate equality in floating-point math - Relative and absolute tolerance guidelines and formulas - Special value handling (NaN, infinities, signed zeroes) - Custom norms with AdditiveArithmetic - Mathematical properties (non-transitivity and why not to use for Equatable) Also update RealModule.md to link to the DocC article and restore the Approximate equality section with a link in Sources/RealModule/README.md. Resolves #153. Signed-off-by: reginaldalfret <reginaldalfret@gmail.com>
This commit is contained in:
3 files changed
+183
No files matched your search
@@ -0,0 +1,155 @@
|
||||
# Approximate Equality
|
||||
|
||||
Compare floating-point and numerical values up to a tolerance.
|
||||
|
||||
## Overview
|
||||
|
||||
Floating-point arithmetic is not exact, so two values that are mathematically
|
||||
equal may differ slightly once they have been computed. Comparing such values
|
||||
with `==` is usually a mistake: the test will fail for inputs that are equal
|
||||
in every way that matters to your program.
|
||||
|
||||
`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
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
A relative tolerance does not work well when comparing against zero, because
|
||||
the scale of zero is zero. To handle values near zero, use the overload that
|
||||
also takes 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)`. The relative tolerance
|
||||
defaults to zero here, so by passing only an absolute tolerance you get a plain
|
||||
absolute comparison. A common pattern is to supply both, using the absolute
|
||||
tolerance to bound the comparison near zero and the relative tolerance
|
||||
elsewhere:
|
||||
|
||||
```swift
|
||||
let error = 1e-8
|
||||
result.isApproximatelyEqual(
|
||||
to: expected,
|
||||
absoluteTolerance: error,
|
||||
relativeTolerance: error
|
||||
)
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
For a complex value, the default norm `\.magnitude` measures the difference
|
||||
inside a square region. To test instead whether a value lies inside a circle of
|
||||
radius `0.001` centered at `1 + 0i`, 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,33 @@ 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
|
||||
|
||||
Because floating-point arithmetic is inexact, two values that are
|
||||
mathematically equal often differ slightly once computed, so comparing them
|
||||
with `==` is usually a mistake.
|
||||
`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
|
||||
|
||||
Reference in new issue
Block a user