diff --git a/docs/Project.toml b/docs/Project.toml index 04a7447e..bd5bf13d 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,7 +1,9 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" IntervalArithmetic = "d1acc4aa-44c8-5952-acd4-ba5d80a2a253" [compat] Documenter = "1" +DocumenterCitations = "1.3" IntervalArithmetic = "0.21, =0.21" # v0.22 changed the output format diff --git a/docs/make.jl b/docs/make.jl index d513f598..c77036e5 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,8 +1,10 @@ -using Documenter, IntervalMatrices +using Documenter, IntervalMatrices, DocumenterCitations DocMeta.setdocmeta!(IntervalMatrices, :DocTestSetup, :(using IntervalMatrices); recursive=true) +bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style=:alpha) + makedocs(; sitename="IntervalMatrices.jl", modules=[IntervalMatrices], format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true", @@ -12,7 +14,7 @@ makedocs(; sitename="IntervalMatrices.jl", "Library" => Any["Types" => "lib/types.md", "Methods" => "lib/methods.md"], "About" => "about.md", - "References" => "references.md"]) + "Bibliography" => "bibliography.md"]) deploydocs(; repo="github.com/JuliaReach/IntervalMatrices.jl.git", push_preview=true) diff --git a/docs/src/bibliography.md b/docs/src/bibliography.md new file mode 100644 index 00000000..a987675a --- /dev/null +++ b/docs/src/bibliography.md @@ -0,0 +1,4 @@ +# Bibliography + +```@bibliography +``` diff --git a/docs/src/index.md b/docs/src/index.md index a8b68e52..55fbdd04 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -19,7 +19,7 @@ See the section [Library Outline](@ref) below for details. An application of interval matrices is to find the set of states reachable by a dynamical system whose coefficients are uncertain. The library [ReachabilityAnalysis.jl](http://github.com/JuliaReach/ReachabilityAnalysis.jl) -implements algorithms that use interval matrices [^3] [^4]. +implements algorithms that use interval matrices [AlthoffKS11](@citet) [Liou66](@citet). ## Installing @@ -100,9 +100,10 @@ relevant definitions and algebraic rules that apply. However, the straightforward application of the rules of interval arithmetic does not always give the exact result: in general it only gives an overapproximation -[^1] [^2]. To illustrate, suppose that we are interested in the quadratic term -``At + \frac{1}{2}A^2 t^2``, which corresponds to the Taylor-series expansion at order two of -``e^{At} - I``. Then, at ``t = 1.0``, +[AlthoffSB08](@citet) [KoshelevaKMN05](@citet). To illustrate, suppose that we +are interested in the quadratic term ``At + \frac{1}{2}A^2 t^2``, which +corresponds to the Taylor-series expansion at order two of ``e^{At} - I``. +Then, at ``t = 1.0``, ```jldoctest quickstart julia> A + 1/2 * A^2 @@ -138,20 +139,3 @@ Pages = [ ] Depth = 2 ``` - -## References - -[^1]: Althoff, Matthias, Olaf Stursberg, and Martin Buss. *Reachability analysis - of nonlinear systems with uncertain parameters using conservative linearization.* - 2008 47th IEEE Conference on Decision and Control. IEEE, 2008. - -[^2]: Kosheleva, Olga, et al. *Computing the cube of an interval matrix is NP-hard.* - Proceedings of the 2005 ACM symposium on Applied computing. ACM, 2005. - -[^3]: Althoff, Matthias, Bruce H. Krogh, and Olaf Stursberg. *Analyzing reachability - of linear dynamic systems with parametric uncertainties.* - Modeling, Design, and Simulation of Systems with Uncertainties. - Springer, Berlin, Heidelberg, 2011. 69-94. - -[^4]: Liou, M. L. *A novel method of evaluating transient response.* - Proceedings of the IEEE 54.1 (1966): 20-23. diff --git a/docs/src/references.md b/docs/src/references.md deleted file mode 100644 index 10c0e647..00000000 --- a/docs/src/references.md +++ /dev/null @@ -1,53 +0,0 @@ -# References - -#### [RUM10] - -```@raw html - -``` ---- - -#### [RUM99] - -```@raw html - -``` diff --git a/docs/src/refs.bib b/docs/src/refs.bib new file mode 100644 index 00000000..54f4d63d --- /dev/null +++ b/docs/src/refs.bib @@ -0,0 +1,106 @@ +@article{Liou66, + title={A novel method of evaluating transient response}, + author={Liou, ML}, + journal={Proceedings of the {IEEE}}, + volume={54}, + number={1}, + pages={20--23}, + year={1966}, + publisher={IEEE} +} + +@article{Rump99, + title={Fast and parallel interval arithmetic}, + author={Rump, Siegfried M}, + journal={{BIT} Numerical Mathematics}, + volume={39}, + number={3}, + pages={534--554}, + year={1999}, + publisher={Springer}, + url={https://www.tuhh.de/ti3/paper/rump/Ru99b.pdf} +} + +@inproceedings{KoshelevaKMN05, + author = {Olga Kosheleva and + Vladik Kreinovich and + G{\"{u}}nter Mayer and + Hung T. Nguyen}, + editor = {Hisham Haddad and + Lorie M. Liebrock and + Andrea Omicini and + Roger L. Wainwright}, + title = {Computing the cube of an interval matrix is NP-Hard}, + booktitle = {Symposium on Applied Computing ({SAC})}, + pages = {1449--1453}, + publisher = {{ACM}}, + year = {2005}, + url = {https://doi.org/10.1145/1066677.1067007}, + doi = {10.1145/1066677.1067007} +} + +@inproceedings{AlthoffSB07, + author = {Matthias Althoff and + Olaf Stursberg and + Martin Buss}, + title = {Reachability analysis of linear systems with uncertain parameters + and inputs}, + booktitle = {Conference on Decision and Control ({CDC})}, + pages = {726--732}, + publisher = {{IEEE}}, + year = {2007}, + url = {https://doi.org/10.1109/CDC.2007.4434084}, + doi = {10.1109/CDC.2007.4434084} +} + +@inproceedings{AlthoffSB08, + author = {Matthias Althoff and + Olaf Stursberg and + Martin Buss}, + title = {Reachability analysis of nonlinear systems with uncertain parameters + using conservative linearization}, + booktitle = {Conference on Decision and Control ({CDC})}, + pages = {4042--4048}, + publisher = {{IEEE}}, + year = {2008}, + url = {https://doi.org/10.1109/CDC.2008.4738704}, + doi = {10.1109/CDC.2008.4738704} +} + +@phdthesis{Althoff10, + title={Reachability analysis and its application to the safety assessment of autonomous cars}, + author={Althoff, Matthias}, + year={2010}, + school={Technische Universit{\"a}t M{\"u}nchen} +} + +@article{Rump10, + author = {Siegfried M. Rump}, + title = {Verification methods: Rigorous results using floating-point arithmetic}, + journal = {Acta Numerica}, + volume = {19}, + pages = {287--449}, + year = {2010}, + url = {https://www.tuhh.de/ti3/paper/rump/Ru10.pdf}, + doi = {10.1017/S096249291000005X} +} + +@article{AlthoffKS11, + title={Analyzing reachability of linear dynamic systems with parametric uncertainties}, + author={Althoff, Matthias and Krogh, Bruce H and Stursberg, Olaf}, + journal={Modeling, Design, and Simulation of Systems with Uncertainties}, + pages={69--94}, + year={2011}, + publisher={Springer} +} + +@article{GoldsztejnN14, + author = {Alexandre Goldsztejn and + Arnold Neumaier}, + title = {On the Exponentiation of Interval Matrices}, + journal = {Reliable Computing}, + volume = {20}, + pages = {53--72}, + year = {2014}, + url = {http://interval.louisiana.edu/reliable-computing-journal/volume-20/reliable-computing-20-pp-053-072.pdf} +} diff --git a/src/correction_matrices.jl b/src/correction_matrices.jl index e55ddb5c..1f99dd2d 100644 --- a/src/correction_matrices.jl +++ b/src/correction_matrices.jl @@ -16,10 +16,7 @@ An interval matrix representing the correction term. ### Algorithm -See Theorem 3 in [1]. - -[1] M. Althoff, O. Stursberg, M. Buss. Reachability Analysis of Linear Systems -with Uncertain Parameters and Inputs. CDC 2007. +See [AlthoffSB07; Theorem 3](@citet). """ function correction_hull(A::IntervalMatrix{T}, t, p) where {T} F = _exp_remainder(A, t, p) @@ -51,10 +48,7 @@ An interval matrix representing the correction matrix. ### Algorithm -See Proposition 3.4 in [1]. - -[1] M. Althoff. Reachability analysis and its application to the safety -assessment of autonomous cars. 2010. +See [Althoff10; Proposition 3.4](@citet). """ function input_correction(A::IntervalMatrix{T}, t, p) where {T} n = checksquare(A) diff --git a/src/exponential.jl b/src/exponential.jl index a7d5c22b..c652ed0f 100644 --- a/src/exponential.jl +++ b/src/exponential.jl @@ -67,8 +67,7 @@ such that `[exp(A*t)]_{ij} ⊆ m_{ij}`. ### Algorithm -See Theorem 1 in *Reachability Analysis of Linear Systems with Uncertain -Parameters and Inputs* by M. Althoff, O. Stursberg, M. Buss. +See [AlthoffSB07; Theorem 1](@citet). """ function exp_overapproximation(A::IntervalMatrix{T}, t, p) where {T} n = checksquare(A) @@ -77,9 +76,7 @@ function exp_overapproximation(A::IntervalMatrix{T}, t, p) where {T} return S + E end -# Implementation of Prop. 1 in Althoff, Matthias, Bruce H. Krogh, and Olaf Stursberg. -# "Analyzing reachability of linear dynamic systems with parametric uncertainties." -# Modeling, Design, and Simulation of Systems with Uncertainties. Springer, Berlin, Heidelberg, 2011. 69-94. +# Implementation of [AlthoffKS11; Prop. 1](@citet). function _exp_remainder(A::IntervalMatrix{T}, t, p; n=checksquare(A)) where {T} C = max.(abs.(inf(A)), abs.(sup(A))) # compute Q = I + Ct + (Ct)^2/2! + ... + (Ct)^p/p! @@ -101,10 +98,8 @@ function _exp_remainder(A::IntervalMatrix{T}, t, p; n=checksquare(A)) where {T} return E end -# Estimates the sum of the series in the matrix exponential. See Theorem 1 -# in [1] Althoff, Matthias, Olaf Stursberg, and Martin Buss. -# Reachability analysis of nonlinear systems with uncertain parameters using conservative linearization. -# 2008 47th IEEE Conference on Decision and Control. IEEE, 2008. +# Estimates the sum of the series in the matrix exponential. See +# [AlthoffSB08; Theorem 1](@citet). function _exp_remainder_series(A::IntervalMatrix{T}, t, p; n=checksquare(A)) where {T} nA = opnorm(A, Inf) c = nA * t / (p + 2) @@ -134,8 +129,7 @@ such that `m_{ij} ⊆ [exp(A*t)]_{ij}`. ### Algorithm -See Theorem 2 in *Reachability Analysis of Linear Systems with Uncertain -Parameters and Inputs* by M. Althoff, O. Stursberg, M. Buss. +See [AlthoffSB07; Theorem 2](@citet). """ function exp_underapproximation(A::IntervalMatrix{T}, t, p) where {T} @assert p > 1 "the order $p < 2 is not supported" @@ -196,7 +190,7 @@ An interval matrix that encloses ``B := αA + βA^2``. ### Algorithm -This a variation of the algorithm in [1, Section 6]. If ``A = (aᵢⱼ)`` and +This a variation of the algorithm in [KoshelevaKMN05, Section 6](@citet). If ``A = (aᵢⱼ)`` and ``B := αA + βA^2 = (bᵢⱼ)``, the idea is to compute each ``bᵢⱼ`` by factoring out repeated expressions (thus the term *single-use expressions*). @@ -211,9 +205,6 @@ Now consider ``i ≠ j``. Then, ```math bᵢⱼ = β\\sum_\\{k, k ≠ i, k ≠ j} a_{ik} a_{kj} + (α + βa_{ii} + βa_{jj}) a_{ij}. ``` - -[1] Kosheleva, Kreinovich, Mayer, Nguyen. Computing the cube of an interval -matrix is NP-hard. SAC 2005. """ function quadratic_expansion(A::IntervalMatrix, α::Real, β::Real) B = similar(A) @@ -323,16 +314,13 @@ Compute the matrix exponential using scaling and squaring. ### Algorithm -We use the algorithm in [1, Section 4.3], which first scales `A` by factor +We use the algorithm in [GoldsztejnN14; Section 4.3](@citet), which first scales `A` by factor ``2^{-l}``, computes the matrix exponential for the scaled matrix, and then squares the result ``l`` times. ```math \\exp(A * 2^{-l})^{2^l} ``` - -[1] Goldsztejn, Alexandre, Arnold Neumaier. "On the exponentiation of interval -matrices". Reliable Computing. 2014. """ function scale_and_square(A::IntervalMatrix{T}, l::Integer, t, p; validate::Bool=true) where {T} @@ -390,10 +378,7 @@ Compute the matrix exponential using the Horner scheme. ### Algorithm -We use the algorithm in [1, Section 4.2]. - -[1] Goldsztejn, Alexandre, Arnold Neumaier. "On the exponentiation of interval -matrices". Reliable Computing. 2014. +We use the algorithm in [GoldsztejnN14; Section 4.2](@citet). """ function horner(A::IntervalMatrix{T}, K::Integer; validate::Bool=true) where {T} @@ -418,7 +403,7 @@ function horner(A::IntervalMatrix{T}, K::Integer; H = Iₙ + A / i * H end - # remainder; ref [1] uses a less precise computation here + # remainder; ref [GoldsztejnN14] uses a less precise computation here R = _exp_remainder(A, one(T), K) return H + R diff --git a/src/operations/arithmetic.jl b/src/operations/arithmetic.jl index c8b38165..099e6cb0 100644 --- a/src/operations/arithmetic.jl +++ b/src/operations/arithmetic.jl @@ -59,10 +59,7 @@ An interval matrix equivalent to `A * A`. ### Algorithm -We follow [1, Section 6]. - -[1] Kosheleva, Kreinovich, Mayer, Nguyen. Computing the cube of an interval -matrix is NP-hard. SAC 2005. +We follow [KoshelevaKMN05; Section 6](@citet). """ function square(A::IntervalMatrix) B = similar(A) diff --git a/src/operations/mult.jl b/src/operations/mult.jl index 680e4918..e82908e8 100644 --- a/src/operations/mult.jl +++ b/src/operations/mult.jl @@ -14,7 +14,7 @@ Sets the algorithm used to perform matrix multiplication with interval matrices. - `multype` -- symbol describing the algorithm used - `:slow` -- uses traditional matrix multiplication algorithm. - `:fast` -- computes an enclosure of the matrix product using the midpoint-radius - notation of the matrix [[RUM10]](@ref). + notation of the matrix [Rump10](@citet). !!! note ":fast option no longer supported" `:fast` support was removed in `IntervalArithmetic` v0.22. @@ -24,7 +24,7 @@ Sets the algorithm used to perform matrix multiplication with interval matrices. - By default, `:slow` is used. - Using `fast` is generally significantly faster, but it may return larger intervals, especially if midpoint and radius have the same order of magnitude - (50% overestimate at most) [[RUM99]](@ref). + (50% overestimate at most) [Rump99](@citet). """ function set_multiplication_mode(multype) multype in (:fast, :slow) || throw(ArgumentError("$multype is not a valid input")) diff --git a/test/models.jl b/test/models.jl index 2822fc5a..165d84ea 100644 --- a/test/models.jl +++ b/test/models.jl @@ -1,15 +1,11 @@ #= -State matrix `A` from the transmission line model [1]; we refer to that paper +State matrix `A` from the transmission line model [AlthoffKS11](@citet); we refer to that paper for the interpretation of the physical parameters in this matrix. Here `A` is a sparse, structured, square matrix of order 2η, where η ≥ 2 is a parameter (optional, default: 2). For any choice of (positive) parameters, this matrix is stable in the sense of Hurwitz (i.e. its eigenvalues have strictly negative real-part). A parameter `scale` (optional, default: 1e-9) to rescale the physical quantities is applied to `A`. - -[1] M. Althoff, B. H. Krogh, and O. Stursberg. Analyzing Reachability of -Linear Dynamic Systems with Parametric Uncertainties. Modeling, Design, -and Simulation of Systems with Uncertainties. 2011. =# function transmission_line(; η=2, R₀=1.00, Rd₀=10.0, L₀=1e-10, C₀=1e-13 * 4.00, scale=1e-9) A₁₁ = zeros(η, η)