diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 76ec60b1..9260d608 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-05T15:26:53","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-05T15:59:13","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/about/index.html b/dev/about/index.html index 530b0635..a5edd734 100644 --- a/dev/about/index.html +++ b/dev/about/index.html @@ -1,4 +1,4 @@ About · RangeEnclosures.jl
GitHub

About

This page contains some general information about this project, and recommendations about contributing.

Contributing

If you like this package, consider contributing! You can send bug reports (or fix them and send your code), add examples to the documentation, or propose new features.

Below some conventions that we follow when contributing to this package are detailed. For specific guidelines on documentation, see the Documentations Guidelines wiki.

Branches and pull requests (PR)

We use a standard pull request policy: You work in a private branch and eventually add a pull request, which is then reviewed by other programmers and merged into the master branch.

Each pull request should be pushed in a new branch with the name of the author followed by a descriptive name, e.g., mforets/my_feature. If the branch is associated to a previous discussion in one issue, we use the name of the issue for easier lookup, e.g., mforets/7.

Unit testing and continuous integration (CI)

This project is synchronized with GitHub Actions such that each PR gets tested before merging (and the build is automatically triggered after each new commit). For the maintainability of this project, it is important to make all unit tests pass.

To run the unit tests locally, you can do:

julia> using Pkg
 
-julia> Pkg.test("RangeEnclosures")

We also advise adding new unit tests when adding new features to ensure long-term support of your contributions.

Contributing to the documentation

New functions and types should be documented according to our guidelines directly in the source code.

You can view the source code documentation from inside the REPL by typing ? followed by the name of the type or function. For example, the following command will print the documentation of the enclose function:

julia> ?enclose

This documentation you are currently reading is written in Markdown, and it relies on Documenter.jl to produce the HTML layout. The sources for creating this documentation are found in docs/src. You can easily include the documentation that you wrote for your functions or types there (see the Documenter.jl guide or our sources for examples).

To generate the documentation locally, run make.jl, e.g., by executing the following command in the terminal:

$ julia --color=yes docs/make.jl

Credits

Core developers

The RangeEnclosures.jl library is maintained by (in alphabetic order):

Contributors

Huge thanks to all the contributors.

Acknowledgments

We are grateful to the following persons for enlightening discussions during the preparation of this package:

During Summer 2022, this project was financially supported by Google through the Google Summer of Code program. During Summer 2019, this project was financially supported by Julia through the Julia Season of Contributions program.

+julia> Pkg.test("RangeEnclosures")

We also advise adding new unit tests when adding new features to ensure long-term support of your contributions.

Contributing to the documentation

New functions and types should be documented according to our guidelines directly in the source code.

You can view the source code documentation from inside the REPL by typing ? followed by the name of the type or function. For example, the following command will print the documentation of the enclose function:

julia> ?enclose

This documentation you are currently reading is written in Markdown, and it relies on Documenter.jl to produce the HTML layout. The sources for creating this documentation are found in docs/src. You can easily include the documentation that you wrote for your functions or types there (see the Documenter.jl guide or our sources for examples).

To generate the documentation locally, run make.jl, e.g., by executing the following command in the terminal:

$ julia --color=yes docs/make.jl

Credits

Core developers

The RangeEnclosures.jl library is maintained by (in alphabetic order):

Contributors

Huge thanks to all the contributors.

Acknowledgments

We are grateful to the following persons for enlightening discussions during the preparation of this package:

During Summer 2022, this project was financially supported by Google through the Google Summer of Code program. During Summer 2019, this project was financially supported by Julia through the Julia Season of Contributions program.

diff --git a/dev/index.html b/dev/index.html index dae71f5c..6f5de7a0 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · RangeEnclosures.jl
GitHub

RangeEnclosures.jl

A Julia package to compute range enclosures of real-valued functions.

Features

  • Computation of lower and upper bounds of real-valued functions, either univariate or multivariate, over hyperrectangular (i.e. box shaped) domains.
  • The following solvers are always available (using the package IntervalArithmetic.jl):
    • NaturalEnclosure
    • MeanValueEnclosure
    • BranchAndBoundEnclosure
  • The following solvers are available upon loading other packages:

Quickstart

The package exports one single function, enclose, which receives a Julia function, a domain, and (optionally) a solver and additional options passed to the solver. See the README.md file for the basic usage, or consult the source code docstrings, either in the REPL or in the github repository source code

Library Outline

+Home · RangeEnclosures.jl
GitHub

RangeEnclosures.jl

A Julia package to compute range enclosures of real-valued functions.

Features

  • Computation of lower and upper bounds of real-valued functions, either univariate or multivariate, over hyperrectangular (i.e. box shaped) domains.
  • The following solvers are always available (using the package IntervalArithmetic.jl):
    • NaturalEnclosure
    • MeanValueEnclosure
    • BranchAndBoundEnclosure
  • The following solvers are available upon loading other packages:

Quickstart

The package exports one single function, enclose, which receives a Julia function, a domain, and (optionally) a solver and additional options passed to the solver. See the README.md file for the basic usage, or consult the source code docstrings, either in the REPL or in the github repository source code

Library Outline

diff --git a/dev/lib/methods/index.html b/dev/lib/methods/index.html index f2ab08ee..978b0e30 100644 --- a/dev/lib/methods/index.html +++ b/dev/lib/methods/index.html @@ -5,11 +5,11 @@ julia> enclose(x -> 1 - x^4 + x^5, 0..1, TaylorModelsEnclosure()) [0.8125, 1.09375]

A vector of solvers can be passed in the solver options. Then, the result is obtained by intersecting the range enclosure of each solver.

julia> enclose(x -> 1 - x^4 + x^5, 0..1, [TaylorModelsEnclosure(), NaturalEnclosure()])
 [0.8125, 1.09375]
-
source

Utility functions

RangeEnclosures.relative_precision — Function
relative_precision(x::Interval, xref::Interval)

Return the relative precision of an interval with respect to a reference interval.

Input

  • x – test interval
  • xref – reference interval

Output

Left and right relative precision (in %) computed as

  • rleft = (inf(xref) - inf(x)) / diam(xref) * 100%
  • rright = (sup(x) - sup(xright)) / diam(xref) * 100%

Examples

julia> xref = interval(-1.2, 4.6)
+
source

Utility functions

RangeEnclosures.relative_precision — Function
relative_precision(x::Interval, xref::Interval)

Return the relative precision of an interval with respect to a reference interval.

Input

  • x – test interval
  • xref – reference interval

Output

Left and right relative precision (in %) computed as

  • rleft = (inf(xref) - inf(x)) / diam(xref) * 100%
  • rright = (sup(x) - sup(xright)) / diam(xref) * 100%

Examples

julia> xref = interval(-1.2, 4.6)
 [-1.2, 4.6]
 
 julia> x = interval(-1.25, 7.45)
 [-1.25, 7.45001]
 
 julia> relative_precision(x, xref)
-(0.8620689655172422, 49.13793103448277)

Algorithm

This function measures the relative precision of the result in a more informative way than taking the scalar overestimation because it evaluates the precision of the lower and the upper bounds separately (cf. Eq. (20) in [1]).

[1] Althoff, Matthias, Dmitry Grebenyuk, and Niklas Kochdumper. Implementation of Taylor models in CORA 2018. Proc. of the 5th International Workshop on Applied Verification for Continuous and Hybrid Systems. 2018.

source
+(0.8620689655172422, 49.13793103448277)

Algorithm

This function measures the relative precision of the result in a more informative way than taking the scalar overestimation because it evaluates the precision of the lower and the upper bounds separately (cf. Eq. (20) in [1]).

[1] Althoff, Matthias, Dmitry Grebenyuk, and Niklas Kochdumper. Implementation of Taylor models in CORA 2018. Proc. of the 5th International Workshop on Applied Verification for Continuous and Hybrid Systems. 2018.

source diff --git a/dev/lib/types/index.html b/dev/lib/types/index.html index cc614543..1a77af89 100644 --- a/dev/lib/types/index.html +++ b/dev/lib/types/index.html @@ -1,24 +1,24 @@ -Types · RangeEnclosures.jl
GitHub

Types

This section describes systems types implemented in RangeEnclosures.jl.

RangeEnclosures.AffineArithmeticEnclosure — Type
AffineArithmeticEnclosure <: AbstractDirectRangeAlgorithm

Data type to bound the range of f over X using affine arithmetic. See AffineArithmetic.jl for more details.

Notes

To use this algorithm, you need to load AffineArithmetic.jl. Note also that AffineArithmetic.jl currently supports only arithmetic operations.

source
RangeEnclosures.BranchAndBoundEnclosure — Type
BranchAndBoundEnclosure <: AbstractIterativeRangeAlgorithm

Data type to bound the range of f over X using the branch and bound algorithm.

Fields

  • maxdepth (default 10): maximum depth of the search tree
  • tol (default 1e-3): tolerance to compute the range of the function

Algorithm

The algorithm evaluates a function f over an interval X. If the maximum depth is reached or the width of f(X) is below the tolerance, the algorithm returns the computed range; otherwise it bisects the interval/interval box.

The algorithm also looks at the sign of the derivative / gradient to see if the range can be computed directly. By default, the derivative / gradient is computed using ForwardDiff.jl, but a custom value can be passed via the df keyword argument to enclose.

Examples

julia> enclose(x -> -x^3/6 + 5x, 1..4, BranchAndBoundEnclosure())
+Types · RangeEnclosures.jl
GitHub
Types
This section describes systems types implemented in RangeEnclosures.jl.
RangeEnclosures.AffineArithmeticEnclosure — Type
AffineArithmeticEnclosure <: AbstractDirectRangeAlgorithm
Data type to bound the range of f over X using affine arithmetic. See AffineArithmetic.jl for more details.
Notes
To use this algorithm, you need to load AffineArithmetic.jl. Note also that AffineArithmetic.jl currently supports only arithmetic operations.
source
RangeEnclosures.BranchAndBoundEnclosure — Type
BranchAndBoundEnclosure <: AbstractIterativeRangeAlgorithm
Data type to bound the range of f over X using the branch and bound algorithm.
Fields
  • maxdepth (default 10): maximum depth of the search tree
  • tol (default 1e-3): tolerance to compute the range of the function
Algorithm
The algorithm evaluates a function f over an interval X. If the maximum depth is reached or the width of f(X) is below the tolerance, the algorithm returns the computed range; otherwise it bisects the interval/interval box.
The algorithm also looks at the sign of the derivative / gradient to see if the range can be computed directly. By default, the derivative / gradient is computed using ForwardDiff.jl, but a custom value can be passed via the df keyword argument to enclose.
Examples
julia> enclose(x -> -x^3/6 + 5x, 1..4, BranchAndBoundEnclosure())
 [4.83333, 10.5709]
 
 julia> enclose(x -> -x^3/6 + 5x, 1..4, BranchAndBoundEnclosure(tol=1e-2); df=x->-x^2/2+5)
-[4.83333, 10.5709]
source
RangeEnclosures.NaturalEnclosure — Type
NaturalEnclosure <: AbstractDirectRangeAlgorithm
Data type to bound the range of f over X using natural enclosure, i.e., to evaluate f(X) with interval arithmetic.
Examples
julia> enclose(x -> 1 - x^4 + x^5, 0..1, NaturalEnclosure())
-[0, 2]
source
RangeEnclosures.MeanValueEnclosure — Type
MeanValueEnclosure
Data type to bound the range of f over X using the mean value form, that is the range is bounded by the expression $f(Xc) + f'(X) * (X - Xc)$, where Xc is the midpoint of X and f' is the derivative of f (gradient in the multivariate case).
source
RangeEnclosures.MooreSkelboeEnclosure — Type
MooreSkelboeEnclosure{T} <: AbstractIterativeRangeAlgorithm
Data type to bound the range of f over X using the Moore-Skelboe algorithm, which rigorously computes the global minimum and maximum of the function. See IntervalOptimisation.jl for more details.
Fields
  • structure – (default: HeapedVector) the way in which vector elements                are kept arranged; possible options are HeapedVector and SortedVector
  • tol       – (default 1e-3) tolerance to which the optima are computed
Notes
To use this algorithm, you need to load IntervalOptimisation.jl.
Examples
julia> using IntervalOptimisation
+[4.83333, 10.5709]
source
RangeEnclosures.NaturalEnclosure — Type
NaturalEnclosure <: AbstractDirectRangeAlgorithm
Data type to bound the range of f over X using natural enclosure, i.e., to evaluate f(X) with interval arithmetic.
Examples
julia> enclose(x -> 1 - x^4 + x^5, 0..1, NaturalEnclosure())
+[0, 2]
source
RangeEnclosures.MeanValueEnclosure — Type
MeanValueEnclosure
Data type to bound the range of f over X using the mean value form, that is the range is bounded by the expression $f(Xc) + f'(X) * (X - Xc)$, where Xc is the midpoint of X and f' is the derivative of f (gradient in the multivariate case).
source
RangeEnclosures.MooreSkelboeEnclosure — Type
MooreSkelboeEnclosure{T} <: AbstractIterativeRangeAlgorithm
Data type to bound the range of f over X using the Moore-Skelboe algorithm, which rigorously computes the global minimum and maximum of the function. See IntervalOptimisation.jl for more details.
Fields
  • structure – (default: HeapedVector) the way in which vector elements                are kept arranged; possible options are HeapedVector and SortedVector
  • tol       – (default 1e-3) tolerance to which the optima are computed
Notes
To use this algorithm, you need to load IntervalOptimisation.jl.
Examples
julia> using IntervalOptimisation
 
 julia> enclose(x -> 1 - x^4 + x^5, 0..1, MooreSkelboeEnclosure()) # default parameters
 [0.916034, 1.00213]
 
 julia> enclose(x -> 1 - x^4 + x^5, 0..1, MooreSkelboeEnclosure(; tol=1e-2))
-[0.900812, 1.0326]
source
RangeEnclosures.SumOfSquaresEnclosure — Type
SumOfSquaresEnclosure{T} <: AbstractIterativeRangeAlgorithm
Data type to bound the range of f over X using sum-of-squares optimization. See SumOfSquares.jl for more details
Fields
  • backend – backend used to solve the optimization problem; a list of available backends            can be found here
  • order – (default 5), maximum degree of the SDP relaxation
Notes
To use this solver, you need to load SumOfSquares.jl and a backend.
Since the optimization problem is solved numerically and not with interval arithmetic, the result of this algorithm is not rigorous.
Examples
julia> using SumOfSquares, SDPA, DynamicPolynomials
+[0.900812, 1.0326]
source
RangeEnclosures.SumOfSquaresEnclosure — Type
SumOfSquaresEnclosure{T} <: AbstractIterativeRangeAlgorithm
Data type to bound the range of f over X using sum-of-squares optimization. See SumOfSquares.jl for more details
Fields
  • backend – backend used to solve the optimization problem; a list of available backends            can be found here
  • order – (default 5), maximum degree of the SDP relaxation
Notes
To use this solver, you need to load SumOfSquares.jl and a backend.
Since the optimization problem is solved numerically and not with interval arithmetic, the result of this algorithm is not rigorous.
Examples
julia> using SumOfSquares, SDPA, DynamicPolynomials
 
 julia> backend = SDPA.Optimizer;
 
 julia> @polyvar x;
 
 julia> enclose(-x^3/6 + 5x, 1..4, SumOfSquaresEnclosure(; backend=backend))
-[4.83333, 10.541]
source
RangeEnclosures.TaylorModelsEnclosure — Type
TaylorModelsEnclosure <: AbstractDirectRangeAlgorithm
Data type to bound the range of f over X using Taylor models. See TaylorModels.jl for more details.
Fields
  • order     – (default: 10) order of the Taylor model used to compute                an enclosure of f over dom
  • normalize – (default: true) if true, normalize the Taylor model                on the unit symmetric box around the origin
Notes
To use this solver, you need to load TaylorModels.jl and a backend.
Examples
julia> enclose(x -> 1 - x^4 + x^5, 0..1, TaylorModelsEnclosure()) # default parameters
+[4.83333, 10.541]
source
RangeEnclosures.TaylorModelsEnclosure — Type
TaylorModelsEnclosure <: AbstractDirectRangeAlgorithm
Data type to bound the range of f over X using Taylor models. See TaylorModels.jl for more details.
Fields
  • order     – (default: 10) order of the Taylor model used to compute                an enclosure of f over dom
  • normalize – (default: true) if true, normalize the Taylor model                on the unit symmetric box around the origin
Notes
To use this solver, you need to load TaylorModels.jl and a backend.
Examples
julia> enclose(x -> 1 - x^4 + x^5, 0..1, TaylorModelsEnclosure()) # default parameters
 [0.8125, 1.09375]
 
 julia> enclose(x -> 1 - x^4 + x^5, 0..1, TaylorModelsEnclosure(; order=4))
-[0.78125, 1.125]
source

+[0.78125, 1.125]
source
diff --git a/dev/tutorial/index.html b/dev/tutorial/index.html index 838687ba..ca1b3113 100644 --- a/dev/tutorial/index.html +++ b/dev/tutorial/index.html @@ -31,4 +31,4 @@ D::Union{Interval,IntervalBox}, solver::MyEnclosure; kwargs...) # solver-specific implementation -end

Note that the domain D can be of type Interval for univariate ($n = 1$) functions or of type IntervalBox for multivariate ($n > 1$) functions.

+end

Note that the domain D can be of type Interval for univariate ($n = 1$) functions or of type IntervalBox for multivariate ($n > 1$) functions.