Comparison

Comparison

This module provides convenience functions to compare numerical values up to some user-controlled precision.

Tolerance{N<:Number}

Type that represents the tolerances for a given numeric type.

Fields

• rtol – relative tolerance
• ztol – zero tolerance or absolute tolerance for comparison against zero
• atol – absolute tolerance

Notes

The type Tolerance, parametric in the numeric type N, is used to store default values for numeric comparisons. It is mutable and setting the value of a field affects the getter functions hence it can be used to globally fix the tolerance.

Default values are defined for the most commonly used numeric types, and for those cases when other numeric types are needed one can extend the default values as explained next.

The cases Float64 and Rational are special in the sense that they are the most commonly used types in applications. Getting and setting default tolerances is achieved with the functions _rtol and set_rtol (and similarly for the other tolerances); the implementation creates an instance of Tolerance{Float64} (resp. Tolerance{Rational}) and sets some default values. Again since Tolerance is mutable, setting a value is possible e.g. set_rtol(Type{Float64}, ε) for some floating-point ε.

For all other cases, a dictionary mapping numeric types to instances of Tolerance for that numeric type is used. For floating-point types, a default value has been defined through default_tolerance as follows:

default_tolerance(N::Type{<:AbstractFloat}) = Tolerance(Base.rtoldefault(N), N(10) * sqrt(eps(N)), zero(N))

Hence to set a single tolerance (either rtol, ztol or atol) for a given floating-point type, use the corresponding set_rtol function, while the values which have not been set will be pulled from default_tolerance. If you would like to define the three default values at once, or are computing with a non floating-point numeric type, you can just extend default_tolerance(N::Type{<:Number}).

isapproxzero(x::N; ztol::Real=_ztol(N)) where {N<:Real}

Determine if x is approximately zero.

Input

• x – number
• ztol – (optional, default: _ztol(N)) tolerance against zero

Output

A boolean that is true iff x ≈ 0.

Algorithm

It is considered that x ≈ 0 whenever x (in absolute value) is smaller than the tolerance for zero, ztol.

_isapprox(x::N, y::N;
          rtol::Real=_rtol(N),
          ztol::Real=_ztol(N),
          atol::Real=_atol(N)) where {N<:Real}

Determine if x is approximately equal to y.

Input

• x – number
• y – another number (of the same numeric type as x)
• rtol – (optional, default: _rtol(N)) relative tolerance
• ztol – (optional, default: _ztol(N)) absolute tolerance for comparison against zero
• atol – (optional, default: _atol(N)) absolute tolerance

Output

A boolean that is true iff x ≈ y.

Algorithm

We first check if x and y are both approximately zero, using isapproxzero(x) && isapproxzero(y). If that fails, we check if x ≈ y, using Julia's isapprox(x, y). In the latter check we use atol absolute tolerance and rtol relative tolerance.

Comparing to zero with default tolerances is a special case in Julia's isapprox, see the last paragraph in ?isapprox. This function tries to combine isapprox with its default values and a branch for x ≈ 0 ≈ y which includes x == 0 == y but also admits a tolerance ztol.

Note that if x = ztol and y = -ztol, then |x-y| = 2*ztol and still _isapprox returns true.

_leq(x::Real, y::Real; [kwargs...])

Determine if x is smaller than or equal to y.

Input

• x – number
• y – number
• rtol – (optional; default: _rtol(N)) relative tolerance
• ztol – (optional; default: _ztol(N)) absolute tolerance for comparison against zero
• atol – (optional; default: _atol(N)) absolute tolerance

Output

A boolean that is true iff x <= y.

Algorithm

The x <= y comparison is split into x < y or x ≈ y; the latter is implemented by extending Juila's built-in isapprox(x, y) with an absolute tolerance that is used to compare against zero.

_geq(x::Real, y::Real; [kwargs...])

Determine if x is greater than or equal to y.

Input

• x – number
• y – number
• rtol – (optional; default: _rtol(N)) relative tolerance
• ztol – (optional; default: _ztol(N)) absolute tolerance for comparison against zero
• atol – (optional; default: _atol(N)) absolute tolerance

Output

A boolean that is true iff x >= y.

Algorithm

This function falls back to _leq(y, x), with type promotion if needed. See the documentation of _leq for further details.

_in(x, itr)

Approximate containment check.

Input

• x – element
• itr – iterable

Output

A boolean that is true iff y ∈ itr for some y ≈ x.