Merge branch 'master' into IA_v0.22

LICENSE.md

@@ -1,22 +1,25 @@
-The IntervalRootFinding.jl.jl package is licensed under the MIT "Expat" License:
-
-> Copyright (c) 2014-2021: Luis Benet & David P. Sanders
->
-> Permission is hereby granted, free of charge, to any person obtaining a copy
-> of this software and associated documentation files (the "Software"), to deal
-> in the Software without restriction, including without limitation the rights
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-> copies of the Software, and to permit persons to whom the Software is
-> furnished to do so, subject to the following conditions:
->
-> The above copyright notice and this permission notice shall be included in all
-> copies or substantial portions of the Software.
->
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-> SOFTWARE.
->
+MIT License
+
+Copyright (c) 2014 David P. Sanders and Luis Benet
+Copyright (c) 2024 Benoît Richard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
+The code is implemented in Julia, also licensed under the MIT license:
+
+Copyright (c) 2009 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors:
+https://github.com/JuliaLang/julia/contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,71 +1,50 @@
-# IntervalRootFinding.jl
+<h1 align="center">
+IntervalRootFinding
 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliaintervals.github.io/IntervalRootFinding.jl/stable)
 [![Build Status](https://github.com/JuliaIntervals/IntervalRootFinding.jl/workflows/CI/badge.svg)](https://github.com/JuliaIntervals/IntervalRootFinding.jl/actions/workflows/CI.yml)
-
 [![coverage](https://codecov.io/gh/JuliaIntervals/IntervalRootFinding.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaIntervals/IntervalRootFinding.jl)
+</h1>
 
-[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliaintervals.github.io/IntervalRootFinding.jl/latest/)
+IntervalRootFinding.jl is a Julia package for finding the roots of functions, i.e. solutions to the equation $f(x) = 0$.
+To do so, it uses interval arithmetic from the [IntervalArithmetic](https://github.com/JuliaIntervals/IntervalArithmetic.jl) library.
 
-This package provides guaranteed methods for finding **roots** of functions, i.e. solutions to the equation `f(x) == 0` for a function `f`.
-To do so, it uses methods from interval analysis, using interval arithmetic from the [`IntervalArithmetic.jl`](https://github.com/JuliaIntervals/IntervalArithmetic.jl) package by the same authors.
+## Documentation
 
-## Basic usage examples
+The official documentation is available online: https://juliaintervals.github.io/IntervalRootFinding.jl/stable.
 
-The basic function is `roots`. A standard Julia function and an interval is provided and the `roots` function return a list of intervals containing *all* roots of the function located in the starting interval.
+## Installation
 
-```jl
-julia> using IntervalArithmetic, IntervalArithmetic.Symbols, IntervalRootFinding
+The IntervalRootFinding.jl package requires to [install Julia](https://julialang.org/downloads/).
 
-julia> f(x) = sin(x) - 0.1*x^2 + 1
-f (generic function with 1 method)
+Then, start Julia and execute the following command in the REPL:
 
-julia> roots(f, -10..10)
-4-element Vector{Root{Interval{Float64}}}:
- Root([-4.42654, -4.42653]_com_NG, :unique)
- Root([-3.10682, -3.10681]_com_NG, :unique)
- Root([-1.08205, -1.08204]_com_NG, :unique)
- Root([3.14959, 3.1496]_com_NG, :unique)
+```julia
+using Pkg; Pkg.add("IntervalRootFinding")
 ```
 
-The `:unique` status tell us, in addition, that each listed region contains exactly one root. The other possible status is `:unknown`, which corresponds to intervals that may contain zero, one, or more roots - no guarantee is provided for these intervals.
-
-These results are represented in the following plot, the region containing roots being in green. The inset show a close-up of one of the roots:
-
-![basic usage](docs/src/basic_usage.png)
-
-The full documentation is available [here](https://juliaintervals.github.io/IntervalRootFinding.jl/latest/).
-
-
-### Note about guarantee
-
-In the example, the interval of the roots have the `NG` flag, meaning that they are not strictly guaranteed to be correct.
-This happens when numbers and interval are mixed,
-because IntervalArithmetic does not know where the numbers come from,
-and can therefore not guarantee that they are properly rounded.
+## Basic usage examples
 
-The NG flag can usually be avoided by taking the responsibility
-to provide exactly the right number using the `@exact` macro.
+The basic function is `roots`. Given a standard Julia function and an interval, the `roots` function returns a list of intervals containing all roots of the function located in the prescribed interval.
 
 ```julia
-julia> @exact g(x) = sin(x) - 0.1*x^2 + 1
-g (generic function with 1 method)
+julia> using IntervalArithmetic, IntervalRootFinding
+
+julia> using IntervalArithmetic.Symbols # to use `..`
 
-julia> roots(g, -10..10)
-4-element Vector{Root{Interval{Float64}}}:
- Root([-4.42654, -4.42653]_com, :unique)
- Root([-3.10682, -3.10681]_com, :unique)
- Root([-1.08205, -1.08204]_com, :unique)
- Root([3.14959, 3.1496]_com, :unique)
- ```
+julia> f(x) = sin(x) - 0.1*x^2 + 1
+f (generic function with 1 method)
 
-More details about the interval decoration system and what it means for root finding can be found in the documentation.
+julia> roots(f, -10..10)
+4-element Array{Root{Interval{Float64}},1}:
+ Root([3.14959, 3.1496], :unique)
+ Root([-4.42654, -4.42653], :unique)
+ Root([-1.08205, -1.08204], :unique)
+ Root([-3.10682, -3.10681], :unique)
+```
 
-## 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)
+The `:unique` status indicates that each listed interval contains exactly one root. The other possible status is `:unknown`, which corresponds to intervals that may contain zero, one, or more roots (no guarantee is provided for these intervals).
 
-## Acknowledgements ##
+These results are represented in the following plot, the region containing roots being in green.
 
-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).
+![basic usage](docs/src/basic_usage.png)