API

IntervalArithmetic.DECORATIONType
DECORATION

Enumeration constant for the types of interval decorations. The nomenclature of the follows the IEEE-1788 (2015) standard (sect 11.2):

  • com -> 4: common: bounded, non-empty
  • dac -> 3: defined (nonempty) and continuous
  • def -> 2: defined (nonempty)
  • trv -> 1: always true (no information)
  • ill -> 0: nai ("not an interval")
source
IntervalArithmetic.DecoratedIntervalType
DecoratedInterval

A DecoratedInterval is an interval, together with a decoration, i.e. a flag that records the status of the interval when thought of as the result of a previously executed sequence of functions acting on an initial interval.

source
IntervalArithmetic.@formatMacro
@format [style::Symbol] [decorations::Bool] [sigfigs::Integer]

The @format macro provides a simple interface to control the output format for intervals. These options are passed to the setformat function. It returns the new DisplayParameters object.

The arguments may be in any order and of type:

  • Symbol: the output format (:full, :standard or :midpoint)
  • Bool: whether to display decorations
  • Integer: the number of significant figures

E.g.

julia> x = 0.1..0.3
@[0.0999999, 0.300001]

julia> @format full
Display parameters:
- format: full
- decorations: false
- significant figures: 6

julia> x
Interval(0.09999999999999999, 0.30000000000000004)

julia> @format standard 3
Display parameters:
- format: standard
- decorations: false
- significant figures: 3

julia> x
[0.0999, 0.301]
source
IntervalArithmetic.@intervalMacro

The @interval macro is the main method to create an interval. It converts each expression into a narrow interval that is guaranteed to contain the true value passed by the user in the one or two expressions passed to it. When passed two expressions, it takes the hull of the resulting intervals to give a guaranteed containing interval.

Examples:

    @interval(0.1)

    @interval(0.1, 0.2)

    @interval(1/3, 1/6)

    @interval(1/3^2)
source
IntervalArithmetic.@roundMacro
@round(ex1, ex2)

Macro for internal use that creates an interval by rounding down ex1 and rounding up ex2. Each expression may consist of only a single operation that needs rounding, e.g. a.lo + b.lo or sin(a.lo). It also handles min(...) and max(...), where the arguments are each themselves single operations.

The macro uses the internal round_expr function to transform e.g. a + b into +(a, b, RoundDown).

The user-facing equivalent is @interval, which can handle much more general cases.

source
Base.:==Method
==(a,b)

Checks if the intervals a and b are equal.

source
Base.:⊆Method
issubset(a,b)
⊆(a,b)

Checks if all the points of the interval a are within the interval b.

source
Base.Rounding.setroundingMethod
setrounding(Interval, rounding_type::Symbol)

Set the rounding type used for all interval calculations on Julia v0.6 and above. Valid rounding_types are (:fast, :tight, :accurate, :slow, :none).

source
Base.hashMethod

Computes the integer hash code for an Interval using the method for composite types used in AutoHashEquals.jl

source
Base.inMethod
in(x, a)
∈(x, a)

Checks if the number x is a member of the interval a, treated as a set. Corresponds to isMember in the ITF-1788 Standard.

source
Base.intersectFunction
intersect(xx, yy)

Decorated interval extension; the result is decorated as trv, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

source
Base.intersectMethod
intersect(a, b)
∩(a,b)

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

source
Base.intersectMethod
intersect(a::Interval{T}...) where T

Returns the n-ary intersection of its arguments.

This function is applicable to any number of input intervals, as in intersect(a1, a2, a3, a4) where ai is an interval. If your use case needs to splat the input, as in intersect(a...), consider reduce(intersect, a) instead, because you save the cost of splatting.

source
Base.parseMethod
parse{T}(DecoratedInterval{T}, s::AbstractString)

Parse a string of the form "[a, b]_dec" as a DecoratedInterval with decoration dec.

source
Base.parseMethod
parse{T}(Interval{T}, s::AbstractString)

Parse a string as an interval. Formats allowed include:

  • "1"
  • "[1]"
  • "[3.5, 7.2]"
  • "[-0x1.3p-1, 2/3]" # use numerical expressions
source
Base.roundMethod
round(a::Interval[, RoundingMode])

Returns the interval with rounded to an interger limits.

For compliance with the IEEE Std 1788-2015, "roundTiesToEven" corresponds to round(a) or round(a, RoundNearest), and "roundTiesToAway" to round(a, RoundNearestTiesAway).

source
Base.setdiffMethod
setdiff(x::Interval, y::Interval)

Calculate the set difference x ∖ y, i.e. the set of values that are inside the interval x but not inside y.

Returns an array of intervals. The array may:

  • be empty if x ⊆ y;
  • contain a single interval, if y overlaps x
  • contain two intervals, if y is strictly contained within x.
source
Base.setdiffMethod
setdiff(A::IntervalBox{N,T}, B::IntervalBox{N,T})

Returns a vector of IntervalBoxes that are in the set difference A ∖ B, i.e. the set of x that are in A but not in B.

Algorithm: Start from the total overlap (in all directions); expand each direction in turn.

source
Base.signbitMethod
signbit(x::Interval)

Returns an interval containing true (1) if the value of the sign of any element in x is negative, containing false (0) if any element in x is non-negative, and an empy interval if x is empty.

Examples

julia> signbit(@interval(-4))
[1, 1]

julia> signbit(@interval(5))
[0, 0]

julia> signbit(@interval(-4,5))
[0, 1]
source
Base.unionFunction
union(xx, yy)

Decorated interval extension; the result is decorated as trv, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

source
Base.unionMethod
union(a, b)
∪(a,b)

Returns the union (convex hull) of the intervals a and b; it is equivalent to hull(a,b).

source
Base.widenMethod

widen(x) widens the lowest and highest bounds of x to the previous and next representable floating-point numbers, respectively.

source
IntervalArithmetic.atomicFunction
atomic(::Type{<:Interval}, x)

Construct the tightest interval of a given type that contains the value x.

If x is an AbstractString, the interval will be created by calling parse.

Examples

Construct an Interval{Float64} containing a given BigFloat:

julia> x = big"0.1"
1.000000000000000000000000000000000000000000000000000000000000000000000000000002e-01

julia> i = IntervalArithmetic.atomic(Interval{Float64}, x)
[0.0999999, 0.100001]

julia> i isa Interval{Float64}
true

julia> i.lo <= x <= i.hi
true

julia> i.hi === nextfloat(i.lo)
true

Construct an Interval{Float32} containing a the real number 0.1 in two ways:

julia> i1 = IntervalArithmetic.atomic(Interval{Float32}, "0.1")
[0.0999999, 0.100001]

julia> i2 = IntervalArithmetic.atomic(Interval{Float32}, 1//10)
[0.0999999, 0.100001]

julia> i1 === i2
true

julia> i.lo <= 1//10 <= i.hi
true
source
IntervalArithmetic.bisectFunction
bisect(X::Interval, α=0.49609375)

Split the interval X at position α; α=0.5 corresponds to the midpoint. Returns a tuple of the new intervals.

source
IntervalArithmetic.cancelminusFunction
cancelminus(xx, yy)

Decorated interval extension; the result is decorated as trv, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

source
IntervalArithmetic.cancelplusFunction
cancelplus(xx, yy)

Decorated interval extension; the result is decorated as trv, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

source
IntervalArithmetic.emptyintervalMethod

emptyintervals are represented as the interval [∞, -∞]; note that this interval is an exception to the fact that the lower bound is larger than the upper one.

source
IntervalArithmetic.find_quadrantsMethod

Finds the quadrant(s) corresponding to a given floating-point number. The quadrants are labelled as 0 for x ∈ [0, π/2], etc. For numbers very near a boundary of the quadrant, a tuple of two quadrants is returned. The minimum or maximum must then be chosen appropriately.

This is a rather indirect way to determine if π/2 and 3π/2 are contained in the interval; cf. the formula for sine of an interval in Tucker, Validated Numerics.

source
IntervalArithmetic.hullFunction
hull(xx, yy)

Decorated interval extension; the result is decorated as trv, following the IEEE-1788 Standard (see Sect. 11.7.1, pp 47).

source
IntervalArithmetic.hullMethod
hull(a, b)

Returns the "interval hull" of the intervals a and b, considered as (extended) sets of real numbers, i.e. the smallest interval that contains all of a and b.

source
IntervalArithmetic.intervalMethod
interval(a, b)

interval(a, b) checks whether [a, b] is a valid Interval, which is the case if -∞ <= a <= b <= ∞, using the (non-exported) is_valid_interval function. If so, then an Interval(a, b) object is returned; if not, then an error is thrown.

source
IntervalArithmetic.isatomicMethod
isatomic(x::Interval)

Check whether an interval x is atomic, i.e. is unable to be split. This occurs when the interval is empty, or when the upper bound equals the lower bound or the nextfloat of the lower bound.

source
IntervalArithmetic.isthinMethod
isthin(x)

Checks if x is the set consisting of a single exactly representable float. Any float which is not exactly representable does not yield a thin interval. Corresponds to isSingleton of the standard.

source
IntervalArithmetic.labelled_setdiffMethod

Returns a list of pairs (interval, label) label is 1 if the interval is excluded from the setdiff label is 0 if the interval is included in the setdiff label is -1 if the intersection of the two intervals was empty

source
IntervalArithmetic.make_intervalMethod

make_interval does the hard work of taking expressions and making each literal (0.1, 1, etc.) into a corresponding interval construction, by calling transform.

source
IntervalArithmetic.midMethod
mid(X::IntervalBox, α=0.5)

Return a vector of the mid of each interval composing the IntervalBox.

See mid(X::Interval, α=0.5) for more informations.

source
IntervalArithmetic.midMethod
mid(a::Interval)

Find the midpoint of interval a.

For intervals of the form [-∞, x] or [x, +∞] where x is finite, return respectively nextfloat(-∞) and prevfloat(+∞). Note that it differs from the behavior of mid(a, α=0.5).

source
IntervalArithmetic.midMethod
mid(a::Interval, α=0.5)

Find an intermediate point at a relative position αin the intervala. The default is the true midpoint atα = 0.5`.

Assumes 0 ≤ α ≤ 1.

Warning: if the parameter α = 0.5 is explicitly set, the behavior differs from the default case if the provided Interval is not finite, since when α is provided mid simply replaces +∞ (respectively -∞) by prevfloat(+∞) (respecively nextfloat(-∞)) for the computation of the intermediate point.

source
IntervalArithmetic.minceMethod
mince(x::IntervalBox, n)

Splits x in n intervals in each dimension of the same diameter. These intervals are combined in all possible IntervalBox-es, which are returned as a vector.

source
IntervalArithmetic.powMethod
pow(x::Interval, n::Integer)

A faster implementation of x^n, currently using power_by_squaring. pow(x, n) will usually return an interval that is slightly larger than that calculated by x^n, but is guaranteed to be a correct enclosure when using multiplication with correct rounding.

source
IntervalArithmetic.radiusMethod
radius(a::Interval)

Return the radius of the Interval a, such that a ⊆ m ± radius, where m = mid(a) is the midpoint.

source
IntervalArithmetic.round_exprMethod
round_expr(ex::Expr, rounding_mode::RoundingMode)

Transforms a single expression by applying a rounding mode, e.g.

  • a + b into +(a, b, RoundDown)
  • sin(a) into sin(a, RoundDown)
source
IntervalArithmetic.setformatFunction
setformat(format=none; decorations=none, sigfigs=none)

setformat changes how intervals are displayed. It returns the new DisplayParameters object.

Note that The @format macro is more user-friendly.

The following options are available:

  • format: interval output format

    • :standard: [1, 2]
    • :full: Interval(1, 2)
    • :midpoint: 1.5 ± 0.5
  • sigfigs: number of significant figures to show in standard mode; the default is 6

  • decorations (boolean): show decorations or not

Example:

julia> setformat(:full, decorations=true)
Display parameters:
- format: full
- decorations: true
- significant figures: 6
source
IntervalArithmetic.transformMethod

transform transforms a string by applying the function f and type T to each argument, i.e. :(x+y) is transformed to :(f(T, x) + f(T, y))

source