diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 92f2df91..3709ab53 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-10-02T16:43:48","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-10-02T16:44:48","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/examples/pi/index.html b/dev/examples/pi/index.html index ca9306f0..38169bce 100644 --- a/dev/examples/pi/index.html +++ b/dev/examples/pi/index.html @@ -34,4 +34,4 @@ improved_pi_interval = backward_sum(10^6) -midradius(improved_pi_interval)
(3.141592653589793, 4.787281682183675e-13)
+midradius(improved_pi_interval)
(3.141592653589793, 4.787281682183675e-13)
diff --git a/dev/index.html b/dev/index.html index 3f835acf..8c0ab353 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · IntervalArithmetic.jl
GitHub

IntervalArithmetic.jl

IntervalArithmetic.jl is a Julia package for validated numerics in Julia. All calculations are carried out using interval arithmetic where quantities are treated as intervals. The final result is a rigorous enclosure of the true value.

Installation

julia> using Pkg # Julia v1.9 or above
julia> Pkg.add("IntervalArithmetic")

Citation

If you use the IntervalArithmetic library in your publication, research, teaching, or other activities, please use the BibTeX template CITATION.bib.

  • MPFI.jl, a Julia wrapper around the MPFI C library, a multiple-precision interval arithmetic library based on MPFR
  • Intervals.jl, an alternative implementation of basic interval functions by Invenia Technical Computing
+Home · IntervalArithmetic.jl
GitHub

IntervalArithmetic.jl

IntervalArithmetic.jl is a Julia package for validated numerics in Julia. All calculations are carried out using interval arithmetic where quantities are treated as intervals. The final result is a rigorous enclosure of the true value.

Installation

julia> using Pkg # Julia v1.9 or above
julia> Pkg.add("IntervalArithmetic")

Citation

If you use the IntervalArithmetic library in your publication, research, teaching, or other activities, please use the BibTeX template CITATION.bib.

  • MPFI.jl, a Julia wrapper around the MPFI C library, a multiple-precision interval arithmetic library based on MPFR
  • Intervals.jl, an alternative implementation of basic interval functions by Invenia Technical Computing
diff --git a/dev/intro/index.html b/dev/intro/index.html index acd02c0e..a5504c8c 100644 --- a/dev/intro/index.html +++ b/dev/intro/index.html @@ -4,4 +4,4 @@ [a^2, b^2], & 0 \le a \le b, \\ [0, \max(a^2, b^2)], & a \le 0 \le b, \\ [b^2, a^2], & a \le b \le 0. -\end{cases}\]

Of course, we must round the lower endpoint down and the upper endpoint up to get a guaranteed enclosure of the true result.

IntervalArithmetic defines such behaviour for a wide set of basic functions, thereby allowing the evaluation of more complex functions such as

\[f(x) = \sin(3x^2 - 2 \cos(1/x))\]

Applications

To illustrate the use of interval arithmetic, consider the following:

julia> using IntervalArithmetic
julia> f(x) = x^2 - 2f (generic function with 1 method)
julia> x = interval(3, 4)Interval{Float64}(3.0, 4.0, com)
julia> f(x)Interval{Float64}(7.0, 14.0, com)_NG

Since f(x) does not contain 0, the true range of the function $f$ over the interval $[3, 4]$ is guaranteed not to contain $0$, and hence we obtain the following property.

Theorem: $f$ has no root in the interval $[3, 4]$.

This theorem has been obtained using floating-point computations! In fact, we can even extend this to semi-infinite intervals:

julia> f(interval(3, Inf))Interval{Float64}(7.0, Inf, dac)_NG

Therefore, we have excluded the whole unbounded set $[3, \infty)$ from possibly containing roots of $f$.

Interval arithmetic is the foundation of more powerful and elaborate methods in the field of computer-assisted proofs (see e.g. IntervalRootFinding.jl).

The interested reader may refer to the following books:

Compliance with the IEEE standard for interval arithmetic

IntervalArithmetic.jl complies with the specifications described in the IEEE standard for interval arithmetic. However, the reverse-mode of functions are not implemented (see Section 10.5.4).

+\end{cases}\]

Of course, we must round the lower endpoint down and the upper endpoint up to get a guaranteed enclosure of the true result.

IntervalArithmetic defines such behaviour for a wide set of basic functions, thereby allowing the evaluation of more complex functions such as

\[f(x) = \sin(3x^2 - 2 \cos(1/x))\]

Applications

To illustrate the use of interval arithmetic, consider the following:

julia> using IntervalArithmetic
julia> f(x) = x^2 - 2f (generic function with 1 method)
julia> x = interval(3, 4)Interval{Float64}(3.0, 4.0, com)
julia> f(x)Interval{Float64}(7.0, 14.0, com)_NG

Since f(x) does not contain 0, the true range of the function $f$ over the interval $[3, 4]$ is guaranteed not to contain $0$, and hence we obtain the following property.

Theorem: $f$ has no root in the interval $[3, 4]$.

This theorem has been obtained using floating-point computations! In fact, we can even extend this to semi-infinite intervals:

julia> f(interval(3, Inf))Interval{Float64}(7.0, Inf, dac)_NG

Therefore, we have excluded the whole unbounded set $[3, \infty)$ from possibly containing roots of $f$.

Interval arithmetic is the foundation of more powerful and elaborate methods in the field of computer-assisted proofs (see e.g. IntervalRootFinding.jl).

The interested reader may refer to the following books:

Compliance with the IEEE standard for interval arithmetic

IntervalArithmetic.jl complies with the specifications described in the IEEE standard for interval arithmetic. However, the reverse-mode of functions are not implemented (see Section 10.5.4).

diff --git a/dev/manual/api/index.html b/dev/manual/api/index.html index 33a66573..854e202a 100644 --- a/dev/manual/api/index.html +++ b/dev/manual/api/index.html @@ -1,5 +1,5 @@ -API · IntervalArithmetic.jl
GitHub

API

IntervalArithmetic.BareInterval — Type
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.

source
IntervalArithmetic.ExactReal — Type
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.

Danger

By using ExactReal, users acknowledge the responsibility of ensuring that the number they input corresponds to their intended value. For example, ExactReal(0.1) implies that the user knows that $0.1$ can not be represented exactly as a binary number, and that they are using a slightly different number than $0.1$. To help identify the binary number, ExactReal is displayed without any rounding.

julia> ExactReal(0.1)
+API · IntervalArithmetic.jl
GitHub
API
IntervalArithmetic.BareInterval — Type
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.
source
IntervalArithmetic.ExactReal — Type
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.
Danger
By using ExactReal, users acknowledge the responsibility of ensuring that the number they input corresponds to their intended value. For example, ExactReal(0.1) implies that the user knows that $0.1$ can not be represented exactly as a binary number, and that they are using a slightly different number than $0.1$. To help identify the binary number, ExactReal is displayed without any rounding.
julia> ExactReal(0.1)
 ExactReal{Float64}(0.1000000000000000055511151231257827021181583404541015625)
In case of doubt, has_exact_display can be use to check if the string representation of a Real is equal to its binary value.
Examples
julia> setdisplay(:full);
 
 julia> 0.5 * interval(1)
@@ -16,7 +16,7 @@
 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.
source
IntervalArithmetic.Interval — Type
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:
See also: ±, .. and @I_str.
source
IntervalArithmetic.bareinterval — Method
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.
Danger
Nothing is done to compensate for the fact that floating point literals are rounded to the nearest when parsed (e.g. 0.1). In such cases, parse the string containing the desired value to ensure its tight enclosure.
See also: interval, ±, .. and @I_str.
Examples
julia> setdisplay(:full);
+ Interval{Float64}(2.0, 2.0, com)
See also: @exact.
source
IntervalArithmetic.Interval — Type
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:
See also: ±, .. and @I_str.
source
IntervalArithmetic.bareinterval — Method
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.
Danger
Nothing is done to compensate for the fact that floating point literals are rounded to the nearest when parsed (e.g. 0.1). In such cases, parse the string containing the desired value to ensure its tight enclosure.
See also: interval, ±, .. and @I_str.
Examples
julia> setdisplay(:full);
 
 julia> bareinterval(1//1, π)
 BareInterval{Rational{Int64}}(1//1, 85563208//27235615)
@@ -28,8 +28,8 @@
 BareInterval{Float64}(1.0, 3.1415926535897936)
 
 julia> bareinterval(BigFloat, 1, π)
-BareInterval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233)
source
IntervalArithmetic.bisect — Method
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.
source
IntervalArithmetic.cancelminus — Method
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).
source
IntervalArithmetic.cancelplus — Method
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).
source
IntervalArithmetic.emptyinterval — Method
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).
source
IntervalArithmetic.entireinterval — Method
entireinterval(T=default_numtype())
Create an interval representing the entire real line, or the entire complex plane if T is complex.
Note
Depending on the flavor, infinity may or may not be considered part of the interval.
Implement the entire function of the IEEE Standard 1788-2015 (Section 10.5.2).
source
IntervalArithmetic.has_exact_display — Method
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.
source
IntervalArithmetic.hull — Method
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).
source
IntervalArithmetic.intersect_interval — Method
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).
source
IntervalArithmetic.interval — Method
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.
Danger
Nothing is done to compensate for the fact that floating point literals are rounded to the nearest when parsed (e.g. 0.1). In such cases, parse the string containing the desired value to ensure its tight enclosure.
See also: ±, .. and @I_str.
Examples
julia> setdisplay(:full);
+BareInterval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233)
source
IntervalArithmetic.bisect — Method
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.
source
IntervalArithmetic.cancelminus — Method
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).
source
IntervalArithmetic.cancelplus — Method
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).
source
IntervalArithmetic.emptyinterval — Method
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).
source
IntervalArithmetic.entireinterval — Method
entireinterval(T=default_numtype())
Create an interval representing the entire real line, or the entire complex plane if T is complex.
Note
Depending on the flavor, infinity may or may not be considered part of the interval.
Implement the entire function of the IEEE Standard 1788-2015 (Section 10.5.2).
source
IntervalArithmetic.has_exact_display — Method
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.
source
IntervalArithmetic.hull — Method
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).
source
IntervalArithmetic.intersect_interval — Method
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).
source
IntervalArithmetic.interval — Method
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.
Danger
Nothing is done to compensate for the fact that floating point literals are rounded to the nearest when parsed (e.g. 0.1). In such cases, parse the string containing the desired value to ensure its tight enclosure.
See also: ±, .. and @I_str.
Examples
julia> setdisplay(:full);
 
 julia> interval(1//1, π)
 Interval{Rational{Int64}}(1//1, 85563208//27235615, com)
@@ -41,7 +41,7 @@
 Interval{Float64}(1.0, 3.1415926535897936, com)
 
 julia> interval(BigFloat, 1, π)
-Interval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233, com)
source
IntervalArithmetic.isatomic — Method
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.
source
IntervalArithmetic.iscommon — Method
iscommon(x)
Test whether x is not empty and bounded.
Note
This is does not take into consideration the decoration of the interval.
source
IntervalArithmetic.isguaranteed — Method
isguaranteed(x::BareInterval)
+Interval{BigFloat}(1.0, 3.141592653589793238462643383279502884197169399375105820974944592307816406286233, com)
source
IntervalArithmetic.isatomic — Method
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.
source
IntervalArithmetic.iscommon — Method
iscommon(x)
Test whether x is not empty and bounded.
Note
This is does not take into consideration the decoration of the interval.
source
IntervalArithmetic.isguaranteed — Method
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
@@ -53,8 +53,8 @@
 false
 
 julia> isguaranteed(interval(1) + 0)
-false
source
IntervalArithmetic.isinterior — Method
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.
source
IntervalArithmetic.isstrictless — Method
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).
source
IntervalArithmetic.isstrictsubset — Method
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.
source
IntervalArithmetic.isthin — Method
isthin(x)
Test whether x contains only a real.
Implement the isSingleton function of the IEEE Standard 1788-2015 (Table 9.3).
source
IntervalArithmetic.isweakless — Method
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).
source
IntervalArithmetic.mid — Method
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.
source
IntervalArithmetic.mince — Method
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.
source
IntervalArithmetic.overlap — Method
overlap(x::BareInterval, y::BareInterval)
-overlap(x::Interval, y::Interval)
Implement the overlap function of the IEEE Standard 1788-2015 (Table 10.7).
source
IntervalArithmetic.pow — Method
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);
+false
source
IntervalArithmetic.isinterior — Method
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.
source
IntervalArithmetic.isstrictless — Method
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).
source
IntervalArithmetic.isstrictsubset — Method
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.
source
IntervalArithmetic.isthin — Method
isthin(x)
Test whether x contains only a real.
Implement the isSingleton function of the IEEE Standard 1788-2015 (Table 9.3).
source
IntervalArithmetic.isweakless — Method
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).
source
IntervalArithmetic.mid — Method
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.
source
IntervalArithmetic.mince — Method
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.
source
IntervalArithmetic.overlap — Method
overlap(x::BareInterval, y::BareInterval)
+overlap(x::Interval, y::Interval)
Implement the overlap function of the IEEE Standard 1788-2015 (Table 10.7).
source
IntervalArithmetic.pow — Method
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)
@@ -63,7 +63,7 @@
 Interval{Float64}(0.0, 1.0, trv)
 
 julia> pow(interval(-1, 1), interval(-3))
-Interval{Float64}(1.0, Inf, trv)
source
IntervalArithmetic.pown — Method
pown(x, n)
Implement the pown function of the IEEE Standard 1788-2015 (Table 9.1).
Examples
julia> setdisplay(:full);
+Interval{Float64}(1.0, Inf, trv)
source
IntervalArithmetic.pown — Method
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)
@@ -72,7 +72,7 @@
 Interval{Float64}(-1.0, 1.0, com)
 
 julia> pown(interval(-1, 1), -3)
-Interval{Float64}(-Inf, Inf, trv)
source
IntervalArithmetic.precedes — Method
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).
source
IntervalArithmetic.radius — Method
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.
source
IntervalArithmetic.rootn — Method
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).
source
IntervalArithmetic.setdisplay — Function
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
+Interval{Float64}(-Inf, Inf, trv)
source
IntervalArithmetic.precedes — Method
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).
source
IntervalArithmetic.radius — Method
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.
source
IntervalArithmetic.rootn — Method
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).
source
IntervalArithmetic.setdisplay — Function
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
@@ -110,7 +110,7 @@
   - significant digits: 3
 
 julia> x
-[0.0999, 0.301]
source
IntervalArithmetic.strictprecedes — Method
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).
source
IntervalArithmetic.@I_str — Macro
I"str"
Create an interval by parsing the string "str"; this is semantically equivalent to parse(Interval{default_numtype()}, "str").
Examples
julia> setdisplay(:full);
+[0.0999, 0.301]
source
IntervalArithmetic.strictprecedes — Method
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).
source
IntervalArithmetic.@I_str — Macro
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)
@@ -119,7 +119,7 @@
 Interval{Float64}(0.09999999999999999, 0.1, com)
 
 julia> in_interval(1//10, I"0.1")
-true
source
IntervalArithmetic.@exact — Macro
@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.
Danger
By using ExactReal, users acknowledge the responsibility of ensuring that the number they input corresponds to their intended value. For example, ExactReal(0.1) implies that the user knows that $0.1$ can not be represented exactly as a binary number, and that they are using a slightly different number than $0.1$. To help identify the binary number, ExactReal is displayed without any rounding.
julia> ExactReal(0.1)
+true
source
IntervalArithmetic.@exact — Macro
@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.
Danger
By using ExactReal, users acknowledge the responsibility of ensuring that the number they input corresponds to their intended value. For example, ExactReal(0.1) implies that the user knows that $0.1$ can not be represented exactly as a binary number, and that they are using a slightly different number than $0.1$. To help identify the binary number, ExactReal is displayed without any rounding.
julia> ExactReal(0.1)
 ExactReal{Float64}(0.1000000000000000055511151231257827021181583404541015625)
In case of doubt, has_exact_display can be use to check if the string representation of a Real is equal to its binary value.
Examples
julia> setdisplay(:full);
 
 julia> f(x) = 1.2*x + 0.1
@@ -135,7 +135,7 @@
 Interval{Float64}(1.2999999999999998, 2.5, com)
 
 julia> g(1.4)
-1.78
See also: ExactReal.
source
IntervalArithmetic.@interval — Macro
@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);
 
@@ -146,4 +146,4 @@
 :(sin(IntervalArithmetic.atomic(Float32, 1)))
 
 julia> @interval Float64 sin(1) exp(1)
-Interval{Float64}(0.8414709848078965, 2.7182818284590455, com)
source

+Interval{Float64}(0.8414709848078965, 2.7182818284590455, com)
source
diff --git a/dev/manual/construction/index.html b/dev/manual/construction/index.html index 081ccd7e..076abdd6 100644 --- a/dev/manual/construction/index.html +++ b/dev/manual/construction/index.html @@ -7,4 +7,4 @@ └ @ IntervalArithmetic ~/work/IntervalArithmetic.jl/IntervalArithmetic.jl/src/intervals/construction.jl:446 ∅
julia> interval(NaN)┌ Warning: ill-formed interval [a, b] with a = NaN, b = NaN and decoration d = com. NaI is returned └ @ IntervalArithmetic ~/work/IntervalArithmetic.jl/IntervalArithmetic.jl/src/intervals/construction.jl:446 -∅

These are all examples of ill-formed intervals, resulting in the decoration ill.

Danger

The decoration ill is an indicator that an error has occured. Therefore, any interval marked by this decoration cannot be trusted and the code needs to be debugged.

Guarantee

A guarantee is yet another label, independent of decorations, and not described by the IEEE Standard 1788-2015 specifications. Its purpose is to accomodate for Julia's extensive conversion and promotion system, while retaining reliability in computations. Specifically, an interval x constructed via interval satisfies isguaranteed(x) == true. However, if a call to convert(::Type{<:Interval}, ::Real) occurs, then the resulting interval x satisfies isguaranteed(x) == false, receiving the "NG" (not guaranteed) label. For instance, consider the following examples:

julia>  convert(Interval{Float64}, 1.) # considered "not guaranteed" as this call can be done implicitlyInterval{Float64}(1.0, 1.0, com)_NG
julia> interval(1) # considered "guaranteed" as the user explicitly constructed the intervalInterval{Float64}(1.0, 1.0, com)

In contrast, a BareInterval can only be constructed via bareinterval, it is not a subtype of Real, and there are no allowed conversion with Number. Thus, this interval type is always guaranteed.

Danger

A user interested in validated numerics should always have a resulting interval for which isguaranteed is true.

More constructors

The submodule IntervalArithmetic.Symbols exports the infix operator .. and ± as an alias for interval; this submodule must be explicitly imported.

julia> using IntervalArithmetic.Symbols
julia> 0.1 .. 0.2 # interval(0.1, 0.2; format = :infsup)Interval{Float64}(0.1, 0.2, com)
julia> 0.1 ± 0.2 # interval(0.1, 0.2; format = :midpoint)Interval{Float64}(-0.1, 0.30000000000000004, com)

Moreover, one can parse strings into intervals. The various string formats are the following:

To add a specific decoration, add "_com", "_dac", "_dec", "_trv" and "_ill" at the end of the string.

Danger

Most real numbers cannot be exactly represented by floating-points. In such cases, the literal expression is rounded at parse time. To construct an interval enclosing the true real number, one must rely on the string constructor mentioned above.

For instance, consider

julia> x = 0.10.1

This appears to store the real number $1/10$ in a variable x of type Float64. Yet,

julia> x > 1//10true

Hence, the floating-point 0.1 is (slightly) greater than the real number $1/10$ since $1/10$ cannot be represented exactly in binary floating-point arithmetic, at any precision. The true value must be approximated by a floating-point number with fixed precision – this procedure is called rounding.

In particular, this implies that interval(0.1) does not contain the real number $1/10$. A valid interval containing the real number $1/10$ can be constructed by

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

These are all examples of ill-formed intervals, resulting in the decoration ill.

Danger

The decoration ill is an indicator that an error has occured. Therefore, any interval marked by this decoration cannot be trusted and the code needs to be debugged.

Guarantee

A guarantee is yet another label, independent of decorations, and not described by the IEEE Standard 1788-2015 specifications. Its purpose is to accomodate for Julia's extensive conversion and promotion system, while retaining reliability in computations. Specifically, an interval x constructed via interval satisfies isguaranteed(x) == true. However, if a call to convert(::Type{<:Interval}, ::Real) occurs, then the resulting interval x satisfies isguaranteed(x) == false, receiving the "NG" (not guaranteed) label. For instance, consider the following examples:

julia>  convert(Interval{Float64}, 1.) # considered "not guaranteed" as this call can be done implicitlyInterval{Float64}(1.0, 1.0, com)_NG
julia> interval(1) # considered "guaranteed" as the user explicitly constructed the intervalInterval{Float64}(1.0, 1.0, com)

In contrast, a BareInterval can only be constructed via bareinterval, it is not a subtype of Real, and there are no allowed conversion with Number. Thus, this interval type is always guaranteed.

Danger

A user interested in validated numerics should always have a resulting interval for which isguaranteed is true.

More constructors

The submodule IntervalArithmetic.Symbols exports the infix operator .. and ± as an alias for interval; this submodule must be explicitly imported.

julia> using IntervalArithmetic.Symbols
julia> 0.1 .. 0.2 # interval(0.1, 0.2; format = :infsup)Interval{Float64}(0.1, 0.2, com)
julia> 0.1 ± 0.2 # interval(0.1, 0.2; format = :midpoint)Interval{Float64}(-0.1, 0.30000000000000004, com)

Moreover, one can parse strings into intervals. The various string formats are the following:

To add a specific decoration, add "_com", "_dac", "_dec", "_trv" and "_ill" at the end of the string.

Danger

Most real numbers cannot be exactly represented by floating-points. In such cases, the literal expression is rounded at parse time. To construct an interval enclosing the true real number, one must rely on the string constructor mentioned above.

For instance, consider

julia> x = 0.10.1

This appears to store the real number $1/10$ in a variable x of type Float64. Yet,

julia> x > 1//10true

Hence, the floating-point 0.1 is (slightly) greater than the real number $1/10$ since $1/10$ cannot be represented exactly in binary floating-point arithmetic, at any precision. The true value must be approximated by a floating-point number with fixed precision – this procedure is called rounding.

In particular, this implies that interval(0.1) does not contain the real number $1/10$. A valid interval containing the real number $1/10$ can be constructed by

julia> I"0.1"Interval{Float64}(0.09999999999999999, 0.1, com)
diff --git a/dev/manual/usage/index.html b/dev/manual/usage/index.html index 2a8eeeac..28b4046a 100644 --- a/dev/manual/usage/index.html +++ b/dev/manual/usage/index.html @@ -23,4 +23,4 @@ - format: full - decorations: false - NG flag: true - - significant digits: 4 (ignored)
julia> X = interval(0, 1)Interval{Float64}(0.0, 1.0, com)
julia> Y = interval(1, 2)Interval{Float64}(1.0, 2.0, com)
julia> X + YInterval{Float64}(1.0, 3.0, com)

Due to the above definition, subtraction of two intervals may give poor enclosures:

julia> X - XInterval{Float64}(-1.0, 1.0, com)

Elementary functions

The main elementary functions are implemented. The functions for Interval{Float64} internally use routines from the correctly-rounded CRlibm library where possible, i.e. for the following functions defined in that library:

Other functions that are implemented for Interval{Float64} internally convert to an Interval{BigFloat}, and then use routines from the MPFR library (BigFloat in Julia):

In particular, in order to obtain correct rounding for the power function (^), intervals are converted to and from BigFloat; this implies a significant slow-down in this case.

For example,

julia> X = interval(1)Interval{Float64}(1.0, 1.0, com)
julia> sin(X)Interval{Float64}(0.8414709848078965, 0.8414709848078966, com)
julia> cos(cosh(X))Interval{Float64}(0.027712143770207736, 0.02771214377020796, com)
julia> setprecision(BigFloat, 53)53
julia> Y = big(X)Interval{BigFloat}(1.0, 1.0, com)
julia> sin(Y)Interval{BigFloat}(0.8414709848078965, 0.84147098480789662, com)
julia> cos(cosh(Y))Interval{BigFloat}(0.027712143770207736, 0.027712143770207961, com)
julia> setprecision(BigFloat, 128)128
julia> sin(Y)Interval{BigFloat}(0.8414709848078965, 0.84147098480789662, com)

Comparisons and set operations

All comparisons and set operations for Real have been purposely disallowed to prevent silent errors. For instance, x == y does not implies x - y == 0 for non-singleton intervals.

julia> interval(1) < interval(2)ERROR: ArgumentError: `<` is purposely not supported for intervals. See instead `isstrictless`, `strictprecedes`
julia> precedes(interval(1), interval(2))true
julia> issubset(interval(1, 2), interval(2))ERROR: ArgumentError: `issubset` is purposely not supported for intervals. See instead `issubset_interval`
julia> issubset_interval(interval(1, 2), interval(2))false
julia> intersect(interval(1, 2), interval(2))ERROR: ArgumentError: `union!` is purposely not supported for intervals. See instead `hull`
julia> intersect_interval(interval(1, 2), interval(2))Interval{Float64}(2.0, 2.0, trv)

In particular, if ... else ... end statements used for floating-points will generally break with intervals.

One can refer to the following:

Custom interval bounds type

A BareInterval{T} or Interval{T} have the restriction T <: Union{Rational,AbstractFloat} which is the parametric type for the bounds of the interval. Supposing one wishes to use their own numeric type MyNumType <: Union{Rational,AbstractFloat}, they must provide their own arithmetic operations (with correct rounding!).

+ - significant digits: 4 (ignored)
julia> X = interval(0, 1)Interval{Float64}(0.0, 1.0, com)
julia> Y = interval(1, 2)Interval{Float64}(1.0, 2.0, com)
julia> X + YInterval{Float64}(1.0, 3.0, com)

Due to the above definition, subtraction of two intervals may give poor enclosures:

julia> X - XInterval{Float64}(-1.0, 1.0, com)

Elementary functions

The main elementary functions are implemented. The functions for Interval{Float64} internally use routines from the correctly-rounded CRlibm library where possible, i.e. for the following functions defined in that library:

Other functions that are implemented for Interval{Float64} internally convert to an Interval{BigFloat}, and then use routines from the MPFR library (BigFloat in Julia):

In particular, in order to obtain correct rounding for the power function (^), intervals are converted to and from BigFloat; this implies a significant slow-down in this case.

For example,

julia> X = interval(1)Interval{Float64}(1.0, 1.0, com)
julia> sin(X)Interval{Float64}(0.8414709848078965, 0.8414709848078966, com)
julia> cos(cosh(X))Interval{Float64}(0.027712143770207736, 0.02771214377020796, com)
julia> setprecision(BigFloat, 53)53
julia> Y = big(X)Interval{BigFloat}(1.0, 1.0, com)
julia> sin(Y)Interval{BigFloat}(0.8414709848078965, 0.84147098480789662, com)
julia> cos(cosh(Y))Interval{BigFloat}(0.027712143770207736, 0.027712143770207961, com)
julia> setprecision(BigFloat, 128)128
julia> sin(Y)Interval{BigFloat}(0.8414709848078965, 0.84147098480789662, com)

Comparisons and set operations

All comparisons and set operations for Real have been purposely disallowed to prevent silent errors. For instance, x == y does not implies x - y == 0 for non-singleton intervals.

julia> interval(1) < interval(2)ERROR: ArgumentError: `<` is purposely not supported for intervals. See instead `isstrictless`, `strictprecedes`
julia> precedes(interval(1), interval(2))true
julia> issubset(interval(1, 2), interval(2))ERROR: ArgumentError: `issubset` is purposely not supported for intervals. See instead `issubset_interval`
julia> issubset_interval(interval(1, 2), interval(2))false
julia> intersect(interval(1, 2), interval(2))ERROR: ArgumentError: `union!` is purposely not supported for intervals. See instead `hull`
julia> intersect_interval(interval(1, 2), interval(2))Interval{Float64}(2.0, 2.0, trv)

In particular, if ... else ... end statements used for floating-points will generally break with intervals.

One can refer to the following:

Custom interval bounds type

A BareInterval{T} or Interval{T} have the restriction T <: Union{Rational,AbstractFloat} which is the parametric type for the bounds of the interval. Supposing one wishes to use their own numeric type MyNumType <: Union{Rational,AbstractFloat}, they must provide their own arithmetic operations (with correct rounding!).

diff --git a/dev/objects.inv b/dev/objects.inv index 7c421803..da672302 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ