From 8327b0c50a080efeda7fc1f542dae2a3934577e9 Mon Sep 17 00:00:00 2001 From: Luis Benet Date: Sun, 14 May 2017 20:29:15 -0500 Subject: [PATCH 1/5] Use Documenter.jl, with html format, to handle the documentation Also, add doctests blocks instead of julia code-blocks, which meant modifying few lines of the actual code. --- .gitignore | 1 + docs/make.jl | 23 ++++++++++ docs/{ => src}/decorations.md | 50 ++++++++++------------ docs/{ => src}/index.md | 54 ++++++++++++------------ docs/{ => src}/multidim.md | 20 ++++++--- docs/{ => src}/rounding.md | 21 ++++++---- docs/{ => src}/usage.md | 79 +++++++++++++++-------------------- mkdocs.yml | 18 -------- 8 files changed, 136 insertions(+), 130 deletions(-) create mode 100644 .gitignore create mode 100644 docs/make.jl rename docs/{ => src}/decorations.md (88%) rename docs/{ => src}/index.md (77%) rename docs/{ => src}/multidim.md (87%) rename docs/{ => src}/rounding.md (93%) rename docs/{ => src}/usage.md (92%) delete mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..078841d92 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/build/ diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 000000000..e8e47fb6d --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,23 @@ +using Documenter, IntervalArithmetic + +makedocs( + modules = [IntervalArithmetic], + format = :html, + sitename = "IntervalArithmetic", + pages = [ + "Package" => "index.md", + "Basic usage" => "usage.md", + "Decorations" => "decorations.md", + "Multi-dimensional boxes" => "multidim.md", + "Rounding" => "rounding.md" + ] +) + +deploydocs( + repo = "github.com/JuliaIntervals/IntervalArithmetic.jl.git", + target = "build", + julia = "0.5", + osname = "linux", + deps = nothing, + make = nothing +) diff --git a/docs/decorations.md b/docs/src/decorations.md similarity index 88% rename from docs/decorations.md rename to docs/src/decorations.md index 83ee6cf47..dbc387d59 100644 --- a/docs/decorations.md +++ b/docs/src/decorations.md @@ -1,19 +1,8 @@ -[I 160508 10:04:49 handlers:132] Browser Connected: http://127.0.0.1:8000/multid - +```@meta +DocTestSetup = quote + using IntervalArithmetic +end +``` # Decorations @@ -40,19 +29,20 @@ An example will be given at the end of this section. The simplest way to create a `DecoratedInterval` is with the `@decorated` macro, which does correct rounding: -``` +```jldoctest decorations julia> @decorated(0.1, 0.3) -[0.0999999, 0.300001] +[0.1, 0.3] ``` The `DecoratedInterval` constructor may also be used if necessary: -``` +```jldoctest decorations julia> X = DecoratedInterval(3, 4) [3, 4] ``` By default, decorations are not displayed. The following turns on display of decorations: -``` +```jldoctest decorations julia> setformat(decorations=true) +6 julia> X [3, 4]_com @@ -66,7 +56,7 @@ If no decoration is explicitly specified when a `DecoratedInterval` is created, An explicit decoration may be provided for advanced use: -``` +```jldoctest decorations julia> DecoratedInterval(3, 4, dac) [3, 4]_dac @@ -79,7 +69,7 @@ Here, a new `DecoratedInterval` was created by extracting the interval from anot A decoration is the combination of an interval together with the sequence of functions that it has passed through. Here are some examples: -``` +```jldoctest decorations julia> X1 = @decorated(0.5, 3) [0.5, 3]_com @@ -88,7 +78,7 @@ julia> sqrt(X1) ``` In this case, both input and output are "common" intervals, meaning that they are closed and bounded, and that the resulting function is continuous over the input interval, so that fixed-point theorems may be applied. Since `sqrt(X1) ⊆ X1`, we know that there must be a fixed point of the function inside the interval `X1` (in this case, `sqrt(1) == 1`). -``` +```jldoctest decorations julia> X2 = DecoratedInterval(3, ∞) [3, ∞]_dac @@ -97,7 +87,7 @@ julia> sqrt(X2) ``` Since the intervals are unbounded here, the maximum decoration possible is `dac`. -``` +```jldoctest decorations julia> X3 = @decorated(-3, 4) [-3, 4]_com @@ -106,9 +96,9 @@ julia> sign(X3) ``` The `sign` function is discontinuous at 0, but is defined everywhere on the input interval, so the decoration is `def`. -``` +```jldoctest decorations julia> X4 = @decorated(-3.5, 4.1) -[-3.5, 4.10001]_com +[-3.5, 4.1]_com julia> sqrt(X4) [0, 2.02485]_trv @@ -118,7 +108,7 @@ The negative part of `X` is discarded by the `sqrt` function, since its domain i In this case, we know why the decoration was reduced to `trv`. But if this were just a single step in a longer calculation, a resulting `trv` decoration shows only that something like this happened *at some step*. For example: -``` +```jldoctest decorations julia> X5 = @decorated(-3, 3) [-3, 3]_com @@ -133,7 +123,7 @@ julia> asin(sqrt(X6)) ``` In both cases, `asin(sqrt(X))` gives a result with a `trv` decoration, but we do not know at which step this happened, unless we break down the function into its constituent parts: -``` +```jldoctest decorations julia> sqrt(X5) [0, 1.73206]_trv @@ -143,3 +133,7 @@ julia> sqrt(X6) This shows that loose evaluation occurred in different parts of the expression in the two different cases. In general, the `trv` decoration is thus used only to signal that "something unexpected" happened during the calculation. Often this is later used to split up the original interval into pieces and reevaluate the function on each piece to refine the information that is obtained about the function. + +```@meta +DocTestSetup = nothing +``` diff --git a/docs/index.md b/docs/src/index.md similarity index 77% rename from docs/index.md rename to docs/src/index.md index fe1cb32da..38782e8dd 100644 --- a/docs/index.md +++ b/docs/src/index.md @@ -2,48 +2,50 @@ `IntervalArithmetic.jl` is a Julia package for performing *Validated Numerics* in Julia, i.e. *rigorous* computations with finite-precision floating-point arithmetic. -## Installation -To install the package, from within Julia do +All calculations are carried out using **interval arithmetic**: all quantities are treated as intervals, which are propagated throughout a calculation. The final result is an interval that is *guaranteed* to contain the correct result, starting from the given initial data. - julia> Pkg.add("IntervalArithmetic") +The aim of the package is correctness over speed, although performance considerations are also taken into account. -## Interval arithmetic -All calculations are carried out using **interval arithmetic**: all quantities are treated as intervals, which are propagated throughout a calculation. The final result is an interval that is *guaranteed* to contain the correct result, starting from the given initial data. +### Authors +- [Luis Benet](http://www.cicc.unam.mx/~benet/), Instituto de Ciencias Físicas, Universidad Nacional Autónoma de México (UNAM) +- [David P. Sanders](http://sistemas.fciencias.unam.mx/~dsanders), Departamento de Física, Facultad de Ciencias, Universidad Nacional Autónoma de México (UNAM) + +### Contributors +- Oliver Heimlich +- Nikolay Kryukov +- John Verzani + -The aim of the package is correctness over speed, although performance considerations are also taken into account +## Installation +To install the package, from within Julia do + +```julia +julia> Pkg.add("IntervalArithmetic") +``` -## Contents: -- [Basic usage](usage.md) -- [Multi-dimensional](multidim.md) -- [Rounding](rounding.md) -- [Decorations](decorations.md) +## Contents + +```@contents +Pages = ["usage.md", + "decorations.md", + "multidim.md", + "rounding.md"] +``` ## Bibliography - *Validated Numerics: A Short Introduction to Rigorous Computations*, W. Tucker, Princeton University Press (2010) - *Introduction to Interval Analysis*, R.E. Moore, R.B. Kearfott & M.J. Cloud, SIAM (2009) -## Related packages +### Related packages - [MPFI.jl](https://github.com/andrioni/MPFI.jl), a Julia wrapper around the [MPFI C library](http://perso.ens-lyon.fr/nathalie.revol/software.html), a multiple-precision interval arithmetic library based on MPFR - [Intervals.jl](https://github.com/andrioni/Intervals.jl), an alternative implementation of basic interval functions. -- [Unums.jl](https://github.com/JuliaComputing/Unums.jl), an implementation of interval -arithmetic with variable precision ("ubounds") - -## Authors -- [Luis Benet](http://www.cicc.unam.mx/~benet/), Instituto de Ciencias Físicas, -Universidad Nacional Autónoma de México (UNAM) -- [David P. Sanders](http://sistemas.fciencias.unam.mx/~dsanders), -Departamento de Física, Facultad de Ciencias, Universidad Nacional Autónoma de México (UNAM) - -## Contributors -- Oliver Heimlich -- Nikolay Kryukov -- John Verzani +- [Unums.jl](https://github.com/JuliaComputing/Unums.jl), an implementation of interval arithmetic with variable precision ("ubounds") ## Acknowledgements ## This project was developed in a masters' course in the postgraduate programs in Physics and in Mathematics at UNAM during the second semester of 2013 and the first semester of 2015. We thank the participants of the courses for putting up with the half-baked material and contributing energy and ideas. -Financial support is acknowledged from DGAPA-UNAM PAPIME grants PE-105911 and PE-107114, and DGAPA-UNAM PAPIIT grant IN-117214. LB acknowledges support through a *Cátedra Moshinsky* (2013). +Financial support is acknowledged from DGAPA-UNAM PAPIME grants PE-105911 and PE-107114, and DGAPA-UNAM PAPIIT grant IN-117214. LB acknowledges support through a *Cátedra Marcos Moshinsky* (2013). DPS acknowledges a sabbatical fellowship from CONACYT and thanks Alan Edelman and the Julia group at MIT for hosting his sabbatical visit. diff --git a/docs/multidim.md b/docs/src/multidim.md similarity index 87% rename from docs/multidim.md rename to docs/src/multidim.md index c1c8f047a..a6d80a620 100644 --- a/docs/multidim.md +++ b/docs/src/multidim.md @@ -1,3 +1,9 @@ +```@meta +DocTestSetup = quote + using IntervalArithmetic +end +``` + # Multi-dimensional boxes Starting with v0.3, multi-dimensional (hyper-)boxes are implemented in the @@ -8,7 +14,7 @@ cuboids (in 3D), etc. `IntervalBox`es are constructed from an array of `Interval`s; it is often convenient to use the `..` notation: -```julia +```jldoctest julia> X = IntervalBox(1..3, 2..4) [1, 3] × [2, 4] @@ -30,19 +36,23 @@ To facilitate working with `IntervalBox`es, a macro `@intervalbox` is defined. Given a multi-dimensional function taking several inputs, this creates both the original form and a version that works with a single `IntervalBox` argument, e.g. -```julia +```jldoctest julia> @intervalbox f(x, y) = (x + y, x - y) f (generic function with 2 methods) julia> f(1..1, 2..2) -([3.0, 3.0],[-1.0, -1.0]) +([3, 3],[-1, -1]) julia> X = IntervalBox(1..1, 2..2) -[1.0, 1.0] × [2.0, 2.0] +[1, 1] × [2, 2] julia> f(X) -[3.0, 3.0] × [-1.0, -1.0] +[3, 3] × [-1, -1] ``` The first version takes a tuple of `Interval`s and returns another tuple of `Interval`s; the second version takes a single `IntervalBox` and automatically does the necessary unpacking and packing to return an `IntervalBox.` + +```@meta +DocTestSetup = nothing +``` diff --git a/docs/rounding.md b/docs/src/rounding.md similarity index 93% rename from docs/rounding.md rename to docs/src/rounding.md index 01d6b24d5..dc548570f 100644 --- a/docs/rounding.md +++ b/docs/src/rounding.md @@ -1,7 +1,7 @@ # Why is rounding necessary? What happens when we write the following Julia code? -``` +```jldoctest julia> x = 0.1 0.1 ``` @@ -11,7 +11,7 @@ In fact, however, it stores a *slightly different* number, since `0.1` *cannot b The true value that is actually stored in the variable can be conveniently determined in Julia using arbitrary-precision arithmetic with `BigFloat`s: -``` +```jldoctest julia> big(0.1) 1.000000000000000055511151231257827021181583404541015625000000000000000000000000e-01 ``` @@ -20,14 +20,16 @@ So, in fact, the Julia float `0.1` refers to a real number that is slightly grea [Recall that to get a `BigFloat` that is as close as possible to the true 0.1, you can use a special string macro: -``` +```jldoctest julia> big"0.1" 1.000000000000000000000000000000000000000000000000000000000000000000000000000002e-01 ``` ] Suppose that we create a thin interval, containing just the floating-point number `0.1`: -``` +```jldoctest rounding +julia> using IntervalArithmetic + julia> II = Interval(0.1) [0.1, 0.100001] @@ -39,18 +41,21 @@ It looks like `II` contains (the true) 0.1, but from the above discussion we see This rounding is handled by the `@interval` macro, which generates correctly-rounded intervals: -```julia +```jldoctest rounding julia> a = @interval(0.1) [0.0999999, 0.100001] + ``` The true 0.1 is now correctly contained in the intervals, so that any calculations on these intervals will contain the true result of calculating with 0.1. For example, if we define -```julia +```jldoctest rounding julia> f(x) = 2x + 0.2 +f (generic function with 1 method) + ``` then we can apply the function `f` to the interval `a` to obtain -```julia +```jldoctest rounding julia> f(a) [0.399999, 0.400001] @@ -62,7 +67,7 @@ The result correctly contains the true 0.4. ## More detail: the internal representation Let's look at the internal representation of the `Float64` number 0.1: -```julia +```jldoctest julia> bits(0.1) "0011111110111001100110011001100110011001100110011001100110011010" ``` diff --git a/docs/usage.md b/docs/src/usage.md similarity index 92% rename from docs/usage.md rename to docs/src/usage.md index 468a1e790..02f593545 100644 --- a/docs/usage.md +++ b/docs/src/usage.md @@ -1,45 +1,30 @@ - - - # Basic usage The basic elements of the package are **intervals**, i.e. sets of real numbers (possibly including $\pm \infty$) of the form -$$[a, b] := \{ a \le x \le b \} \subseteq \mathbb{R}.$$ +```math +[a, b] := \{ a \le x \le b \} \subseteq \mathbb{R}. +``` ## Creating intervals Intervals are created using the `@interval` macro, which takes one or two expressions: -``` +```jldoctest usage julia> using IntervalArithmetic julia> a = @interval(1) [1, 1] julia> typeof(ans) -Interval{Float64} (constructor with 1 method) +IntervalArithmetic.Interval{Float64} julia> b = @interval(1, 2) [1, 2] ``` -These return objects of the parametrised type `Interval`, the basic object in the package. +The objects returned are of the parameterized type `Interval`, the basic object in the package. By default, `Interval` objects contain `Float64`s, but the library also allows using `BigFloat`s, for example: -``` +```jldoctest usage julia> @biginterval(1, 2) [1, 2]₂₅₆ @@ -49,7 +34,7 @@ Interval(1.000000000000000000000000000000000000000000000000000000000000000000000 The constructor of the `Interval` type may be used directly, but this is generally not recommended, for the following reason: -``` +```jldoctest usage julia> a = Interval(0.1, 0.3) [0.1, 0.3] @@ -61,7 +46,9 @@ What is going on here? Due to the way floating-point arithmetic works, the interval `a` created directly by the constructor turns out to contain -*neither the true real number 0.1, nor 0.3*. +*neither the true real number 0.1, nor 0.3*, since the floating point +number associated to 0.1 is actually rounded up, whereas the +one associated to 0.3 is rounded down. The `@interval` macro, however, uses [**directed rounding**](rounding.md) to *guarantee* that the true 0.1 and 0.3 are included in the result. @@ -70,35 +57,36 @@ function. This allows us to write, for example -``` +```jldoctest usage julia> @interval sin(0.1) + cos(0.2) [1.07989, 1.0799] ``` which is equivalent to -``` +```jldoctest usage julia> sin(@interval(0.1)) + cos(@interval(0.2)) [1.07989, 1.0799] ``` This can be used together with user-defined functions: -``` +```jldoctest usage julia> f(x) = 2x f (generic function with 1 method) julia> f(@interval(0.1)) [0.199999, 0.200001] + julia> @interval f(0.1) [0.199999, 0.200001] ``` ### $\pi$ You can create correctly-rounded intervals containing $\pi$: -``` +```jldoctest usage julia> @interval(pi) [3.14159, 3.1416] ``` and embed it in expressions: -``` +```jldoctest usage julia> @interval(3*pi/2 + 1) [5.71238, 5.71239] @@ -108,7 +96,7 @@ julia> @interval 3π/2 + 1 ## Constructing intervals Intervals may be constructed using rationals: -``` +```jldoctest usage julia> @interval(1//10) [0.0999999, 0.100001] ``` @@ -117,7 +105,7 @@ Real literals are handled by internally converting them to rationals (using the Julia function `rationalize`). This gives a result that contains the computer's "best guess" for the real number the user "had in mind": -``` +```jldoctest usage julia> @interval(0.1) [0.0999999, 0.100001] ``` @@ -125,7 +113,7 @@ If you instead know which exactly-representable floating-point number $a$ you ne want to make a *thin interval*, i.e., an interval of the form $[a, a]$, containing precisely one float, then you can use the `Interval` constructor directly: -``` +```jldoctest usage julia> a = Interval(0.1) [0.1, 0.100001] @@ -138,7 +126,7 @@ internal function (which, in turn, uses the so-called Grisu algorithm) to show exactly as many digits are required to give an unambiguous floating-point number. Strings may be used inside `@interval`: -``` +```jldoctest usage julia> @interval "0.1"*2 [0.199999, 0.200001] @@ -151,13 +139,13 @@ Interval(1.999999999999999999999999999999999999999999999999999999999999999999999 ``` Strings in the form of intervals may also be used: -``` +```jldoctest usage julia> @interval "[1.2, 3.4]" [1.19999, 3.40001] ``` Intervals can be created from variables: -``` +```jldoctest usage julia> a = 3.6 3.6 @@ -167,7 +155,7 @@ julia> b = @interval(a) The upper and lower bounds of the interval may be accessed using the fields `lo` and `hi`: -``` +```jldoctest usage julia> b.lo 3.5999999999999996 @@ -180,7 +168,7 @@ for numbers that cannot be represented exactly in base 2 (i.e., whose *binary* expansion is infinite or exceeds the current precision), the diameter of intervals created by `@interval` with a single argument corresponds to the local machine epsilon (`eps`) in the `:narrow` interval-rounding mode: -``` + ```jldoctest usage julia> diam(b) 4.440892098500626e-16 @@ -190,12 +178,12 @@ julia> eps(b.lo) Starting with v0.3, you can use additional syntax for creating intervals more easily: the `..` operator, -``` +```jldoctest usage julia> 0.1..0.3 [0.0999999, 0.300001] ``` and the `@I_str` string macro: -``` +```jldoctest usage julia> I"3.1" [3.09999, 3.10001] @@ -204,7 +192,7 @@ julia> I"[3.1, 3.2]" ``` From v0.4, you can also use the `±` operator: -``` +```jldoctest usage julia> 1.5 ± 0.1 [1.39999, 1.60001] ``` @@ -216,7 +204,7 @@ Basic arithmetic operations (`+`, `-`, `*`, `/`, `^`) are defined for pairs of i $$X \circ Y := \{ x \circ y: x \in X \text{ and } y \in Y \}.$$ Again, directed rounding is used if necessary. For example: -``` +```jldoctest usage julia> a = @interval(0.1, 0.3) [0.0999999, 0.300001] @@ -228,7 +216,7 @@ julia> a + b ``` However, subtraction of two intervals gives an initially unexpected result, due to the above definition: -``` +```jldoctest usage julia> a = @interval(0, 1) [0, 1] @@ -241,12 +229,13 @@ julia> a - a By default, the `@interval` macro creates intervals of `Float64`s. This may be changed globally using the `setprecision` function: -``` +```jldoctest usage julia> @interval 3π/2 + 1 [5.71238, 5.71239] julia> showall(ans) Interval(5.71238898038469, 5.712388980384691) + julia> setprecision(Interval, 256) 256 @@ -259,7 +248,7 @@ Interval(5.712388980384689857693965074919254326295754099062658731462416888461724 The subscript `256` at the end denotes the precision. To change back to `Float64`s, use -``` +```jldoctest usage julia> setprecision(Interval, Float64) Float64 @@ -268,7 +257,7 @@ julia> @interval(pi) ``` To check which mode is currently set, use -``` +```jldoctest usage julia> precision(Interval) (Float64,256) ``` diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index b701250bc..000000000 --- a/mkdocs.yml +++ /dev/null @@ -1,18 +0,0 @@ -site_name: 'IntervalArithmetic.jl' - -site_description: 'IntervalArithmetic.jl: A Julia package for interval arithmetic' - -repo_url: https://github.com/JuliaIntervals/IntervalArithmetic.jl - -pages: - - 'Package': 'index.md' - - 'Basic usage': 'usage.md' - - 'Multi-dimensional': 'multidim.md' - - 'Rounding': 'rounding.md' - - 'Decorations': 'decorations.md' - -#theme: readthedocs - -#markdown_extensions: [math] - -copyright: Copyright © 2014-2017, Luis Benet & David P. Sanders From 86cf27bf3a8a8a88748808e8d150cbd2c1fe80d3 Mon Sep 17 00:00:00 2001 From: Luis Benet Date: Sun, 14 May 2017 21:09:09 -0500 Subject: [PATCH 2/5] Fix badges and small changes (mainly reordering) --- README.md | 52 +++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 62fe4a46f..15dc1346d 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,41 @@ # IntervalArithmetic.jl # -[![Build Status](https://travis-ci.org/JuliaIntervals/IntervalArithmetic.jl.svg?branch=master)](https://travis-ci.org/dpsanders/IntervalArithmetic.jl) +[![Build Status](https://travis-ci.org/JuliaIntervals/IntervalArithmetic.jl.svg?branch=master)](https://travis-ci.org/JuliaIntervals/IntervalArithmetic.jl) [![Coverage Status](https://coveralls.io/repos/JuliaIntervals/IntervalArithmetic.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/JuliaIntervals/IntervalArithmetic.jl?branch=master) -[![codecov]( -https://codecov.io/gh/JuliaIntervals/IntervalArithmetic.jl/branch/master/graph/badge.svg)] -(https://codecov.io/gh/JuliaIntervals/IntervalArithmetic.jl) +[![codecov](https://codecov.io/gh/JuliaIntervals/IntervalArithmetic.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaIntervals/IntervalArithmetic.jl) + [![Join the chat at https://gitter.im/JuliaIntervals/IntervalArithmetic.jl](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JuliaIntervals/IntervalArithmetic.jl?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) `IntervalArithmetic.jl` is a Julia package for performing *Validated Numerics* in Julia, i.e. *rigorous* computations with finite-precision floating-point arithmetic. +All calculations are carried out using **interval arithmetic**: all quantities are treated as intervals, which are propagated throughout a calculation. The final result is an interval that is *guaranteed* to contain the correct result, starting from the given initial data. +The aim of the package is correctness over speed, although performance considerations are also taken into account. -## Installation -To install the package, from within Julia do - julia> Pkg.add("IntervalArithmetic") +### Authors +- [Luis Benet](http://www.cicc.unam.mx/~benet/), Instituto de Ciencias Físicas, Universidad Nacional Autónoma de México (UNAM) +- [David P. Sanders](http://sistemas.fciencias.unam.mx/~dsanders), Departamento de Física, Facultad de Ciencias, Universidad Nacional Autónoma de México (UNAM) +### Contributors +- Oliver Heimlich +- Nikolay Kryukov +- John Verzani -## Interval arithmetic -All calculations are carried out using **interval arithmetic**: all quantities are treated as intervals, which are propagated throughout a calculation. The final result is an interval that is *guaranteed* to contain the correct result, starting from the given initial data. -The aim of the package is correctness over speed, although performance considerations are also taken into account +## Installation +To install the package, from within Julia do + +```julia +julia> Pkg.add("IntervalArithmetic") +``` ## Documentation -Documentation is available [**here**](https://juliaintervals.github.io/IntervalArithmetic.jl/). -## IEEE Standard 1788-2015 - IEEE Standard for Interval Arithmetic +Documentation is available [here](https://juliaintervals.github.io/IntervalArithmetic.jl/). + +## Standard for Interval Arithmetic: IEEE 1788-2015 + The IEEE Std 1788-2015 - IEEE Standard for Interval Arithmetic was [published](https://standards.ieee.org/findstds/standard/1788-2015.html) in June 2015. We are working towards having `IntervalArithmetic.jl` be conformant with this standard. To do so, we have incorporated tests from the excellent [ITF1788 test suite](https://github.com/oheim/ITF1788), originally written by Marco Nehmeier and Maximilian Kiesner, and converted to a common format and to output tests for Julia by Oliver Heimlich. @@ -35,20 +45,10 @@ To do so, we have incorporated tests from the excellent [ITF1788 test suite](htt - *Validated Numerics: A Short Introduction to Rigorous Computations*, W. Tucker, Princeton University Press (2010) - *Introduction to Interval Analysis*, R.E. Moore, R.B. Kearfott & M.J. Cloud, SIAM (2009) -## Related packages +### Related packages - [MPFI.jl](https://github.com/andrioni/MPFI.jl), a Julia wrapper around the [MPFI C library](http://perso.ens-lyon.fr/nathalie.revol/software.html), a multiple-precision interval arithmetic library based on MPFR - [Intervals.jl](https://github.com/andrioni/Intervals.jl), an alternative implementation of basic interval functions. - -## Authors -- [Luis Benet](http://www.cicc.unam.mx/~benet/), Instituto de Ciencias Físicas, -Universidad Nacional Autónoma de México (UNAM) -- [David P. Sanders](http://sistemas.fciencias.unam.mx/~dsanders), -Departamento de Física, Facultad de Ciencias, Universidad Nacional Autónoma de México (UNAM) - -## Contributors -- Oliver Heimlich -- Nikolay Kryukov -- John Verzani +- [Unums.jl](https://github.com/JuliaComputing/Unums.jl), an implementation of interval arithmetic with variable precision ("ubounds") ## History ## @@ -56,5 +56,7 @@ This project was begun during a masters' course in the postgraduate programs in ## Acknowledgements ## +This project was developed in a masters' course in the postgraduate programs in Physics and in Mathematics at UNAM during the second semester of 2013 and the first semester of 2015. We thank the participants of the courses for putting up with the half-baked material and contributing energy and ideas. -Financial support is acknowledged from DGAPA-UNAM PAPIME grants PE-105911 and PE-107114, and DGAPA-UNAM PAPIIT grants IN-117214 and IN-117117. LB acknowledges support through a *Cátedra Moshinsky* (2013). +Financial support is acknowledged from DGAPA-UNAM PAPIME grants PE-105911 and PE-107114, and DGAPA-UNAM PAPIIT grant IN-117214. LB acknowledges support through a *Cátedra Marcos Moshinsky* (2013). +DPS acknowledges a sabbatical fellowship from CONACYT and thanks Alan Edelman and the Julia group at MIT for hosting his sabbatical visit. From ca454be34d2ab999d5f6371e7141f8b35d6e173c Mon Sep 17 00:00:00 2001 From: Luis Benet Date: Mon, 15 May 2017 08:42:01 -0500 Subject: [PATCH 3/5] Add api.md with autogenerated docstrings --- docs/make.jl | 3 ++- docs/src/api.md | 18 ++++++++++++++++++ docs/src/index.md | 4 +++- 3 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 docs/src/api.md diff --git a/docs/make.jl b/docs/make.jl index e8e47fb6d..e8f3661da 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -9,7 +9,8 @@ makedocs( "Basic usage" => "usage.md", "Decorations" => "decorations.md", "Multi-dimensional boxes" => "multidim.md", - "Rounding" => "rounding.md" + "Rounding" => "rounding.md", + "API" => "api.md" ] ) diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 000000000..76b3b24cb --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,18 @@ +```@meta +DocTestSetup = quote + using IntervalArithmetic +end +``` + +# API + +```@index +Pages = ["api.md"] +Module = [IntervalArithmetic] +Order = [:type, :macro, :function, :constant] +``` + +```@autodocs +Modules = [IntervalArithmetic] +Order = [:type, :macro, :function, :constant] +``` diff --git a/docs/src/index.md b/docs/src/index.md index 38782e8dd..5d078cfd5 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -30,7 +30,9 @@ julia> Pkg.add("IntervalArithmetic") Pages = ["usage.md", "decorations.md", "multidim.md", - "rounding.md"] + "rounding.md", + "api.md" + ] ``` ## Bibliography From 1f49eae0e66c12af518954ba4a042d151a291e5f Mon Sep 17 00:00:00 2001 From: Luis Benet Date: Mon, 15 May 2017 08:52:27 -0500 Subject: [PATCH 4/5] Remove mentioning `@intervalbox` from docs --- docs/src/multidim.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/docs/src/multidim.md b/docs/src/multidim.md index a6d80a620..f411bd223 100644 --- a/docs/src/multidim.md +++ b/docs/src/multidim.md @@ -14,7 +14,7 @@ cuboids (in 3D), etc. `IntervalBox`es are constructed from an array of `Interval`s; it is often convenient to use the `..` notation: -```jldoctest +```jldoctest multidim julia> X = IntervalBox(1..3, 2..4) [1, 3] × [2, 4] @@ -24,7 +24,7 @@ julia> Y = IntervalBox(2.1..2.9, 3.1..4.9) Several operations are defined on `IntervalBox`es, for example: -``` +```jldoctest multidim julia> X ∩ Y [2.09999, 2.90001] × [3.09999, 4] @@ -32,26 +32,21 @@ julia> X ⊆ Y false ``` -To facilitate working with `IntervalBox`es, a macro `@intervalbox` is defined. -Given a multi-dimensional function taking several inputs, this creates both the original form and a -version that works with a single `IntervalBox` argument, e.g. - -```jldoctest -julia> @intervalbox f(x, y) = (x + y, x - y) -f (generic function with 2 methods) +Given a multi-dimensional function taking several inputs, and interval box can be constructed as follows: -julia> f(1..1, 2..2) -([3, 3],[-1, -1]) +```jldoctest multidim +julia> f(x, y) = (x + y, x - y) +f (generic function with 1 method) julia> X = IntervalBox(1..1, 2..2) [1, 1] × [2, 2] -julia> f(X) +julia> f(X...) +([3, 3],[-1, -1]) + +julia> IntervalBox(f(X...)) [3, 3] × [-1, -1] ``` -The first version takes a tuple of `Interval`s and returns another tuple of `Interval`s; -the second version takes a single `IntervalBox` and automatically does the -necessary unpacking and packing to return an `IntervalBox.` ```@meta DocTestSetup = nothing From cb5d490c4fb701937bad985922a71196f1f745e2 Mon Sep 17 00:00:00 2001 From: Luis Benet Date: Mon, 15 May 2017 11:09:56 -0500 Subject: [PATCH 5/5] Add more jldoctests and amend the documentation --- docs/src/multidim.md | 8 ++--- docs/src/usage.md | 69 ++++++++++++++++++++++++++------------------ 2 files changed, 43 insertions(+), 34 deletions(-) diff --git a/docs/src/multidim.md b/docs/src/multidim.md index f411bd223..7542631f9 100644 --- a/docs/src/multidim.md +++ b/docs/src/multidim.md @@ -1,9 +1,3 @@ -```@meta -DocTestSetup = quote - using IntervalArithmetic -end -``` - # Multi-dimensional boxes Starting with v0.3, multi-dimensional (hyper-)boxes are implemented in the @@ -15,6 +9,8 @@ cuboids (in 3D), etc. often convenient to use the `..` notation: ```jldoctest multidim +julia> using IntervalArithmetic # hide + julia> X = IntervalBox(1..3, 2..4) [1, 3] × [2, 4] diff --git a/docs/src/usage.md b/docs/src/usage.md index 02f593545..4d441c610 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -1,13 +1,13 @@ # Basic usage -The basic elements of the package are **intervals**, i.e. sets of real numbers (possibly including $\pm \infty$) of the form +The basic elements of the package are **intervals**, i.e. sets of real numbers (possibly including `\pm \infty`) of the form ```math [a, b] := \{ a \le x \le b \} \subseteq \mathbb{R}. ``` ## Creating intervals -Intervals are created using the `@interval` macro, which takes one or two expressions: +Intervals are created using the [`@interval`](@ref) macro, which takes one or two expressions: ```jldoctest usage julia> using IntervalArithmetic @@ -22,8 +22,8 @@ julia> b = @interval(1, 2) ``` The objects returned are of the parameterized type `Interval`, the basic object in the package. -By default, `Interval` objects contain `Float64`s, but the library also allows using -`BigFloat`s, for example: +By default, `Interval` objects contain `Float64`s, but the library also allows using other types such as `Rational`s and +`BigFloat`s; for example: ```jldoctest usage julia> @biginterval(1, 2) [1, 2]₂₅₆ @@ -49,10 +49,10 @@ Due to the way floating-point arithmetic works, the interval *neither the true real number 0.1, nor 0.3*, since the floating point number associated to 0.1 is actually rounded up, whereas the one associated to 0.3 is rounded down. -The `@interval` macro, however, uses [**directed rounding**](rounding.md) to *guarantee* +The [`@interval`](@ref) macro, however, uses [**directed rounding**](rounding.md) to *guarantee* that the true 0.1 and 0.3 are included in the result. -Behind the scenes, the `@interval` macro rewrites the expression(s) passed to it, replacing the literals (0.1, 1, etc.) by calls to create correctly-rounded intervals, handled by the `convert` +Behind the scenes, the [`@interval`(@ref)] macro rewrites the expression(s) passed to it, replacing the literals (0.1, 1, etc.) by calls to create correctly-rounded intervals, handled by the `convert` function. This allows us to write, for example @@ -79,8 +79,8 @@ julia> @interval f(0.1) [0.199999, 0.200001] ``` -### $\pi$ -You can create correctly-rounded intervals containing $\pi$: +### `\pi` +You can create correctly-rounded intervals containing `\pi`: ```jldoctest usage julia> @interval(pi) [3.14159, 3.1416] @@ -109,8 +109,8 @@ the real number the user "had in mind": julia> @interval(0.1) [0.0999999, 0.100001] ``` -If you instead know which exactly-representable floating-point number $a$ you need and really -want to make a *thin interval*, i.e., an interval of the form $[a, a]$, +If you instead know which exactly-representable floating-point number `a` you need and really +want to make a *thin interval*, i.e., an interval of the form `[a, a]`, containing precisely one float, then you can use the `Interval` constructor directly: ```jldoctest usage @@ -125,7 +125,7 @@ in a reproducible form that may be copied and pasted directly. It uses Julia's internal function (which, in turn, uses the so-called Grisu algorithm) to show exactly as many digits are required to give an unambiguous floating-point number. -Strings may be used inside `@interval`: +Strings may be used inside [`@interval`](@ref): ```jldoctest usage julia> @interval "0.1"*2 [0.199999, 0.200001] @@ -163,10 +163,10 @@ julia> b.hi 3.6 ``` -The diameter (length) of an interval is obtained using `diam(b)`; +The diameter (length) of an interval is obtained using [`diam(b)`](@ref); for numbers that cannot be represented exactly in base 2 (i.e., whose *binary* expansion is infinite or exceeds the current precision), - the diameter of intervals created by `@interval` with a single argument corresponds to the local machine epsilon (`eps`) in the `:narrow` interval-rounding mode: + the diameter of intervals created by [`@interval`](@ref) with a single argument corresponds to the local machine epsilon (`eps`) in the `:narrow` interval-rounding mode: ```jldoctest usage julia> diam(b) @@ -200,8 +200,11 @@ julia> 1.5 ± 0.1 ## Arithmetic -Basic arithmetic operations (`+`, `-`, `*`, `/`, `^`) are defined for pairs of intervals in a standard way (see, e.g., the book by Tucker): the result is the smallest interval containing the result of operating with each element of each interval. That is, for two intervals $X$ and $Y$ and an operation $\circ$, we define the operation on the two intervals by -$$X \circ Y := \{ x \circ y: x \in X \text{ and } y \in Y \}.$$ Again, directed rounding is used if necessary. +Basic arithmetic operations (`+`, `-`, `*`, `/`, `^`) are defined for pairs of intervals in a standard way (see, e.g., the book by Tucker): the result is the smallest interval containing the result of operating with each element of each interval. That is, for two intervals `X` and `Y` and an operation `\bigcirc`, we define the operation on the two intervals by +```math +\bigcirc Y := \{ x \bigcirc y: x \in X \text{ and } y \in Y \}. +``` +Again, directed rounding is used if necessary. For example: ```jldoctest usage @@ -226,7 +229,8 @@ julia> a - a ## Changing the precision -By default, the `@interval` macro creates intervals of `Float64`s. + +By default, the [`@interval`](@ref) macro creates intervals of `Float64`s. This may be changed globally using the `setprecision` function: ```jldoctest usage @@ -296,7 +300,7 @@ intervals are converted to and from `BigFloat`; this implies a significant slow- Examples: -``` +```jldoctest usage julia> a = @interval(1) [1, 1] @@ -307,7 +311,7 @@ julia> cos(cosh(a)) [0.0277121, 0.0277122] ``` -``` +```jldoctest usage julia> setprecision(Interval, 53) 53 @@ -318,7 +322,7 @@ julia> @interval sin(0.1) + cos(0.2) [1.07989, 1.0799]₅₃ ``` -``` +```jldoctest usage julia> setprecision(Interval, 128) 128 @@ -328,22 +332,21 @@ julia> @interval sin(1) ## Interval rounding modes + By default, the directed rounding used corresponds to using the `RoundDown` and `RoundUp` rounding modes when performing calculations; this gives the narrowest resulting intervals, and is set by -``` -setrounding(Interval, :narrow) +```jldoctest usage +julia> setrounding(Interval, :correct) + ``` An alternative rounding method is to perform calculations using the (standard) `RoundNearest` rounding mode, and then widen the result by one machine epsilon in each direction using `prevfloat` and `nextfloat`. This is achived by ``` -setrounding(Interval, :wide) +julia> setrounding(Interval, :fast); + ``` It generally results in wider intervals, but seems to be significantly faster. -The current interval rounding mode may be obtained by -``` -rounding(Interval) -``` ## Display modes There are several useful output representations for intervals, some of which we have already touched on. The display is controlled globally by the `setformat` function, which has @@ -361,8 +364,12 @@ the following options, specified by keyword arguments (type `?setformat` to get - `decorations` (boolean): whether to show [decorations](decorations.md) or not -### Examples: -``` +### Examples + +```jldoctest usage +julia> setprecision(Interval, Float64) +Float64 + julia> a = @interval(1.1, pi) [1.09999, 3.1416] @@ -373,11 +380,13 @@ julia> a [1.099999999, 3.141592654] julia> setformat(:full) +10 julia> a Interval(1.0999999999999999, 3.1415926535897936) julia> setformat(:midpoint) +10 julia> a 2.120796327 ± 1.020796327 @@ -389,7 +398,11 @@ julia> a 2.121 ± 1.021 julia> setformat(:standard) +4 julia> a [1.099, 3.142] + +julia> setformat(:standard, sigfigs=6) +6 ```