8.0 KiB
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.
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:
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:
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:
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:
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. The most general
overload, defined on AdditiveArithmetic, lets you supply one:
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 ifx^2 + y^2exceeds the maximum representable finite value or underflow if both components are tiny,\.magnitudenever 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:
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).