API

IntervalArithmetic

Library for validated numerics using interval arithmetic.

Learn more: https://github.com/JuliaIntervals/IntervalArithmetic.jl

BareInterval{T<:NumTypes}

Interval type for guaranteed computation with interval arithmetic according to the IEEE Standard 1788-2015. Unlike Interval, this bare interval does not have decorations, is not a subtype of Real and errors on operations mixing BareInterval and Number.

Fields:

• lo :: T
• hi :: T

Constructor compliant with the IEEE Standard 1788-2015: bareinterval.

See also: Interval.

ExactReal{T<:Real} <: Real

Real numbers with the assurance that they precisely correspond to the number described by their binary form. The purpose is to guarantee that a non interval number is exact, so that ExactReal can be used with Interval without producing the "NG" flag.

julia> ExactReal(0.1)
ExactReal{Float64}(0.1000000000000000055511151231257827021181583404541015625)

Examples

julia> setdisplay(:full);

julia> 0.5 * interval(1)
Interval{Float64}(0.5, 0.5, com)_NG

julia> ExactReal(0.5) * interval(1)
Interval{Float64}(0.5, 0.5, com)

julia> [1, interval(2)]
2-element Vector{Interval{Float64}}:
 Interval{Float64}(1.0, 1.0, com)_NG
 Interval{Float64}(2.0, 2.0, com)

julia> [ExactReal(1), interval(2)]
2-element Vector{Interval{Float64}}:
 Interval{Float64}(1.0, 1.0, com)
 Interval{Float64}(2.0, 2.0, com)

See also: @exact.

Interval{T<:NumTypes} <: Real

Interval type for guaranteed computation with interval arithmetic according to the IEEE Standard 1788-2015. This structure combines a BareInterval together with a Decoration.

Fields:

• bareinterval :: BareInterval{T}
• decoration :: Decoration
• isguaranteed :: Bool

Constructors compliant with the IEEE Standard 1788-2015:

• interval
• ..
• ±
• @I_str

See also: ±, .. and @I_str.

bareinterval(T, a, b)

Create the bare interval $[a, b]$ according to the IEEE Standard 1788-2015. The validity of the interval is checked by is_valid_interval: if true then a BareInterval{T} is constructed, otherwise an empty interval is returned.

See also: interval, ±, .. and @I_str.

Examples

julia> setdisplay(:full);

julia> bareinterval(1//1, π)
BareInterval{Rational{Int64}}(1//1, 85563208//27235615)

julia> bareinterval(Rational{Int32}, 1//1, π)
BareInterval{Rational{Int32}}(1//1, 85563208//27235615)

julia> bareinterval(1, π)
BareInterval{Float64}(1.0, 3.1415926535897936)

julia> bareinterval(BigFloat, 1, π)
BareInterval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233)

bisect(x, α=0.5)
bisect(x, i, α=0.5)

Split an interval x at a relative position α, where α = 0.5 corresponds to the midpoint.

Split the i-th component of a vector x at a relative position α, where α = 0.5 corresponds to the midpoint.

bounds(x)

Bounds of x given as a tuple. Unlike inf, this function does not normalize the infimum of the interval.

See also: inf, sup, mid, diam, radius and midradius.

cancelminus(x, y)

Compute the unique interval z such that y + z == x.

The result is decorated by at most trv (Section 11.7.1).

Implement the cancelMinus function of the IEEE Standard 1788-2015 (Section 9.2).

cancelplus(x, y)

Compute the unique interval z such that y - z == x; this is semantically equivalent to cancelminus(x, -y).

The result is decorated by at most trv (Section 11.7.1).

Implement the cancelPlus function of the IEEE Standard 1788-2015 (Section 9.2).

diam(x)

Diameter of x. If x is complex, then the diameter is the maximum diameter between its real and imaginary parts.

Implement the wid function of the IEEE Standard 1788-2015 (Table 9.2).

See also: inf, sup, bounds, mid, radius and midradius.

dist(x, y)

Distance between x and y.

emptyinterval(T=default_numtype())

Create an empty interval. This interval is an exception to the fact that the lower bound is larger than the upper one.

Implement the empty function of the IEEE Standard 1788-2015 (Section 10.5.2).

entireinterval(T=default_numtype())

Create an interval representing the entire real line, or the entire complex plane if T is complex.

Implement the entire function of the IEEE Standard 1788-2015 (Section 10.5.2).

extended_div(x, y)

Two-output division.

Implement the mulRevToPair function of the IEEE Standard 1788-2015 (Section 10.5.5).

fastpow(x, y)

A faster implementation of pow(x, y), at the cost of maybe returning a slightly larger interval.

fastpown(x, n)

A faster implementation of pown(x, y), at the cost of maybe returning a slightly larger interval.

has_exact_display(x::Real)

Determine if the display of x up to 2000 decimals is equal to the bitwise value of x. This is famously not true for the float displayed as 0.1.

hull(x, y)

Return the interval hull of the intervals x and y, considered as (extended) sets of real numbers, i.e. the smallest interval that contains all of x and y.

The result is decorated by at most trv (Section 11.7.1).

Implement the convexHull function of the IEEE Standard 1788-2015 (Section 9.3).

in_interval(x, y)

Test whether x is an element of y.

Implement the isMember function of the IEEE Standard 1788-2015 (Section 10.6.3).

inf(x)

Lower bound, or infimum, of x. For a zero AbstractFloat lower bound, a negative zero is returned.

Implement the inf function of the IEEE Standard 1788-2015 (Table 9.2).

See also: sup, bounds, mid, diam, radius and midradius.

interiordiff(x, y)

Remove the interior of y from x. If x and y are vectors, then they are treated as multi-dimensional intervals.

intersect_interval(x, y)

Returns the intersection of the intervals x and y, considered as (extended) sets of real numbers. That is, the set that contains the points common in x and y.

The result is decorated by at most trv (Section 11.7.1).

Implement the intersection function of the IEEE Standard 1788-2015 (Section 9.3).

interval(T, a, b, d = com)

Create the interval $[a, b]$ according to the IEEE Standard 1788-2015. The validity of the interval is checked by is_valid_interval: if true then an Interval{T} is constructed, otherwise an NaI (Not an Interval) is returned.

See also: ±, .. and @I_str.

Examples

julia> setdisplay(:full);

julia> interval(1//1, π)
Interval{Rational{Int64}}(1//1, 85563208//27235615, com)

julia> interval(Rational{Int32}, 1//1, π)
Interval{Rational{Int32}}(1//1, 85563208//27235615, com)

julia> interval(1, π)
Interval{Float64}(1.0, 3.1415926535897936, com)

julia> interval(BigFloat, 1, π)
Interval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233, com)

isatomic(x)

Test whether x is unable to be split. This occurs if the interval is empty, or if its lower and upper bounds are equal, or if the bounds are consecutive floating-point numbers.

isbounded(x)

Test whether x is empty or has finite bounds.

iscommon(x)

Test whether x is not empty and bounded.

isdisjoint_interval(x, y)

Test whether x and y have no common elements.

Implement the disjoint function of the IEEE Standard 1788-2015 (Table 9.3).

isempty_interval(x)

Test whether x contains no elements.

Implement the isEmpty function of the IEEE Standard 1788-2015 (Section 10.6.3).

isentire_interval(x)

Test whether x is the entire real line.

Implement the isEntire function of the IEEE Standard 1788-2015 (Section 10.6.3).

isequal_interval(x, y)

Test whether x and y are identical.

Implement the equal function of the IEEE Standard 1788-2015 (Table 9.3).

isguaranteed(x::BareInterval)
isguaranteed(x::Interval)
isguaranteed(x::Complex{<:Interval})

Test whether the interval is not guaranteed to encompass all possible numerical errors. This happens whenever an Interval is constructed using convert(::Type{<:Interval}, ::Real), which may occur implicitly when mixing intervals and Real types.

Since conversion between BareInterval and Number is prohibited, this implies that isguaranteed(::BareInterval) == true.

In the case of a complex interval x, this is semantically equivalent to isguaranteed(real(x)) & isguaranteed(imag(x)).

Examples

julia> isguaranteed(bareinterval(1))
true

julia> isguaranteed(interval(1))
true

julia> isguaranteed(convert(Interval{Float64}, 1))
false

julia> isguaranteed(interval(1) + 0)
false

isinterior(x, y)

Test whether x is in the interior of y. If x and y are intervals, this is semantically equivalent to isstrictsubset(x, y).

Implement the interior function of the IEEE Standard 1788-2015 (Table 9.3).

See also: isstrictsubset.

isnai(x)

Test whether x is an NaI (Not an Interval).

isstrictless(x, y)

Test whether inf(x) < inf(y) and sup(x) < sup(y), where < is replaced by ≤ for infinite values.

Implement the strictLess function of the IEEE Standard 1788-2015 (Table 10.3).

isstrictsubset(x, y)

Test whether x is a strict subset of y. If x and y are intervals, this is semantically equivalent to isinterior(x, y). If x and y are vectors, x must be a subset of y with at least one of their component being a strict subset.

See also: isinterior.

issubset_interval(x, y)

Test whether x is contained in y.

Implement the subset function of the IEEE Standard 1788-2015 (Table 9.3).

isthin(x, y)

Test whether x contains only y.

isthin(x)

Test whether x contains only a real.

Implement the isSingleton function of the IEEE Standard 1788-2015 (Table 9.3).

isthininteger(x)

Test whether x contains only an integer.

isthinone(x)

Test whether x contains only one.

isthinzero(x)

Test whether x contains only zero.

isunbounded(x)

Test whether x is not empty and has infinite bounds.

isweakless(x, y)

Test whether inf(x) ≤ inf(y) and sup(x) ≤ sup(y), where < is replaced by ≤ for infinite values.

Implement the less function of the IEEE Standard 1788-2015 (Table 10.3).

mag(x)

Magnitude of x.

Implement the mag function of the IEEE Standard 1788-2015 (Table 9.2).

See also: mig.

mid(x, α = 0.5)

Relative midpoint of x, for α between 0 and 1 such that mid(x, 0) is the lower bound of the interval, mid(x, 1) its upper bound, and mid(x, 0.5) its midpoint.

Implement the mid function of the IEEE Standard 1788-2015 (Table 9.2).

See also: inf, sup, bounds, diam, radius and midradius.

midradius(x)

Midpoint and radius of x.

Function required by the IEEE Standard 1788-2015 in Section 10.5.9 for the set-based flavor.

See also: inf, sup, bounds, mid, mid and radius.

mig(x)

Mignitude of x.

Implement the mig function of the IEEE Standard 1788-2015 (Table 9.2).

See also: mag.

mince!(v, x, n)

In-place version of mince.

mince(x, n)

Split an interval x in n intervals of the same diameter.

Split the i-th component of a vector x in n[i] intervals of the same diameter; n can be a tuple of integers, or a single integer in which case the same n is used for all the components of x.

nai(T=default_numtype())

Create an NaI (Not an Interval).

overlap(x::BareInterval, y::BareInterval)
overlap(x::Interval, y::Interval)

Implement the overlap function of the IEEE Standard 1788-2015 (Table 10.7).

pow(x, y)

Compute the power of the positive real part of x by y. In particular, even if y is a thin integer, this is not equivalent to pown(x, sup(y)).

Implement the pow function of the IEEE Standard 1788-2015 (Table 9.1).

See also: pown.

Examples

julia> setdisplay(:full);

julia> pow(bareinterval(2, 3), bareinterval(2))
BareInterval{Float64}(4.0, 9.0)

julia> pow(interval(-1, 1), interval(3))
Interval{Float64}(0.0, 1.0, trv)

julia> pow(interval(-1, 1), interval(-3))
Interval{Float64}(1.0, Inf, trv)

pown(x, n)

Implement the pown function of the IEEE Standard 1788-2015 (Table 9.1).

Examples

julia> setdisplay(:full);

julia> pown(bareinterval(2, 3), 2)
BareInterval{Float64}(4.0, 9.0)

julia> pown(interval(-1, 1), 3)
Interval{Float64}(-1.0, 1.0, com)

julia> pown(interval(-1, 1), -3)
Interval{Float64}(-Inf, Inf, trv)

precedes(x, y)

Test whether any element of x is lesser or equal to every elements of y.

Implement the precedes function of the IEEE Standard 1788-2015 (Table 10.3).

radius(x)

Radius of x, such that issubset_interval(x, mid(x) ± radius(x)). If x is complex, then the radius is the maximum radius between its real and imaginary parts.

Implement the rad function of the IEEE Standard 1788-2015 (Table 9.2).

See also: inf, sup, bounds, mid, diam and midradius.

rootn(x::BareInterval, n::Integer)

Compute the real n-th root of x.

Implement the rootn function of the IEEE Standard 1788-2015 (Table 9.1).

setdisplay(format::Symbol; decorations::Bool, ng_flag::Bool, sigdigits::Int)

Change the format used by show to display intervals.

Possible options:

• format can be:
  • :infsup: display intervals as [a, b].
  • :midpoint: display intervals as m ± r.
  • :full: display interval bounds entirely, ignoring sigdigits.
• decorations: display the decorations or not.
• ng_flag: display the NG flag or not.
• sigdigits: number (greater or equal to 1) of significant digits to display.

Initially, the display options are set to setdisplay(:infsup; decorations = true, ng_flag = true, sigdigits = 6). If any of format, decorations, ng_flag and sigdigits is omitted, then their value is left unchanged.

Examples

julia> setdisplay(:infsup; decorations = true, sigdigits = 6) # default display options
Display options:
  - format: infsup
  - decorations: true
  - NG flag: true
  - significant digits: 6

julia> x = interval(0.1, 0.3)
[0.0999999, 0.300001]_com

julia> setdisplay(:full)
Display options:
  - format: full
  - decorations: true
  - NG flag: true
  - significant digits: 6 (ignored)

julia> x
Interval{Float64}(0.1, 0.3, com)

julia> setdisplay(:infsup; sigdigits = 3)
Display options:
  - format: infsup
  - decorations: true
  - NG flag: true
  - significant digits: 3

julia> x
[0.0999, 0.301]_com

julia> setdisplay(; decorations = false)
Display options:
  - format: infsup
  - decorations: false
  - NG flag: true
  - significant digits: 3

julia> x
[0.0999, 0.301]

strictprecedes(x, y)

Test whether any element of x is strictly lesser than every elements of y.

Implement the strictPrecedes function of the IEEE Standard 1788-2015 (Table 10.3).

sup(x)

Upper bound, or supremum, of x.

Implement the sup function of the IEEE Standard 1788-2015 (Table 9.2).

See also: inf, bounds, mid, diam, radius and midradius.

I"str"

Create an interval by parsing the string "str"; this is semantically equivalent to parse(Interval{default_numtype()}, "str").

Examples

julia> setdisplay(:full);

julia> I"[3, 4]"
Interval{Float64}(3.0, 4.0, com)

julia> I"0.1"
Interval{Float64}(0.09999999999999999, 0.1, com)

julia> in_interval(1//10, I"0.1")
true

@exact

Wrap every literal numbers of the expression in an ExactReal. This macro allows defining generic functions, seamlessly accepting both Number and Interval arguments, without producing the "NG" flag.

julia> ExactReal(0.1)
ExactReal{Float64}(0.1000000000000000055511151231257827021181583404541015625)

Examples

julia> setdisplay(:full);

julia> f(x) = 1.2*x + 0.1
f (generic function with 1 method)

julia> f(interval(1, 2))
Interval{Float64}(1.2999999999999998, 2.5, com)_NG

julia> @exact g(x) = 1.2*x + 0.1
g (generic function with 1 method)

julia> g(interval(1, 2))
Interval{Float64}(1.2999999999999998, 2.5, com)

julia> g(1.4)
1.78

See also: ExactReal.

@interval(expr)
@interval(T, expr)
@interval(T, expr1, expr2)

Walk through an expression and wrap each argument of functions with the internal constructor atomic.

Examples

julia> setdisplay(:full);

julia> @macroexpand @interval sin(1) # Float64 is the default bound type
:(sin(IntervalArithmetic.atomic(Float64, 1)))

julia> @macroexpand @interval Float32 sin(1)
:(sin(IntervalArithmetic.atomic(Float32, 1)))

julia> @interval Float64 sin(1) exp(1)
Interval{Float64}(0.8414709848078965, 2.7182818284590455, com)