From f7dbea8caebe85929864dbb24810d2223737d190 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 7 Aug 2024 21:50:42 +0200 Subject: [PATCH 01/83] docs Tsit5 --- docs/make.jl | 5 +++ docs/src/explicit/Tsit5.md | 39 +++++++++++++++++++++++ lib/OrdinaryDiffEqTsit5/src/algorithms.jl | 14 ++++++-- 3 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 docs/src/explicit/Tsit5.md diff --git a/docs/make.jl b/docs/make.jl index 6eaf972530..91ffe5182b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -28,6 +28,11 @@ makedocs(sitename = "OrdinaryDiffEq.jl", pages = [ "OrdinaryDiffEq.jl: ODE solvers and utilities" => "index.md", "Usage" => "usage.md", + "ODEProblem Solver Libraries" => [ + "Explicit Solvers" =>[ + "explicit/Tsit5.md" + ], + ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", "nonstiff/lowstorage_ssprk.md", diff --git a/docs/src/explicit/Tsit5.md b/docs/src/explicit/Tsit5.md new file mode 100644 index 0000000000..79bf388e5d --- /dev/null +++ b/docs/src/explicit/Tsit5.md @@ -0,0 +1,39 @@ +# OrdinaryDiffEqTsit5 + +Recommended solver for most non-stiff problems. + +## Installation + +To be able to access the solvers in `OrdinaryDiffEqTsit5`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqTsit5") +``` + +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage + +```julia +using OrdinaryDiffEqTsit5 + +function lorenz!(du, u, p, t) + du[1] = 10.0 * (u[2] - u[1]) + du[2] = u[1] * (28.0 - u[3]) - u[2] + du[3] = u[1] * u[2] - (8 / 3) * u[3] +end +u0 = [1.0; 0.0; 0.0] +tspan = (0.0, 100.0) +prob = ODEProblem(lorenz!, u0, tspan) +sol = solve(prob, Tsit5()) +``` + +## Full list of solvers + +```@docs +Tsit5 +AutoTsit5 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqTsit5/src/algorithms.jl b/lib/OrdinaryDiffEqTsit5/src/algorithms.jl index 45cfbcc5a1..c19efefcd3 100644 --- a/lib/OrdinaryDiffEqTsit5/src/algorithms.jl +++ b/lib/OrdinaryDiffEqTsit5/src/algorithms.jl @@ -1,6 +1,7 @@ @doc explicit_rk_docstring( "A fifth-order explicit Runge-Kutta method with embedded error -estimator of Tsitouras. Free 4th order interpolant.", "Tsit5", + estimator of Tsitouras. Free 4th order interpolant.", + "Tsit5", references = "@article{tsitouras2011runge, title={Runge--Kutta pairs of order 5 (4) satisfying only the first column simplifying assumption}, author={Tsitouras, Ch}, @@ -23,4 +24,13 @@ function Tsit5(stage_limiter!, step_limiter! = trivial_limiter!) Tsit5(stage_limiter!, step_limiter!, False()) end -AutoTsit5(alg; kwargs...) = AutoAlgSwitch(Tsit5(), alg; kwargs...) +""" +Automatic switching algorithm that can switch between the (non-stiff) `Tsit5()` and `stiff_alg`. + + AutoTsit5(stiff_alg; kwargs...) + +This method is equivalent to `AutoAlgSwitch(Tsit5(), stiff_alg; kwargs...)`. +To gain access to stiff algorithms you might have to install additional libraries, +such as `OrdinaryDiffEqRosenbrock`. +""" +AutoTsit5(stiff_alg; kwargs...) = AutoAlgSwitch(Tsit5(), stiff_alg; kwargs...) From c7652ae4d109c22b49c694b7237182840068921a Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 8 Aug 2024 02:53:45 +0200 Subject: [PATCH 02/83] automate common first steps --- docs/common_first_steps.jl | 29 +++++++++++++++++++++++++++++ docs/src/explicit/Tsit5.md | 32 ++++---------------------------- 2 files changed, 33 insertions(+), 28 deletions(-) create mode 100644 docs/common_first_steps.jl diff --git a/docs/common_first_steps.jl b/docs/common_first_steps.jl new file mode 100644 index 0000000000..a84500e058 --- /dev/null +++ b/docs/common_first_steps.jl @@ -0,0 +1,29 @@ +using Markdown +function first_steps(name, solver) + Markdown.parse("""## Installation + To be able to access the solvers in `$name`, you must first install them use the Julia package manager: + + ```julia + using Pkg + Pkg.add("$name") + ``` + This will only install the solvers listed at the bottom of this page. + If you want to explore other solvers for your problem, + you will need to install some of the other libraries listed in the navigation bar on the left. + + ## Example usage + + ```julia + using $name + + function lorenz!(du, u, p, t) + du[1] = 10.0 * (u[2] - u[1]) + u[2] = u[1] * (28.0 - u[3]) - u[2] + du[3] = u[1] * u[2] - (8 / 3) * u[3] + end + u0 = [1.0; 0.0; 0.0] + tspan = (0.0, 100.0) + prob = ODEProblem(lorenz!, u0, tspan) + sol = solve(prob, $solver()) + ```""") +end diff --git a/docs/src/explicit/Tsit5.md b/docs/src/explicit/Tsit5.md index 79bf388e5d..dc88ae8ef2 100644 --- a/docs/src/explicit/Tsit5.md +++ b/docs/src/explicit/Tsit5.md @@ -2,33 +2,9 @@ Recommended solver for most non-stiff problems. -## Installation - -To be able to access the solvers in `OrdinaryDiffEqTsit5`, you must first install them use the Julia package manager: - -```julia -using Pkg -Pkg.add("OrdinaryDiffEqTsit5") -``` - -This will only install the solvers listed at the bottom of this page. -If you want to explore other solvers for your problem, -you will need to install some of the other libraries listed in the navigation bar on the left. - -## Example usage - -```julia -using OrdinaryDiffEqTsit5 - -function lorenz!(du, u, p, t) - du[1] = 10.0 * (u[2] - u[1]) - du[2] = u[1] * (28.0 - u[3]) - u[2] - du[3] = u[1] * u[2] - (8 / 3) * u[3] -end -u0 = [1.0; 0.0; 0.0] -tspan = (0.0, 100.0) -prob = ODEProblem(lorenz!, u0, tspan) -sol = solve(prob, Tsit5()) +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqTsit5", "Tsit5") ``` ## Full list of solvers @@ -36,4 +12,4 @@ sol = solve(prob, Tsit5()) ```@docs Tsit5 AutoTsit5 -``` \ No newline at end of file +``` From 1172b795122eef15128d3245d64aebccbfb9e1e1 Mon Sep 17 00:00:00 2001 From: Arno Strouwen Date: Wed, 7 Aug 2024 22:37:31 +0200 Subject: [PATCH 03/83] add more info to Tsit5 use cases. Co-authored-by: Christopher Rackauckas --- docs/src/explicit/Tsit5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/explicit/Tsit5.md b/docs/src/explicit/Tsit5.md index dc88ae8ef2..3289c51583 100644 --- a/docs/src/explicit/Tsit5.md +++ b/docs/src/explicit/Tsit5.md @@ -1,6 +1,6 @@ # OrdinaryDiffEqTsit5 -Recommended solver for most non-stiff problems. +Recommended solver for most non-stiff problems at default and higher tolerance. ```@eval first_steps = evalfile("./common_first_steps.jl") From 5af8afb73e4140b6527f3b50ed44c53f0f716c3a Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Fri, 9 Aug 2024 05:51:01 +0200 Subject: [PATCH 04/83] docs LowOrderRK --- docs/make.jl | 4 + docs/src/explicit/LowOrderRK.md | 43 +++ docs/src/explicit/Tsit5.md | 2 +- lib/OrdinaryDiffEqCore/src/doc_utils.jl | 2 + .../src/algorithms.jl | 324 ++++++------------ 5 files changed, 146 insertions(+), 229 deletions(-) create mode 100644 docs/src/explicit/LowOrderRK.md diff --git a/docs/make.jl b/docs/make.jl index 91ffe5182b..699a19d612 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -28,6 +28,10 @@ makedocs(sitename = "OrdinaryDiffEq.jl", pages = [ "OrdinaryDiffEq.jl: ODE solvers and utilities" => "index.md", "Usage" => "usage.md", + "Explicit Solvers" => [ + "explicit/Tsit5.md", + "explicit/LowOrderRK.md" + ], "ODEProblem Solver Libraries" => [ "Explicit Solvers" =>[ "explicit/Tsit5.md" diff --git a/docs/src/explicit/LowOrderRK.md b/docs/src/explicit/LowOrderRK.md new file mode 100644 index 0000000000..ed13d76aec --- /dev/null +++ b/docs/src/explicit/LowOrderRK.md @@ -0,0 +1,43 @@ +# OrdinaryDiffEqLowOrderRK + +If [`OrdinaryDiffEqTsit5`](@ref OrdinaryDiffEqTsit5) is not working well for your non-stiff problem at default and higher tolerance, +it can be worthwhile to explore the options in this package. +In particular, when more robust error control is required, [`BS5`](@ref) is a good choice. +If at moderate tolerances and the interpolation error is very important, +consider the [`OwrenZen5`](@ref) method. +For fast solving at higher tolerances, we recommend [`BS3`](@ref), +or [`OwrenZen3`](@ref)if the interpolation error is important. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqLowOrderRK", "BS3") +``` + +## Full list of solvers + +```@docs +Heun +Ralston +Midpoint +RK4 +BS3 +OwrenZen3 +OwrenZen4 +OwrenZen5 +BS5 +DP5 +Anas5 +RKO65 +FRK65 +RKM +MSRK5 +MSRK6 +PSRK4p7q6 +PSRK3p5q4 +PSRK3p6q5 +Stepanov5 +SIR54 +Alshina2 +Alshina3 +Alshina6 +``` diff --git a/docs/src/explicit/Tsit5.md b/docs/src/explicit/Tsit5.md index 3289c51583..9494c4e118 100644 --- a/docs/src/explicit/Tsit5.md +++ b/docs/src/explicit/Tsit5.md @@ -1,4 +1,4 @@ -# OrdinaryDiffEqTsit5 +# [OrdinaryDiffEqTsit5](@id OrdinaryDiffEqTsit5) Recommended solver for most non-stiff problems at default and higher tolerance. diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index 28c4fe64a0..abaa9eead7 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -62,11 +62,13 @@ function explicit_rk_docstring(description::String, keyword_default = """ stage_limiter! = OrdinaryDiffEq.trivial_limiter!, step_limiter! = OrdinaryDiffEq.trivial_limiter!, + thread = OrdinaryDiffEq.False(), """ * extra_keyword_default keyword_default_description = """ - `stage_limiter!`: function of the form `limiter!(u, integrator, p, t)` - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. """ * extra_keyword_description generic_solver_docstring( diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index 3e044f73b3..e5683dd6e8 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -80,7 +80,7 @@ function RK4(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A third-order, four-stage explicit FSAL Runge-Kutta method with embedded error + "A third-order, four-stage FSAL method with embedded error estimator of Bogacki and Shampine.", "BS3", references = "@article{bogacki19893, @@ -188,8 +188,7 @@ end year={1996}, publisher={Elsevier} }", - extra_keyword_description = """- `lazy`: determines if the lazy interpolant is used. - """, + extra_keyword_description = """- `lazy`: determines if the lazy interpolant is used.""", extra_keyword_default = "lazy = true") Base.@kwdef struct BS5{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -230,8 +229,7 @@ AutoDP5(alg; kwargs...) = AutoAlgSwitch(DP5(), alg; kwargs...) @doc explicit_rk_docstring("4th order Runge-Kutta method designed for periodic problems.", "Anas5", extra_keyword_description = """- `w`: a periodicity estimate, which when accurate the method becomes 5th order - (and is otherwise 4th order with less error for better estimates). - """, + (and is otherwise 4th order with less error for better estimates).""", extra_keyword_default = "w = 1") Base.@kwdef struct Anas5{StageLimiter, StepLimiter, Thread, T} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -244,7 +242,7 @@ function Anas5(stage_limiter!, step_limiter! = trivial_limiter!; w = 1) Anas5(stage_limiter!, step_limiter!, False(), w) end -@doc explicit_rk_docstring("5th order Explicit RK method.", "RKO5", +@doc explicit_rk_docstring("5th order method.", "RKO65", references = "Tsitouras, Ch. \"Explicit Runge–Kutta methods for starting integration of Lane–Emden problem.\" Applied Mathematics and Computation 354 (2019): 353-364. doi: https://doi.org/10.1016/j.amc.2019.02.047") @@ -260,8 +258,7 @@ end @doc explicit_rk_docstring("Zero Dissipation Runge-Kutta of 6th order.", "FRK65", extra_keyword_description = """- `omega`: a periodicity phase estimate, - when accurate this method results in zero numerical dissipation. - """, + when accurate this method results in zero numerical dissipation.""", extra_keyword_default = "omega = 0.0") Base.@kwdef struct FRK65{StageLimiter, StepLimiter, Thread, T} <: OrdinaryDiffEqAdaptiveAlgorithm @@ -276,7 +273,7 @@ function FRK65(stage_limiter!, step_limiter! = trivial_limiter!; omega = 0.0) FRK65(stage_limiter!, step_limiter!, False(), omega) end -@doc explicit_rk_docstring("TBD", "RKM") +@doc explicit_rk_docstring("To be done", "RKM") Base.@kwdef struct RKM{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! @@ -287,7 +284,7 @@ function RKM(stage_limiter!, step_limiter! = trivial_limiter!) RKM(stage_limiter!, step_limiter!, False()) end -@doc explicit_rk_docstring("5th order Explicit RK method.", "MSRK5", +@doc explicit_rk_docstring("5th order method.", "MSRK5", references = "Misha Stepanov - https://arxiv.org/pdf/2202.08443.pdf : Figure 3.") Base.@kwdef struct MSRK5{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -299,7 +296,7 @@ function MSRK5(stage_limiter!, step_limiter! = trivial_limiter!) MSRK5(stage_limiter!, step_limiter!, False()) end -@doc explicit_rk_docstring("6th order Explicit RK method.", "MSRK6", +@doc explicit_rk_docstring("6th order method.", "MSRK6", references = "Misha Stepanov - https://arxiv.org/pdf/2202.08443.pdf : Table4") Base.@kwdef struct MSRK6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -311,7 +308,7 @@ function MSRK6(stage_limiter!, step_limiter! = trivial_limiter!) MSRK6(stage_limiter!, step_limiter!, False()) end -@doc explicit_rk_docstring("6-stage Pseudo-Symplectic Explicit RK method.", "4p7q(6)", +@doc explicit_rk_docstring("6-stage Pseudo-Symplectic method.", "PSRK4p7q6", references = "@article{Aubry1998, author = {A. Aubry and P. Chartier}, journal = {BIT Numer. Math.}, @@ -335,7 +332,7 @@ Base.@kwdef struct PSRK4p7q6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffE thread::Thread = False() end -@doc explicit_rk_docstring("4-stage Pseudo-Symplectic Explicit RK method.", "3p5q(4)", +@doc explicit_rk_docstring("4-stage Pseudo-Symplectic method.", "PSRK3p5q4", references = "@article{Aubry1998, author = {A. Aubry and P. Chartier}, journal = {BIT Numer. Math.}, @@ -353,7 +350,7 @@ Base.@kwdef struct PSRK3p5q4{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffE thread::Thread = False() end -@doc explicit_rk_docstring("5-stage Pseudo-Symplectic Explicit RK method.", "3p6q(5)", +@doc explicit_rk_docstring("5-stage Pseudo-Symplectic method.", "PSRK3p6q5", references = "@article{Aubry1998, author = {A. Aubry and P. Chartier}, journal = {BIT Numer. Math.}, @@ -371,7 +368,7 @@ Base.@kwdef struct PSRK3p6q5{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffE thread::Thread = False() end -@doc explicit_rk_docstring("5th order Explicit RK method.", +@doc explicit_rk_docstring("5th order method.", "Stepanov5", references = "@article{Stepanov2021Embedded5, title={Embedded (4, 5) pairs of explicit 7-stage Runge–Kutta methods with FSAL property}, @@ -391,226 +388,97 @@ function Stepanov5(stage_limiter!, step_limiter! = trivial_limiter!) Stepanov5(stage_limiter!, step_limiter!, False()) end -""" - SIR54(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!, - step_limiter! = OrdinaryDiffEq.trivial_limiter!, - thread = OrdinaryDiffEq.False()) - -5th order Explicit RK method suited for SIR-type epidemic models. - -Like SSPRK methods, this method also takes optional arguments `stage_limiter!` -and `step_limiter!`, where `stage_limiter!` and `step_limiter!` are functions -of the form `limiter!(u, integrator, p, t)`. - -The argument `thread` determines whether internal broadcasting on -appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`, -default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when -Julia is started with multiple threads. - -## Reference - -@article{Kovalnogov2020RungeKuttaPS, -title={Runge–Kutta pairs suited for SIR‐type epidemic models}, -author={Vladislav N. Kovalnogov and Theodore E. Simos and Ch. Tsitouras}, -journal={Mathematical Methods in the Applied Sciences}, -year={2020}, -volume={44}, -pages={5210 - 5216} -} -""" -struct SIR54{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm - stage_limiter!::StageLimiter - step_limiter!::StepLimiter - thread::Thread -end - -function SIR54(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, - thread = False()) - SIR54{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!, - step_limiter!, - thread) +@doc explicit_rk_docstring("5th order method suited for SIR-type epidemic models.", + "SIR54", + references = "@article{Kovalnogov2020RungeKuttaPS, + title={Runge–Kutta pairs suited for SIR‐type epidemic models}, + author={Vladislav N. Kovalnogov and Theodore E. Simos and Ch. Tsitouras}, + journal={Mathematical Methods in the Applied Sciences}, + year={2020}, + volume={44}, + pages={5210 - 5216} + }") +Base.@kwdef struct SIR54{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() end - # for backwards compatibility function SIR54(stage_limiter!, step_limiter! = trivial_limiter!) - SIR54{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!, - step_limiter!, - False()) -end - -function Base.show(io::IO, alg::SIR54) - print(io, "SIR54(stage_limiter! = ", alg.stage_limiter!, - ", step_limiter! = ", alg.step_limiter!, - ", thread = ", alg.thread, ")") -end - -""" - Alshina2(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!, - step_limiter! = OrdinaryDiffEq.trivial_limiter!, - thread = OrdinaryDiffEq.False()) - -2nd order, 2-stage Explicit Runge-Kutta Method with optimal parameters. - -Like SSPRK methods, this method also takes optional arguments `stage_limiter!` -and `step_limiter!`, where `stage_limiter!` and `step_limiter!` are functions -of the form `limiter!(u, integrator, p, t)`. - -The argument `thread` determines whether internal broadcasting on -appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`, -default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when -Julia is started with multiple threads. - -## Reference - -@article{Alshina2008, -doi = {10.1134/s0965542508030068}, -url = {https://doi.org/10.1134/s0965542508030068}, -year = {2008}, -month = mar, -publisher = {Pleiades Publishing Ltd}, -volume = {48}, -number = {3}, -pages = {395--405}, -author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, -title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, -journal = {Computational Mathematics and Mathematical Physics} -} -""" -struct Alshina2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm - stage_limiter!::StageLimiter - step_limiter!::StepLimiter - thread::Thread -end - -function Alshina2(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, - thread = False()) - Alshina2{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!, - step_limiter!, - thread) + SIR54(stage_limiter!, step_limiter!, False()) +end + +@doc explicit_rk_docstring("2nd order, 2-stage Method with optimal parameters.", + "Alshina2", + references = "@article{Alshina2008, + doi = {10.1134/s0965542508030068}, + url = {https://doi.org/10.1134/s0965542508030068}, + year = {2008}, + month = mar, + publisher = {Pleiades Publishing Ltd}, + volume = {48}, + number = {3}, + pages = {395--405}, + author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, + title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, + journal = {Computational Mathematics and Mathematical Physics} + }") +Base.@kwdef struct Alshina2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() end - +# for backwards compatibility function Alshina2(stage_limiter!, step_limiter! = trivial_limiter!) - Alshina2{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!, - step_limiter!, - False()) -end - -function Base.show(io::IO, alg::Alshina2) - print(io, "Alshina2(stage_limiter! = ", alg.stage_limiter!, - ", step_limiter! = ", alg.step_limiter!, - ", thread = ", alg.thread, ")") -end - -""" - Alshina3(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!, - step_limiter! = OrdinaryDiffEq.trivial_limiter!, - thread = OrdinaryDiffEq.False()) - -3rd order, 3-stage Explicit Runge-Kutta Method with optimal parameters. - -Like SSPRK methods, this method also takes optional arguments `stage_limiter!` -and `step_limiter!`, where `stage_limiter!` and `step_limiter!` are functions -of the form `limiter!(u, integrator, p, t)`. - -The argument `thread` determines whether internal broadcasting on -appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`, -default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when -Julia is started with multiple threads. - -## Reference - -@article{Alshina2008, -doi = {10.1134/s0965542508030068}, -url = {https://doi.org/10.1134/s0965542508030068}, -year = {2008}, -month = mar, -publisher = {Pleiades Publishing Ltd}, -volume = {48}, -number = {3}, -pages = {395--405}, -author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, -title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, -journal = {Computational Mathematics and Mathematical Physics} -} -""" -struct Alshina3{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm - stage_limiter!::StageLimiter - step_limiter!::StepLimiter - thread::Thread -end - -function Alshina3(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, - thread = False()) - Alshina3{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!, - step_limiter!, - thread) + Alshina2(stage_limiter!, step_limiter!, False()) +end + +@doc explicit_rk_docstring("3rd order, 3-stage Method with optimal parameters.", + "Alshina3", + references = "@article{Alshina2008, + doi = {10.1134/s0965542508030068}, + url = {https://doi.org/10.1134/s0965542508030068}, + year = {2008}, + month = mar, + publisher = {Pleiades Publishing Ltd}, + volume = {48}, + number = {3}, + pages = {395--405}, + author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, + title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, + journal = {Computational Mathematics and Mathematical Physics} + }") +Base.@kwdef struct Alshina3{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() end - +# for backwards compatibility function Alshina3(stage_limiter!, step_limiter! = trivial_limiter!) - Alshina3{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!, - step_limiter!, - False()) -end - -function Base.show(io::IO, alg::Alshina3) - print(io, "Alshina3(stage_limiter! = ", alg.stage_limiter!, - ", step_limiter! = ", alg.step_limiter!, - ", thread = ", alg.thread, ")") -end - -""" - Alshina6(; stage_limiter! = OrdinaryDiffEq.trivial_limiter!, - step_limiter! = OrdinaryDiffEq.trivial_limiter!, - thread = OrdinaryDiffEq.False()) - -6th order, 7-stage Explicit Runge-Kutta Method with optimal parameters. - -Like SSPRK methods, this method also takes optional arguments `stage_limiter!` -and `step_limiter!`, where `stage_limiter!` and `step_limiter!` are functions -of the form `limiter!(u, integrator, p, t)`. - -The argument `thread` determines whether internal broadcasting on -appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`, -default) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when -Julia is started with multiple threads. - -## Reference - -@article{Alshina2008, -doi = {10.1134/s0965542508030068}, -url = {https://doi.org/10.1134/s0965542508030068}, -year = {2008}, -month = mar, -publisher = {Pleiades Publishing Ltd}, -volume = {48}, -number = {3}, -pages = {395--405}, -author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, -title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, -journal = {Computational Mathematics and Mathematical Physics} -} -""" -struct Alshina6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm - stage_limiter!::StageLimiter - step_limiter!::StepLimiter - thread::Thread -end - -function Alshina6(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, - thread = False()) - Alshina6{typeof(stage_limiter!), typeof(step_limiter!), typeof(thread)}(stage_limiter!, - step_limiter!, - thread) + Alshina3(stage_limiter!, step_limiter!, False()) +end + +@doc explicit_rk_docstring("6th order, 7-stage Method with optimal parameters.", + "Alshina6", + references = "@article{Alshina2008, + doi = {10.1134/s0965542508030068}, + url = {https://doi.org/10.1134/s0965542508030068}, + year = {2008}, + month = mar, + publisher = {Pleiades Publishing Ltd}, + volume = {48}, + number = {3}, + pages = {395--405}, + author = {E. A. Alshina and E. M. Zaks and N. N. Kalitkin}, + title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, + journal = {Computational Mathematics and Mathematical Physics} + }") +Base.@kwdef struct Alshina6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() end - +# for backwards compatibility function Alshina6(stage_limiter!, step_limiter! = trivial_limiter!) - Alshina6{typeof(stage_limiter!), typeof(step_limiter!), False}(stage_limiter!, - step_limiter!, - False()) -end - -function Base.show(io::IO, alg::Alshina6) - print(io, "Alshina6(stage_limiter! = ", alg.stage_limiter!, - ", step_limiter! = ", alg.step_limiter!, - ", thread = ", alg.thread, ")") + Alshina6(stage_limiter!, step_limiter!, False()) end From 76008491a463ba083ccc5e92b9133dcc65967206 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Fri, 9 Aug 2024 05:52:17 +0200 Subject: [PATCH 05/83] docs reproducibility --- docs/src/index.md | 35 +++++++++++------------------------ 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/docs/src/index.md b/docs/src/index.md index 6ff9dd7ed6..b2647f8898 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -56,32 +56,19 @@ Pkg.status(; mode = PKGMODE_MANIFEST) # hide ``` -```@raw html -You can also download the -manifest file and the -project file. +link_manifest = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version * + "/assets/Manifest.toml" +link_project = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version * + "/assets/Project.toml" +Markdown.parse("""You can also download the +[manifest]($link_manifest) +file and the +[project]($link_project) +file. +""") ``` From 94025dd47c955ed8ed557c1433a87bd8afdce848 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 06:31:45 +0200 Subject: [PATCH 06/83] Alshina 6 non-adaptive --- lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index e5683dd6e8..a953ffb364 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -473,7 +473,7 @@ end title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, journal = {Computational Mathematics and Mathematical Physics} }") -Base.@kwdef struct Alshina6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm +Base.@kwdef struct Alshina6{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() From c9c257c3f06bbf92a9b3354069915ec66aab270a Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 06:36:47 +0200 Subject: [PATCH 07/83] docs HighOrderRK --- docs/make.jl | 3 ++- docs/src/explicit/HighOrderRK.md | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 docs/src/explicit/HighOrderRK.md diff --git a/docs/make.jl b/docs/make.jl index 699a19d612..533b53371b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -30,7 +30,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "Usage" => "usage.md", "Explicit Solvers" => [ "explicit/Tsit5.md", - "explicit/LowOrderRK.md" + "explicit/LowOrderRK.md", + "explicit/HighOrderRK.md" ], "ODEProblem Solver Libraries" => [ "Explicit Solvers" =>[ diff --git a/docs/src/explicit/HighOrderRK.md b/docs/src/explicit/HighOrderRK.md new file mode 100644 index 0000000000..9be5b8f788 --- /dev/null +++ b/docs/src/explicit/HighOrderRK.md @@ -0,0 +1,18 @@ +# OrdinaryDiffEqHighOrderRK + +Solvers for non-stiff problems at low tolerance. +However, the solvers in `OrdinaryDiffEqVerner` are generally perform better at low + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqHighOrderRK", "DP8") +``` + +## Full list of solvers + +```@docs +TanYam7 +TsitPap8 +DP8 +PFRK87 +``` From 33b45222d0607aa687cc7397ec95e957b4bc273c Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 06:40:12 +0200 Subject: [PATCH 08/83] docs Verner --- docs/make.jl | 3 +- docs/src/explicit/HighOrderRK.md | 2 +- docs/src/explicit/Verner.md | 27 ++++++++++++++++ lib/OrdinaryDiffEqVerner/src/algorithms.jl | 36 ++++++++++++++++++++++ 4 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 docs/src/explicit/Verner.md diff --git a/docs/make.jl b/docs/make.jl index 533b53371b..453d969e3c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -31,7 +31,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "Explicit Solvers" => [ "explicit/Tsit5.md", "explicit/LowOrderRK.md", - "explicit/HighOrderRK.md" + "explicit/HighOrderRK.md", + "explicit/Verner.md" ], "ODEProblem Solver Libraries" => [ "Explicit Solvers" =>[ diff --git a/docs/src/explicit/HighOrderRK.md b/docs/src/explicit/HighOrderRK.md index 9be5b8f788..69a88fd280 100644 --- a/docs/src/explicit/HighOrderRK.md +++ b/docs/src/explicit/HighOrderRK.md @@ -1,7 +1,7 @@ # OrdinaryDiffEqHighOrderRK Solvers for non-stiff problems at low tolerance. -However, the solvers in `OrdinaryDiffEqVerner` are generally perform better at low +However, the solvers in [`OrdinaryDiffEqVerner`](@ref OrdinaryDiffEqVerner) generally perform better at low tolerances. ```@eval first_steps = evalfile("./common_first_steps.jl") diff --git a/docs/src/explicit/Verner.md b/docs/src/explicit/Verner.md new file mode 100644 index 0000000000..3654f9b729 --- /dev/null +++ b/docs/src/explicit/Verner.md @@ -0,0 +1,27 @@ +# [OrdinaryDiffEqVerner](@id OrdinaryDiffEqVerner) + +Preferred solvers for non-stiff problems at low tolerance. +`Vern6`, `Vern7`, or `Vern8` are good methods for tolerances between `~1e-8-1e-12`, +and using `Float64` numbers for the state of the differential equation. +For even lower tolerances,`Vern9` should be used, combined with the more precise `BigFloat` number type. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqVerner", "Vern6") +``` + +## Full list of solvers + +```@docs +Vern6 +Vern7 +Vern8 +Vern9 +``` + +```@docs +AutoVern6 +AutoVern7 +AutoVern8 +AutoVern9 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqVerner/src/algorithms.jl b/lib/OrdinaryDiffEqVerner/src/algorithms.jl index 7786b94e22..e1fbb1fb16 100644 --- a/lib/OrdinaryDiffEqVerner/src/algorithms.jl +++ b/lib/OrdinaryDiffEqVerner/src/algorithms.jl @@ -113,7 +113,43 @@ function Vern9(stage_limiter!, step_limiter! = trivial_limiter!; lazy = true) Vern9(stage_limiter!, step_limiter!, False(), lazy) end +""" +Automatic switching algorithm that can switch between the (non-stiff) `Vern6()` and `stiff_alg`. + + AutoVern6(stiff_alg; kwargs...) + +This method is equivalent to `AutoAlgSwitch(Vern6(), stiff_alg; kwargs...)`. +To gain access to stiff algorithms you might have to install additional libraries, +such as `OrdinaryDiffEqRosenbrock`. +""" AutoVern6(alg; lazy = true, kwargs...) = AutoAlgSwitch(Vern6(lazy = lazy), alg; kwargs...) +""" +Automatic switching algorithm that can switch between the (non-stiff) `Vern7()` and `stiff_alg`. + + AutoVern7(stiff_alg; kwargs...) + +This method is equivalent to `AutoAlgSwitch(Vern7(), stiff_alg; kwargs...)`. +To gain access to stiff algorithms you might have to install additional libraries, +such as `OrdinaryDiffEqRosenbrock`. +""" AutoVern7(alg; lazy = true, kwargs...) = AutoAlgSwitch(Vern7(lazy = lazy), alg; kwargs...) +""" +Automatic switching algorithm that can switch between the (non-stiff) `Vern8()` and `stiff_alg`. + + AutoVern8(stiff_alg; kwargs...) + +This method is equivalent to `AutoAlgSwitch(Vern8(), stiff_alg; kwargs...)`. +To gain access to stiff algorithms you might have to install additional libraries, +such as `OrdinaryDiffEqRosenbrock`. +""" AutoVern8(alg; lazy = true, kwargs...) = AutoAlgSwitch(Vern8(lazy = lazy), alg; kwargs...) +""" +Automatic switching algorithm that can switch between the (non-stiff) `Vern9()` and `stiff_alg`. + + AutoVern9(stiff_alg; kwargs...) + +This method is equivalent to `AutoAlgSwitch(Vern9(), stiff_alg; kwargs...)`. +To gain access to stiff algorithms you might have to install additional libraries, +such as `OrdinaryDiffEqRosenbrock`. +""" AutoVern9(alg; lazy = true, kwargs...) = AutoAlgSwitch(Vern9(lazy = lazy), alg; kwargs...) From 5f2480911408202ebbf5b98b65bd1398459ab5d0 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 07:56:07 +0200 Subject: [PATCH 09/83] docs Feagin --- docs/make.jl | 11 ++- docs/src/explicit/Feagin.md | 17 +++++ lib/OrdinaryDiffEqCore/src/doc_utils.jl | 2 +- .../src/OrdinaryDiffEqFeagin.jl | 2 +- lib/OrdinaryDiffEqFeagin/src/algorithms.jl | 74 +++++++++++-------- 5 files changed, 69 insertions(+), 37 deletions(-) create mode 100644 docs/src/explicit/Feagin.md diff --git a/docs/make.jl b/docs/make.jl index 453d969e3c..71e81e603d 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -16,6 +16,9 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqFeagin, OrdinaryDiffEq.OrdinaryDiffEqSymplecticRK, OrdinaryDiffEq.OrdinaryDiffEqRKN, + OrdinaryDiffEq.OrdinaryDiffEqTsit5, + OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, + OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, OrdinaryDiffEq.OrdinaryDiffEqVerner, OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, @@ -32,12 +35,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Tsit5.md", "explicit/LowOrderRK.md", "explicit/HighOrderRK.md", - "explicit/Verner.md" - ], - "ODEProblem Solver Libraries" => [ - "Explicit Solvers" =>[ - "explicit/Tsit5.md" - ], + "explicit/Verner.md", + "explicit/Feagin.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", diff --git a/docs/src/explicit/Feagin.md b/docs/src/explicit/Feagin.md new file mode 100644 index 0000000000..daca5e2f1b --- /dev/null +++ b/docs/src/explicit/Feagin.md @@ -0,0 +1,17 @@ +# OrdinaryDiffEqFeagin + +Preferred solvers for non-stiff problems at very low tolerance, `<1e-30`. +Best combined with preciser than `Float64` number types for the state, such as the `BigFloat` number type. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqFeagin", "Feagin14") +``` + +## Full list of solvers + +```@docs +Feagin10 +Feagin12 +Feagin14 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index abaa9eead7..8dbcf36feb 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -16,7 +16,7 @@ function generic_solver_docstring(description::String, # Indent the keywords properly indentation = repeat(" ", length(name) + 3) # We do not indent the first kw and no newline for the last one - if length(keyword_default) > 1 + if length(keywords_split) > 1 keywords_split[1] = keywords_split[1] * "\n" for i in 2:(length(keywords_split) - 1) keywords_split[i] = indentation * keywords_split[i] * "\n" diff --git a/lib/OrdinaryDiffEqFeagin/src/OrdinaryDiffEqFeagin.jl b/lib/OrdinaryDiffEqFeagin/src/OrdinaryDiffEqFeagin.jl index 5573a4dea2..a1a4236c9f 100644 --- a/lib/OrdinaryDiffEqFeagin/src/OrdinaryDiffEqFeagin.jl +++ b/lib/OrdinaryDiffEqFeagin/src/OrdinaryDiffEqFeagin.jl @@ -8,7 +8,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, OrdinaryDiffEqAdaptiveAlgorithm, CompiledFloats, uses_uprev, alg_cache, _vec, _reshape, @cache, isfsal, full_cache, constvalue, _unwrap_val, get_fsalfirstlast, - explicit_rk_docstring, trivial_limiter!, + generic_solver_docstring, trivial_limiter!, _ode_interpolant!, _ode_addsteps! using FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools using DiffEqBase: @def, @tight_loop_macros diff --git a/lib/OrdinaryDiffEqFeagin/src/algorithms.jl b/lib/OrdinaryDiffEqFeagin/src/algorithms.jl index 76260ce1b6..7b3a581a05 100644 --- a/lib/OrdinaryDiffEqFeagin/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFeagin/src/algorithms.jl @@ -1,40 +1,56 @@ -""" -@article{feagin2012high, -title={High-order explicit Runge-Kutta methods using m-symmetry}, -author={Feagin, Terry}, -year={2012}, -publisher={Neural, Parallel \\& Scientific Computations} -} - -Feagin10: Explicit Runge-Kutta Method -Feagin's 10th-order Runge-Kutta method. -""" +@doc generic_solver_docstring( + "Feagin's 10th-order method.", "Feagin10", "Explicit Runge-Kutta Method. ", + """@article{feagin2012high, + title={High-order explicit Runge-Kutta methods using m-symmetry}, + author={Feagin, Terry}, + year={2012}, + publisher={Neural, Parallel \\& Scientific Computations} + }""", + """ + - `stage_limiter!`: function of the form `limiter!(u, integrator, p, t)` + """, + """ + step_limiter! = OrdinaryDiffEq.trivial_limiter!, + """ +) Base.@kwdef struct Feagin10{StepLimiter} <: OrdinaryDiffEqAdaptiveAlgorithm step_limiter!::StepLimiter = trivial_limiter! end -""" -@article{feagin2012high, -title={High-order explicit Runge-Kutta methods using m-symmetry}, -author={Feagin, Terry}, -year={2012}, -publisher={Neural, Parallel \\& Scientific Computations} -} - -Feagin12: Explicit Runge-Kutta Method -Feagin's 12th-order Runge-Kutta method. -""" +@doc generic_solver_docstring( + "Feagin's 12th-order method.", "Feagin12", "Explicit Runge-Kutta Method. ", + """@article{feagin2012high, + title={High-order explicit Runge-Kutta methods using m-symmetry}, + author={Feagin, Terry}, + year={2012}, + publisher={Neural, Parallel \\& Scientific Computations} + }""", + """ + - `stage_limiter!`: function of the form `limiter!(u, integrator, p, t)` + """, + """ + step_limiter! = OrdinaryDiffEq.trivial_limiter!, + """ +) Base.@kwdef struct Feagin12{StepLimiter} <: OrdinaryDiffEqAdaptiveAlgorithm step_limiter!::StepLimiter = trivial_limiter! end -""" -Feagin, T., “An Explicit Runge-Kutta Method of Order Fourteen,” Numerical -Algorithms, 2009 - -Feagin14: Explicit Runge-Kutta Method -Feagin's 14th-order Runge-Kutta method. -""" +@doc generic_solver_docstring( + "Feagin's 14th-order method.", "Feagin14", "Explicit Runge-Kutta Method. ", + """@article{feagin2009explicit, + title={An Explicit Runge-Kutta Method of Order Fourteen}, + author={Feagin, Terry}, + year={2009}, + publisher={Numerical Algorithms} + }""", + """ + - `stage_limiter!`: function of the form `limiter!(u, integrator, p, t)` + """, + """ + step_limiter! = OrdinaryDiffEq.trivial_limiter!, + """ +) Base.@kwdef struct Feagin14{StepLimiter} <: OrdinaryDiffEqAdaptiveAlgorithm step_limiter!::StepLimiter = trivial_limiter! end From 336c515d6bf3dfaaaa34cd1dc7f29370bad29263 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 07:56:19 +0200 Subject: [PATCH 10/83] add Euler --- docs/src/explicit/LowOrderRK.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/explicit/LowOrderRK.md b/docs/src/explicit/LowOrderRK.md index ed13d76aec..39d48a1438 100644 --- a/docs/src/explicit/LowOrderRK.md +++ b/docs/src/explicit/LowOrderRK.md @@ -16,6 +16,7 @@ first_steps("OrdinaryDiffEqLowOrderRK", "BS3") ## Full list of solvers ```@docs +Euler Heun Ralston Midpoint From 68a9c6ae440b659dcb3a14406261fea20b6e6114 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 08:13:50 +0200 Subject: [PATCH 11/83] docs LowStorageRK --- docs/make.jl | 3 +- docs/src/explicit/LowStorageRK.md | 57 +++++++++++++++++++ .../src/algorithms.jl | 35 ++++++++---- 3 files changed, 84 insertions(+), 11 deletions(-) create mode 100644 docs/src/explicit/LowStorageRK.md diff --git a/docs/make.jl b/docs/make.jl index 71e81e603d..3711bf2109 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -36,7 +36,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/LowOrderRK.md", "explicit/HighOrderRK.md", "explicit/Verner.md", - "explicit/Feagin.md" + "explicit/Feagin.md", + "explicit/LowStorageRK.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", diff --git a/docs/src/explicit/LowStorageRK.md b/docs/src/explicit/LowStorageRK.md new file mode 100644 index 0000000000..1e99da02fb --- /dev/null +++ b/docs/src/explicit/LowStorageRK.md @@ -0,0 +1,57 @@ +# OrdinaryDiffEqLowStorageRK + +Solvers specialized on certain PDE types. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqLowStorageRK", "CarpenterKennedy2N54") +``` + +## Full list of solvers + +```@docs +ORK256 +DGLDDRK73_C +CarpenterKennedy2N54 +NDBLSRK124 +NDBLSRK144 +CFRLDDRK64 +TSLDDRK74 +DGLDDRK84_C +DGLDDRK84_F +SHLDDRK64 +RK46NL +ParsaniKetchesonDeconinck3S32 +ParsaniKetchesonDeconinck3S82 +ParsaniKetchesonDeconinck3S53 +ParsaniKetchesonDeconinck3S173 +ParsaniKetchesonDeconinck3S94 +ParsaniKetchesonDeconinck3S184 +ParsaniKetchesonDeconinck3S105 +ParsaniKetchesonDeconinck3S205 +CKLLSRK43_2 +CKLLSRK54_3C +CKLLSRK95_4S +CKLLSRK95_4C +CKLLSRK95_4M +CKLLSRK54_3C_3R +CKLLSRK54_3M_3R +CKLLSRK54_3N_3R +CKLLSRK85_4C_3R +CKLLSRK85_4M_3R +CKLLSRK85_4P_3R +CKLLSRK54_3N_4R +CKLLSRK54_3M_4R +CKLLSRK65_4M_4R +CKLLSRK85_4FM_4R +CKLLSRK75_4M_5R +RDPK3Sp35 +RDPK3SpFSAL35 +RDPK3Sp49 +RDPK3SpFSAL49 +RDPK3Sp510 +RDPK3SpFSAL510 +HSLDDRK64 +NDBLSRK134 +KYK2014DGSSPRK_3S2 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl index d0f69f7711..bbcabc2034 100644 --- a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl @@ -1,5 +1,5 @@ @doc explicit_rk_docstring( - "A second-order, five-stage explicit Runge-Kutta method for wave propagation + "A second-order, five-stage method for wave propagation equations. Fixed timestep only.", "ORK256", references = "Matteo Bernardini, Sergio Pirozzoli. A General Strategy for the Optimization of Runge-Kutta Schemes for Wave @@ -78,7 +78,7 @@ function SHLDDRK52(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A fourth-order, five-stage explicit low-storage method of Carpenter and Kennedy + "A fourth-order, five-stage low-storage method of Carpenter and Kennedy (free 3rd order Hermite interpolant). Fixed timestep only. Designed for hyperbolic PDEs (stability properties).", "CarpenterKennedy2N54", @@ -251,7 +251,7 @@ function DGLDDRK84_F(stage_limiter!, step_limiter! = trivial_limiter!; end @doc explicit_rk_docstring( - "A fourth-order, six-stage explicit low-storage method. Fixed timestep only.", + "A fourth-order, six-stage low-storage method. Fixed timestep only.", "SHLDDRK64", references = "D. Stanescu, W. G. Habashi. 2N-Storage Low Dissipation and Dispersion Runge-Kutta Schemes for Computational @@ -737,7 +737,7 @@ function CKLLSRK75_4M_5R(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A third-order, five-stage explicit Runge-Kutta method with embedded error estimator + "A third-order, five-stage method with embedded error estimator designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3Sp35", references = "Ranocha, Dalcin, Parsani, Ketcheson (2021) @@ -757,7 +757,7 @@ function RDPK3Sp35(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A third-order, five-stage explicit Runge-Kutta method with embedded error estimator + "A third-order, five-stage method with embedded error estimator using the FSAL property designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3SpFSAL35", @@ -779,7 +779,7 @@ function RDPK3SpFSAL35(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A fourth-order, nine-stage explicit Runge-Kutta method with embedded error estimator + "A fourth-order, nine-stage method with embedded error estimator designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3Sp49", references = "Ranocha, Dalcin, Parsani, Ketcheson (2021) @@ -799,7 +799,7 @@ function RDPK3Sp49(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A fourth-order, nine-stage explicit Runge-Kutta method with embedded error estimator + "A fourth-order, nine-stage method with embedded error estimator using the FSAL property designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3SpFSAL49", @@ -821,7 +821,7 @@ function RDPK3SpFSAL49(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A fifth-order, ten-stage explicit Runge-Kutta method with embedded error estimator + "A fifth-order, ten-stage method with embedded error estimator designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3Sp510", references = "Ranocha, Dalcin, Parsani, Ketcheson (2021) @@ -841,7 +841,7 @@ function RDPK3Sp510(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "A fifth-order, ten-stage explicit Runge-Kutta method with embedded error estimator + "A fifth-order, ten-stage method with embedded error estimator using the FSAL property designed for spectral element discretizations of compressible fluid mechanics.", "RDPK3SpFSAL510", @@ -914,4 +914,19 @@ function NDBLSRK134(stage_limiter!, step_limiter! = trivial_limiter!; williamson_condition) end -#SSP Optimized Runge-Kutta Methods \ No newline at end of file +#SSP Optimized Runge-Kutta Methods + +@doc explicit_rk_docstring("To be done", + "KYK2014DGSSPRK_3S2") +Base.@kwdef struct KYK2014DGSSPRK_3S2{StageLimiter, StepLimiter, Thread} <: + OrdinaryDiffEqAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() +end +# for backwards compatibility +function KYK2014DGSSPRK_3S2(stage_limiter!, step_limiter! = trivial_limiter!) + KYK2014DGSSPRK_3S2(stage_limiter!, + step_limiter!, + False()) +end From 5a24e104b9113a1ecd7c086fd9c234dac4ee38be Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 08:19:26 +0200 Subject: [PATCH 12/83] finish RKM docstring --- lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index a953ffb364..0a0bdc1289 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -273,7 +273,20 @@ function FRK65(stage_limiter!, step_limiter! = trivial_limiter!; omega = 0.0) FRK65(stage_limiter!, step_limiter!, False(), omega) end -@doc explicit_rk_docstring("To be done", "RKM") +@doc explicit_rk_docstring("""Method designed to have good stability properties + when applied to pseudospectral discretizations + of hyperbolic partial differential equaitons.""", + "RKM", + references = """@article{mead1999optimal, + title={Optimal Runge--Kutta methods for first order pseudospectral operators}, + author={Mead, JL and Renaut, RA}, + journal={Journal of Computational Physics}, + volume={152}, + number={1}, + pages={404--419}, + year={1999}, + publisher={Elsevier} + }""") Base.@kwdef struct RKM{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! From 3dca8f7e85c1493ebdb22b6d59cd9d4b1081c883 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 12:06:51 +0200 Subject: [PATCH 13/83] docs SSPRK --- docs/make.jl | 3 ++- docs/src/explicit/SSPRK.md | 32 +++++++++++++++++++++++ lib/OrdinaryDiffEqSSPRK/src/algorithms.jl | 21 +++++++++++---- 3 files changed, 50 insertions(+), 6 deletions(-) create mode 100644 docs/src/explicit/SSPRK.md diff --git a/docs/make.jl b/docs/make.jl index 3711bf2109..be4528df23 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -37,7 +37,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/HighOrderRK.md", "explicit/Verner.md", "explicit/Feagin.md", - "explicit/LowStorageRK.md" + "explicit/LowStorageRK.md", + "explicit/SSPRK.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", diff --git a/docs/src/explicit/SSPRK.md b/docs/src/explicit/SSPRK.md new file mode 100644 index 0000000000..af98e6b704 --- /dev/null +++ b/docs/src/explicit/SSPRK.md @@ -0,0 +1,32 @@ +# OrdinaryDiffEqSSPRK + +Solvers specialized on certain PDE types. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqSSPRK", "SSPRK22") +``` + +## Full list of solvers + +```@docs +SSPRK22 +SSPRK33 +SSPRK53 +KYKSSPRK42 +SSPRK53_2N1 +SSPRK53_2N2 +SSPRK53_H +SSPRK63 +SSPRK73 +SSPRK83 +SSPRK43 +SSPRK432 +SSPRKMSVS43 +SSPRKMSVS32 +SSPRK932 +SSPRK54 +SSPRK104 +SHLDDRK_2N +SHLDDRK52 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl index efe6a1ef75..84da2be50b 100644 --- a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl @@ -320,7 +320,20 @@ function SSPRK33(stage_limiter!, step_limiter! = trivial_limiter!) step_limiter!, False()) end -@doc explicit_rk_docstring("TBD", +@doc explicit_rk_docstring("To be done", "SHLDDRK_2N") +Base.@kwdef struct SHLDDRK_2N{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() +end +# for backwards compatibility +function SHLDDRK_2N(stage_limiter!, step_limiter! = trivial_limiter!) + SHLDDRK_2N(stage_limiter!, + step_limiter!, + False()) +end + +@doc explicit_rk_docstring("To be done", "KYKSSPRK42") Base.@kwdef struct KYKSSPRK42{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -334,10 +347,8 @@ function KYKSSPRK42(stage_limiter!, step_limiter! = trivial_limiter!) False()) end -@doc explicit_rk_docstring("TBD", - "KYK2014DGSSPRK_3S2") -Base.@kwdef struct KYK2014DGSSPRK_3S2{StageLimiter, StepLimiter, Thread} <: - OrdinaryDiffEqAlgorithm +@doc explicit_rk_docstring("To be done", "SHLDDRK52") +Base.@kwdef struct SHLDDRK52{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() From 21db9748e1bd38c3e98a0c6a240b14facab99b39 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 23:35:47 +0200 Subject: [PATCH 14/83] docs AdamsBashforthMoulton --- docs/make.jl | 4 +- docs/src/explicit/AdamsBashforthMoulton.md | 26 +++ .../OrdinaryDiffEqAdamsBashforthMoulton.jl | 1 + .../src/algorithms.jl | 207 +++++++++--------- lib/OrdinaryDiffEqCore/src/doc_utils.jl | 14 +- 5 files changed, 134 insertions(+), 118 deletions(-) create mode 100644 docs/src/explicit/AdamsBashforthMoulton.md diff --git a/docs/make.jl b/docs/make.jl index be4528df23..0b498eaa24 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -20,6 +20,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, OrdinaryDiffEq.OrdinaryDiffEqVerner, + OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, OrdinaryDiffEq.OrdinaryDiffEqDefault, @@ -38,7 +39,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Verner.md", "explicit/Feagin.md", "explicit/LowStorageRK.md", - "explicit/SSPRK.md" + "explicit/SSPRK.md", + "explicit/AdamsBashforthMoulton.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", diff --git a/docs/src/explicit/AdamsBashforthMoulton.md b/docs/src/explicit/AdamsBashforthMoulton.md new file mode 100644 index 0000000000..5623a7c43c --- /dev/null +++ b/docs/src/explicit/AdamsBashforthMoulton.md @@ -0,0 +1,26 @@ +# OrdinaryDiffEqAdamsBashforthMoulton + +Multistep methods, useful for integrating a very expensive to evaluate non-stiff system of differential equations. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqAdamsBashforthMoulton", "VCABM") +``` + +## Full list of solvers + +```@docs +AB3 +AB4 +AB5 +ABM32 +ABM43 +ABM54 +VCAB3 +VCAB4 +VCAB5 +VCABM3 +VCABM4 +VCABM5 +VCABM +``` diff --git a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/OrdinaryDiffEqAdamsBashforthMoulton.jl b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/OrdinaryDiffEqAdamsBashforthMoulton.jl index 2b86ce4923..070524d8a3 100644 --- a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/OrdinaryDiffEqAdamsBashforthMoulton.jl +++ b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/OrdinaryDiffEqAdamsBashforthMoulton.jl @@ -8,6 +8,7 @@ import OrdinaryDiffEqCore: OrdinaryDiffEqMutableCache, OrdinaryDiffEqConstantCac OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm, constvalue, calculate_residuals, calculate_residuals!, trivial_limiter!, get_fsalfirstlast, + generic_solver_docstring, full_cache import OrdinaryDiffEqLowOrderRK: BS3ConstantCache, BS3Cache, RK4ConstantCache, RK4Cache import RecursiveArrayTools: recursivefill! diff --git a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl index b2125d68d9..44f390c432 100644 --- a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl +++ b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl @@ -1,139 +1,128 @@ # Adams Bashforth and Adams moulton methods - -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -AB3: Adams-Bashforth Explicit Method -The 3-step third order multistep method. Ralston's Second Order Method is used to calculate starting values. -""" +reference = """E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff + Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: + https://doi.org/10.1007/978-3-540-78862-1""" + +@doc generic_solver_docstring("The 3-step third order multistep method. + Ralston's Second Order Method is used to calculate starting values.", + "AB3", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct AB3 <: OrdinaryDiffEqAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -AB4: Adams-Bashforth Explicit Method -The 4-step fourth order multistep method. Runge-Kutta method of order 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("The 4-step fourth order multistep method. + Runge-Kutta method of order 4 is used to calculate starting values.", + "AB4", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct AB4 <: OrdinaryDiffEqAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -AB5: Adams-Bashforth Explicit Method -The 3-step third order multistep method. Ralston's Second Order Method is used to calculate starting values. -""" +@doc generic_solver_docstring("The 3-step third order multistep method. + Ralston's Second Order Method is used to calculate starting values.", + "AB5", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct AB5 <: OrdinaryDiffEqAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -ABM32: Adams-Bashforth Explicit Method -It is third order method. In ABM32, AB3 works as predictor and Adams Moulton 2-steps method works as Corrector. -Ralston's Second Order Method is used to calculate starting values. -""" +@doc generic_solver_docstring("It is third order method. + In ABM32, AB3 works as predictor and Adams Moulton 2-steps method works as Corrector. + Ralston's Second Order Method is used to calculate starting values.", + "ABM32", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct ABM32 <: OrdinaryDiffEqAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -ABM43: Adams-Bashforth Explicit Method -It is fourth order method. In ABM43, AB4 works as predictor and Adams Moulton 3-steps method works as Corrector. -Runge-Kutta method of order 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("It is fourth order method. + In ABM43, AB4 works as predictor and Adams Moulton 3-steps method works as Corrector. + Runge-Kutta method of order 4 is used to calculate starting values.", + "ABM43", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct ABM43 <: OrdinaryDiffEqAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -ABM54: Adams-Bashforth Explicit Method -It is fifth order method. In ABM54, AB5 works as predictor and Adams Moulton 4-steps method works as Corrector. -Runge-Kutta method of order 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("It is fifth order method. + In ABM54, AB5 works as predictor and Adams Moulton 4-steps method works as Corrector. + Runge-Kutta method of order 4 is used to calculate starting values.", + "ABM54", + "Adams-Bashforth Explicit Method", + reference, + "", + "") struct ABM54 <: OrdinaryDiffEqAlgorithm end # Variable Step Size Adams methods -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCAB3: Adaptive step size Adams explicit Method -The 3rd order Adams method. Bogacki-Shampine 3/2 method is used to calculate starting values. -""" +@doc generic_solver_docstring("The 3rd order Adams method. + Bogacki-Shampine 3/2 method is used to calculate starting values.", + "VCAB3", + "Adams explicit Method", + reference, + "", + "") struct VCAB3 <: OrdinaryDiffEqAdaptiveAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCAB4: Adaptive step size Adams explicit Method -The 4th order Adams method. Runge-Kutta 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("The 4th order Adams method. + Runge-Kutta 4 is used to calculate starting values.", + "VCAB4", + "Adams explicit Method", + reference, + "", + "") struct VCAB4 <: OrdinaryDiffEqAdaptiveAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCAB5: Adaptive step size Adams explicit Method -The 5th order Adams method. Runge-Kutta 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("The 5th order Adams method. + Runge-Kutta 4 is used to calculate starting values.", + "VCAB5", + "Adams explicit Method", + reference, + "", + "") struct VCAB5 <: OrdinaryDiffEqAdaptiveAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCABM3: Adaptive step size Adams explicit Method -The 3rd order Adams-Moulton method. Bogacki-Shampine 3/2 method is used to calculate starting values. -""" +@doc generic_solver_docstring("The 3rd order Adams-Moulton method. + Bogacki-Shampine 3/2 method is used to calculate starting values.", + "VCABM3", + "Adams explicit Method", + reference, + "", + "") struct VCABM3 <: OrdinaryDiffEqAdaptiveAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCABM4: Adaptive step size Adams explicit Method -The 4th order Adams-Moulton method. Runge-Kutta 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("The 4th order Adams-Moulton method. + Runge-Kutta 4 is used to calculate starting values.", + "VCABM4", + "Adams explicit Method", + reference, + "", + "") struct VCABM4 <: OrdinaryDiffEqAdaptiveAlgorithm end -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCABM5: Adaptive step size Adams explicit Method -The 5th order Adams-Moulton method. Runge-Kutta 4 is used to calculate starting values. -""" +@doc generic_solver_docstring("The 5th order Adams-Moulton method. + Runge-Kutta 4 is used to calculate starting values.", + "VCABM5", + "Adams explicit Method", + reference, + "", + "") struct VCABM5 <: OrdinaryDiffEqAdaptiveAlgorithm end # Variable Order and Variable Step Size Adams methods -""" -E. Hairer, S. P. Norsett, G. Wanner, Solving Ordinary Differential Equations I, Nonstiff -Problems. Computational Mathematics (2nd revised ed.), Springer (1996) doi: -https://doi.org/10.1007/978-3-540-78862-1 - -VCABM: Adaptive step size Adams explicit Method -An adaptive order adaptive time Adams Moulton method. -It uses an order adaptivity algorithm is derived from Shampine's DDEABM. -""" +@doc generic_solver_docstring("An adaptive order adaptive time Adams Moulton method. + It uses an order adaptivity algorithm is derived from Shampine's DDEABM.", + "VCABM", + "adaptive order Adams explicit Method", + reference, + "", + "") struct VCABM <: OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm end diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index 8dbcf36feb..033889193c 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -34,14 +34,12 @@ function generic_solver_docstring(description::String, ``` $solver_class - """ : - """ - ```julia - $name() - ``` - - $solver_class - """ + """ : """ + ```julia + $name() + ``` + $solver_class + """ keyword_docstring = """ From 539f9f33e72c0a6cf74def8894da279ee90ac7e3 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 11 Aug 2024 23:36:44 +0200 Subject: [PATCH 15/83] format --- docs/src/explicit/Feagin.md | 4 ++-- docs/src/explicit/HighOrderRK.md | 2 +- docs/src/explicit/LowStorageRK.md | 2 +- docs/src/explicit/SSPRK.md | 2 +- docs/src/explicit/Verner.md | 4 ++-- lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl | 9 ++++++--- 6 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/src/explicit/Feagin.md b/docs/src/explicit/Feagin.md index daca5e2f1b..53f4f91da9 100644 --- a/docs/src/explicit/Feagin.md +++ b/docs/src/explicit/Feagin.md @@ -1,7 +1,7 @@ # OrdinaryDiffEqFeagin Preferred solvers for non-stiff problems at very low tolerance, `<1e-30`. -Best combined with preciser than `Float64` number types for the state, such as the `BigFloat` number type. +Best combined with preciser than `Float64` number types for the state, such as the `BigFloat` number type. ```@eval first_steps = evalfile("./common_first_steps.jl") @@ -14,4 +14,4 @@ first_steps("OrdinaryDiffEqFeagin", "Feagin14") Feagin10 Feagin12 Feagin14 -``` \ No newline at end of file +``` diff --git a/docs/src/explicit/HighOrderRK.md b/docs/src/explicit/HighOrderRK.md index 69a88fd280..e509405580 100644 --- a/docs/src/explicit/HighOrderRK.md +++ b/docs/src/explicit/HighOrderRK.md @@ -1,7 +1,7 @@ # OrdinaryDiffEqHighOrderRK Solvers for non-stiff problems at low tolerance. -However, the solvers in [`OrdinaryDiffEqVerner`](@ref OrdinaryDiffEqVerner) generally perform better at low tolerances. +However, the solvers in [`OrdinaryDiffEqVerner`](@ref OrdinaryDiffEqVerner) generally perform better at low tolerances. ```@eval first_steps = evalfile("./common_first_steps.jl") diff --git a/docs/src/explicit/LowStorageRK.md b/docs/src/explicit/LowStorageRK.md index 1e99da02fb..1404b1df19 100644 --- a/docs/src/explicit/LowStorageRK.md +++ b/docs/src/explicit/LowStorageRK.md @@ -54,4 +54,4 @@ RDPK3SpFSAL510 HSLDDRK64 NDBLSRK134 KYK2014DGSSPRK_3S2 -``` \ No newline at end of file +``` diff --git a/docs/src/explicit/SSPRK.md b/docs/src/explicit/SSPRK.md index af98e6b704..8756eb785f 100644 --- a/docs/src/explicit/SSPRK.md +++ b/docs/src/explicit/SSPRK.md @@ -29,4 +29,4 @@ SSPRK54 SSPRK104 SHLDDRK_2N SHLDDRK52 -``` \ No newline at end of file +``` diff --git a/docs/src/explicit/Verner.md b/docs/src/explicit/Verner.md index 3654f9b729..21425524be 100644 --- a/docs/src/explicit/Verner.md +++ b/docs/src/explicit/Verner.md @@ -3,7 +3,7 @@ Preferred solvers for non-stiff problems at low tolerance. `Vern6`, `Vern7`, or `Vern8` are good methods for tolerances between `~1e-8-1e-12`, and using `Float64` numbers for the state of the differential equation. -For even lower tolerances,`Vern9` should be used, combined with the more precise `BigFloat` number type. +For even lower tolerances,`Vern9` should be used, combined with the more precise `BigFloat` number type. ```@eval first_steps = evalfile("./common_first_steps.jl") @@ -24,4 +24,4 @@ AutoVern6 AutoVern7 AutoVern8 AutoVern9 -``` \ No newline at end of file +``` diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index 0a0bdc1289..586da781c0 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -411,7 +411,8 @@ end volume={44}, pages={5210 - 5216} }") -Base.@kwdef struct SIR54{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm +Base.@kwdef struct SIR54{StageLimiter, StepLimiter, Thread} <: + OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() @@ -436,7 +437,8 @@ end title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, journal = {Computational Mathematics and Mathematical Physics} }") -Base.@kwdef struct Alshina2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm +Base.@kwdef struct Alshina2{StageLimiter, StepLimiter, Thread} <: + OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() @@ -461,7 +463,8 @@ end title = {Optimal first- to sixth-order accurate Runge-Kutta schemes}, journal = {Computational Mathematics and Mathematical Physics} }") -Base.@kwdef struct Alshina3{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm +Base.@kwdef struct Alshina3{StageLimiter, StepLimiter, Thread} <: + OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() From 7e8e5ac89586451fd2b98834e51149320bb7ed0c Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 04:56:06 +0200 Subject: [PATCH 16/83] fix AB5 docstring --- lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl index 44f390c432..af35c61140 100644 --- a/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl +++ b/lib/OrdinaryDiffEqAdamsBashforthMoulton/src/algorithms.jl @@ -20,9 +20,8 @@ struct AB3 <: OrdinaryDiffEqAlgorithm end "", "") struct AB4 <: OrdinaryDiffEqAlgorithm end - -@doc generic_solver_docstring("The 3-step third order multistep method. - Ralston's Second Order Method is used to calculate starting values.", +@doc generic_solver_docstring("The 5-step fifth order multistep method. + Ralston's 3rd order Runge-Kutta method is used to calculate starting values.", "AB5", "Adams-Bashforth Explicit Method", reference, From a52c2e95481b2a497e6d9f15a202ab0d0b38b9f1 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 05:14:39 +0200 Subject: [PATCH 17/83] finish some SSPRK docstrings --- lib/OrdinaryDiffEqSSPRK/src/algorithms.jl | 33 ++++++++++++++++++++--- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl index 84da2be50b..8f9ee62222 100644 --- a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl @@ -320,7 +320,16 @@ function SSPRK33(stage_limiter!, step_limiter! = trivial_limiter!) step_limiter!, False()) end -@doc explicit_rk_docstring("To be done", "SHLDDRK_2N") +@doc explicit_rk_docstring("Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", "SHLDDRK_2N", + references = "@article{stanescu19982n, + title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, + author={Stanescu, D and Habashi, WG}, + journal={Journal of Computational Physics}, + volume={143}, + number={2}, + pages={674--681}, + year={1998}, + publisher={Elsevier}}") Base.@kwdef struct SHLDDRK_2N{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! @@ -333,8 +342,15 @@ function SHLDDRK_2N(stage_limiter!, step_limiter! = trivial_limiter!) False()) end -@doc explicit_rk_docstring("To be done", - "KYKSSPRK42") +@doc explicit_rk_docstring("Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", "KYKSSPRK42", + references = "@article{kubatko2014optimal, + title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, + author={Kubatko, Ethan J and Yeager, Benjamin A and Ketcheson, David I}, + journal={Journal of Scientific Computing}, + volume={60}, + pages={313--344}, + year={2014}, + publisher={Springer}}") Base.@kwdef struct KYKSSPRK42{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! @@ -347,7 +363,16 @@ function KYKSSPRK42(stage_limiter!, step_limiter! = trivial_limiter!) False()) end -@doc explicit_rk_docstring("To be done", "SHLDDRK52") +@doc explicit_rk_docstring("Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", "SHLDDRK52", + references = "@article{stanescu19982n, + title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, + author={Stanescu, D and Habashi, WG}, + journal={Journal of Computational Physics}, + volume={143}, + number={2}, + pages={674--681}, + year={1998}, + publisher={Elsevier}}") Base.@kwdef struct SHLDDRK52{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! From 87bb3f1eed902986155775134728740bb5bb0fdf Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 05:15:08 +0200 Subject: [PATCH 18/83] start Nordsieck documentation --- docs/make.jl | 4 +++- docs/src/explicit/Nordsieck.md | 15 +++++++++++++++ .../src/OrdinaryDiffEqNordsieck.jl | 1 + lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 10 ++++++---- 4 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 docs/src/explicit/Nordsieck.md diff --git a/docs/make.jl b/docs/make.jl index 0b498eaa24..3738d6668a 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -21,6 +21,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, OrdinaryDiffEq.OrdinaryDiffEqVerner, OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, + OrdinaryDiffEq.OrdinaryDiffEqNordsieck, OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, OrdinaryDiffEq.OrdinaryDiffEqDefault, @@ -40,7 +41,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Feagin.md", "explicit/LowStorageRK.md", "explicit/SSPRK.md", - "explicit/AdamsBashforthMoulton.md" + "explicit/AdamsBashforthMoulton.md", + "explicit/Nordsieck.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", diff --git a/docs/src/explicit/Nordsieck.md b/docs/src/explicit/Nordsieck.md new file mode 100644 index 0000000000..d1cee56917 --- /dev/null +++ b/docs/src/explicit/Nordsieck.md @@ -0,0 +1,15 @@ +# OrdinaryDiffEqNordsieck + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqNordsieck", "AN5") +``` + +## Full list of solvers + +```@docs +AN5 +``` +`JVODE` still needs to be properly documented. \ No newline at end of file diff --git a/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl b/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl index ae0b0ea0d1..a8c9280efa 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl @@ -11,6 +11,7 @@ import OrdinaryDiffEqCore: alg_order, alg_adaptive_order, qsteady_max_default, calculate_residuals, calculate_residuals!, get_current_adaptive_order, get_fsalfirstlast, ode_interpolant, ode_interpolant!, trivial_limiter! + generic_solver_docstring using MuladdMacro, FastBroadcast, RecursiveArrayTools import LinearAlgebra: rmul! import Static: False diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index 37aa0ced98..80805dbc88 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -1,8 +1,10 @@ # Adams/BDF methods in Nordsieck forms -""" -AN5: Adaptive step size Adams explicit Method -An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form. -""" +@doc generic_solver_docstring("An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form.", + "AN5", + "Adaptive step size Adams explicit Method", + "", + "", + "") struct AN5 <: OrdinaryDiffEqAdaptiveAlgorithm end struct JVODE{bType, aType} <: OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm algorithm::Symbol From e0d8eacc6cca3bb3a63f99aa922763450a567510 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 06:26:46 +0200 Subject: [PATCH 19/83] Add warnings for JVODE --- docs/src/explicit/Nordsieck.md | 4 +++- lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 12 ++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/src/explicit/Nordsieck.md b/docs/src/explicit/Nordsieck.md index d1cee56917..e38b8f10a6 100644 --- a/docs/src/explicit/Nordsieck.md +++ b/docs/src/explicit/Nordsieck.md @@ -11,5 +11,7 @@ first_steps("OrdinaryDiffEqNordsieck", "AN5") ```@docs AN5 +JVODE +JVODE_Adams +JVODE_BDF ``` -`JVODE` still needs to be properly documented. \ No newline at end of file diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index 80805dbc88..ef257fd507 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -6,6 +6,10 @@ "", "") struct AN5 <: OrdinaryDiffEqAdaptiveAlgorithm end +""" +!!! warning "Experimental" + `JVODE` is experimental, the solver `FBDF` is generally preferred. +""" struct JVODE{bType, aType} <: OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm algorithm::Symbol bias1::bType @@ -18,5 +22,13 @@ function JVODE(algorithm = :Adams; bias1 = 6, bias2 = 6, bias3 = 10, addon = 1 // 10^6) JVODE(algorithm, bias1, bias2, bias3, addon) end +""" +!!! warning "Experimental" + `JVODE` is experimental, the solver `FBDF` is generally preferred. +""" JVODE_Adams(; kwargs...) = JVODE(:Adams; kwargs...) +""" +!!! warning "Experimental" + `JVODE` is experimental, the solver `FBDF` is generally preferred. +""" JVODE_BDF(; kwargs...) = JVODE(:BDF; kwargs...) From f397f99fe9d3f08e7c4b243b1e43faaa27991588 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 11:39:53 +0200 Subject: [PATCH 20/83] docs RKN --- docs/make.jl | 2 + docs/src/misc/RKN.md | 30 ++ .../src/OrdinaryDiffEqRKN.jl | 1 + lib/OrdinaryDiffEqRKN/src/algorithms.jl | 510 +++++++----------- 4 files changed, 235 insertions(+), 308 deletions(-) create mode 100644 docs/src/misc/RKN.md diff --git a/docs/make.jl b/docs/make.jl index 3738d6668a..a5b3967b50 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -22,6 +22,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqVerner, OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, OrdinaryDiffEq.OrdinaryDiffEqNordsieck, + OrdinaryDiffEq.OrdinaryDiffEqRKN, OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, OrdinaryDiffEq.OrdinaryDiffEqDefault, @@ -44,6 +45,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/AdamsBashforthMoulton.md", "explicit/Nordsieck.md" ], + "Misc solvers" => ["misc/RKN.md"], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicitrk.md", "nonstiff/lowstorage_ssprk.md", diff --git a/docs/src/misc/RKN.md b/docs/src/misc/RKN.md new file mode 100644 index 0000000000..29f8fd755f --- /dev/null +++ b/docs/src/misc/RKN.md @@ -0,0 +1,30 @@ +# OrdinaryDiffEqRKN + +Second order solvers. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqRKN", "Nystrom4") +``` + +## Full list of solvers + +```@docs +IRKN3 +IRKN4 +Nystrom4 +Nystrom4VelocityIndependent +Nystrom5VelocityIndependent +FineRKN4 +FineRKN5 +DPRKN4 +DPRKN5 +DPRKN6 +DPRKN6FM +DPRKN8 +DPRKN12 +ERKN4 +ERKN5 +ERKN7 +RKN4 +``` diff --git a/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl b/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl index 4385ace2a7..b86dbc96ef 100644 --- a/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl +++ b/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl @@ -12,6 +12,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, constvalue, _unwrap_val, _ode_interpolant, get_fsalfirstlast, trivial_limiter!, _ode_interpolant!, _ode_addsteps! + generic_solver_docstring using FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools using DiffEqBase: @def, @tight_loop_macros import OrdinaryDiffEqCore diff --git a/lib/OrdinaryDiffEqRKN/src/algorithms.jl b/lib/OrdinaryDiffEqRKN/src/algorithms.jl index 7c9de04976..f072820973 100644 --- a/lib/OrdinaryDiffEqRKN/src/algorithms.jl +++ b/lib/OrdinaryDiffEqRKN/src/algorithms.jl @@ -1,341 +1,235 @@ -""" - IRKN3 - -Improved Runge-Kutta-Nyström method of order three, which minimizes the amount of evaluated functions in each step. Fixed time steps only. - -Second order ODE should not depend on the first derivative. - -## References - -@article{rabiei2012numerical, -title={Numerical Solution of Second-Order Ordinary Differential Equations by Improved Runge-Kutta Nystrom Method}, -author={Rabiei, Faranak and Ismail, Fudziah and Norazak, S and Emadi, Saeid}, -publisher={Citeseer} -} -""" +@doc generic_solver_docstring("Method of order three, which minimizes the amount of evaluated functions in each step. Fixed time steps only. + Second order ODE should not depend on the first derivative.", + "IRKN3", + "Improved Runge-Kutta-Nyström method", + "@article{rabiei2012numerical, + title={Numerical Solution of Second-Order Ordinary Differential Equations by Improved Runge-Kutta Nystrom Method}, + author={Rabiei, Faranak and Ismail, Fudziah and Norazak, S and Emadi, Saeid}, + publisher={Citeseer}}", "", "") struct IRKN3 <: OrdinaryDiffEqPartitionedAlgorithm end -""" - Nystrom4 - -A 4th order explicit Runge-Kutta-Nyström method which can be applied directly on second order ODEs. Can only be used with fixed time steps. - -In case the ODE Problem is not dependent on the first derivative consider using -[`Nystrom4VelocityIndependent`](@ref) to increase performance. - -## References - -E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. -Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, -Springer-Verlag. -""" +@doc generic_solver_docstring("A 4th order explicit method which can be applied directly on second order ODEs. + Can only be used with fixed time steps. + In case the ODE Problem is not dependent on the first derivative consider using + [`Nystrom4VelocityIndependent`](@ref) to increase performance.", + "Nystrom4", + "Improved Runge-Kutta-Nyström method", + "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.", "", "") struct Nystrom4 <: OrdinaryDiffEqPartitionedAlgorithm end -""" - FineRKN4() - -A 4th order explicit Runge-Kutta-Nyström method which can be applied directly to second order ODEs. -In particular, this method allows the acceleration equation to depend on the velocity. - -## References - -``` -@article{fine1987low, - title={Low order practical {R}unge-{K}utta-{N}ystr{\"o}m methods}, - author={Fine, Jerry Michael}, - journal={Computing}, - volume={38}, - number={4}, - pages={281--297}, - year={1987}, - publisher={Springer} -} -``` -""" +@doc generic_solver_docstring("A 4th order explicit method which can be applied directly to second order ODEs. + In particular, this method allows the acceleration equation to depend on the velocity.", + "FineRKN4", + "Improved Runge-Kutta-Nyström method", + "@article{fine1987low, + title={Low order practical {R}unge-{K}utta-{N}ystr{\"o}m methods}, + author={Fine, Jerry Michael}, + journal={Computing}, + volume={38}, + number={4}, + pages={281--297}, + year={1987}, + publisher={Springer}}", "", "") struct FineRKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - FineRKN5() - -A 5th order explicit Runge-Kutta-Nyström method which can be applied directly to second order ODEs. -In particular, this method allows the acceleration equation to depend on the velocity. - -## References - -``` -@article{fine1987low, - title={Low order practical {R}unge-{K}utta-{N}ystr{\"o}m methods}, - author={Fine, Jerry Michael}, - journal={Computing}, - volume={38}, - number={4}, - pages={281--297}, - year={1987}, - publisher={Springer} -} -``` -""" +@doc generic_solver_docstring("A 5th order explicit method which can be applied directly to second order ODEs. + In particular, this method allows the acceleration equation to depend on the velocity.", + "FineRKN5", + "Improved Runge-Kutta-Nyström method", + "@article{fine1987low, + title={Low order practical {R}unge-{K}utta-{N}ystr{\"o}m methods}, + author={Fine, Jerry Michael}, + journal={Computing}, + volume={38}, + number={4}, + pages={281--297}, + year={1987}, + publisher={Springer}}", "", "") struct FineRKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - Nystrom4VelocityIdependent - -A 4th order explicit Runkge-Kutta-Nyström method. Used directly on second order ODEs, where the acceleration is independent from velocity (ODE Problem is not dependent on the first derivative). - -More efficient then [`Nystrom4`](@ref) on velocity independent problems, since less evaluations are needed. - -Fixed time steps only. - -## References - -E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. -Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, -Springer-Verlag. -""" +@doc generic_solver_docstring("A 4th order explicit method. + Used directly on second order ODEs, where the acceleration is independent from velocity + (ODE Problem is not dependent on the first derivative).", + "Nystrom4VelocityIndependent", + "Improved Runge-Kutta-Nyström method", + "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.", "", "") struct Nystrom4VelocityIndependent <: OrdinaryDiffEqPartitionedAlgorithm end -""" - IRKN4 - -Improves Runge-Kutta-Nyström method of order four, which minimizes the amount of evaluated functions in each step. Fixed time steps only. - -Second order ODE should not be dependent on the first derivative. - -Recommended for smooth problems with expensive functions to evaluate. - -## References - -@article{rabiei2012numerical, -title={Numerical Solution of Second-Order Ordinary Differential Equations by Improved Runge-Kutta Nystrom Method}, -author={Rabiei, Faranak and Ismail, Fudziah and Norazak, S and Emadi, Saeid}, -publisher={Citeseer} -} -""" +@doc generic_solver_docstring("Improves Runge-Kutta-Nyström method of order four, + which minimizes the amount of evaluated functions in each step. + Fixed time steps only. + Second order ODE should not be dependent on the first derivative. + Recommended for smooth problems with expensive functions to evaluate.", + "IRKN4", + "Improved Runge-Kutta-Nyström method", + "@article{rabiei2012numerical, + title={Numerical Solution of Second-Order Ordinary Differential Equations by Improved Runge-Kutta Nystrom Method}, + author={Rabiei, Faranak and Ismail, Fudziah and Norazak, S and Emadi, Saeid}, + publisher={Citeseer}}", "", "") struct IRKN4 <: OrdinaryDiffEqPartitionedAlgorithm end -""" - Nystrom5VelocityIndependent - -A 5th order explicit Runkge-Kutta-Nyström method. Used directly on second order ODEs, where the acceleration is independent from velocity (ODE Problem is not dependent on the first derivative). -Fixed time steps only. - -## References - -E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. -Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, -Springer-Verlag. -""" +@doc generic_solver_docstring("A 5th order explicit method. + Used directly on second order ODEs, where the acceleration is independent from velocity + (ODE Problem is not dependent on the first derivative).", + "Nystrom5VelocityIndependent", + "Improved Runge-Kutta-Nyström method", + "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.", "", "") struct Nystrom5VelocityIndependent <: OrdinaryDiffEqPartitionedAlgorithm end -""" - DPRKN4 - -4th order explicit Runge-Kutta-Nyström methods. The second order ODE should not depend on the first derivative. - -## References - -@article{Dormand1987FamiliesOR, -title={Families of Runge-Kutta-Nystrom Formulae}, -author={J. R. Dormand and Moawwad E. A. El-Mikkawy and P. J. Prince}, -journal={Ima Journal of Numerical Analysis}, -year={1987}, -volume={7}, -pages={235-250} -} -""" +@doc generic_solver_docstring("4th order explicit method. + The second order ODE should not depend on the first derivative.", + "DPRKN4", + "Improved Runge-Kutta-Nyström method", + "@article{Dormand1987FamiliesOR, + title={Families of Runge-Kutta-Nystrom Formulae}, + author={J. R. Dormand and Moawwad E. A. El-Mikkawy and P. J. Prince}, + journal={Ima Journal of Numerical Analysis}, + year={1987}, + volume={7}, + pages={235-250}}", "", "") struct DPRKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - DPRKN5 - -5th order explicit Runge-Kutta-Nyström mehod. The second order ODE should not depend on the first derivative. - -## References - -@article{Bettis1973ARN, -title={A Runge-Kutta Nystrom algorithm}, -author={Dale G. Bettis}, -journal={Celestial mechanics}, -year={1973}, -volume={8}, -pages={229-233}, -publisher={Springer} -} -""" +@doc generic_solver_docstring("5th order explicit method. + The second order ODE should not depend on the first derivative.", + "DPRKN5", + "Improved Runge-Kutta-Nyström method", + "@article{Bettis1973ARN, + title={A Runge-Kutta Nystrom algorithm}, + author={Dale G. Bettis}, + journal={Celestial mechanics}, + year={1973}, + volume={8}, + pages={229-233}, + publisher={Springer}}", "", "") struct DPRKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - DPRKN6 - -6th order explicit Runge-Kutta-Nyström method. The second order ODE should not depend on the first derivative. Free 6th order interpolant. - -## References - -@article{dormand1987runge, -title={Runge-kutta-nystrom triples}, -author={Dormand, JR and Prince, PJ}, -journal={Computers \\& Mathematics with Applications}, -volume={13}, -number={12}, -pages={937--949}, -year={1987}, -publisher={Elsevier} -} -""" +@doc generic_solver_docstring("6th order explicit method. + The second order ODE should not depend on the first derivative. Free 6th order interpolant", + "DPRKN6", + "Improved Runge-Kutta-Nyström method", + "@article{Dormand1987FamiliesOR, + title={Families of Runge-Kutta-Nystrom Formulae}, + author={J. R. Dormand and Moawwad E. A. El-Mikkawy and P. J. Prince}, + journal={Ima Journal of Numerical Analysis}, + year={1987}, + volume={7}, + pages={235-250}}", "", "") struct DPRKN6 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - DPRKN6FM - -6th order explicit Runge-Kutta-Nyström method. The second order ODE should not depend on the first derivative. - -Compared to [`DPRKN6`](@ref), this method has smaller truncation error coefficients which leads to performance gain -when only the main solution points are considered. - -## References - -@article{Dormand1987FamiliesOR, -title={Families of Runge-Kutta-Nystrom Formulae}, -author={J. R. Dormand and Moawwad E. A. El-Mikkawy and P. J. Prince}, -journal={Ima Journal of Numerical Analysis}, -year={1987}, -volume={7}, -pages={235-250} -} -""" +@doc generic_solver_docstring("6th order explicit method. + The second order ODE should not depend on the first derivative. + Compared to [`DPRKN6`](@ref), this method has smaller truncation error coefficients + which leads to performance gain when only the main solution points are considered.", + "DPRKN6FM", + "Improved Runge-Kutta-Nyström method", + "@article{Dormand1987FamiliesOR, + title={Families of Runge-Kutta-Nystrom Formulae}, + author={J. R. Dormand and Moawwad E. A. El-Mikkawy and P. J. Prince}, + journal={Ima Journal of Numerical Analysis}, + year={1987}, + volume={7}, + pages={235-250}}", "", "") struct DPRKN6FM <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - DPRKN8 - -8th order explicit Runge-Kutta-Nyström method. The second order ODE should not depend on the first derivative. - -Not as efficient as [`DPRKN12`](@ref) when high accuracy is needed, however this solver is competitive with -[`DPRKN6`](@ref) at lax tolerances and, depending on the problem, might be a good option between performance and accuracy. - -## References - -@article{dormand1987high, -title={High-order embedded Runge-Kutta-Nystrom formulae}, -author={Dormand, JR and El-Mikkawy, MEA and Prince, PJ}, -journal={IMA Journal of Numerical Analysis}, -volume={7}, -number={4}, -pages={423--430}, -year={1987}, -publisher={Oxford University Press} -} -""" +@doc generic_solver_docstring("8th order explicit method. + The second order ODE should not depend on the first derivative. + Not as efficient as [`DPRKN12`](@ref) when high accuracy is needed, + however this solver is competitive with [`DPRKN6`](@ref) at lax tolerances and, + depending on the problem, might be a good option between performance and accuracy.", + "DPRKN8", + "Improved Runge-Kutta-Nyström method", + "@article{dormand1987high, + title={High-order embedded Runge-Kutta-Nystrom formulae}, + author={Dormand, JR and El-Mikkawy, MEA and Prince, PJ}, + journal={IMA Journal of Numerical Analysis}, + volume={7}, + number={4}, + pages={423--430}, + year={1987}, + publisher={Oxford University Press}}", "", "") struct DPRKN8 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - DPRKN12 - -12th order explicit Rugne-Kutta-Nyström method. The second order ODE should not depend on the first derivative. - -Most efficient when high accuracy is needed. - -## References - -@article{dormand1987high, -title={High-order embedded Runge-Kutta-Nystrom formulae}, -author={Dormand, JR and El-Mikkawy, MEA and Prince, PJ}, -journal={IMA Journal of Numerical Analysis}, -volume={7}, -number={4}, -pages={423--430}, -year={1987}, -publisher={Oxford University Press} -} -""" +@doc generic_solver_docstring("12th order explicit method. + The second order ODE should not depend on the first derivative. + Most efficient when high accuracy is needed.", + "DPRKN12", + "Improved Runge-Kutta-Nyström method", + "@article{dormand1987high, + title={High-order embedded Runge-Kutta-Nystrom formulae}, + author={Dormand, JR and El-Mikkawy, MEA and Prince, PJ}, + journal={IMA Journal of Numerical Analysis}, + volume={7}, + number={4}, + pages={423--430}, + year={1987}, + publisher={Oxford University Press}}", "", "") struct DPRKN12 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - ERKN4 - -Embedded 4(3) pair of explicit Runge-Kutta-Nyström methods. Integrates the periodic properties of the harmonic oscillator exactly. - -The second order ODE should not depend on the first derivative. - -Uses adaptive step size control. This method is extra efficient on periodic problems. - -## References - -@article{demba2017embedded, -title={An Embedded 4 (3) Pair of Explicit Trigonometrically-Fitted Runge-Kutta-Nystr{\"o}m Method for Solving Periodic Initial Value Problems}, -author={Demba, MA and Senu, N and Ismail, F}, -journal={Applied Mathematical Sciences}, -volume={11}, -number={17}, -pages={819--838}, -year={2017} -} -""" +@doc generic_solver_docstring("Embedded 4(3) pair of explicit methods. + Integrates the periodic properties of the harmonic oscillator exactly. + The second order ODE should not depend on the first derivative. + Uses adaptive step size control. This method is extra efficient on periodic problems.", + "ERKN4", + "Improved Runge-Kutta-Nyström method", + "@article{demba2017embedded, + title={An Embedded 4 (3) Pair of Explicit Trigonometrically-Fitted Runge-Kutta-Nystr{\"o}m Method for Solving Periodic Initial Value Problems}, + author={Demba, MA and Senu, N and Ismail, F}, + journal={Applied Mathematical Sciences}, + volume={11}, + number={17}, + pages={819--838}, + year={2017}}", "", "") struct ERKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - ERKN5 - -Embedded 5(4) pair of explicit Runge-Kutta-Nyström methods. Integrates the periodic properties of the harmonic oscillator exactly. - -The second order ODE should not depend on the first derivative. - -Uses adaptive step size control. This method is extra efficient on periodic problems. - -## References - -@article{demba20165, -title={A 5 (4) Embedded Pair of Explicit Trigonometrically-Fitted Runge--Kutta--Nystr{\"o}m Methods for the Numerical Solution of Oscillatory Initial Value Problems}, -author={Demba, Musa A and Senu, Norazak and Ismail, Fudziah}, -journal={Mathematical and Computational Applications}, -volume={21}, -number={4}, -pages={46}, -year={2016}, -publisher={Multidisciplinary Digital Publishing Institute} -} -""" +@doc generic_solver_docstring("Embedded 5(4) pair of explicit methods. + Integrates the periodic properties of the harmonic oscillator exactly. + The second order ODE should not depend on the first derivative. + Uses adaptive step size control. This method is extra efficient on periodic problems.", + "ERKN5", + "Improved Runge-Kutta-Nyström method", + "@article{demba20165, + title={A 5 (4) Embedded Pair of Explicit Trigonometrically-Fitted Runge--Kutta--Nystr{\"o}m Methods for the Numerical Solution of Oscillatory Initial Value Problems}, + author={Demba, Musa A and Senu, Norazak and Ismail, Fudziah}, + journal={Mathematical and Computational Applications}, + volume={21}, + number={4}, + pages={46}, + year={2016}, + publisher={Multidisciplinary Digital Publishing Institute}}", "", "") struct ERKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" - ERKN7 - -Embedded pair of explicit Runge-Kutta-Nyström methods. Integrates the periodic properties of the harmonic oscillator exactly. - -The second order ODE should not depend on the first derivative. - -Uses adaptive step size control. This method is extra efficient on periodic Problems. - -## References - -@article{SimosOnHO, -title={On high order Runge-Kutta-Nystr{\"o}m pairs}, -author={Theodore E. Simos and Ch. Tsitouras}, -journal={J. Comput. Appl. Math.}, -volume={400}, -pages={113753} -} -""" +@doc generic_solver_docstring("Embedded pair of explicit methods. + Integrates the periodic properties of the harmonic oscillator exactly. + The second order ODE should not depend on the first derivative. + Uses adaptive step size control. This method is extra efficient on periodic problems.", + "ERKN7", + "Improved Runge-Kutta-Nyström method", + "@article{SimosOnHO, + title={On high order Runge-Kutta-Nystr{\"o}m pairs}, + author={Theodore E. Simos and Ch. Tsitouras}, + journal={J. Comput. Appl. Math.}, + volume={400}, + pages={113753}}", "", "") struct ERKN7 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -""" -3 stage fourth order Runge-Kutta Nystrom method to solve second order linear inhomogeneous IVPs. - -Does not include an adaptive method. Solves for for d-dimensional differential systems of second order linear inhomogeneous equations. - -!!! warn - - This method is only fourth order for these systems, the method is second order otherwise! - -## References - -@article{MONTIJANO2024115533, -title = {Explicit Runge–Kutta–Nyström methods for the numerical solution of second order linear inhomogeneous IVPs}, -author = {J.I. Montijano and L. Rández and M. Calvo}, -journal = {Journal of Computational and Applied Mathematics}, -volume = {438}, -pages = {115533}, -year = {2024}, -} -""" +@doc generic_solver_docstring("3 stage fourth order method to solve second order linear inhomogeneous IVPs. + Does not include an adaptive method. Solves for for d-dimensional differential systems of second order linear inhomogeneous equations. + + !!! warning + This method is only fourth order for these systems, the method is second order otherwise!", + "RKN4", + "Improved Runge-Kutta-Nyström method", + "@article{MONTIJANO2024115533, + title = {Explicit Runge–Kutta–Nyström methods for the numerical solution of second order linear inhomogeneous IVPs}, + author = {J.I. Montijano and L. Rández and M. Calvo}, + journal = {Journal of Computational and Applied Mathematics}, + volume = {438}, + pages = {115533}, + year = {2024},}", "", "") struct RKN4 <: OrdinaryDiffEqAlgorithm end From 684a30752ee16346398257c4d2e52c390f40b660 Mon Sep 17 00:00:00 2001 From: Arno Strouwen Date: Mon, 12 Aug 2024 11:51:57 +0200 Subject: [PATCH 21/83] changeJVODE preferred alternative Co-authored-by: Christopher Rackauckas --- lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index ef257fd507..a500387778 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -8,7 +8,7 @@ struct AN5 <: OrdinaryDiffEqAdaptiveAlgorithm end """ !!! warning "Experimental" - `JVODE` is experimental, the solver `FBDF` is generally preferred. + `JVODE` is experimental, the solver `VCABM` is generally preferred. """ struct JVODE{bType, aType} <: OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm algorithm::Symbol From 12a8be73c0cf312786c1915bd45535c3dc22fe08 Mon Sep 17 00:00:00 2001 From: Arno Strouwen Date: Mon, 12 Aug 2024 11:52:22 +0200 Subject: [PATCH 22/83] change JVODE preferred alternative Co-authored-by: Christopher Rackauckas --- lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index a500387778..740a2218c0 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -24,7 +24,7 @@ function JVODE(algorithm = :Adams; bias1 = 6, bias2 = 6, bias3 = 10, end """ !!! warning "Experimental" - `JVODE` is experimental, the solver `FBDF` is generally preferred. + `JVODE` is experimental, the solver `VCABM` is generally preferred. """ JVODE_Adams(; kwargs...) = JVODE(:Adams; kwargs...) """ From f6589e242f670670a13796b8f616560fcbb8f936 Mon Sep 17 00:00:00 2001 From: Arno Strouwen Date: Mon, 12 Aug 2024 11:52:50 +0200 Subject: [PATCH 23/83] Expand upon low storage docs Co-authored-by: Christopher Rackauckas --- docs/src/explicit/LowStorageRK.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/src/explicit/LowStorageRK.md b/docs/src/explicit/LowStorageRK.md index 1404b1df19..3bd22b9941 100644 --- a/docs/src/explicit/LowStorageRK.md +++ b/docs/src/explicit/LowStorageRK.md @@ -1,6 +1,10 @@ # OrdinaryDiffEqLowStorageRK -Solvers specialized on certain PDE types. +These methods are designed to have reduced register requirements, allowing for larger sets of ODEs to more +easily fit into RAM. For example, while the 5th order Tsit5 requires around 9 concurrent instantiations of the +ODE state `u`, `RDPK3Sp510` can achieve 5th order with 3 registers, effectively requiring 1/3 of the memory. +However, there are some efficiency trade-offs used in the design of the low-storage RK methods, and thus they +are generally only recommended in situations which are RAM bound, like large-scale PDE discretizations. ```@eval first_steps = evalfile("./common_first_steps.jl") From 69ff21167cf75ca01a34dc0a3a050363fa782414 Mon Sep 17 00:00:00 2001 From: Arno Strouwen Date: Mon, 12 Aug 2024 11:54:36 +0200 Subject: [PATCH 24/83] Expand upon Feagin docs. Co-authored-by: Christopher Rackauckas --- docs/src/explicit/Feagin.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/src/explicit/Feagin.md b/docs/src/explicit/Feagin.md index 53f4f91da9..5790939f17 100644 --- a/docs/src/explicit/Feagin.md +++ b/docs/src/explicit/Feagin.md @@ -2,6 +2,11 @@ Preferred solvers for non-stiff problems at very low tolerance, `<1e-30`. Best combined with preciser than `Float64` number types for the state, such as the `BigFloat` number type. +Note that the Feagin methods have a less robust error estimator than the Verner methods, and thus even for +very low tolerance problems the Verner methods (`Vern9`) may still be more efficient. In addition, at extremely +low tolerances the explicit extrapolation methods allow for arbitrarily high variable order stepping which will +also outperform the Feagin methods. As such, the Feagin methods may be useful in the Float128 precision range +but should be tested against other algorithms. ```@eval first_steps = evalfile("./common_first_steps.jl") From b0e494afdded0a4c2cbeae6766dd195a2ee3ea59 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 12:08:31 +0200 Subject: [PATCH 25/83] docs Nordsieck --- docs/src/explicit/Nordsieck.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/src/explicit/Nordsieck.md b/docs/src/explicit/Nordsieck.md index e38b8f10a6..1008806852 100644 --- a/docs/src/explicit/Nordsieck.md +++ b/docs/src/explicit/Nordsieck.md @@ -1,6 +1,16 @@ # OrdinaryDiffEqNordsieck -This article is a stub. +The Nordsieck form is an alternative representation of multistep methods which, +instead of representing and saving past step values in a history vector, +it uses a derivative list (like a Taylor expansion) for the computation of the next point. +The Nordsieck form was pioneered by early implementations of BDF methods such LSODE, VODE, and finally CVODE. +It can have some advantages in terms of restartability as the full Nordsieck vector can be instantiated given only the information of f and its derivatives after discontinuities, +but the higher derivative representations can also introduce numerical instabilities of their own. + +The Nordsieck implementations here are considered experimental implementations of the LSODE non-fixed leading coefficient form +and are generally considered inferior to the fixed-leading history-based BDF implementation of FBDF, and thus for all standard usage we recommend FBDF. +However, this algorithm is kept for experimental research and development purposes with the possibility of one day becoming a more discontinuity-aware BDF implementation. + ```@eval first_steps = evalfile("./common_first_steps.jl") From 47114af5fa8eecb6a649110691b3c3441e4ca4c8 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 12:08:51 +0200 Subject: [PATCH 26/83] mark AN5 as experimental --- lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index 740a2218c0..fe4b0bbc51 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -1,5 +1,8 @@ # Adams/BDF methods in Nordsieck forms -@doc generic_solver_docstring("An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form.", +@doc generic_solver_docstring("""An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form. + !!! warning "Experimental" + `AN5` is experimental, the solver `VCABM` is generally preferred. + """, "AN5", "Adaptive step size Adams explicit Method", "", From 1cff39dfb3f29b9e0b658df924fb250d3e01e39f Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 12:52:40 +0200 Subject: [PATCH 27/83] docs SymplecticRK and remove old docs --- docs/make.jl | 11 +- docs/src/dynamical/nystrom.md | 18 -- docs/src/dynamical/symplectic.md | 21 -- docs/src/{misc => explicit}/RKN.md | 0 docs/src/explicit/SymplecticRK.md | 30 ++ docs/src/nonstiff/explicitrk.md | 67 ---- docs/src/nonstiff/lowstorage_ssprk.md | 72 ----- .../src/OrdinaryDiffEqSymplecticRK.jl | 3 +- .../src/algorithms.jl | 301 ++++++++---------- 9 files changed, 169 insertions(+), 354 deletions(-) delete mode 100644 docs/src/dynamical/nystrom.md delete mode 100644 docs/src/dynamical/symplectic.md rename docs/src/{misc => explicit}/RKN.md (100%) create mode 100644 docs/src/explicit/SymplecticRK.md delete mode 100644 docs/src/nonstiff/explicitrk.md delete mode 100644 docs/src/nonstiff/lowstorage_ssprk.md diff --git a/docs/make.jl b/docs/make.jl index a5b3967b50..ade67b594e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -43,12 +43,11 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/LowStorageRK.md", "explicit/SSPRK.md", "explicit/AdamsBashforthMoulton.md", - "explicit/Nordsieck.md" + "explicit/Nordsieck.md", + "explicit/RKN.md", + "explicit/SymplecticRK.md" ], - "Misc solvers" => ["misc/RKN.md"], "Standard Non-Stiff ODEProblem Solvers" => [ - "nonstiff/explicitrk.md", - "nonstiff/lowstorage_ssprk.md", "nonstiff/explicit_extrapolation.md", "nonstiff/nonstiff_multistep.md" ], @@ -60,10 +59,6 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "stiff/stiff_multistep.md", "stiff/implicit_extrapolation.md" ], - "Second Order and Dynamical ODE Solvers" => [ - "dynamical/nystrom.md", - "dynamical/symplectic.md" - ], "IMEX Solvers" => [ "imex/imex_multistep.md", "imex/imex_sdirk.md" diff --git a/docs/src/dynamical/nystrom.md b/docs/src/dynamical/nystrom.md deleted file mode 100644 index 7c9567cc49..0000000000 --- a/docs/src/dynamical/nystrom.md +++ /dev/null @@ -1,18 +0,0 @@ -# Runge-Kutta Nystrom Methods - -```@docs -IRKN3 -IRKN4 -Nystrom4 -Nystrom4VelocityIndependent -Nystrom5VelocityIndependent -FineRKN4 -FineRKN5 -DPRKN6 -DPRKN6FM -DPRKN8 -DPRKN12 -ERKN4 -ERKN5 -ERKN7 -``` diff --git a/docs/src/dynamical/symplectic.md b/docs/src/dynamical/symplectic.md deleted file mode 100644 index e423f4f34e..0000000000 --- a/docs/src/dynamical/symplectic.md +++ /dev/null @@ -1,21 +0,0 @@ -# Symplectic Runge-Kutta Methods - -```@docs -SymplecticEuler -VelocityVerlet -VerletLeapfrog -PseudoVerletLeapfrog -McAte2 -Ruth3 -McAte3 -CandyRoz4 -McAte4 -CalvoSanz4 -McAte42 -McAte5 -Yoshida6 -KahanLi6 -McAte8 -KahanLi8 -SofSpa10 -``` diff --git a/docs/src/misc/RKN.md b/docs/src/explicit/RKN.md similarity index 100% rename from docs/src/misc/RKN.md rename to docs/src/explicit/RKN.md diff --git a/docs/src/explicit/SymplecticRK.md b/docs/src/explicit/SymplecticRK.md new file mode 100644 index 0000000000..b8cef125b3 --- /dev/null +++ b/docs/src/explicit/SymplecticRK.md @@ -0,0 +1,30 @@ +# OrdinaryDiffEqSymplecticRK + +Solvers for Hamiltonian systems. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqSymplecticRK", "Nystrom4") +``` + +## Full list of solvers + +```@docs +SymplecticEuler +VelocityVerlet +VerletLeapfrog +PseudoVerletLeapfrog +McAte2 +Ruth3 +McAte3 +CandyRoz4 +McAte4 +CalvoSanz4 +McAte42 +McAte5 +Yoshida6 +KahanLi6 +McAte8 +KahanLi8 +SofSpa10 +``` diff --git a/docs/src/nonstiff/explicitrk.md b/docs/src/nonstiff/explicitrk.md deleted file mode 100644 index 010a10e11f..0000000000 --- a/docs/src/nonstiff/explicitrk.md +++ /dev/null @@ -1,67 +0,0 @@ -# Explicit Runge-Kutta Methods - -With the help of [FastBroadcast.jl](https://github.com/YingboMa/FastBroadcast.jl), -we can use threaded parallelism to reduce compute time for all of the explicit Runge-Kutta methods! -The `thread` option determines whether internal broadcasting on appropriate CPU arrays should be serial -(`thread = OrdinaryDiffEq.False()`, default) or use multiple threads -(`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. -When we call `solve(prob, alg(thread=OrdinaryDiffEq.True()))`, -we can turn on the multithreading option to achieve acceleration -(for sufficiently large problems). - -## Standard Explicit Runge-Kutta Methods - -```@docs -Heun -Ralston -Midpoint -RK4 -RKM -MSRK5 -MSRK6 -Anas5 -RKO65 -OwrenZen3 -OwrenZen4 -OwrenZen5 -BS3 -DP5 -Tsit5 -DP8 -TanYam7 -TsitPap8 -Feagin10 -Feagin12 -Feagin14 -FRK65 -PFRK87 -Stepanov5 -SIR54 -Alshina2 -Alshina3 -Alshina6 -``` - -## Lazy Interpolation Explicit Runge-Kutta Methods - -```@docs -BS5 -Vern6 -Vern7 -Vern8 -Vern9 -``` - -## Fixed Timestep Only Explicit Runge-Kutta Methods - -```@docs -Euler -RK46NL -ORK256 -``` - -## Parallel Explicit Runge-Kutta Methods - -```@docs -KuttaPRK2p5 -``` diff --git a/docs/src/nonstiff/lowstorage_ssprk.md b/docs/src/nonstiff/lowstorage_ssprk.md deleted file mode 100644 index a8fa854f41..0000000000 --- a/docs/src/nonstiff/lowstorage_ssprk.md +++ /dev/null @@ -1,72 +0,0 @@ -# PDE-Specialized Explicit Runge-Kutta Methods - -## Low Storage Explicit Runge-Kutta Methods - -```@docs -CarpenterKennedy2N54 -SHLDDRK64 -SHLDDRK52 -SHLDDRK_2N -HSLDDRK64 -DGLDDRK73_C -DGLDDRK84_C -DGLDDRK84_F -NDBLSRK124 -NDBLSRK134 -NDBLSRK144 -CFRLDDRK64 -TSLDDRK74 -CKLLSRK43_2 -CKLLSRK54_3C -CKLLSRK95_4S -CKLLSRK95_4C -CKLLSRK95_4M -CKLLSRK54_3C_3R -CKLLSRK54_3M_3R -CKLLSRK54_3N_3R -CKLLSRK85_4C_3R -CKLLSRK85_4M_3R -CKLLSRK85_4P_3R -CKLLSRK54_3N_4R -CKLLSRK54_3M_4R -CKLLSRK65_4M_4R -CKLLSRK85_4FM_4R -CKLLSRK75_4M_5R -ParsaniKetchesonDeconinck3S32 -ParsaniKetchesonDeconinck3S82 -ParsaniKetchesonDeconinck3S53 -ParsaniKetchesonDeconinck3S173 -ParsaniKetchesonDeconinck3S94 -ParsaniKetchesonDeconinck3S184 -ParsaniKetchesonDeconinck3S105 -ParsaniKetchesonDeconinck3S205 -RDPK3Sp35 -RDPK3SpFSAL35 -RDPK3Sp49 -RDPK3SpFSAL49 -RDPK3Sp510 -RDPK3SpFSAL510 -``` - -## SSP Optimized Runge-Kutta Methods - -```@docs -KYK2014DGSSPRK_3S2 -SSPRK22 -SSPRK33 -SSPRK53 -KYKSSPRK42 -SSPRK53_2N1 -SSPRK53_2N2 -SSPRK53_H -SSPRK63 -SSPRK73 -SSPRK83 -SSPRK43 -SSPRK432 -SSPRKMSVS43 -SSPRKMSVS32 -SSPRK932 -SSPRK54 -SSPRK104 -``` diff --git a/lib/OrdinaryDiffEqSymplecticRK/src/OrdinaryDiffEqSymplecticRK.jl b/lib/OrdinaryDiffEqSymplecticRK/src/OrdinaryDiffEqSymplecticRK.jl index 67dc1e38d8..c100a75215 100644 --- a/lib/OrdinaryDiffEqSymplecticRK/src/OrdinaryDiffEqSymplecticRK.jl +++ b/lib/OrdinaryDiffEqSymplecticRK/src/OrdinaryDiffEqSymplecticRK.jl @@ -11,7 +11,8 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, alg_cache, _vec, _reshape, @cache, isfsal, full_cache, constvalue, _unwrap_val, explicit_rk_docstring, trivial_limiter!, - _ode_interpolant!, _ode_addsteps!, get_fsalfirstlast + _ode_interpolant!, _ode_addsteps!, get_fsalfirstlast, + generic_solver_docstring using FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools import OrdinaryDiffEqCore diff --git a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl index c93ee790d8..75e02eb4c5 100644 --- a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl @@ -1,6 +1,10 @@ +@doc generic_solver_docstring("DESCRIPTION TBD", + "SymplecticEuler", + "Symplectic Runge-Kutta Methods", + "REF TBD", "", "") struct SymplecticEuler <: OrdinaryDiffEqPartitionedAlgorithm end -""" +verlet1967 = """ @article{verlet1967computer, title={Computer" experiments" on classical fluids. I. Thermodynamical properties of Lennard-Jones molecules}, author={Verlet, Loup}, @@ -13,39 +17,25 @@ publisher={APS} } """ +@doc generic_solver_docstring("DESCRIPTION TBD", + "VelocityVerlet", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct VelocityVerlet <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{verlet1967computer, -title={Computer" experiments" on classical fluids. I. Thermodynamical properties of Lennard-Jones molecules}, -author={Verlet, Loup}, -journal={Physical review}, -volume={159}, -number={1}, -pages={98}, -year={1967}, -publisher={APS} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "VerletLeapfrog", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct VerletLeapfrog <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{verlet1967computer, -title={Computer" experiments" on classical fluids. I. Thermodynamical properties of Lennard-Jones molecules}, -author={Verlet, Loup}, -journal={Physical review}, -volume={159}, -number={1}, -pages={98}, -year={1967}, -publisher={APS} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "PseudoVerletLeapfrog", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct PseudoVerletLeapfrog <: OrdinaryDiffEqPartitionedAlgorithm end -""" +mclachlan1992 = """ @article{mclachlan1992accuracy, title={The accuracy of symplectic integrators}, author={McLachlan, Robert I and Atela, Pau}, @@ -58,167 +48,144 @@ publisher={IOP Publishing} } """ +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte2", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte2 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{ruth1983canonical, -title={A canonical integration technique}, -author={Ruth, Ronald D}, -journal={IEEE Trans. Nucl. Sci.}, -volume={30}, -number={CERN-LEP-TH-83-14}, -pages={2669--2671}, -year={1983} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "Ruth3", + "Symplectic Runge-Kutta Methods", + """@article{ruth1983canonical, + title={A canonical integration technique}, + author={Ruth, Ronald D}, + journal={IEEE Trans. Nucl. Sci.}, + volume={30}, + number={CERN-LEP-TH-83-14}, + pages={2669--2671}, + year={1983}}""", "", "") struct Ruth3 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{mclachlan1992accuracy, -title={The accuracy of symplectic integrators}, -author={McLachlan, Robert I and Atela, Pau}, -journal={Nonlinearity}, -volume={5}, -number={2}, -pages={541}, -year={1992}, -publisher={IOP Publishing} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte3", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte3 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{candy1991symplectic, -title={A symplectic integration algorithm for separable Hamiltonian functions}, -author={Candy, J and Rozmus, W}, -journal={Journal of Computational Physics}, -volume={92}, -number={1}, -pages={230--256}, -year={1991}, -publisher={Elsevier} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "CandyRoz4", + "Symplectic Runge-Kutta Methods", + """@article{candy1991symplectic, + itle={A symplectic integration algorithm for separable Hamiltonian functions}, + uthor={Candy, J and Rozmus, W}, + ournal={Journal of Computational Physics}, + olume={92}, + umber={1}, + ages={230--256}, + ear={1991}, + ublisher={Elsevier}}""", "", "") struct CandyRoz4 <: OrdinaryDiffEqPartitionedAlgorithm end +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte4", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte4 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{sanz1993symplectic, -title={Symplectic numerical methods for Hamiltonian problems}, -author={Sanz-Serna, Jes{\'u}s Maria and Calvo, Mari-Paz}, -journal={International Journal of Modern Physics C}, -volume={4}, -number={02}, -pages={385--392}, -year={1993}, -publisher={World Scientific} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "CalvoSanz4", + "Symplectic Runge-Kutta Methods", + """@article{sanz1993symplectic, + title={Symplectic numerical methods for Hamiltonian problems}, + author={Sanz-Serna, Jes{\'u}s Maria and Calvo, Mari-Paz}, + journal={International Journal of Modern Physics C}, + volume={4}, + number={02}, + pages={385--392}, + year={1993}, + publisher={World Scientific} + }""", "", "") struct CalvoSanz4 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{mclachlan1992accuracy, -title={The accuracy of symplectic integrators}, -author={McLachlan, Robert I and Atela, Pau}, -journal={Nonlinearity}, -volume={5}, -number={2}, -pages={541}, -year={1992}, -publisher={IOP Publishing} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte42", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte42 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{mclachlan1992accuracy, -title={The accuracy of symplectic integrators}, -author={McLachlan, Robert I and Atela, Pau}, -journal={Nonlinearity}, -volume={5}, -number={2}, -pages={541}, -year={1992}, -publisher={IOP Publishing} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte5", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte5 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{yoshida1990construction, -title={Construction of higher order symplectic integrators}, -author={Yoshida, Haruo}, -journal={Physics letters A}, -volume={150}, -number={5-7}, -pages={262--268}, -year={1990}, -publisher={Elsevier} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "Yoshida6", + "Symplectic Runge-Kutta Methods", + """@article{yoshida1990construction, + title={Construction of higher order symplectic integrators}, + author={Yoshida, Haruo}, + journal={Physics letters A}, + volume={150}, + number={5-7}, + pages={262--268}, + year={1990}, + publisher={Elsevier}}""", "", "") struct Yoshida6 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{kahan1997composition, -title={Composition constants for raising the orders of unconventional schemes for ordinary differential equations}, -author={Kahan, William and Li, Ren-Cang}, -journal={Mathematics of computation}, -volume={66}, -number={219}, -pages={1089--1099}, -year={1997} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "KahanLi6", + "Symplectic Runge-Kutta Methods", + """@article{yoshida1990construction, + title={Construction of higher order symplectic integrators}, + author={Yoshida, Haruo}, + journal={Physics letters A}, + volume={150}, + number={5-7}, + pages={262--268}, + year={1990}, + publisher={Elsevier}}""", "", "") struct KahanLi6 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{mclachlan1995numerical, -title={On the numerical integration of ordinary differential equations by symmetric composition methods}, -author={McLachlan, Robert I}, -journal={SIAM Journal on Scientific Computing}, -volume={16}, -number={1}, -pages={151--168}, -year={1995}, -publisher={SIAM} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "McAte8", + "Symplectic Runge-Kutta Methods", + """@article{mclachlan1995numerical, + title={On the numerical integration of ordinary differential equations by symmetric composition methods}, + author={McLachlan, Robert I}, + journal={SIAM Journal on Scientific Computing}, + volume={16}, + number={1}, + pages={151--168}, + year={1995}, + publisher={SIAM} + }""", "", "") struct McAte8 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{kahan1997composition, -title={Composition constants for raising the orders of unconventional schemes for ordinary differential equations}, -author={Kahan, William and Li, Ren-Cang}, -journal={Mathematics of computation}, -volume={66}, -number={219}, -pages={1089--1099}, -year={1997} -} -""" - +@doc generic_solver_docstring("DESCRIPTION TBD", + "KahanLi8", + "Symplectic Runge-Kutta Methods", + """@article{kahan1997composition, + title={Composition constants for raising the orders of unconventional schemes for ordinary differential equations}, + author={Kahan, William and Li, Ren-Cang}, + journal={Mathematics of computation}, + volume={66}, + number={219}, + pages={1089--1099}, + year={1997}}""", "", "") struct KahanLi8 <: OrdinaryDiffEqPartitionedAlgorithm end -""" -@article{sofroniou2005derivation, -title={Derivation of symmetric composition constants for symmetric integrators}, -author={Sofroniou, Mark and Spaletta, Giulia}, -journal={Optimization Methods and Software}, -volume={20}, -number={4-5}, -pages={597--613}, -year={2005}, -publisher={Taylor \\& Francis} -} -""" +@doc generic_solver_docstring("DESCRIPTION TBD", + "SofSpa10", + "Symplectic Runge-Kutta Methods", + """@article{sofroniou2005derivation, + title={Derivation of symmetric composition constants for symmetric integrators}, + author={Sofroniou, Mark and Spaletta, Giulia}, + journal={Optimization Methods and Software}, + volume={20}, + number={4-5}, + pages={597--613}, + year={2005}, + publisher={Taylor \\& Francis}}""", "", "") struct SofSpa10 <: OrdinaryDiffEqPartitionedAlgorithm end From 4c272b82c1f5ef53d98bbfbba131fac4e4720b0e Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 12 Aug 2024 13:00:24 +0200 Subject: [PATCH 28/83] expand SSPRK explanation --- docs/src/explicit/SSPRK.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/src/explicit/SSPRK.md b/docs/src/explicit/SSPRK.md index 8756eb785f..e5f52c55d1 100644 --- a/docs/src/explicit/SSPRK.md +++ b/docs/src/explicit/SSPRK.md @@ -1,6 +1,12 @@ # OrdinaryDiffEqSSPRK -Solvers specialized on certain PDE types. +SSPRK methods are Runge-Kutta methods which support the "strongly preserving property" (SSP). +They are designed for the use in discretizations of hyperbolic partial differential equations and conservation laws +as they have extra stability properties ( e.g., stability with respect to total variation, the maximum norm, or other convex functionals) +when step-size restrictions are respected. +In particular, these properties are granted if the step-size is kept to a level where the CFL coefficients are less than the SSP coefficient. + +Note that for SSPRK methods, a algorithm utility `OrdinaryDiffEqCore.ssp_coefficient(alg)` exists that allows for querying the SSP coefficient for use in step size calculations. ```@eval first_steps = evalfile("./common_first_steps.jl") From 5931a4783162ef9b91a812e472cb260fba0870b5 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Tue, 13 Aug 2024 15:23:54 +0200 Subject: [PATCH 29/83] start docstring dependent on OrdinaryDiffEqDifferentiation --- docs/make.jl | 3 +- docs/src/explicit/Extrapolation.md | 3 + .../src/OrdinaryDiffEqExtrapolation.jl | 2 +- .../src/algorithms.jl | 72 ++++++++++++++----- 4 files changed, 61 insertions(+), 19 deletions(-) create mode 100644 docs/src/explicit/Extrapolation.md diff --git a/docs/make.jl b/docs/make.jl index ade67b594e..b16ef76f46 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -45,7 +45,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/AdamsBashforthMoulton.md", "explicit/Nordsieck.md", "explicit/RKN.md", - "explicit/SymplecticRK.md" + "explicit/SymplecticRK.md", + "explicit/Extrapolation.md", ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md new file mode 100644 index 0000000000..061cc6d410 --- /dev/null +++ b/docs/src/explicit/Extrapolation.md @@ -0,0 +1,3 @@ +```@docs +ImplicitEulerExtrapolation +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl b/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl index fd4dc8d7b3..2f9338a874 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl @@ -16,7 +16,7 @@ import OrdinaryDiffEqCore: alg_order, alg_maximum_order, get_current_adaptive_or DEFAULT_PRECS, full_cache, constvalue, PolyesterThreads, Sequential, BaseThreads, _digest_beta1_beta2, timedepentdtmin, _unwrap_val, - _reshape, _vec, get_fsalfirstlast + _reshape, _vec, get_fsalfirstlast, generic_solver_docstring using DiffEqBase, FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools, LinearSolve import OrdinaryDiffEqCore import OrdinaryDiffEqDifferentiation: TimeDerivativeWrapper, UDerivativeWrapper, calc_J, diff --git a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl index 7b84e36bdc..ec85ce8fb2 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl @@ -3,24 +3,62 @@ abstract type OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm <: abstract type OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} <: OrdinaryDiffEqAdaptiveImplicitAlgorithm{CS, AD, FDT, ST, CJ} end -""" -AitkenNeville: Parallelized Explicit Extrapolation Method -Euler extrapolation using Aitken-Neville with the Romberg Sequence. -""" -struct AitkenNeville{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm - max_order::Int - min_order::Int - init_order::Int - threading::TO -end -function AitkenNeville(; max_order = 10, min_order = 1, init_order = 5, threading = false) - AitkenNeville(max_order, min_order, init_order, threading) +@doc generic_solver_docstring("Euler extrapolation using Aitken-Neville with the Romberg Sequence.", + "AitkenNeville", + "Parallelized Explicit Extrapolation Method.", + "TBD", + """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + """, + """ + max_order::Int = 10, + min_order::Int = 1, + init_order = 3, + threading = false + """) +Base.@kwdef struct AitkenNeville{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm + max_order::Int = 10 + min_order::Int = 1 + init_order::Int = 5 + threading::TO = false end -""" -ImplicitEulerExtrapolation: Parallelized Implicit Extrapolation Method -Extrapolation of implicit Euler method with Romberg sequence. -Similar to Hairer's SEULEX. -""" + +@doc generic_solver_docstring("Extrapolation of implicit Euler method with Romberg sequence. + Similar to Hairer's SEULEX.", + "ImplicitEulerExtrapolation", + "Parallelized Explicit Extrapolation Method.", + "TBD", + """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + """, + """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + max_order = 12, + min_order = 3, + init_order = 5, + threading = false, + sequence = :harmonic + """) struct ImplicitEulerExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 4d51a1649396146607e71214d9bd2f69f045ec4d Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 14 Aug 2024 22:37:17 +0200 Subject: [PATCH 30/83] start docstring dependent on OrdinaryDiffEqNonlinearSolve --- docs/make.jl | 3 + docs/src/implicit/FIRK.md | 3 + .../src/OrdinaryDiffEqFIRK.jl | 2 +- lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 62 ++++++++++++++----- 4 files changed, 54 insertions(+), 16 deletions(-) create mode 100644 docs/src/implicit/FIRK.md diff --git a/docs/make.jl b/docs/make.jl index b16ef76f46..731cc24779 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -48,6 +48,9 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/SymplecticRK.md", "explicit/Extrapolation.md", ], + "Iplicit Solvers" => [ + "implicit/FIRK.md" + ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", "nonstiff/nonstiff_multistep.md" diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md new file mode 100644 index 0000000000..69c954c8cc --- /dev/null +++ b/docs/src/implicit/FIRK.md @@ -0,0 +1,3 @@ +```@docs +RadauIIA9 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl b/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl index f7039b2cfc..95edd533b6 100644 --- a/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl +++ b/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl @@ -16,7 +16,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, PredictiveController, alg_can_repeat_jac, NewtonAlgorithm, fac_default_gamma, get_current_adaptive_order, get_fsalfirstlast, - isfirk + isfirk, generic_solver_docstring using MuladdMacro, DiffEqBase, RecursiveArrayTools using SciMLOperators: AbstractSciMLOperator using LinearAlgebra: I, UniformScaling, mul!, lu diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index d95430f5a5..e41eee6904 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -102,21 +102,53 @@ function RadauIIA5(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -""" -@article{hairer1999stiff, -title={Stiff differential equations solved by Radau methods}, -author={Hairer, Ernst and Wanner, Gerhard}, -journal={Journal of Computational and Applied Mathematics}, -volume={111}, -number={1-2}, -pages={93--111}, -year={1999}, -publisher={Elsevier} -} - -RadauIIA9: Fully-Implicit Runge-Kutta Method -An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. -""" +@doc generic_solver_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. + Similar to Hairer's SEULEX.", + "RadauIIA9", + "Fully-Implicit Runge-Kutta Method.", + "@article{hairer1999stiff, + title={Stiff differential equations solved by Radau methods}, + author={Hairer, Ernst and Wanner, Gerhard}, + journal={Journal of Computational and Applied Mathematics}, + volume={111}, + number={1-2}, + pages={93--111}, + year={1999}, + publisher={Elsevier}}", + """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + - `extrapolant`: TBD + - `fast_convergence_cutoff`: TBD + - `new_W_γdt_cutoff`: TBD + - `controller`: TBD + - `κ`: TBD + - `maxiters`: TBD + - `smooth_est`: TBD + - `step_limiter!`: TBD + """, + """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + extrapolant = :dense, + fast_convergence_cutoff = 1 // 5, + new_W_γdt_cutoff = 1 // 5, + controller = :Predictive, + κ = nothing, + maxiters = 10, + smooth_est = true, + step_limiter! = trivial_limiter! + """) struct RadauIIA9{CS, AD, F, P, FDT, ST, CJ, Tol, C1, C2, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 65034a579aff9a9894846e6cc310446c5c19314c Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Fri, 16 Aug 2024 07:28:35 +0200 Subject: [PATCH 31/83] start function for all implicit docstrings --- lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 60 +++++++++++++++--------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index e41eee6904..6069034494 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -1,3 +1,33 @@ +function implicit_rk_docstring(description::String, + name::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") + keyword_default = """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + """ * extra_keyword_description + + generic_solver_docstring( + description, name, "Fully-Implicit Runge-Kutta Method.", references, + keyword_default_description, keyword_default + ) +end # FIRK Methods """ @@ -102,11 +132,10 @@ function RadauIIA5(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -@doc generic_solver_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. Similar to Hairer's SEULEX.", - "RadauIIA9", - "Fully-Implicit Runge-Kutta Method.", - "@article{hairer1999stiff, + "RadauIIA9"; + references = """@article{hairer1999stiff, title={Stiff differential equations solved by Radau methods}, author={Hairer, Ernst and Wanner, Gerhard}, journal={Journal of Computational and Applied Mathematics}, @@ -114,15 +143,8 @@ end number={1-2}, pages={93--111}, year={1999}, - publisher={Elsevier}}", - """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD + publisher={Elsevier}}""", + extra_keyword_description = """ - `extrapolant`: TBD - `fast_convergence_cutoff`: TBD - `new_W_γdt_cutoff`: TBD @@ -130,16 +152,8 @@ end - `κ`: TBD - `maxiters`: TBD - `smooth_est`: TBD - - `step_limiter!`: TBD - """, - """ - chunk_size = Val{0}(), - autodiff = true, - standardtag = Val{true}(), - concrete_jac = nothing, - diff_type = Val{:forward}, - linsolve = nothing, - precs = DEFAULT_PRECS, + - `step_limiter!`: TBD""", + extra_keyword_default = """ extrapolant = :dense, fast_convergence_cutoff = 1 // 5, new_W_γdt_cutoff = 1 // 5, From 72245c47ff05697320e519fc79bc37c50baac3a3 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 17 Aug 2024 15:35:45 +0200 Subject: [PATCH 32/83] upstream algorithm show method --- lib/OrdinaryDiffEqCore/src/alg_utils.jl | 9 +++++++++ lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl | 8 -------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/lib/OrdinaryDiffEqCore/src/alg_utils.jl b/lib/OrdinaryDiffEqCore/src/alg_utils.jl index 955540f2d6..1af5fa8320 100644 --- a/lib/OrdinaryDiffEqCore/src/alg_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/alg_utils.jl @@ -430,3 +430,12 @@ is_mass_matrix_alg(alg::Union{OrdinaryDiffEqAlgorithm, DAEAlgorithm}) = false is_mass_matrix_alg(alg::CompositeAlgorithm) = all(is_mass_matrix_alg, alg.algs) is_mass_matrix_alg(alg::RosenbrockAlgorithm) = true is_mass_matrix_alg(alg::NewtonAlgorithm) = !isesdirk(alg) + +# All algorithms should be shown using their keyword definition, and not as structs +function Base.show(io::IO, alg::OrdinaryDiffEqAlgorithm) + print(io, String(typeof(alg).name.name), "(;") + for fieldname in fieldnames(typeof(alg)) + print(io, " ", fieldname, " = ", getfield(alg, fieldname), ",") + end + print(io, ")") +end diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index 586da781c0..e120187bd4 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -1,11 +1,3 @@ -function Base.show(io::IO, alg::OrdinaryDiffEqAlgorithm) - print(io, String(typeof(alg).name.name), "(;") - for fieldname in fieldnames(typeof(alg)) - print(io, " ", fieldname, " = ", getfield(alg, fieldname), ",") - end - print(io, ")") -end - """ Euler - The canonical forward Euler method. Fixed timestep only. """ From 9bc7e0af981955b981a00e869a4f05bf4b7cbfc7 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 12:27:10 +0200 Subject: [PATCH 33/83] docs FIRK --- docs/src/implicit/FIRK.md | 11 +++ lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 101 ++++++++++------------- 2 files changed, 54 insertions(+), 58 deletions(-) diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md index 69c954c8cc..9dff594b73 100644 --- a/docs/src/implicit/FIRK.md +++ b/docs/src/implicit/FIRK.md @@ -1,3 +1,14 @@ +# OrdinaryDiffEqFIRK + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqFIRK", "RadauIIA5") +``` + ```@docs +RadauIIA3 +RadauIIA5 RadauIIA9 ``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index 6069034494..81109c6efb 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -28,23 +28,42 @@ function implicit_rk_docstring(description::String, keyword_default_description, keyword_default ) end -# FIRK Methods -""" -@article{hairer1999stiff, -title={Stiff differential equations solved by Radau methods}, -author={Hairer, Ernst and Wanner, Gerhard}, -journal={Journal of Computational and Applied Mathematics}, -volume={111}, -number={1-2}, -pages={93--111}, -year={1999}, -publisher={Elsevier} -} +hairer1999stiff = """@article{hairer1999stiff, + title={Stiff differential equations solved by Radau methods}, + author={Hairer, Ernst and Wanner, Gerhard}, + journal={Journal of Computational and Applied Mathematics}, + volume={111}, + number={1-2}, + pages={93--111}, + year={1999}, + publisher={Elsevier}}""" + +extra_keyword_description = """ + - `extrapolant`: TBD + - `fast_convergence_cutoff`: TBD + - `new_W_γdt_cutoff`: TBD + - `controller`: TBD + - `κ`: TBD + - `maxiters`: TBD + - `smooth_est`: TBD + - `step_limiter!`: TBD""" +extra_keyword_default = """ + extrapolant = :dense, + fast_convergence_cutoff = 1 // 5, + new_W_γdt_cutoff = 1 // 5, + controller = :Predictive, + κ = nothing, + maxiters = 10, + smooth_est = true, + step_limiter! = trivial_limiter!""" -RadauIIA3: Fully-Implicit Runge-Kutta Method -An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. -""" +@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. + Similar to Hairer's SEULEX.", + "RadauIIA3"; + references = hairer1999stiff, + extra_keyword_description = extra_keyword_description, + extra_keyword_default = extra_keyword_default) struct RadauIIA3{CS, AD, F, P, FDT, ST, CJ, Tol, C1, C2, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -80,21 +99,12 @@ function RadauIIA3(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -""" -@article{hairer1999stiff, -title={Stiff differential equations solved by Radau methods}, -author={Hairer, Ernst and Wanner, Gerhard}, -journal={Journal of Computational and Applied Mathematics}, -volume={111}, -number={1-2}, -pages={93--111}, -year={1999}, -publisher={Elsevier} -} - -RadauIIA5: Fully-Implicit Runge-Kutta Method -An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. -""" +@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. + Similar to Hairer's SEULEX.", + "RadauIIA5"; + references = hairer1999stiff, + extra_keyword_description = extra_keyword_description, + extra_keyword_default = extra_keyword_default) struct RadauIIA5{CS, AD, F, P, FDT, ST, CJ, Tol, C1, C2, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -135,34 +145,9 @@ end @doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. Similar to Hairer's SEULEX.", "RadauIIA9"; - references = """@article{hairer1999stiff, - title={Stiff differential equations solved by Radau methods}, - author={Hairer, Ernst and Wanner, Gerhard}, - journal={Journal of Computational and Applied Mathematics}, - volume={111}, - number={1-2}, - pages={93--111}, - year={1999}, - publisher={Elsevier}}""", - extra_keyword_description = """ - - `extrapolant`: TBD - - `fast_convergence_cutoff`: TBD - - `new_W_γdt_cutoff`: TBD - - `controller`: TBD - - `κ`: TBD - - `maxiters`: TBD - - `smooth_est`: TBD - - `step_limiter!`: TBD""", - extra_keyword_default = """ - extrapolant = :dense, - fast_convergence_cutoff = 1 // 5, - new_W_γdt_cutoff = 1 // 5, - controller = :Predictive, - κ = nothing, - maxiters = 10, - smooth_est = true, - step_limiter! = trivial_limiter! - """) + references = hairer1999stiff, + extra_keyword_description = extra_keyword_description, + extra_keyword_default = extra_keyword_default) struct RadauIIA9{CS, AD, F, P, FDT, ST, CJ, Tol, C1, C2, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 6d86116dda6275aaeeacf1b99e800e7303129a80 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 12:27:27 +0200 Subject: [PATCH 34/83] add text MIME to show method for algs --- lib/OrdinaryDiffEqCore/src/alg_utils.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqCore/src/alg_utils.jl b/lib/OrdinaryDiffEqCore/src/alg_utils.jl index 1af5fa8320..bb0a9a020f 100644 --- a/lib/OrdinaryDiffEqCore/src/alg_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/alg_utils.jl @@ -432,7 +432,7 @@ is_mass_matrix_alg(alg::RosenbrockAlgorithm) = true is_mass_matrix_alg(alg::NewtonAlgorithm) = !isesdirk(alg) # All algorithms should be shown using their keyword definition, and not as structs -function Base.show(io::IO, alg::OrdinaryDiffEqAlgorithm) +function Base.show(io::IO, ::MIME"text/plain", alg::OrdinaryDiffEqAlgorithm) print(io, String(typeof(alg).name.name), "(;") for fieldname in fieldnames(typeof(alg)) print(io, " ", fieldname, " = ", getfield(alg, fieldname), ",") From 4223150a916f6562b59ce0ca7f48acd6611ea7e4 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 12:59:28 +0200 Subject: [PATCH 35/83] docs PRK --- docs/src/explicit/PRK.md | 14 ++++++++++++++ lib/OrdinaryDiffEqPRK/src/OrdinaryDiffEqPRK.jl | 2 +- lib/OrdinaryDiffEqPRK/src/algorithms.jl | 14 +++++++------- 3 files changed, 22 insertions(+), 8 deletions(-) create mode 100644 docs/src/explicit/PRK.md diff --git a/docs/src/explicit/PRK.md b/docs/src/explicit/PRK.md new file mode 100644 index 0000000000..13e1406ed6 --- /dev/null +++ b/docs/src/explicit/PRK.md @@ -0,0 +1,14 @@ +# OrdinaryDiffEqPRK + +Explicit solvers optimized for a certain number of parallel calls of the system of ordinary differential equations `f`. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqPRK", "KuttaPRK2p5") +``` + +## Full list of solvers + +```@docs +KuttaPRK2p5 +``` diff --git a/lib/OrdinaryDiffEqPRK/src/OrdinaryDiffEqPRK.jl b/lib/OrdinaryDiffEqPRK/src/OrdinaryDiffEqPRK.jl index e2d35fe635..437d2769d9 100644 --- a/lib/OrdinaryDiffEqPRK/src/OrdinaryDiffEqPRK.jl +++ b/lib/OrdinaryDiffEqPRK/src/OrdinaryDiffEqPRK.jl @@ -4,7 +4,7 @@ import OrdinaryDiffEqCore: OrdinaryDiffEqAlgorithm, alg_order, OrdinaryDiffEqMut OrdinaryDiffEqConstantCache, constvalue, @unpack, @cache, alg_cache, get_fsalfirstlast, unwrap_alg, perform_step!, @threaded, initialize!, isthreaded, - full_cache + full_cache, generic_solver_docstring import MuladdMacro: @muladd import FastBroadcast: @.. using Polyester diff --git a/lib/OrdinaryDiffEqPRK/src/algorithms.jl b/lib/OrdinaryDiffEqPRK/src/algorithms.jl index 81cdf20782..67372af92d 100644 --- a/lib/OrdinaryDiffEqPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPRK/src/algorithms.jl @@ -1,10 +1,10 @@ -""" -KuttaPRK2p5: Parallel Explicit Runge-Kutta Method -A 5 parallel, 2 processor explicit Runge-Kutta method of 5th order. - -These methods utilize multithreading on the f calls to parallelize the problem. -This requires that simultaneous calls to f are thread-safe. -""" +@doc generic_solver_docstring("A 5 parallel, 2 processor method of 5th order. + ", + "KuttaPRK2p5", + "Explicit Runge-Kutta Method", + "REFERENCE TBD", + "- `threading`: TBD", + "threading = true,") Base.@kwdef struct KuttaPRK2p5{TO} <: OrdinaryDiffEqAlgorithm threading::TO = true end From 9754be2064f21ded5413897c9e735a35632acab4 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 13:01:23 +0200 Subject: [PATCH 36/83] finish docstring LowStorageRK --- lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl index bbcabc2034..bd5ed4c23a 100644 --- a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl @@ -916,8 +916,16 @@ end #SSP Optimized Runge-Kutta Methods -@doc explicit_rk_docstring("To be done", - "KYK2014DGSSPRK_3S2") +@doc explicit_rk_docstring("Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", + "KYK2014DGSSPRK_3S2", + references = """@article{kubatko2014optimal, + title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, + author={Kubatko, Ethan J and Yeager, Benjamin A and Ketcheson, David I}, + journal={Journal of Scientific Computing}, + volume={60}, + pages={313--344}, + year={2014}, + publisher={Springer}}""") Base.@kwdef struct KYK2014DGSSPRK_3S2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! From 3912665d1a52dbf842b2bdcf7bb48aabb86f1bd3 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 13:01:55 +0200 Subject: [PATCH 37/83] more docs PRK --- docs/make.jl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/make.jl b/docs/make.jl index 731cc24779..39adc97ccc 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -22,6 +22,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqVerner, OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, OrdinaryDiffEq.OrdinaryDiffEqNordsieck, + OrdinaryDiffEq.OrdinaryDiffEqPRK, OrdinaryDiffEq.OrdinaryDiffEqRKN, OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, @@ -46,6 +47,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Nordsieck.md", "explicit/RKN.md", "explicit/SymplecticRK.md", + "explicit/PRK.md", "explicit/Extrapolation.md", ], "Iplicit Solvers" => [ From 413d36aee9e2c64f2a12dffc3368384a97503bf2 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 15:07:33 +0200 Subject: [PATCH 38/83] PDIRK docs --- docs/src/implicit/PDIRK.md | 12 +++++ lib/OrdinaryDiffEqCore/src/doc_utils.jl | 31 +++++++++++++ .../src/OrdinaryDiffEqFIRK.jl | 2 +- lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 45 ++++--------------- .../src/OrdinaryDiffEqPDIRK.jl | 2 +- lib/OrdinaryDiffEqPDIRK/src/algorithms.jl | 21 ++++++--- 6 files changed, 68 insertions(+), 45 deletions(-) create mode 100644 docs/src/implicit/PDIRK.md diff --git a/docs/src/implicit/PDIRK.md b/docs/src/implicit/PDIRK.md new file mode 100644 index 0000000000..f97d1b416b --- /dev/null +++ b/docs/src/implicit/PDIRK.md @@ -0,0 +1,12 @@ +# OrdinaryDiffEqPDIRK + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqPDIRK", "PDIRK44") +``` + +```@docs +PDIRK44 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index 033889193c..c323a91d71 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -74,3 +74,34 @@ function explicit_rk_docstring(description::String, keyword_default_description, keyword_default ) end +function differentiation_rk_docstring(description::String, + name::String, + solver_class::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") + keyword_default = """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + """ * extra_keyword_description + + generic_solver_docstring( + description, name, solver_class, references, + keyword_default_description, keyword_default + ) +end diff --git a/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl b/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl index 95edd533b6..af3e4a7dd2 100644 --- a/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl +++ b/lib/OrdinaryDiffEqFIRK/src/OrdinaryDiffEqFIRK.jl @@ -8,7 +8,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, OrdinaryDiffEqAdaptiveAlgorithm, CompiledFloats, uses_uprev, alg_cache, _vec, _reshape, @cache, isfsal, full_cache, constvalue, _unwrap_val, - explicit_rk_docstring, trivial_limiter!, + differentiation_rk_docstring, trivial_limiter!, _ode_interpolant!, _ode_addsteps!, AbstractController, qmax_default, alg_adaptive_order, DEFAULT_PRECS, stepsize_controller!, step_accept_controller!, diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index 81109c6efb..a7195de431 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -1,33 +1,3 @@ -function implicit_rk_docstring(description::String, - name::String; - references::String = "", - extra_keyword_description::String = "", - extra_keyword_default::String = "") - keyword_default = """ - chunk_size = Val{0}(), - autodiff = true, - standardtag = Val{true}(), - concrete_jac = nothing, - diff_type = Val{:forward}, - linsolve = nothing, - precs = DEFAULT_PRECS, - """ * extra_keyword_default - - keyword_default_description = """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD - """ * extra_keyword_description - - generic_solver_docstring( - description, name, "Fully-Implicit Runge-Kutta Method.", references, - keyword_default_description, keyword_default - ) -end hairer1999stiff = """@article{hairer1999stiff, title={Stiff differential equations solved by Radau methods}, @@ -58,9 +28,10 @@ extra_keyword_default = """ smooth_est = true, step_limiter! = trivial_limiter!""" -@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. Similar to Hairer's SEULEX.", - "RadauIIA3"; + "RadauIIA3", + "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, extra_keyword_description = extra_keyword_description, extra_keyword_default = extra_keyword_default) @@ -99,9 +70,10 @@ function RadauIIA3(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. Similar to Hairer's SEULEX.", - "RadauIIA5"; + "RadauIIA5", + "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, extra_keyword_description = extra_keyword_description, extra_keyword_default = extra_keyword_default) @@ -142,9 +114,10 @@ function RadauIIA5(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -@doc implicit_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. Similar to Hairer's SEULEX.", - "RadauIIA9"; + "RadauIIA9", + "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, extra_keyword_description = extra_keyword_description, extra_keyword_default = extra_keyword_default) diff --git a/lib/OrdinaryDiffEqPDIRK/src/OrdinaryDiffEqPDIRK.jl b/lib/OrdinaryDiffEqPDIRK/src/OrdinaryDiffEqPDIRK.jl index ccdf6a9131..18a4e56205 100644 --- a/lib/OrdinaryDiffEqPDIRK/src/OrdinaryDiffEqPDIRK.jl +++ b/lib/OrdinaryDiffEqPDIRK/src/OrdinaryDiffEqPDIRK.jl @@ -5,7 +5,7 @@ import OrdinaryDiffEqCore: isfsal, alg_order, _unwrap_val, OrdinaryDiffEqMutableCache, constvalue, alg_cache, uses_uprev, @unpack, unwrap_alg, @cache, DEFAULT_PRECS, @threaded, initialize!, perform_step!, isthreaded, - full_cache, get_fsalfirstlast + full_cache, get_fsalfirstlast, differentiation_rk_docstring import StaticArrays: SVector import MuladdMacro: @muladd import FastBroadcast: @.. diff --git a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl index 264feb64a0..af194ec6af 100644 --- a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl @@ -1,10 +1,17 @@ -################################################################################ - -################################################# -""" -PDIRK44: Parallel Diagonally Implicit Runge-Kutta Method -A 2 processor 4th order diagonally non-adaptive implicit method. -""" +@doc differentiation_rk_docstring("A 2 processor 4th order diagonally non-adaptive implicit method.", + "PDIRK44", + "Parallel Diagonally Implicit Runge-Kutta Method."; + references = "TBD", + extra_keyword_description = """ + - `nlsolve`: TBD, + - `extrapolant`: TBD, + - `threading`: TBD, + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :constant, + threading = true, + """) struct PDIRK44{CS, AD, F, F2, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 303268835a517d6c474a2c87cd30019cb07ce726 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 15:36:25 +0200 Subject: [PATCH 39/83] more PDIRK docs --- docs/make.jl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 39adc97ccc..ca5b5cb5e1 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -27,7 +27,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqSDIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, OrdinaryDiffEq.OrdinaryDiffEqDefault, - OrdinaryDiffEq.OrdinaryDiffEqFIRK], + OrdinaryDiffEq.OrdinaryDiffEqFIRK, + OrdinaryDiffEq.OrdinaryDiffEqPDIRK], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -52,6 +53,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", ], "Iplicit Solvers" => [ "implicit/FIRK.md" + "implicit/PDIRK.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", From cfe4549a40575f88c731576cf8bf960880c250b5 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 15:36:39 +0200 Subject: [PATCH 40/83] Extrapolation docs --- docs/src/explicit/Extrapolation.md | 15 ++ .../src/OrdinaryDiffEqExtrapolation.jl | 3 +- .../src/algorithms.jl | 145 +++++++++++++----- 3 files changed, 124 insertions(+), 39 deletions(-) diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index 061cc6d410..2285506368 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -1,3 +1,18 @@ +# OrdinaryDiffEqExtrapolation + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqExtrapolation", "ImplicitEulerExtrapolation") +``` + ```@docs +AitkenNeville ImplicitEulerExtrapolation +ExtrapolationMidpointDeuflhard +ImplicitDeuflhardExtrapolation +ExtrapolationMidpointHairerWanner +ImplicitHairerWannerExtrapolation +ImplicitEulerBarycentricExtrapolation ``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl b/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl index 2f9338a874..29bbc6ca8b 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/OrdinaryDiffEqExtrapolation.jl @@ -16,7 +16,8 @@ import OrdinaryDiffEqCore: alg_order, alg_maximum_order, get_current_adaptive_or DEFAULT_PRECS, full_cache, constvalue, PolyesterThreads, Sequential, BaseThreads, _digest_beta1_beta2, timedepentdtmin, _unwrap_val, - _reshape, _vec, get_fsalfirstlast, generic_solver_docstring + _reshape, _vec, get_fsalfirstlast, generic_solver_docstring, + differentiation_rk_docstring using DiffEqBase, FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools, LinearSolve import OrdinaryDiffEqCore import OrdinaryDiffEqDifferentiation: TimeDerivativeWrapper, UDerivativeWrapper, calc_J, diff --git a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl index ec85ce8fb2..90533a7e34 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl @@ -26,33 +26,19 @@ Base.@kwdef struct AitkenNeville{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarSt threading::TO = false end -@doc generic_solver_docstring("Extrapolation of implicit Euler method with Romberg sequence. +@doc differentiation_rk_docstring("Extrapolation of implicit Euler method with Romberg sequence. Similar to Hairer's SEULEX.", "ImplicitEulerExtrapolation", "Parallelized Explicit Extrapolation Method.", - "TBD", - """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD + references = "TBD", + extra_keyword_description = """ - `max_order`: TBD - `min_order`: TBD - `init_order`: TBD - `threading`: TBD - `sequence`: TBD """, - """ - chunk_size = Val{0}(), - autodiff = true, - standardtag = Val{true}(), - concrete_jac = nothing, - diff_type = Val{:forward}, - linsolve = nothing, - precs = DEFAULT_PRECS, + extra_keyword_default = """ max_order = 12, min_order = 3, init_order = 5, @@ -110,10 +96,27 @@ Initial order: " * lpad(init_order, 2, " ") * " --> " * lpad(init_order, 2, " ") init_order, threading, sequence) end -""" -ExtrapolationMidpointDeuflhard: Parallelized Explicit Extrapolation Method -Midpoint extrapolation using Barycentric coordinates -""" + +@doc generic_solver_docstring("Midpoint extrapolation using Barycentric coordinates.", + "ExtrapolationMidpointDeuflhard", + "Parallelized Explicit Extrapolation Method.", + "REFS TBD", + """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + - `sequence_factor`: TBD + """, + """ + max_order = 10, + min_order = 1, + init_order = 5, + threading = true, + sequence = :harmonic, + sequence_factor = 2, + """) struct ExtrapolationMidpointDeuflhard{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm min_order::Int # Minimal extrapolation order @@ -163,10 +166,25 @@ Initial order: " * lpad(init_order, 2, " ") * " --> " * lpad(init_order, 2, " ") ExtrapolationMidpointDeuflhard(min_order, init_order, max_order, sequence, threading, sequence_factor) end -""" -ImplicitDeuflhardExtrapolation: Parallelized Implicit Extrapolation Method -Midpoint extrapolation using Barycentric coordinates -""" + +@doc differentiation_rk_docstring("Midpoint extrapolation using Barycentric coordinates.", + "ImplicitDeuflhardExtrapolation", + "Parallelized Explicit Extrapolation Method.", + references = "TBD", + extra_keyword_description = """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + """, + extra_keyword_default = """ + max_order = 10, + min_order = 1, + init_order = 5, + threading = false, + sequence = :harmonic, + """) struct ImplicitDeuflhardExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -221,10 +239,28 @@ Initial order: " * lpad(init_order, 2, " ") * " --> " * lpad(init_order, 2, " ") init_order, max_order, sequence, threading) end -""" -ExtrapolationMidpointHairerWanner: Parallelized Explicit Extrapolation Method -Midpoint extrapolation using Barycentric coordinates, following Hairer's ODEX in the adaptivity behavior. -""" + +@doc generic_solver_docstring("Midpoint extrapolation using Barycentric coordinates, + following Hairer's ODEX in the adaptivity behavior.", + "ExtrapolationMidpointHairerWanner", + "Parallelized Explicit Extrapolation Method.", + "REFS TBD", + """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + - `sequence_factor`: TBD + """, + """ + max_order = 10, + min_order = 2, + init_order = 5, + threading = true, + sequence = :harmonic, + sequence_factor = 2, + """) struct ExtrapolationMidpointHairerWanner{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm min_order::Int # Minimal extrapolation order @@ -276,10 +312,26 @@ Initial order: " * lpad(init_order, 2, " ") * " --> " * lpad(init_order, 2, " ") min_order, init_order, max_order, sequence, threading, sequence_factor) end -""" -ImplicitHairerWannerExtrapolation: Parallelized Implicit Extrapolation Method -Midpoint extrapolation using Barycentric coordinates, following Hairer's SODEX in the adaptivity behavior. -""" + +@doc differentiation_rk_docstring("Midpoint extrapolation using Barycentric coordinates, + following Hairer's SODEX in the adaptivity behavior.", + "ImplicitHairerWannerExtrapolation", + "Parallelized Explicit Extrapolation Method.", + references = "TBD", + extra_keyword_description = """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + """, + extra_keyword_default = """ + max_order = 10, + min_order = 2, + init_order = 5, + threading = false, + sequence = :harmonic, + """) struct ImplicitHairerWannerExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -337,10 +389,27 @@ Initial order: " * lpad(init_order, 2, " ") * " --> " * lpad(init_order, 2, " ") max_order, sequence, threading) end -""" -ImplicitEulerBarycentricExtrapolation: Parallelized Implicit Extrapolation Method -Euler extrapolation using Barycentric coordinates, following Hairer's SODEX in the adaptivity behavior. -""" +@doc differentiation_rk_docstring("Euler extrapolation using Barycentric coordinates, + following Hairer's SODEX in the adaptivity behavior.", + "ImplicitEulerBarycentricExtrapolation", + "Parallelized Explicit Extrapolation Method.", + references = "TBD", + extra_keyword_description = """ + - `max_order`: TBD + - `min_order`: TBD + - `init_order`: TBD + - `threading`: TBD + - `sequence`: TBD + - `sequence_factor`: TBD + """, + extra_keyword_default = """ + max_order = 10, + min_order = 3, + init_order = 5, + threading = false, + sequence = :harmonic, + sequence_factor = 2, + """) struct ImplicitEulerBarycentricExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From daffc25ed903d11485f83f77e8c71ce6f829ac14 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 17:13:19 +0200 Subject: [PATCH 41/83] docs Rosenbrock --- docs/make.jl | 8 +-- docs/src/implicit/Rosenbrock.md | 50 +++++++++++++++++++ .../src/OrdinaryDiffEqRosenbrock.jl | 38 +++++++++----- 3 files changed, 80 insertions(+), 16 deletions(-) create mode 100644 docs/src/implicit/Rosenbrock.md diff --git a/docs/make.jl b/docs/make.jl index ca5b5cb5e1..5998ea4968 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -28,7 +28,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqBDF, OrdinaryDiffEq.OrdinaryDiffEqDefault, OrdinaryDiffEq.OrdinaryDiffEqFIRK, - OrdinaryDiffEq.OrdinaryDiffEqPDIRK], + OrdinaryDiffEq.OrdinaryDiffEqPDIRK, + OrdinaryDiffEq.OrdinaryDiffEqRosenbrock], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -52,8 +53,9 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Extrapolation.md", ], "Iplicit Solvers" => [ - "implicit/FIRK.md" - "implicit/PDIRK.md" + "implicit/FIRK.md", + "implicit/PDIRK.md", + "implicit/Rosenbrock.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", diff --git a/docs/src/implicit/Rosenbrock.md b/docs/src/implicit/Rosenbrock.md new file mode 100644 index 0000000000..337c8cee6c --- /dev/null +++ b/docs/src/implicit/Rosenbrock.md @@ -0,0 +1,50 @@ +# OrdinaryDiffEqRosenbrock + +Methods for small and medium sized stiff systems of differential equations. +At high tolerances, `>1e-2`, `Rosenbrock23` is a good choice. +At medium tolerances `>1e-8` it is recommended you use `Rodas5P` or `Rodas4P`, +the former is more efficient, but the latter is more reliable. +For larger systems look at multistep methods. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqRosenbrock", "Rodas5P") +``` + +```@docs +Rosenbrock23 +Rosenbrock32 +ROS3P +Rodas3 +Rodas23W +Rodas3P +Rodas4 +Rodas42 +Rodas4P +Rodas4P2 +Rodas5 +Rodas5P +Rodas5Pe +Rodas5Pr +RosenbrockW6S4OS +ROS2 +ROS2PR +ROS2S +ROS3 +ROS3PR +Scholz4_7 +ROS34PW1a +ROS34PW1b +ROS34PW2 +ROS34PW3 +ROS34PRw +ROS3PRL +ROS3PRL2 +ROK4a +RosShamp4 +Veldd4 +Velds4 +GRK4T +GRK4A +Ros4LStab +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl index ae3b93b291..5228b77e1a 100644 --- a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl +++ b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl @@ -48,15 +48,21 @@ function rosenbrock_wanner_docstring(description::String, extra_keyword_default = "", with_step_limiter = false) keyword_default = """ + chunk_size = Val{0}(), + standardtag = Val{true}(), autodiff = Val{true}(), concrete_jac = nothing, + diff_type = Val{:central}, linsolve = nothing, precs = DEFAULT_PRECS, """ * extra_keyword_default keyword_default_description = """ + - `chunk_size`: TBD + - `standardtag`: TBD - `autodiff`: boolean to control if the Jacobian should be computed via AD or not - `concrete_jac`: function of the form `jac!(J, u, p, t)` + - `diff_type`: TBD - `linsolve`: custom solver for the inner linear systems - `precs`: custom preconditioner for the inner linear solver """ * extra_keyword_description @@ -78,19 +84,25 @@ function rosenbrock_docstring(description::String, extra_keyword_description = "", extra_keyword_default = "", with_step_limiter = false) - keyword_default = """ - autodiff = Val{true}(), - concrete_jac = nothing, - linsolve = nothing, - precs = DEFAULT_PRECS, - """ * extra_keyword_default - - keyword_default_description = """ - - `autodiff`: boolean to control if the Jacobian should be computed via AD or not - - `concrete_jac`: function of the form `jac!(J, u, p, t)` - - `linsolve`: custom solver for the inner linear systems - - `precs`: custom preconditioner for the inner linear solver - """ * extra_keyword_description + keyword_default = """ + chunk_size = Val{0}(), + standardtag = Val{true}(), + autodiff = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:central}, + linsolve = nothing, + precs = DEFAULT_PRECS, + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `standardtag`: TBD + - `autodiff`: boolean to control if the Jacobian should be computed via AD or not + - `concrete_jac`: function of the form `jac!(J, u, p, t)` + - `diff_type`: TBD + - `linsolve`: custom solver for the inner linear systems + - `precs`: custom preconditioner for the inner linear solver + """ * extra_keyword_description if with_step_limiter keyword_default *= "step_limiter! = OrdinaryDiffEq.trivial_limiter!,\n" From 21f47aadfd8df67ef8537bee37456a0bf0d54ff6 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 17:51:38 +0200 Subject: [PATCH 42/83] delete refactored implicit docstrings --- docs/src/stiff/firk.md | 6 ---- docs/src/stiff/implicit_extrapolation.md | 8 ----- docs/src/stiff/rosenbrock.md | 44 ------------------------ docs/src/stiff/stabilized_rk.md | 28 --------------- 4 files changed, 86 deletions(-) delete mode 100644 docs/src/stiff/firk.md delete mode 100644 docs/src/stiff/implicit_extrapolation.md delete mode 100644 docs/src/stiff/rosenbrock.md delete mode 100644 docs/src/stiff/stabilized_rk.md diff --git a/docs/src/stiff/firk.md b/docs/src/stiff/firk.md deleted file mode 100644 index 774562b1de..0000000000 --- a/docs/src/stiff/firk.md +++ /dev/null @@ -1,6 +0,0 @@ -# Fully Implicit Runge-Kutta (FIRK) Methods - -```@docs -RadauIIA3 -RadauIIA5 -``` diff --git a/docs/src/stiff/implicit_extrapolation.md b/docs/src/stiff/implicit_extrapolation.md deleted file mode 100644 index 95677e885f..0000000000 --- a/docs/src/stiff/implicit_extrapolation.md +++ /dev/null @@ -1,8 +0,0 @@ -# Implicit Extrapolation Methods - -```@docs -ImplicitEulerExtrapolation -ImplicitDeuflhardExtrapolation -ImplicitHairerWannerExtrapolation -ImplicitEulerBarycentricExtrapolation -``` diff --git a/docs/src/stiff/rosenbrock.md b/docs/src/stiff/rosenbrock.md deleted file mode 100644 index e44443d7f6..0000000000 --- a/docs/src/stiff/rosenbrock.md +++ /dev/null @@ -1,44 +0,0 @@ -# Rosenbrock Methods - -## Standard Rosenbrock Methods - -```@docs -ROS2 -ROS3 -ROS2PR -ROS3PR -Scholz4_7 -ROS3PRL -ROS3PRL2 -ROS3P -Rodas3 -Rodas3P -RosShamp4 -Veldd4 -Velds4 -GRK4T -GRK4A -Ros4LStab -Rodas4 -Rodas42 -Rodas4P -Rodas4P2 -Rodas5 -Rodas5P -``` - -## Rosenbrock W-Methods - -```@docs -Rosenbrock23 -Rosenbrock32 -Rodas23W -ROS34PW1a -ROS34PW1b -ROS34PW2 -ROS34PW3 -ROS34PRw -ROK4a -ROS2S -RosenbrockW6S4OS -``` diff --git a/docs/src/stiff/stabilized_rk.md b/docs/src/stiff/stabilized_rk.md deleted file mode 100644 index 927aa3f94f..0000000000 --- a/docs/src/stiff/stabilized_rk.md +++ /dev/null @@ -1,28 +0,0 @@ -# Stabilized Runge-Kutta Methods (Runge-Kutta-Chebyshev) - -## Explicit Stabilized Runge-Kutta Methods - -Explicit stabilized methods utilize an upper bound on the spectral radius of the Jacobian. -Users can supply an upper bound by specifying the keyword argument `eigen_est`, for example - -```julia -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound` -``` - -The methods `ROCK2` and `ROCK4` also include keyword arguments `min_stages` and `max_stages`, -which specify upper and lower bounds on the adaptively chosen number of stages for stability. - -```@docs -ROCK2 -ROCK4 -SERK2 -ESERK4 -ESERK5 -RKC -``` - -## Implicit Stabilized Runge-Kutta Methods - -```@docs -IRKC -``` From 58b16a66251f3d83f5518f7f2b1f35e6b585d860 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 17:52:32 +0200 Subject: [PATCH 43/83] docs StabalizedRK --- docs/make.jl | 10 +- docs/src/implicit/StabalizedRK.md | 25 +++ .../src/OrdinaryDiffEqStabilizedRK.jl | 3 +- .../src/algorithms.jl | 189 ++++++++++-------- 4 files changed, 132 insertions(+), 95 deletions(-) create mode 100644 docs/src/implicit/StabalizedRK.md diff --git a/docs/make.jl b/docs/make.jl index 5998ea4968..d0319362ac 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -29,7 +29,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqDefault, OrdinaryDiffEq.OrdinaryDiffEqFIRK, OrdinaryDiffEq.OrdinaryDiffEqPDIRK, - OrdinaryDiffEq.OrdinaryDiffEqRosenbrock], + OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, + OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -55,19 +56,16 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "Iplicit Solvers" => [ "implicit/FIRK.md", "implicit/PDIRK.md", - "implicit/Rosenbrock.md" + "implicit/Rosenbrock.md", + "implicit/StabalizedRK.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", "nonstiff/nonstiff_multistep.md" ], "Standard Stiff ODEProblem Solvers" => [ - "stiff/firk.md", - "stiff/rosenbrock.md", - "stiff/stabilized_rk.md", "stiff/sdirk.md", "stiff/stiff_multistep.md", - "stiff/implicit_extrapolation.md" ], "IMEX Solvers" => [ "imex/imex_multistep.md", diff --git a/docs/src/implicit/StabalizedRK.md b/docs/src/implicit/StabalizedRK.md new file mode 100644 index 0000000000..91e8daabb7 --- /dev/null +++ b/docs/src/implicit/StabalizedRK.md @@ -0,0 +1,25 @@ +# OrdinaryDiffEqStabalizedRK + +Explicit stabilized methods utilize an upper bound on the spectral radius of the Jacobian. +Users can supply an upper bound by specifying the keyword argument `eigen_est`, for example + +```julia +`eigen_est = (integrator) -> integrator.eigen_est = upper_bound` +``` + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqStabalizedRK", "ROCK4") +``` + +## Full list of solvers + +```@docs +ROCK2 +ROCK4 +RKC +SERK2 +ESERK4 +ESERK5 +``` + diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/OrdinaryDiffEqStabilizedRK.jl b/lib/OrdinaryDiffEqStabilizedRK/src/OrdinaryDiffEqStabilizedRK.jl index 10a03b8d2b..d9ad47342e 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/OrdinaryDiffEqStabilizedRK.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/OrdinaryDiffEqStabilizedRK.jl @@ -9,7 +9,8 @@ import OrdinaryDiffEqCore: alg_order, alg_adaptive_order, calculate_residuals!, OrdinaryDiffEqMutableCache, OrdinaryDiffEqConstantCache, OrdinaryDiffEqAdaptiveAlgorithm, calc_dt_propose!, alg_cache, _vec, _reshape, @cache, - constvalue, _unwrap_val, full_cache, get_fsalfirstlast + constvalue, _unwrap_val, full_cache, get_fsalfirstlast, + generic_solver_docstring using FastBroadcast, MuladdMacro, RecursiveArrayTools import StaticArrays: SArray, MVector, SVector, @SVector, StaticArray, MMatrix, SA import OrdinaryDiffEqCore diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl index de7c9228e7..0cda2709ee 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl @@ -1,19 +1,23 @@ -""" -Assyr Abdulle, Alexei A. Medovikov. Second Order Chebyshev Methods based on Orthogonal Polynomials. -Numerische Mathematik, 90 (1), pp 1-18, 2001. doi: https://dx.doi.org/10.1007/s002110100292 -ROCK2: Stabilized Explicit Method. -Second order stabilized Runge-Kutta method. -Exhibits high stability for real eigenvalues and is smoothened to allow for moderate sized complex eigenvalues. - -This method takes optional keyword arguments `min_stages`, `max_stages`, and `eigen_est`. -The function `eigen_est` should be of the form - -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound`, - -where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. If `eigen_est` -is not provided, `upper_bound` will be estimated using the power iteration. -""" +@doc generic_solver_docstring("""Second order method. Exhibits high stability for real eigenvalues + and is smoothened to allow for moderate sized complex eigenvalues.""", + "ROCK2", + "Stabilized Explicit Method.", + """Assyr Abdulle, Alexei A. Medovikov. Second Order Chebyshev Methods based on Orthogonal Polynomials. + Numerische Mathematik, 90 (1), pp 1-18, 2001. doi: https://dx.doi.org/10.1007/s002110100292""", + """ + - `min_stages`: TBD + - `max_stages`: TBD + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + min_stages = 0, + max_stages = 200, + eigen_est = nothing, + """) struct ROCK2{E} <: OrdinaryDiffEqAdaptiveAlgorithm min_stages::Int max_stages::Int @@ -23,25 +27,26 @@ function ROCK2(; min_stages = 0, max_stages = 200, eigen_est = nothing) ROCK2(min_stages, max_stages, eigen_est) end -""" - ROCK4(; min_stages = 0, max_stages = 152, eigen_est = nothing) - -Assyr Abdulle. Fourth Order Chebyshev Methods With Recurrence Relation. 2002 Society for -Industrial and Applied Mathematics Journal on Scientific Computing, 23(6), pp 2041-2054, 2001. -doi: https://doi.org/10.1137/S1064827500379549 - -ROCK4: Stabilized Explicit Method. -Fourth order stabilized Runge-Kutta method. -Exhibits high stability for real eigenvalues and is smoothened to allow for moderate sized complex eigenvalues. - -This method takes optional keyword arguments `min_stages`, `max_stages`, and `eigen_est`. -The function `eigen_est` should be of the form - -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound`, - -where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. If `eigen_est` -is not provided, `upper_bound` will be estimated using the power iteration. -""" +@doc generic_solver_docstring("""Fourth order method. Exhibits high stability for real eigenvalues + and is smoothened to allow for moderate sized complex eigenvalues.""", + "ROCK4", + "Stabilized Explicit Method.", + """Assyr Abdulle. Fourth Order Chebyshev Methods With Recurrence Relation. 2002 Society for + Industrial and Applied Mathematics Journal on Scientific Computing, 23(6), pp 2041-2054, 2001. + doi: https://doi.org/10.1137/S1064827500379549""", + """ + - `min_stages`: TBD + - `max_stages`: TBD + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + min_stages = 0, + max_stages = 152, + eigen_est = nothing, + """) struct ROCK4{E} <: OrdinaryDiffEqAdaptiveAlgorithm min_stages::Int max_stages::Int @@ -62,66 +67,74 @@ for Alg in [:ESERK4, :ESERK5, :RKC] end end -""" - RKC(; eigen_est = nothing) - -B. P. Sommeijer, L. F. Shampine, J. G. Verwer. RKC: An Explicit Solver for Parabolic PDEs, -Journal of Computational and Applied Mathematics, 88(2), pp 315-326, 1998. doi: -https://doi.org/10.1016/S0377-0427(97)00219-7 - -RKC: Stabilized Explicit Method. -Second order stabilized Runge-Kutta method. -Exhibits high stability for real eigenvalues. - -This method takes the keyword argument `eigen_est` of the form - -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound`, - -where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. If `eigen_est` -is not provided, `upper_bound` will be estimated using the power iteration. -""" +@doc generic_solver_docstring("""Second order method. Exhibits high stability for real eigenvalues.""", + "RKC", + "Stabilized Explicit Method.", + """B. P. Sommeijer, L. F. Shampine, J. G. Verwer. RKC: An Explicit Solver for Parabolic PDEs, + Journal of Computational and Applied Mathematics, 88(2), pp 315-326, 1998. doi: + https://doi.org/10.1016/S0377-0427(97)00219-7""", + """ + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + eigen_est = nothing, + """) function RKC end -""" - ESERK4(; eigen_est = nothing) - -J. Martín-Vaquero, B. Kleefeld. Extrapolated stabilized explicit Runge-Kutta methods, -Journal of Computational Physics, 326, pp 141-155, 2016. doi: -https://doi.org/10.1016/j.jcp.2016.08.042. - -ESERK4: Stabilized Explicit Method. -Fourth order extrapolated stabilized Runge-Kutta method. -Exhibits high stability for real eigenvalues and is smoothened to allow for moderate sized complex eigenvalues. - -This method takes the keyword argument `eigen_est` of the form - -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound`, - -where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. -If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. -""" +@doc generic_solver_docstring("""Fourth order method. Exhibits high stability for real eigenvalues + and is smoothened to allow for moderate sized complex eigenvalues.""", + "ESERK4", + "Stabilized Explicit Method.", + """J. Martín-Vaquero, B. Kleefeld. Extrapolated stabilized explicit Runge-Kutta methods, + Journal of Computational Physics, 326, pp 141-155, 2016. doi: + https://doi.org/10.1016/j.jcp.2016.08.042.""", + """ + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + eigen_est = nothing, + """) function ESERK4 end -""" - ESERK5(; eigen_est = nothing) - -J. Martín-Vaquero, A. Kleefeld. ESERK5: A fifth-order extrapolated stabilized explicit Runge-Kutta method, -Journal of Computational and Applied Mathematics, 356, pp 22-36, 2019. doi: -https://doi.org/10.1016/j.cam.2019.01.040. - -ESERK5: Stabilized Explicit Method. -Fifth order extrapolated stabilized Runge-Kutta method. -Exhibits high stability for real eigenvalues and is smoothened to allow for moderate sized complex eigenvalues. - -This method takes the keyword argument `eigen_est` of the form - -`eigen_est = (integrator) -> integrator.eigen_est = upper_bound`, - -where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. -If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. -""" +@doc generic_solver_docstring("""Fifth order method. Exhibits high stability for real eigenvalues + and is smoothened to allow for moderate sized complex eigenvalues.""", + "ESERK5", + "Stabilized Explicit Method.", + """J. Martín-Vaquero, A. Kleefeld. ESERK5: A fifth-order extrapolated stabilized explicit Runge-Kutta method, + Journal of Computational and Applied Mathematics, 356, pp 22-36, 2019. doi: + https://doi.org/10.1016/j.cam.2019.01.040.""", + """ + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + eigen_est = nothing, + """) function ESERK5 end +@doc generic_solver_docstring("""Second order method. description TBD""", + "ESERK5", + "Stabilized Explicit Method.", + """REF TBD""", + """ + - `controller`: TBD + - `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration. + """, + """ + controller = :PI + eigen_est = nothing, + """) struct SERK2{E} <: OrdinaryDiffEqAdaptiveAlgorithm controller::Symbol eigen_est::E From cb5ed9c4bd2fcd6c2aee5b7ea15b27e42f25df46 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 17:55:56 +0200 Subject: [PATCH 44/83] fix name SERK2 --- lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl index 0cda2709ee..78c1ea0256 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl @@ -121,7 +121,7 @@ function ESERK4 end function ESERK5 end @doc generic_solver_docstring("""Second order method. description TBD""", - "ESERK5", + "SERK2", "Stabilized Explicit Method.", """REF TBD""", """ From 863b36527e60543d4464b25854c0dacb2773248b Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 18:36:38 +0200 Subject: [PATCH 45/83] add some subtitles in documentation --- docs/src/explicit/Extrapolation.md | 2 ++ docs/src/implicit/FIRK.md | 2 ++ docs/src/implicit/PDIRK.md | 2 ++ docs/src/implicit/Rosenbrock.md | 2 ++ 4 files changed, 8 insertions(+) diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index 2285506368..7f172a9bb2 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -7,6 +7,8 @@ first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqExtrapolation", "ImplicitEulerExtrapolation") ``` +## Full list of solvers + ```@docs AitkenNeville ImplicitEulerExtrapolation diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md index 9dff594b73..d00d79beb6 100644 --- a/docs/src/implicit/FIRK.md +++ b/docs/src/implicit/FIRK.md @@ -7,6 +7,8 @@ first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqFIRK", "RadauIIA5") ``` +## Full list of solvers + ```@docs RadauIIA3 RadauIIA5 diff --git a/docs/src/implicit/PDIRK.md b/docs/src/implicit/PDIRK.md index f97d1b416b..3d9073d8d0 100644 --- a/docs/src/implicit/PDIRK.md +++ b/docs/src/implicit/PDIRK.md @@ -7,6 +7,8 @@ first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqPDIRK", "PDIRK44") ``` +## Full list of solvers + ```@docs PDIRK44 ``` \ No newline at end of file diff --git a/docs/src/implicit/Rosenbrock.md b/docs/src/implicit/Rosenbrock.md index 337c8cee6c..116dd934ec 100644 --- a/docs/src/implicit/Rosenbrock.md +++ b/docs/src/implicit/Rosenbrock.md @@ -11,6 +11,8 @@ first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqRosenbrock", "Rodas5P") ``` +## Full list of solvers + ```@docs Rosenbrock23 Rosenbrock32 From 5ab2ad42530a435b67373ebc6cad098f27a6ef3d Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 18:37:04 +0200 Subject: [PATCH 46/83] add more references --- .../src/algorithms.jl | 19 +- .../src/OrdinaryDiffEqLowOrderRK.jl | 3 +- .../src/algorithms.jl | 47 ++++- .../src/algorithms.jl | 176 ++++++++++++++++-- 4 files changed, 219 insertions(+), 26 deletions(-) diff --git a/lib/OrdinaryDiffEqHighOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqHighOrderRK/src/algorithms.jl index 32ddbc9dd7..87f2740948 100644 --- a/lib/OrdinaryDiffEqHighOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqHighOrderRK/src/algorithms.jl @@ -15,7 +15,16 @@ function TanYam7(stage_limiter!, step_limiter! = trivial_limiter!) TanYam7(stage_limiter!, step_limiter!, False()) end -@doc explicit_rk_docstring("Tsitouras-Papakostas 8/7 Runge-Kutta method.", "TsitPap8") +@doc explicit_rk_docstring("Tsitouras-Papakostas 8/7 Runge-Kutta method.", "TsitPap8", + references = """@article{tsitouras1999cheap, + title={Cheap error estimation for Runge--Kutta methods}, + author={Tsitouras, Ch and Papakostas, SN}, + journal={SIAM Journal on Scientific Computing}, + volume={20}, + number={6}, + pages={2067--2088}, + year={1999}, + publisher={SIAM}}""") Base.@kwdef struct TsitPap8{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -44,6 +53,14 @@ function DP8(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring("Phase-fitted Runge-Kutta of 8th order.", "PFRK87", + references = """@article{tsitouras2017phase, + title={Phase-fitted Runge--Kutta pairs of orders 8 (7)}, + author={Tsitouras, Ch and Famelis, I Th and Simos, TE}, + journal={Journal of Computational and Applied Mathematics}, + volume={321}, + pages={226--231}, + year={2017}, + publisher={Elsevier}}""", extra_keyword_description = """- `omega`: a periodicity phase estimate, when accurate this method results in zero numerical dissipation. """, diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/OrdinaryDiffEqLowOrderRK.jl b/lib/OrdinaryDiffEqLowOrderRK/src/OrdinaryDiffEqLowOrderRK.jl index 1f83cc628b..5d3455a4ea 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/OrdinaryDiffEqLowOrderRK.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/OrdinaryDiffEqLowOrderRK.jl @@ -4,7 +4,8 @@ import OrdinaryDiffEqCore: alg_order, isfsal, beta2_default, beta1_default, alg_stability_size, ssp_coefficient, OrdinaryDiffEqAlgorithm, OrdinaryDiffEqExponentialAlgorithm, - explicit_rk_docstring, trivial_limiter!, + explicit_rk_docstring, generic_solver_docstring, + trivial_limiter!, OrdinaryDiffEqAdaptiveAlgorithm, unwrap_alg, @unpack, initialize!, perform_step!, calculate_residuals, diff --git a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl index e120187bd4..2c9472fb27 100644 --- a/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowOrderRK/src/algorithms.jl @@ -1,6 +1,10 @@ -""" -Euler - The canonical forward Euler method. Fixed timestep only. -""" +@doc generic_solver_docstring( + "The canonical forward Euler method. Fixed timestep only.", + "Euler", + "Explicit Runge-Kutta Method.", + """E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.""", "", "") struct Euler <: OrdinaryDiffEqAlgorithm end struct SplitEuler <: @@ -8,7 +12,10 @@ struct SplitEuler <: @doc explicit_rk_docstring( "The second order Heun's method. Uses embedded Euler method for adaptivity.", - "Heun") + "Heun", + references = """E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.""") Base.@kwdef struct Heun{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -22,7 +29,10 @@ end @doc explicit_rk_docstring( "The optimized second order midpoint method. Uses embedded Euler method for adaptivity.", - "Ralston") + "Ralston", + references = """E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.""") Base.@kwdef struct Ralston{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -36,7 +46,10 @@ end @doc explicit_rk_docstring( "The second order midpoint method. Uses embedded Euler method for adaptivity.", - "Midpoint") + "Midpoint", + references = """E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. + Nonstiff Problems. 2nd Edition. Springer Series in Computational Mathematics, + Springer-Verlag.""") Base.@kwdef struct Midpoint{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -222,7 +235,16 @@ AutoDP5(alg; kwargs...) = AutoAlgSwitch(DP5(), alg; kwargs...) "Anas5", extra_keyword_description = """- `w`: a periodicity estimate, which when accurate the method becomes 5th order (and is otherwise 4th order with less error for better estimates).""", - extra_keyword_default = "w = 1") + extra_keyword_default = "w = 1", + references = """@article{anastassi2005optimized, + title={An optimized Runge--Kutta method for the solution of orbital problems}, + author={Anastassi, ZA and Simos, TE}, + journal={Journal of Computational and Applied Mathematics}, + volume={175}, + number={1}, + pages={1--9}, + year={2005}, + publisher={Elsevier}}""") Base.@kwdef struct Anas5{StageLimiter, StepLimiter, Thread, T} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! @@ -251,7 +273,16 @@ end @doc explicit_rk_docstring("Zero Dissipation Runge-Kutta of 6th order.", "FRK65", extra_keyword_description = """- `omega`: a periodicity phase estimate, when accurate this method results in zero numerical dissipation.""", - extra_keyword_default = "omega = 0.0") + extra_keyword_default = "omega = 0.0", + references = """@article{medvedev2018fitted, + title={Fitted modifications of Runge-Kutta pairs of orders 6 (5)}, + author={Medvedev, Maxim A and Simos, TE and Tsitouras, Ch}, + journal={Mathematical Methods in the Applied Sciences}, + volume={41}, + number={16}, + pages={6184--6194}, + year={2018}, + publisher={Wiley Online Library}}""") Base.@kwdef struct FRK65{StageLimiter, StepLimiter, Thread, T} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! diff --git a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl index bd5ed4c23a..fe3822254f 100644 --- a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl @@ -468,7 +468,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 4-stage, third order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK43_2") +", "CKLLSRK43_2", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK43_2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -485,7 +494,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3C") +", "CKLLSRK54_3C", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3C{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -502,7 +520,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK95_4S") +", "CKLLSRK95_4S", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4S{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -519,7 +546,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK95_4C") +", "CKLLSRK95_4C", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4C{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -536,7 +572,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK95_4M") +", "CKLLSRK95_4M", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4M{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -553,7 +598,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3C_3R") +", "CKLLSRK54_3C_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3C_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -570,7 +624,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3M_3R") +", "CKLLSRK54_3M_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3M_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -587,7 +650,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3N_3R") +", "CKLLSRK54_3N_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3N_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -604,7 +676,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK85_4C_3R") +", "CKLLSRK85_4C_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4C_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -621,7 +702,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK85_4M_3R") +", "CKLLSRK85_4M_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4M_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -638,7 +728,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK85_4P_3R") +", "CKLLSRK85_4P_3R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4P_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -655,7 +754,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3N_4R") +", "CKLLSRK54_3N_4R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3N_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -672,7 +780,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. -", "CKLLSRK54_3M_4R") +", "CKLLSRK54_3M_4R", +references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3M_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -688,7 +805,16 @@ end @doc explicit_rk_docstring( "6-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations.", - "CKLLSRK65_4M_4R") + "CKLLSRK65_4M_4R", + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK65_4M_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -705,7 +831,16 @@ end @doc explicit_rk_docstring( "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations.", - "CKLLSRK85_4FM_4R") + "CKLLSRK85_4FM_4R", + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4FM_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -722,7 +857,16 @@ end @doc explicit_rk_docstring( "CKLLSRK75_4M_5R: Low-Storage Method 7-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations.", - "CKLLSRK75_4M_5R") + "CKLLSRK75_4M_5R", + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK75_4M_5R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! From 788d90042348f19fc0d91e49f95e12d6f131c4e2 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 18:38:34 +0200 Subject: [PATCH 47/83] add PDIRK explanation --- docs/src/implicit/PDIRK.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/src/implicit/PDIRK.md b/docs/src/implicit/PDIRK.md index 3d9073d8d0..65e3b24737 100644 --- a/docs/src/implicit/PDIRK.md +++ b/docs/src/implicit/PDIRK.md @@ -1,6 +1,22 @@ # OrdinaryDiffEqPDIRK -This article is a stub. +PDIRK methods are parallel DIRK methods. +SDIRK methods, or singly-diagonally implicit methods, +have to build and solve a factorize a Jacobian of the form `W = I-gammaJ` where `gamma` is dependent on the chosen method. +PDIRK methods use multiple different choices of `gamma`, i.e. `W_i = I-gamma_iJ`, +which are all used in the update process. +There are some advantages to this, +as no SDIRK method can be a higher order than 5, +while DIRK methods generally can have arbitrarily high order and lower error coefficients, +leading to lower errors at larger dt sizes. +With the right construction of the tableau, +these matrices can be factorized and the underlying steps can be computed in parallel, +which is why these are the parallel DIRK methods. + +!!! warning "Experimental" + `OrdinaryDiffEqPDIRK` is experimental, + as there are no parallel DIRK tableaus that achieve good performance in the literature. + ```@eval first_steps = evalfile("./common_first_steps.jl") From 2457ecfa2c302463e496003a24aa055cb0a95f45 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sun, 18 Aug 2024 22:03:05 +0200 Subject: [PATCH 48/83] docs BDF --- docs/make.jl | 14 +- docs/src/dae/fully_implicit.md | 7 - docs/src/imex/imex_multistep.md | 4 - docs/src/implicit/BDF.md | 35 ++ docs/src/stiff/stiff_multistep.md | 13 - .../src/OrdinaryDiffEqBDF.jl | 2 +- lib/OrdinaryDiffEqBDF/src/algorithms.jl | 308 ++++++++++++++---- 7 files changed, 291 insertions(+), 92 deletions(-) delete mode 100644 docs/src/dae/fully_implicit.md create mode 100644 docs/src/implicit/BDF.md delete mode 100644 docs/src/stiff/stiff_multistep.md diff --git a/docs/make.jl b/docs/make.jl index d0319362ac..59016d38cf 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -30,7 +30,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqFIRK, OrdinaryDiffEq.OrdinaryDiffEqPDIRK, OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK], + OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, + OrdinaryDiffEq.OrdinaryDiffEqBDF], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -53,19 +54,19 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/PRK.md", "explicit/Extrapolation.md", ], - "Iplicit Solvers" => [ + "Implicit Solvers" => [ "implicit/FIRK.md", "implicit/PDIRK.md", "implicit/Rosenbrock.md", - "implicit/StabalizedRK.md" + "implicit/StabalizedRK.md", + "implicit/BDF.md" ], "Standard Non-Stiff ODEProblem Solvers" => [ "nonstiff/explicit_extrapolation.md", "nonstiff/nonstiff_multistep.md" ], "Standard Stiff ODEProblem Solvers" => [ - "stiff/sdirk.md", - "stiff/stiff_multistep.md", + "stiff/sdirk.md" ], "IMEX Solvers" => [ "imex/imex_multistep.md", @@ -75,9 +76,6 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "semilinear/exponential_rk.md", "semilinear/magnus.md" ], - "DAEProblem Solvers" => [ - "dae/fully_implicit.md" - ], "Misc Solvers" => [ "misc.md" ] diff --git a/docs/src/dae/fully_implicit.md b/docs/src/dae/fully_implicit.md deleted file mode 100644 index b9fcb50da9..0000000000 --- a/docs/src/dae/fully_implicit.md +++ /dev/null @@ -1,7 +0,0 @@ -# Methods for Fully Implicit ODEs (DAEProblem) - -```@docs -DImplicitEuler -DABDF2 -DFBDF -``` diff --git a/docs/src/imex/imex_multistep.md b/docs/src/imex/imex_multistep.md index aa87f22b59..d809534362 100644 --- a/docs/src/imex/imex_multistep.md +++ b/docs/src/imex/imex_multistep.md @@ -3,8 +3,4 @@ ```@docs CNAB2 CNLF2 -SBDF -SBDF2 -SBDF3 -SBDF4 ``` diff --git a/docs/src/implicit/BDF.md b/docs/src/implicit/BDF.md new file mode 100644 index 0000000000..06b08263a6 --- /dev/null +++ b/docs/src/implicit/BDF.md @@ -0,0 +1,35 @@ +# OrdinaryDiffEqBDF + +Multistep methods, good for large stiff systems. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqBDF", "QNDF") +``` + +## Full list of solvers + +```@docs +ABDF2 +QNDF +QNDF1 +QNDF2 +QBDF +QBDF1 +QBDF2 +MEBDF2 +FBDF +``` +### IMEX Multistep +```@docs +OrdinaryDiffEqBDF.SBDF +SBDF2 +SBDF3 +SBDF4 +``` +### DAE +```@docs +DImplicitEuler +DABDF2 +DFBDF +``` \ No newline at end of file diff --git a/docs/src/stiff/stiff_multistep.md b/docs/src/stiff/stiff_multistep.md deleted file mode 100644 index b84e2e88c0..0000000000 --- a/docs/src/stiff/stiff_multistep.md +++ /dev/null @@ -1,13 +0,0 @@ -# Multistep Methods for Stiff Equations - -```@docs -QNDF1 -QBDF1 -QNDF2 -QBDF2 -ABDF2 -QNDF -QBDF -FBDF -MEBDF2 -``` diff --git a/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl b/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl index 28d3ab39c3..575d22ecc5 100644 --- a/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl +++ b/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl @@ -20,7 +20,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, step_accept_controller!, step_reject_controller!, post_newton_controller!, u_modified!, DAEAlgorithm, _unwrap_val, DummyController, - get_fsalfirstlast + get_fsalfirstlast, generic_solver_docstring using OrdinaryDiffEqSDIRK: ImplicitEulerConstantCache, ImplicitEulerCache using TruncatedStacktraces, MuladdMacro, MacroTools, FastBroadcast, RecursiveArrayTools diff --git a/lib/OrdinaryDiffEqBDF/src/algorithms.jl b/lib/OrdinaryDiffEqBDF/src/algorithms.jl index 4f25e268a7..797a63191c 100644 --- a/lib/OrdinaryDiffEqBDF/src/algorithms.jl +++ b/lib/OrdinaryDiffEqBDF/src/algorithms.jl @@ -1,11 +1,61 @@ -""" -E. Alberdi Celayaa, J. J. Anza Aguirrezabalab, P. Chatzipantelidisc. Implementation of -an Adaptive BDF2 Formula and Comparison with The MATLAB Ode15s. Procedia Computer Science, -29, pp 1014-1026, 2014. doi: https://doi.org/10.1016/j.procs.2014.05.091 +function BDF_docstring(description::String, + name::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") + keyword_default = """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + - `precs`: TBD + """ * extra_keyword_description + + generic_solver_docstring( + description, name, "Multistep Method.", references, + keyword_default_description, keyword_default + ) +end -ABDF2: Multistep Method -An adaptive order 2 L-stable fixed leading coefficient multistep BDF method. -""" + +@doc BDF_docstring("An adaptive order 2 L-stable fixed leading coefficient multistep BDF method.", + "ABDF2", + references = """ + E. Alberdi Celayaa, J. J. Anza Aguirrezabalab, P. Chatzipantelidisc. Implementation of + an Adaptive BDF2 Formula and Comparison with The MATLAB Ode15s. Procedia Computer Science, + 29, pp 1014-1026, 2014. doi: https://doi.org/10.1016/j.procs.2014.05.091 + """, + extra_keyword_description = """ + - `κ`: TBD + - `tol`: TBD + - `nlsolve`: TBD + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + κ = nothing, + tol = nothing, + nlsolve = NLNewton(), + smooth_est = true, + extrapolant = :linear, + controller = :Standard, + step_limiter! = trivial_limiter!, + """) struct ABDF2{CS, AD, F, F2, P, FDT, ST, CJ, K, T, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -31,11 +81,29 @@ function ABDF2(; chunk_size = Val{0}(), autodiff = true, standardtag = Val{true} smooth_est, extrapolant, controller, step_limiter!) end -""" -Uri M. Ascher, Steven J. Ruuth, Brian T. R. Wetton. Implicit-Explicit Methods for Time- -Dependent Partial Differential Equations. 1995 Society for Industrial and Applied Mathematics -Journal on Numerical Analysis, 32(3), pp 797-823, 1995. doi: https://doi.org/10.1137/0732037 -""" + +@doc BDF_docstring("description TBD.", + "SBDF", + references = """ + E. Alberdi Celayaa, J. J. Anza Aguirrezabalab, P. Chatzipantelidisc. Implementation of + an Adaptive BDF2 Formula and Comparison with The MATLAB Ode15s. Procedia Computer Science, + 29, pp 1014-1026, 2014. doi: https://doi.org/10.1016/j.procs.2014.05.091 + """, + extra_keyword_description = """ + - `κ`: TBD + - `tol`: TBD + - `nlsolve`: TBD + - `extrapolant`: TBD + - `ark`: TBD + """, + extra_keyword_default = """ + κ = nothing, + tol = nothing, + nlsolve = NLNewton(), + extrapolant = :linear, + ark = false, + order, + """) struct SBDF{CS, AD, F, F2, P, FDT, ST, CJ, K, T} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -129,13 +197,33 @@ See also `SBDF`. """ SBDF4(; kwargs...) = SBDF(4; kwargs...) -""" -QNDF1: Multistep Method -An adaptive order 1 quasi-constant timestep L-stable numerical differentiation function (NDF) method. -Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850. - -See also `QNDF`. -""" +@doc BDF_docstring("An adaptive order 1 quasi-constant timestep L-stable numerical differentiation function (NDF) method. + Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850.", + "QNDF1", + references = """@article{shampine1997matlab, + title={The matlab ode suite}, + author={Shampine, Lawrence F and Reichelt, Mark W}, + journal={SIAM journal on scientific computing}, + volume={18}, + number={1}, + pages={1--22}, + year={1997}, + publisher={SIAM} + }""", + extra_keyword_description = """ + - `nlsolve`: TBD + - `extrapolant`: TBD + - `kappa`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :linear, + kappa = -0.1850, + controller = :Standard, + step_limiter! = trivial_limiter!, + """) struct QNDF1{CS, AD, F, F2, P, FDT, ST, CJ, κType, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -164,12 +252,32 @@ function QNDF1(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va step_limiter!) end -""" -QNDF2: Multistep Method -An adaptive order 2 quasi-constant timestep L-stable numerical differentiation function (NDF) method. - -See also `QNDF`. -""" +@doc BDF_docstring("An adaptive order 2 quasi-constant timestep L-stable numerical differentiation function (NDF) method.", + "QNDF2", + references = """@article{shampine1997matlab, + title={The matlab ode suite}, + author={Shampine, Lawrence F and Reichelt, Mark W}, + journal={SIAM journal on scientific computing}, + volume={18}, + number={1}, + pages={1--22}, + year={1997}, + publisher={SIAM} + }""", + extra_keyword_description = """ + - `nlsolve`: TBD + - `extrapolant`: TBD + - `kappa`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :linear, + kappa = -1 // 9, + controller = :Standard, + step_limiter! = trivial_limiter!, + """) struct QNDF2{CS, AD, F, F2, P, FDT, ST, CJ, κType, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -198,22 +306,37 @@ function QNDF2(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va step_limiter!) end -""" -QNDF: Multistep Method -An adaptive order quasi-constant timestep NDF method. -Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients). - -@article{shampine1997matlab, -title={The matlab ode suite}, -author={Shampine, Lawrence F and Reichelt, Mark W}, -journal={SIAM journal on scientific computing}, -volume={18}, -number={1}, -pages={1--22}, -year={1997}, -publisher={SIAM} -} -""" +@doc BDF_docstring("An adaptive order quasi-constant timestep NDF method. + Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", + "QNDF", + references = """@article{shampine1997matlab, + title={The matlab ode suite}, + author={Shampine, Lawrence F and Reichelt, Mark W}, + journal={SIAM journal on scientific computing}, + volume={18}, + number={1}, + pages={1--22}, + year={1997}, + publisher={SIAM} + }""", + extra_keyword_description = """ + - `κ`: TBD + - `tol`: TBD + - `nlsolve`: TBD + - `extrapolant`: TBD + - `kappa`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + κ = nothing, + tol = nothing, + nlsolve = NLNewton(), + extrapolant = :linear, + kappa = promote(-0.1850, -1 // 9, -0.0823, -0.0415, 0), + controller = :Standard, + step_limiter! = trivial_limiter!, + """) struct QNDF{MO, CS, AD, F, F2, P, FDT, ST, CJ, K, T, κType, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} max_order::Val{MO} @@ -246,11 +369,19 @@ end TruncatedStacktraces.@truncate_stacktrace QNDF -""" -MEBDF2: Multistep Method -The second order Modified Extended BDF method, which has improved stability properties over the standard BDF. -Fixed timestep only. -""" +@doc BDF_docstring("The second order Modified Extended BDF method, + which has improved stability properties over the standard BDF. + Fixed timestep only.", + "MEBDF2", + references = """TBD""", + extra_keyword_description = """ + - `nlsolve`: TBD + - `extrapolant`: TBD + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :constant, + """) struct MEBDF2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -270,19 +401,33 @@ function MEBDF2(; chunk_size = Val{0}(), autodiff = true, standardtag = Val{true extrapolant) end -""" -FBDF: Fixed leading coefficient BDF - -An adaptive order quasi-constant timestep NDF method. -Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients). - -@article{shampine2002solving, -title={Solving 0= F (t, y (t), y′(t)) in Matlab}, -author={Shampine, Lawrence F}, -year={2002}, -publisher={Walter de Gruyter GmbH \\& Co. KG} -} -""" +@doc BDF_docstring("An adaptive order quasi-constant timestep NDF method. + Fixed leading coefficient BDF. + Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", + "FBDF", + references = """@article{shampine2002solving, + title={Solving 0= F (t, y (t), y′(t)) in Matlab}, + author={Shampine, Lawrence F}, + year={2002}, + publisher={Walter de Gruyter GmbH \\& Co. KG}}""", + extra_keyword_description = """ + - `κ`: TBD + - `tol`: TBD + - `nlsolve`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + - `max_order`: TBD + """, + extra_keyword_default = """ + κ = nothing, + tol = nothing, + nlsolve = NLNewton(), + extrapolant = :linear, + controller = :Standard, + step_limiter! = trivial_limiter!, + max_order::Val{MO} = Val{5}(), + """) struct FBDF{MO, CS, AD, F, F2, P, FDT, ST, CJ, K, T, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} max_order::Val{MO} @@ -390,6 +535,19 @@ See also `SBDF`, `IMEXEuler`. """ IMEXEulerARK(; kwargs...) = SBDF(1; ark = true, kwargs...) +@doc BDF_docstring("TBD.", + "DImplicitEuler", + references = """TBD""", + extra_keyword_description = """ + - `nlsolve`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :constant, + controller = :Standard, + """) struct DImplicitEuler{CS, AD, F, F2, P, FDT, ST, CJ} <: DAEAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F nlsolve::F2 @@ -409,6 +567,19 @@ function DImplicitEuler(; nlsolve, precs, extrapolant, controller) end +@doc BDF_docstring("TBD.", + "DABDF2", + references = """TBD""", + extra_keyword_description = """ + - `nlsolve`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + nlsolve = NLNewton(), + extrapolant = :constant, + controller = :Standard, + """) struct DABDF2{CS, AD, F, F2, P, FDT, ST, CJ} <: DAEAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F nlsolve::F2 @@ -441,6 +612,25 @@ DBDF(;chunk_size=Val{0}(),autodiff=Val{true}(), standardtag = Val{true}(), concr linsolve,nlsolve,precs,extrapolant) =# +@doc BDF_docstring("Description TBD", + "DFBDF", + references = """TBD""", + extra_keyword_description = """ + - `κ`: TBD + - `tol`: TBD + - `nlsolve`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `max_order`: TBD + """, + extra_keyword_default = """ + κ = nothing, + tol = nothing, + nlsolve = NLNewton(), + extrapolant = :linear, + controller = :Standard, + max_order::Val{MO} = Val{5}(), + """) struct DFBDF{MO, CS, AD, F, F2, P, FDT, ST, CJ, K, T} <: DAEAlgorithm{CS, AD, FDT, ST, CJ} max_order::Val{MO} linsolve::F From 686bfe02064476bb039f5858b6069903ae592b08 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 19 Aug 2024 11:27:31 +0200 Subject: [PATCH 49/83] remove more old docstrings --- docs/make.jl | 9 +------ docs/src/imex/imex_sdirk.md | 10 -------- docs/src/nonstiff/explicit_extrapolation.md | 7 ------ docs/src/nonstiff/nonstiff_multistep.md | 26 --------------------- docs/src/stiff/sdirk.md | 23 ------------------ 5 files changed, 1 insertion(+), 74 deletions(-) delete mode 100644 docs/src/nonstiff/explicit_extrapolation.md delete mode 100644 docs/src/nonstiff/nonstiff_multistep.md delete mode 100644 docs/src/stiff/sdirk.md diff --git a/docs/make.jl b/docs/make.jl index 59016d38cf..5cc6b12b84 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -59,14 +59,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "implicit/PDIRK.md", "implicit/Rosenbrock.md", "implicit/StabalizedRK.md", - "implicit/BDF.md" - ], - "Standard Non-Stiff ODEProblem Solvers" => [ - "nonstiff/explicit_extrapolation.md", - "nonstiff/nonstiff_multistep.md" - ], - "Standard Stiff ODEProblem Solvers" => [ - "stiff/sdirk.md" + "implicit/BDF.md", ], "IMEX Solvers" => [ "imex/imex_multistep.md", diff --git a/docs/src/imex/imex_sdirk.md b/docs/src/imex/imex_sdirk.md index 24ebaaaa89..24cfca1446 100644 --- a/docs/src/imex/imex_sdirk.md +++ b/docs/src/imex/imex_sdirk.md @@ -3,14 +3,4 @@ ```@docs IMEXEuler IMEXEulerARK -KenCarp3 -KenCarp4 -KenCarp47 -KenCarp5 -KenCarp58 -ESDIRK54I8L2SA -ESDIRK436L2SA2 -ESDIRK437L2SA -ESDIRK547L2SA2 -ESDIRK659L2SA ``` diff --git a/docs/src/nonstiff/explicit_extrapolation.md b/docs/src/nonstiff/explicit_extrapolation.md deleted file mode 100644 index 16a1b27916..0000000000 --- a/docs/src/nonstiff/explicit_extrapolation.md +++ /dev/null @@ -1,7 +0,0 @@ -# Explicit Extrapolation Methods - -```@docs -AitkenNeville -ExtrapolationMidpointDeuflhard -ExtrapolationMidpointHairerWanner -``` diff --git a/docs/src/nonstiff/nonstiff_multistep.md b/docs/src/nonstiff/nonstiff_multistep.md deleted file mode 100644 index bfd1d15d8f..0000000000 --- a/docs/src/nonstiff/nonstiff_multistep.md +++ /dev/null @@ -1,26 +0,0 @@ -# Multistep Methods for Non-Stiff Equations - -## Explicit Multistep Methods - -```@docs -AB3 -AB4 -AB5 -AN5 -``` - -## Predictor-Corrector Methods - -```@docs -ABM32 -ABM43 -ABM54 -VCAB3 -VCAB4 -VCAB5 -VCABM3 -VCABM4 -VCABM5 -VCABM - -``` diff --git a/docs/src/stiff/sdirk.md b/docs/src/stiff/sdirk.md deleted file mode 100644 index 5236046ad0..0000000000 --- a/docs/src/stiff/sdirk.md +++ /dev/null @@ -1,23 +0,0 @@ -# Singly-Diagonally Implicit Runge-Kutta (SDIRK) Methods - -```@docs -ImplicitEuler -ImplicitMidpoint -Trapezoid -TRBDF2 -SDIRK2 -SDIRK22 -SSPSDIRK2 -Kvaerno3 -CFNLIRK3 -Cash4 -SFSDIRK4 -SFSDIRK5 -SFSDIRK6 -SFSDIRK7 -SFSDIRK8 -Hairer4 -Hairer42 -Kvaerno4 -Kvaerno5 -``` From 5913ac4ceb53d479be86e3b19f7706b89206d4f9 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 19 Aug 2024 11:27:38 +0200 Subject: [PATCH 50/83] add more doc subtitles --- docs/src/explicit/AdamsBashforthMoulton.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/src/explicit/AdamsBashforthMoulton.md b/docs/src/explicit/AdamsBashforthMoulton.md index 5623a7c43c..f1e6638cfc 100644 --- a/docs/src/explicit/AdamsBashforthMoulton.md +++ b/docs/src/explicit/AdamsBashforthMoulton.md @@ -9,10 +9,17 @@ first_steps("OrdinaryDiffEqAdamsBashforthMoulton", "VCABM") ## Full list of solvers +### Explicit Multistep Methods + ```@docs AB3 AB4 AB5 +``` + +### Predictor-Corrector Methods + +```@docs ABM32 ABM43 ABM54 From dc8496330d8b38e3b99d7a7b3ee71cb8ed24276d Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 19 Aug 2024 11:28:17 +0200 Subject: [PATCH 51/83] try make SBDF show up in docs --- docs/src/implicit/BDF.md | 2 +- lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/implicit/BDF.md b/docs/src/implicit/BDF.md index 06b08263a6..20b1bf9c30 100644 --- a/docs/src/implicit/BDF.md +++ b/docs/src/implicit/BDF.md @@ -22,7 +22,7 @@ FBDF ``` ### IMEX Multistep ```@docs -OrdinaryDiffEqBDF.SBDF +SBDF SBDF2 SBDF3 SBDF4 diff --git a/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl b/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl index 575d22ecc5..5a2981219b 100644 --- a/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl +++ b/lib/OrdinaryDiffEqBDF/src/OrdinaryDiffEqBDF.jl @@ -93,7 +93,7 @@ PrecompileTools.@compile_workload begin end export ABDF2, QNDF1, QBDF1, QNDF2, QBDF2, QNDF, QBDF, FBDF, - SBDF2, SBDF3, SBDF4, MEBDF2, IMEXEuler, IMEXEulerARK, + SBDF, SBDF2, SBDF3, SBDF4, MEBDF2, IMEXEuler, IMEXEulerARK, DABDF2, DImplicitEuler, DFBDF end From a6ceab23cc1f258f4902a9a47410b9b2e66bda42 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 19 Aug 2024 11:28:29 +0200 Subject: [PATCH 52/83] docs SDIRK --- docs/make.jl | 1 + docs/src/implicit/SDIRK.md | 45 ++ .../src/OrdinaryDiffEqSDIRK.jl | 2 +- lib/OrdinaryDiffEqSDIRK/src/algorithms.jl | 747 ++++++++++++------ 4 files changed, 562 insertions(+), 233 deletions(-) create mode 100644 docs/src/implicit/SDIRK.md diff --git a/docs/make.jl b/docs/make.jl index 5cc6b12b84..2d270bb225 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -55,6 +55,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/Extrapolation.md", ], "Implicit Solvers" => [ + "implicit/SDIRK.md", "implicit/FIRK.md", "implicit/PDIRK.md", "implicit/Rosenbrock.md", diff --git a/docs/src/implicit/SDIRK.md b/docs/src/implicit/SDIRK.md new file mode 100644 index 0000000000..4e373d83d9 --- /dev/null +++ b/docs/src/implicit/SDIRK.md @@ -0,0 +1,45 @@ +# OrdinaryDiffEqSDIRK + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqSDIRK", "PDIRK44") +``` + +## Full list of solvers + +```@docs +ImplicitEuler +ImplicitMidpoint +Trapezoid +TRBDF2 +SDIRK2 +SDIRK22 +SSPSDIRK2 +Kvaerno3 +KenCarp3 +CFNLIRK3 +Cash4 +SFSDIRK4 +SFSDIRK5 +SFSDIRK6 +SFSDIRK7 +SFSDIRK8 +Hairer4 +Hairer42 +Kvaerno4 +Kvaerno5 +``` +### IMEX SDIRK +```@docs +KenCarp4 +KenCarp47 +KenCarp5 +KenCarp58 +ESDIRK54I8L2SA +ESDIRK436L2SA2 +ESDIRK437L2SA +ESDIRK547L2SA2 +ESDIRK659L2SA +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqSDIRK/src/OrdinaryDiffEqSDIRK.jl b/lib/OrdinaryDiffEqSDIRK/src/OrdinaryDiffEqSDIRK.jl index 0d8ff786a1..f9fc3bbd9e 100644 --- a/lib/OrdinaryDiffEqSDIRK/src/OrdinaryDiffEqSDIRK.jl +++ b/lib/OrdinaryDiffEqSDIRK/src/OrdinaryDiffEqSDIRK.jl @@ -13,7 +13,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, constvalue, _unwrap_val, _ode_interpolant, trivial_limiter!, _ode_interpolant!, isesdirk, issplit, - ssp_coefficient, get_fsalfirstlast + ssp_coefficient, get_fsalfirstlast, generic_solver_docstring using TruncatedStacktraces, MuladdMacro, MacroTools, FastBroadcast, RecursiveArrayTools using SciMLBase: SplitFunction using LinearAlgebra: mul!, I diff --git a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl index 01f796f650..75f8489ea0 100644 --- a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl @@ -1,9 +1,51 @@ -# SDIRK Methods -""" -ImplicitEuler: SDIRK Method -A 1st order implicit solver. A-B-L-stable. Adaptive timestepping through a divided differences estimate via memory. -Strong-stability preserving (SSP). -""" +function SDIRK_docstring(description::String, + name::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") + keyword_default = """ + chunk_size = Val{0}(), + autodiff = true, + standardtag = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:forward}, + linsolve = nothing, + precs = DEFAULT_PRECS, + nlsolve = NLNewton(), + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `autodiff`: TBD + - `standardtag`: TBD + - `concrete_jac`: TBD + - `diff_type`: TBD + - `linsolve`: TBD + - `precs`: TBD + - `nlsolve`: TBD + """ * extra_keyword_description + + generic_solver_docstring( + description, name, "SDIRK Method.", references, + keyword_default_description, keyword_default + ) +end + +@doc SDIRK_docstring("A 1st order implicit solver. A-B-L-stable. + Adaptive timestepping through a divided differences estimate via memory. + Strong-stability preserving (SSP).", + "ImplicitEuler"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + extrapolant = :constant, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct ImplicitEuler{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -25,11 +67,19 @@ function ImplicitEuler(; chunk_size = Val{0}(), autodiff = Val{true}(), _unwrap_val(concrete_jac), typeof(step_limiter!)}(linsolve, nlsolve, precs, extrapolant, controller, step_limiter!) end -""" -ImplicitMidpoint: SDIRK Method -A second order A-stable symplectic and symmetric implicit solver. -Good for highly stiff equations which need symplectic integration. -""" + +@doc SDIRK_docstring("A second order A-stable symplectic and symmetric implicit solver. + Good for highly stiff equations which need symplectic integration.", + "ImplicitMidpoint"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + step_limiter! = trivial_limiter!, + """) struct ImplicitMidpoint{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -53,17 +103,24 @@ function ImplicitMidpoint(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -""" -Andre Vladimirescu. 1994. The Spice Book. John Wiley & Sons, Inc., New York, -NY, USA. -Trapezoid: SDIRK Method -A second order A-stable symmetric ESDIRK method. -"Almost symplectic" without numerical dampening. -Also known as Crank-Nicolson when applied to PDEs. Adaptive timestepping via divided -differences approximation to the second derivative terms in the local truncation error -estimate (the SPICE approximation strategy). -""" +@doc SDIRK_docstring("""Second order A-stable symmetric ESDIRK method. + "Almost symplectic" without numerical dampening. + Also known as Crank-Nicolson when applied to PDEs. Adaptive timestepping via divided + differences approximation to the second derivative terms in the local truncation error + estimate (the SPICE approximation strategy).""", + "Trapezoid"; + references = "Andre Vladimirescu. 1994. The Spice Book. John Wiley & Sons, Inc., New York, NY, USA.", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct Trapezoid{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -90,22 +147,31 @@ function Trapezoid(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -""" -@article{hosea1996analysis, -title={Analysis and implementation of TR-BDF2}, -author={Hosea, ME and Shampine, LF}, -journal={Applied Numerical Mathematics}, -volume={20}, -number={1-2}, -pages={21--37}, -year={1996}, -publisher={Elsevier} -} - -TRBDF2: SDIRK Method -A second order A-B-L-S-stable one-step ESDIRK method. -Includes stiffness-robust error estimates for accurate adaptive timestepping, smoothed derivatives for highly stiff and oscillatory problems. -""" +@doc SDIRK_docstring("A second order A-B-L-S-stable one-step ESDIRK method. + Includes stiffness-robust error estimates for accurate adaptive timestepping, + smoothed derivatives for highly stiff and oscillatory problems.", + "TRBDF2"; + references = "@article{hosea1996analysis, + title={Analysis and implementation of TR-BDF2}, + author={Hosea, ME and Shampine, LF}, + journal={Applied Numerical Mathematics}, + volume={20}, + number={1-2}, + pages={21--37}, + year={1996}, + publisher={Elsevier}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct TRBDF2{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -130,21 +196,29 @@ end TruncatedStacktraces.@truncate_stacktrace TRBDF2 -""" -@article{hindmarsh2005sundials, -title={{SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers}, -author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S}, -journal={ACM Transactions on Mathematical Software (TOMS)}, -volume={31}, -number={3}, -pages={363--396}, -year={2005}, -publisher={ACM} -} - -SDIRK2: SDIRK Method -An A-B-L stable 2nd order SDIRK method -""" +@doc SDIRK_docstring("SDIRK2: SDIRK Method An A-B-L stable 2nd order SDIRK method", + "SDIRK2"; + references = "@article{hindmarsh2005sundials, + title={{SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers}, + author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S}, + journal={ACM Transactions on Mathematical Software (TOMS)}, + volume={31}, + number={3}, + pages={363--396}, + year={2005}, + publisher={ACM}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct SDIRK2{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -169,6 +243,21 @@ function SDIRK2(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = V step_limiter!) end +@doc SDIRK_docstring("Description TBD", + "SDIRK22"; + references = "TBD", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct SDIRK22{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -195,6 +284,19 @@ function SDIRK22(; step_limiter!) end +@doc SDIRK_docstring("Description TBD", + "SSPSDIRK2"; + references = "TBD", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :constant, + controller = :PI, + """) struct SSPSDIRK2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} # Not adaptive linsolve::F @@ -217,21 +319,30 @@ function SSPSDIRK2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{kvaerno2004singly, -title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, -author={Kv{\\ae}rn{\\o}, Anne}, -journal={BIT Numerical Mathematics}, -volume={44}, -number={3}, -pages={489--502}, -year={2004}, -publisher={Springer} -} - -Kvaerno3: SDIRK Method -An A-L stable stiffly-accurate 3rd order ESDIRK method -""" + +@doc SDIRK_docstring("An A-L stable stiffly-accurate 3rd order ESDIRK method.", + "Kvaerno3"; + references = "@article{kvaerno2004singly, + title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, + author={Kv{\\ae}rn{\\o}, Anne}, + journal={BIT Numerical Mathematics}, + volume={44}, + number={3}, + pages={489--502}, + year={2004}, + publisher={Springer}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct Kvaerno3{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -254,17 +365,25 @@ function Kvaerno3(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -""" -@book{kennedy2001additive, -title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, -author={Kennedy, Christopher Alan}, -year={2001}, -publisher={National Aeronautics and Space Administration, Langley Research Center} -} - -KenCarp3: SDIRK Method -An A-L stable stiffly-accurate 3rd order ESDIRK method with splitting -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 3rd order ESDIRK method with splitting.", + "KenCarp3"; + references = "@book{kennedy2001additive, + title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, + author={Kennedy, Christopher Alan}, + year={2001}, + publisher={National Aeronautics and Space Administration, Langley Research Center}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter!`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct KenCarp3{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -287,6 +406,15 @@ function KenCarp3(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end +@doc SDIRK_docstring("Description TBD.", + "CFNLIRK3"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct CFNLIRK3{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -307,21 +435,29 @@ function CFNLIRK3(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end -""" -@article{hindmarsh2005sundials, -title={{SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers}, -author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S}, -journal={ACM Transactions on Mathematical Software (TOMS)}, -volume={31}, -number={3}, -pages={363--396}, -year={2005}, -publisher={ACM} -} - -Cash4: SDIRK Method -An A-L stable 4th order SDIRK method -""" +@doc SDIRK_docstring("An A-L stable 4th order SDIRK method.", + "Cash4"; + references = "@article{hindmarsh2005sundials, + title={{SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers}, + author={Hindmarsh, Alan C and Brown, Peter N and Grant, Keith E and Lee, Steven L and Serban, Radu and Shumaker, Dan E and Woodward, Carol S}, + journal={ACM Transactions on Mathematical Software (TOMS)}, + volume={31}, + number={3}, + pages={363--396}, + year={2005}, + publisher={ACM}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `embedding`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + embedding = 3, + """) struct Cash4{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -349,6 +485,15 @@ function Cash4(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va controller) end +@doc SDIRK_docstring("Description TBD.", + "SFSDIRK4"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct SFSDIRK4{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -369,6 +514,15 @@ function SFSDIRK4(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end +@doc SDIRK_docstring("Description TBD.", + "SFSDIRK5"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct SFSDIRK5{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -390,6 +544,15 @@ function SFSDIRK5(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end +@doc SDIRK_docstring("Description TBD.", + "SFSDIRK6"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct SFSDIRK6{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -411,6 +574,16 @@ function SFSDIRK6(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end + +@doc SDIRK_docstring("Description TBD.", + "SFSDIRK7"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct SFSDIRK7{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -432,6 +605,15 @@ function SFSDIRK7(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end +@doc SDIRK_docstring("Description TBD.", + "SFSDIRK8"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + """) struct SFSDIRK8{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -453,14 +635,21 @@ function SFSDIRK8(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end -""" -E. Hairer, G. Wanner, Solving ordinary differential equations II, stiff and -differential-algebraic problems. Computational mathematics (2nd revised ed.), -Springer (1996) - -Hairer4: SDIRK Method -An A-L stable 4th order SDIRK method -""" +@doc SDIRK_docstring("An A-L stable 4th order SDIRK method.", + "Hairer4"; + references = "E. Hairer, G. Wanner, Solving ordinary differential equations II, stiff and + differential-algebraic problems. Computational mathematics (2nd revised ed.), + Springer (1996)", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + """) struct Hairer4{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -482,14 +671,21 @@ function Hairer4(; controller) end -""" -E. Hairer, G. Wanner, Solving ordinary differential equations II, stiff and -differential-algebraic problems. Computational mathematics (2nd revised ed.), -Springer (1996) - -Hairer42: SDIRK Method -An A-L stable 4th order SDIRK method -""" +@doc SDIRK_docstring("An A-L stable 4th order SDIRK method.", + "Hairer42"; + references = "E. Hairer, G. Wanner, Solving ordinary differential equations II, stiff and + differential-algebraic problems. Computational mathematics (2nd revised ed.), + Springer (1996)", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + """) struct Hairer42{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -511,21 +707,29 @@ function Hairer42(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{kvaerno2004singly, -title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, -author={Kv{\\ae}rn{\\o}, Anne}, -journal={BIT Numerical Mathematics}, -volume={44}, -number={3}, -pages={489--502}, -year={2004}, -publisher={Springer} -} - -Kvaerno4: SDIRK Method -An A-L stable stiffly-accurate 4th order ESDIRK method. -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 4th order ESDIRK method.", + "Kvaerno4"; + references = "@article{kvaerno2004singly, + title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, + author={Kv{\\ae}rn{\\o}, Anne}, + journal={BIT Numerical Mathematics}, + volume={44}, + number={3}, + pages={489--502}, + year={2004}, + publisher={Springer}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct Kvaerno4{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -548,21 +752,29 @@ function Kvaerno4(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -""" -@article{kvaerno2004singly, -title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, -author={Kv{\\ae}rn{\\o}, Anne}, -journal={BIT Numerical Mathematics}, -volume={44}, -number={3}, -pages={489--502}, -year={2004}, -publisher={Springer} -} - -Kvaerno5: SDIRK Method -An A-L stable stiffly-accurate 5th order ESDIRK method -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 5th order ESDIRK method.", + "Kvaerno5"; + references = "@article{kvaerno2004singly, + title={Singly diagonally implicit Runge--Kutta methods with an explicit first stage}, + author={Kv{\\ae}rn{\\o}, Anne}, + journal={BIT Numerical Mathematics}, + volume={44}, + number={3}, + pages={489--502}, + year={2004}, + publisher={Springer}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct Kvaerno5{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -585,17 +797,25 @@ function Kvaerno5(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -""" -@book{kennedy2001additive, -title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, -author={Kennedy, Christopher Alan}, -year={2001}, -publisher={National Aeronautics and Space Administration, Langley Research Center} -} - -KenCarp4: SDIRK Method -An A-L stable stiffly-accurate 4th order ESDIRK method with splitting -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 4th order ESDIRK method with splitting.", + "KenCarp4"; + references = "@book{kennedy2001additive, + title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, + author={Kennedy, Christopher Alan}, + year={2001}, + publisher={National Aeronautics and Space Administration, Langley Research Center}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct KenCarp4{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -620,20 +840,26 @@ end TruncatedStacktraces.@truncate_stacktrace KenCarp4 -""" -@article{kennedy2019higher, -title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, -author={Kennedy, Christopher A and Carpenter, Mark H}, -journal={Applied Numerical Mathematics}, -volume={136}, -pages={183--205}, -year={2019}, -publisher={Elsevier} -} - -KenCarp47: SDIRK Method -An A-L stable stiffly-accurate 4th order seven-stage ESDIRK method with splitting -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 4th order seven-stage ESDIRK method with splitting.", + "KenCarp47"; + references = "@article{kennedy2019higher, + title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, + author={Kennedy, Christopher A and Carpenter, Mark H}, + journal={Applied Numerical Mathematics}, + volume={136}, + pages={183--205}, + year={2019}, + publisher={Elsevier}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + """) struct KenCarp47{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -655,17 +881,25 @@ function KenCarp47(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@book{kennedy2001additive, -title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, -author={Kennedy, Christopher Alan}, -year={2001}, -publisher={National Aeronautics and Space Administration, Langley Research Center} -} - -KenCarp5: SDIRK Method -An A-L stable stiffly-accurate 5th order ESDIRK method with splitting -""" +@doc SDIRK_docstring("An A-L stable stiffly-accurate 5th order ESDIRK method with splitting.", + "KenCarp5"; + references = "@book{kennedy2001additive, + title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, + author={Kennedy, Christopher Alan}, + year={2001}, + publisher={National Aeronautics and Space Administration, Langley Research Center}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + - `step_limiter`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + step_limiter! = trivial_limiter!, + """) struct KenCarp5{CS, AD, F, F2, P, FDT, ST, CJ, StepLimiter} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -687,20 +921,27 @@ function KenCarp5(; chunk_size = Val{0}(), autodiff = Val{true}(), _unwrap_val(concrete_jac), typeof(step_limiter!)}(linsolve, nlsolve, precs, smooth_est, extrapolant, controller, step_limiter!) end -""" -@article{kennedy2019higher, -title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, -author={Kennedy, Christopher A and Carpenter, Mark H}, -journal={Applied Numerical Mathematics}, -volume={136}, -pages={183--205}, -year={2019}, -publisher={Elsevier} -} - -KenCarp58: SDIRK Method -An A-L stable stiffly-accurate 5th order eight-stage ESDIRK method with splitting -""" + +@doc SDIRK_docstring("An A-L stable stiffly-accurate 5th order eight-stage ESDIRK method with splitting.", + "KenCarp58"; + references = "@article{kennedy2019higher, + title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, + author={Kennedy, Christopher A and Carpenter, Mark H}, + journal={Applied Numerical Mathematics}, + volume={136}, + pages={183--205}, + year={2019}, + publisher={Elsevier}}", + extra_keyword_description = """ + - `smooth_est`: TBD + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + smooth_est = true, + extrapolant = :linear, + controller = :PI, + """) struct KenCarp58{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -723,6 +964,17 @@ function KenCarp58(; chunk_size = Val{0}(), autodiff = Val{true}(), end # `smooth_est` is not necessary, as the embedded method is also L-stable +@doc SDIRK_docstring("Description TBD.", + "ESDIRK54I8L2SA"; + references = "TBD", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + """) struct ESDIRK54I8L2SA{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -742,16 +994,24 @@ function ESDIRK54I8L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{Kennedy2019DiagonallyIR, -title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, -author={Christopher A. Kennedy and Mark H. Carpenter}, -journal={Applied Numerical Mathematics}, -year={2019}, -volume={146}, -pages={221-244} -} -""" +@doc SDIRK_docstring("Description TBD.", + "ESDIRK436L2SA2"; + references = """@article{Kennedy2019DiagonallyIR, + title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, + author={Christopher A. Kennedy and Mark H. Carpenter}, + journal={Applied Numerical Mathematics}, + year={2019}, + volume={146}, + pages={221-244} + }""", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + """) struct ESDIRK436L2SA2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -771,16 +1031,24 @@ function ESDIRK436L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{Kennedy2019DiagonallyIR, -title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, -author={Christopher A. Kennedy and Mark H. Carpenter}, -journal={Applied Numerical Mathematics}, -year={2019}, -volume={146}, -pages={221-244} -} -""" +@doc SDIRK_docstring("Description TBD.", + "ESDIRK437L2SA"; + references = """@article{Kennedy2019DiagonallyIR, + title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, + author={Christopher A. Kennedy and Mark H. Carpenter}, + journal={Applied Numerical Mathematics}, + year={2019}, + volume={146}, + pages={221-244} + }""", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + """) struct ESDIRK437L2SA{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -800,16 +1068,24 @@ function ESDIRK437L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{Kennedy2019DiagonallyIR, -title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, -author={Christopher A. Kennedy and Mark H. Carpenter}, -journal={Applied Numerical Mathematics}, -year={2019}, -volume={146}, -pages={221-244} -} -""" +@doc SDIRK_docstring("Description TBD.", + "ESDIRK547L2SA2"; + references = """@article{Kennedy2019DiagonallyIR, + title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, + author={Christopher A. Kennedy and Mark H. Carpenter}, + journal={Applied Numerical Mathematics}, + year={2019}, + volume={146}, + pages={221-244} + }""", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + """) struct ESDIRK547L2SA2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -829,19 +1105,26 @@ function ESDIRK547L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -""" -@article{Kennedy2019DiagonallyIR, -title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, -author={Christopher A. Kennedy and Mark H. Carpenter}, -journal={Applied Numerical Mathematics}, -year={2019}, -volume={146}, -pages={221-244} - -Currently has STABILITY ISSUES, causing it to fail the adaptive tests. -Check issue https://github.com/SciML/OrdinaryDiffEq.jl/issues/1933 for more details. -} -""" +@doc SDIRK_docstring("Description TBD. + Currently has STABILITY ISSUES, causing it to fail the adaptive tests. + Check issue https://github.com/SciML/OrdinaryDiffEq.jl/issues/1933 for more details.", + "ESDIRK659L2SA"; + references = """@article{Kennedy2019DiagonallyIR, + title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, + author={Christopher A. Kennedy and Mark H. Carpenter}, + journal={Applied Numerical Mathematics}, + year={2019}, + volume={146}, + pages={221-244} + }""", + extra_keyword_description = """ + - `extrapolant`: TBD + - `controller`: TBD + """, + extra_keyword_default = """ + extrapolant = :linear, + controller = :PI, + """) struct ESDIRK659L2SA{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 0a9ef290d2eabb6dd35e1659060df061a3abc754 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 19 Aug 2024 11:40:49 +0200 Subject: [PATCH 53/83] fix some fsal rebase issues --- lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl | 2 +- lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl b/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl index a8c9280efa..fa8b873e42 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/OrdinaryDiffEqNordsieck.jl @@ -10,7 +10,7 @@ import OrdinaryDiffEqCore: alg_order, alg_adaptive_order, qsteady_max_default, step_accept_controller!, step_reject_controller!, calculate_residuals, calculate_residuals!, get_current_adaptive_order, get_fsalfirstlast, - ode_interpolant, ode_interpolant!, trivial_limiter! + ode_interpolant, ode_interpolant!, trivial_limiter!, generic_solver_docstring using MuladdMacro, FastBroadcast, RecursiveArrayTools import LinearAlgebra: rmul! diff --git a/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl b/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl index b86dbc96ef..953bc58ec6 100644 --- a/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl +++ b/lib/OrdinaryDiffEqRKN/src/OrdinaryDiffEqRKN.jl @@ -11,7 +11,7 @@ import OrdinaryDiffEqCore: alg_order, calculate_residuals!, alg_cache, _vec, _reshape, @cache, isfsal, full_cache, constvalue, _unwrap_val, _ode_interpolant, get_fsalfirstlast, - trivial_limiter!, _ode_interpolant!, _ode_addsteps! + trivial_limiter!, _ode_interpolant!, _ode_addsteps!, generic_solver_docstring using FastBroadcast, Polyester, MuladdMacro, RecursiveArrayTools using DiffEqBase: @def, @tight_loop_macros From 8f2eb382890db8d12030cea04e3f91cc576ebe46 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Tue, 20 Aug 2024 19:05:57 +0200 Subject: [PATCH 54/83] add FIRK description --- docs/src/implicit/FIRK.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md index d00d79beb6..c27aafe27c 100644 --- a/docs/src/implicit/FIRK.md +++ b/docs/src/implicit/FIRK.md @@ -1,6 +1,26 @@ # OrdinaryDiffEqFIRK -This article is a stub. +FIRK methods are fully implicit Runge-Kutta methods. +They can have special properties, like be symplectic integrators, and can achieve higher order for the same number of stage in comparison to diagonal methods. +However, the fully implicit methods have a larger implicit system to solve and thus have a higher linear algebra cost. +This can be useful in some contexts to promote more parallelism, +but also since the size of the factorization is cubic and the dominant cost for large equations, +multiplying `O(n^3)` operations to `O((sn)^3)` can be a considerable cost increase for FIRK tableaus, +where `s`, the number of stages, is particularly large. +That said, the restriction to diagonal implicitness imposes order restrictions, +such as SDIRK methods having a maximum order of 5, which can restrict the problems best suited for SDIRK methods. + +The most common FIRK method in production are those based on RadauIIA tableaus, +which is an ODE representation of Gaussian collocation. +Like Gaussian collocation, it achieves higher order convergence than its stages, namely order 2s+1 for s stages. +Thus RadauIIA FIRK methods tend to be some of the highest order methods (excluding extrapolation methods). +This means that high order RadauIIA methods are recommended in the same scenarios that high-order explicit Runge-Kutta methods are recommended simply with the restriction of being a stiff equation. +Such scenarios include cases like very low tolerances: RadauIIA methods can be the best performing methods for scenarios where tolerances are `1e-9` and below. +Additionally, for ODE systems of size less than 200, the increased size of the Jacobian is mitigated by improved multithreading, +since BLAS implementations are only good at multithreading LU factorizations after a certain matrix size. +For this reason, RadauIIA methods tend to be recommended in cases where ODE size is small to intermediate and very accurate solutions are required. + +They should be tested against the parallel implicit extrapolation which also specialize in this regime. ```@eval first_steps = evalfile("./common_first_steps.jl") From b99f110ab29e497498c2d117cd72ae949d9499cc Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Tue, 20 Aug 2024 19:53:59 +0200 Subject: [PATCH 55/83] Split Extrapolation into stiff and non-stiff --- docs/make.jl | 1 + docs/src/explicit/Extrapolation.md | 10 ++++------ docs/src/implicit/Extrapolation.md | 19 +++++++++++++++++++ 3 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 docs/src/implicit/Extrapolation.md diff --git a/docs/make.jl b/docs/make.jl index 2d270bb225..579492fb75 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -61,6 +61,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "implicit/Rosenbrock.md", "implicit/StabalizedRK.md", "implicit/BDF.md", + "implicit/Extrapolation.md" ], "IMEX Solvers" => [ "imex/imex_multistep.md", diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index 7f172a9bb2..9a86d024e3 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -1,20 +1,18 @@ # OrdinaryDiffEqExtrapolation -This article is a stub. +Solvers based on within method parallelism. +The explicit solvers are outclassed by other explicit methods. +However, some [stiff extrapolation](@ref StiffExtrapolation) methods perform very well. ```@eval first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqExtrapolation", "ImplicitEulerExtrapolation") +first_steps("OrdinaryDiffEqExtrapolation", "ExtrapolationMidpointDeuflhard") ``` ## Full list of solvers ```@docs AitkenNeville -ImplicitEulerExtrapolation ExtrapolationMidpointDeuflhard -ImplicitDeuflhardExtrapolation ExtrapolationMidpointHairerWanner -ImplicitHairerWannerExtrapolation -ImplicitEulerBarycentricExtrapolation ``` \ No newline at end of file diff --git a/docs/src/implicit/Extrapolation.md b/docs/src/implicit/Extrapolation.md new file mode 100644 index 0000000000..031ac91534 --- /dev/null +++ b/docs/src/implicit/Extrapolation.md @@ -0,0 +1,19 @@ +# [OrdinaryDiffEqExtrapolation](@id StiffExtrapolation) + +Solvers based on within method parallelism. +These solvers perform well for medium sized systems of ordinary differential equations, of about 20 to 500 equations, +at low tolerances. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqExtrapolation", "ImplicitEulerBarycentricExtrapolation") +``` + +## Full list of solvers + +```@docs +ImplicitEulerExtrapolation +ImplicitDeuflhardExtrapolation +ImplicitHairerWannerExtrapolation +ImplicitEulerBarycentricExtrapolation +``` \ No newline at end of file From 78c44dd90972631d05c6777ed8b1045a73b25b0b Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 12:07:05 +0200 Subject: [PATCH 56/83] expand symplectic explanation --- docs/src/explicit/SymplecticRK.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/src/explicit/SymplecticRK.md b/docs/src/explicit/SymplecticRK.md index b8cef125b3..a2f5e4488f 100644 --- a/docs/src/explicit/SymplecticRK.md +++ b/docs/src/explicit/SymplecticRK.md @@ -1,10 +1,15 @@ # OrdinaryDiffEqSymplecticRK -Solvers for Hamiltonian systems. +A symplectic integrator is an integrator whose solution resides on a symplectic manifold. +Because of discretization error, when it is solving a Hamiltonian system it doesn't get exactly the correct trajectory on the manifold. +Instead, that trajectory itself is perturbed `O(Δtn)` for the order n from the true trajectory. +Then there's a linear drift due to numerical error of this trajectory over time +Normal integrators tend to have a quadratic (or more) drift, and do not have any good global guarantees about this phase space path (just local). +What means is that symplectic integrators tend to capture the long-time patterns better than normal integrators because of this lack of drift and this almost guarantee of periodicity. ```@eval first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqSymplecticRK", "Nystrom4") +first_steps("OrdinaryDiffEqSymplecticRK", "McAte2") ``` ## Full list of solvers From c44932f94be38ff8a563cc9c4b7cd15784812d58 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 12:08:03 +0200 Subject: [PATCH 57/83] add more algorithms and descriptions --- lib/OrdinaryDiffEqBDF/src/algorithms.jl | 52 +++++-- .../src/algorithms.jl | 23 +-- lib/OrdinaryDiffEqPDIRK/src/algorithms.jl | 10 +- lib/OrdinaryDiffEqPRK/src/algorithms.jl | 21 ++- .../src/generic_rosenbrock.jl | 76 +++++++--- lib/OrdinaryDiffEqSDIRK/src/algorithms.jl | 136 +++++++++++++++--- .../src/algorithms.jl | 12 +- .../src/algorithms.jl | 36 ++--- 8 files changed, 277 insertions(+), 89 deletions(-) diff --git a/lib/OrdinaryDiffEqBDF/src/algorithms.jl b/lib/OrdinaryDiffEqBDF/src/algorithms.jl index 797a63191c..ca15fc2a49 100644 --- a/lib/OrdinaryDiffEqBDF/src/algorithms.jl +++ b/lib/OrdinaryDiffEqBDF/src/algorithms.jl @@ -82,12 +82,20 @@ function ABDF2(; chunk_size = Val{0}(), autodiff = true, standardtag = Val{true} end -@doc BDF_docstring("description TBD.", +@doc BDF_docstring("Implicit-explicit (IMEX) method designed for SplitODEFunction equations, + which reduce the size of the implicit handling to a subset of the equations. + It's similar to the additive Runge-Kutta methods in splitting mode, + like `KenCarp4`, but instead using a multistep BDF approach", "SBDF", - references = """ - E. Alberdi Celayaa, J. J. Anza Aguirrezabalab, P. Chatzipantelidisc. Implementation of - an Adaptive BDF2 Formula and Comparison with The MATLAB Ode15s. Procedia Computer Science, - 29, pp 1014-1026, 2014. doi: https://doi.org/10.1016/j.procs.2014.05.091 + references = """@article{ascher1995implicit, + title={Implicit-explicit methods for time-dependent partial differential equations}, + author={Ascher, Uri M and Ruuth, Steven J and Wetton, Brian TR}, + journal={SIAM Journal on Numerical Analysis}, + volume={32}, + number={3}, + pages={797--823}, + year={1995}, + publisher={SIAM}} """, extra_keyword_description = """ - `κ`: TBD @@ -373,7 +381,15 @@ TruncatedStacktraces.@truncate_stacktrace QNDF which has improved stability properties over the standard BDF. Fixed timestep only.", "MEBDF2", - references = """TBD""", + references = """@article{cash2000modified, + title={Modified extended backward differentiation formulae for the numerical solution of stiff initial value problems in ODEs and DAEs}, + author={Cash, JR}, + journal={Journal of Computational and Applied Mathematics}, + volume={125}, + number={1-2}, + pages={117--130}, + year={2000}, + publisher={Elsevier}}""", extra_keyword_description = """ - `nlsolve`: TBD - `extrapolant`: TBD @@ -535,9 +551,9 @@ See also `SBDF`, `IMEXEuler`. """ IMEXEulerARK(; kwargs...) = SBDF(1; ark = true, kwargs...) -@doc BDF_docstring("TBD.", +@doc BDF_docstring("Implicit Euler for implicit DAE form. + It uses an apriori error estimator for adaptivity based on a finite differencing approximation from SPICE.", "DImplicitEuler", - references = """TBD""", extra_keyword_description = """ - `nlsolve`: TBD - `extrapolant`: TBD @@ -567,9 +583,16 @@ function DImplicitEuler(; nlsolve, precs, extrapolant, controller) end -@doc BDF_docstring("TBD.", +@doc BDF_docstring("Fully implicit implementation of BDF2.", "DABDF2", - references = """TBD""", + references = """@article{celaya2014implementation, + title={Implementation of an Adaptive BDF2 Formula and Comparison with the MATLAB Ode15s}, + author={Celaya, E Alberdi and Aguirrezabala, JJ Anza and Chatzipantelidis, Panagiotis}, + journal={Procedia Computer Science}, + volume={29}, + pages={1014--1026}, + year={2014}, + publisher={Elsevier}}""", extra_keyword_description = """ - `nlsolve`: TBD - `extrapolant`: TBD @@ -612,9 +635,14 @@ DBDF(;chunk_size=Val{0}(),autodiff=Val{true}(), standardtag = Val{true}(), concr linsolve,nlsolve,precs,extrapolant) =# -@doc BDF_docstring("Description TBD", +@doc BDF_docstring("Fully implicit implementation of FBDF based on Shampine's", "DFBDF", - references = """TBD""", + references = """@article{shampine2002solving, + title={Solving 0= F (t, y (t), y′(t)) in Matlab}, + author={Shampine, Lawrence F}, + year={2002}, + publisher={Walter de Gruyter GmbH and Co. KG} + }""", extra_keyword_description = """ - `κ`: TBD - `tol`: TBD diff --git a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl index 90533a7e34..cf3b25a816 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl @@ -2,11 +2,18 @@ abstract type OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm <: OrdinaryDiffEqAdaptiveAlgorithm end abstract type OrdinaryDiffEqImplicitExtrapolationAlgorithm{CS, AD, FDT, ST, CJ} <: OrdinaryDiffEqAdaptiveImplicitAlgorithm{CS, AD, FDT, ST, CJ} end - +reference = """@inproceedings{elrod2022parallelizing, + title={Parallelizing explicit and implicit extrapolation methods for ordinary differential equations}, + author={Elrod, Chris and Ma, Yingbo and Althaus, Konstantin and Rackauckas, Christopher and others}, + booktitle={2022 IEEE High Performance Extreme Computing Conference (HPEC)}, + pages={1--9}, + year={2022}, + organization={IEEE}} +""" @doc generic_solver_docstring("Euler extrapolation using Aitken-Neville with the Romberg Sequence.", "AitkenNeville", "Parallelized Explicit Extrapolation Method.", - "TBD", + reference , """ - `max_order`: TBD - `min_order`: TBD @@ -30,7 +37,7 @@ end Similar to Hairer's SEULEX.", "ImplicitEulerExtrapolation", "Parallelized Explicit Extrapolation Method.", - references = "TBD", + references = reference, extra_keyword_description = """ - `max_order`: TBD - `min_order`: TBD @@ -100,7 +107,7 @@ end @doc generic_solver_docstring("Midpoint extrapolation using Barycentric coordinates.", "ExtrapolationMidpointDeuflhard", "Parallelized Explicit Extrapolation Method.", - "REFS TBD", + reference, """ - `max_order`: TBD - `min_order`: TBD @@ -170,7 +177,7 @@ end @doc differentiation_rk_docstring("Midpoint extrapolation using Barycentric coordinates.", "ImplicitDeuflhardExtrapolation", "Parallelized Explicit Extrapolation Method.", - references = "TBD", + references = reference, extra_keyword_description = """ - `max_order`: TBD - `min_order`: TBD @@ -244,7 +251,7 @@ end following Hairer's ODEX in the adaptivity behavior.", "ExtrapolationMidpointHairerWanner", "Parallelized Explicit Extrapolation Method.", - "REFS TBD", + reference, """ - `max_order`: TBD - `min_order`: TBD @@ -317,7 +324,7 @@ end following Hairer's SODEX in the adaptivity behavior.", "ImplicitHairerWannerExtrapolation", "Parallelized Explicit Extrapolation Method.", - references = "TBD", + references = reference, extra_keyword_description = """ - `max_order`: TBD - `min_order`: TBD @@ -393,7 +400,7 @@ end following Hairer's SODEX in the adaptivity behavior.", "ImplicitEulerBarycentricExtrapolation", "Parallelized Explicit Extrapolation Method.", - references = "TBD", + references = reference, extra_keyword_description = """ - `max_order`: TBD - `min_order`: TBD diff --git a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl index af194ec6af..8dc282a034 100644 --- a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl @@ -1,7 +1,15 @@ @doc differentiation_rk_docstring("A 2 processor 4th order diagonally non-adaptive implicit method.", "PDIRK44", "Parallel Diagonally Implicit Runge-Kutta Method."; - references = "TBD", + references = """"@article{iserles1990theory, + title={On the theory of parallel Runge—Kutta methods}, + author={Iserles, Arieh and Norrsett, SP}, + journal={IMA Journal of numerical Analysis}, + volume={10}, + number={4}, + pages={463--488}, + year={1990}, + publisher={Oxford University Press}}""", extra_keyword_description = """ - `nlsolve`: TBD, - `extrapolant`: TBD, diff --git a/lib/OrdinaryDiffEqPRK/src/algorithms.jl b/lib/OrdinaryDiffEqPRK/src/algorithms.jl index 67372af92d..ee1d0ff1c6 100644 --- a/lib/OrdinaryDiffEqPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPRK/src/algorithms.jl @@ -1,10 +1,17 @@ -@doc generic_solver_docstring("A 5 parallel, 2 processor method of 5th order. - ", - "KuttaPRK2p5", - "Explicit Runge-Kutta Method", - "REFERENCE TBD", - "- `threading`: TBD", - "threading = true,") +@doc generic_solver_docstring("A 5 parallel, 2 processor method of 5th order.", + "KuttaPRK2p5", + "Explicit Runge-Kutta Method", + """@article{jackson1995potential, + title={The potential for parallelism in Runge--Kutta methods. Part 1: RK formulas in standard form}, + author={Jackson, Kenneth R and Norsett, Syvert Paul}, + journal={SIAM journal on numerical analysis}, + volume={32}, + number={1}, + pages={49--82}, + year={1995}, + publisher={SIAM}}""", + "- `threading`: TBD", + "threading = true,") Base.@kwdef struct KuttaPRK2p5{TO} <: OrdinaryDiffEqAlgorithm threading::TO = true end diff --git a/lib/OrdinaryDiffEqRosenbrock/src/generic_rosenbrock.jl b/lib/OrdinaryDiffEqRosenbrock/src/generic_rosenbrock.jl index 5600b1bc27..e6bfaaf4d9 100644 --- a/lib/OrdinaryDiffEqRosenbrock/src/generic_rosenbrock.jl +++ b/lib/OrdinaryDiffEqRosenbrock/src/generic_rosenbrock.jl @@ -959,25 +959,65 @@ with_step_limiter = true) Rodas23W """ A 4th order L-stable Rosenbrock-W method. """, -"ROS34PW1a") ROS34PW1a +"ROS34PW1a", +references = """ +@article{rang2005new, + title={New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1}, + author={Rang, Joachim and Angermann, L}, + journal={BIT Numerical Mathematics}, + volume={45}, + pages={761--787}, + year={2005}, + publisher={Springer}} +""") ROS34PW1a @doc rosenbrock_wanner_docstring( """ A 4th order L-stable Rosenbrock-W method. """, -"ROS34PW1b") ROS34PW1b +"ROS34PW1b", +references = """ +@article{rang2005new, + title={New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1}, + author={Rang, Joachim and Angermann, L}, + journal={BIT Numerical Mathematics}, + volume={45}, + pages={761--787}, + year={2005}, + publisher={Springer}} +""") ROS34PW1b @doc rosenbrock_wanner_docstring( """ A 4th order stiffy accurate Rosenbrock-W method for PDAEs. """, -"ROS34PW2") ROS34PW2 +"ROS34PW2", +references = """ +@article{rang2005new, + title={New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1}, + author={Rang, Joachim and Angermann, L}, + journal={BIT Numerical Mathematics}, + volume={45}, + pages={761--787}, + year={2005}, + publisher={Springer}} +""") ROS34PW2 @doc rosenbrock_wanner_docstring( """ A 4th order strongly A-stable (Rinf~0.63) Rosenbrock-W method. """, -"ROS34PW3") ROS34PW3 +"ROS34PW3", +references = """ +@article{rang2005new, + title={New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1}, + author={Rang, Joachim and Angermann, L}, + journal={BIT Numerical Mathematics}, + volume={45}, + pages={761--787}, + year={2005}, + publisher={Springer}} +""") ROS34PW3 @doc rosenbrock_docstring( """ @@ -995,7 +1035,7 @@ references = """ """, "Rodas3", references = """ -- Steinebach G. Construction of Rosenbrock–Wanner method Rodas5P and numerical benchmarks +- Steinebach G. Construction of Rosenbrock–Wanner method Rodas5P and numerical benchmarks within the Julia Differential Equations package. In: BIT Numerical Mathematics, 63(2), 2023 """, @@ -1056,7 +1096,7 @@ lower if not corrected). """, "Rodas4P", references = """ -- Steinebach G., Rodas23W / Rodas32P - a Rosenbrock-type method for DAEs with additional error estimate +- Steinebach G., Rodas23W / Rodas32P - a Rosenbrock-type method for DAEs with additional error estimate for dense output and Julia implementation, In progress. """, @@ -1070,7 +1110,7 @@ of Roadas4P and in case of inexact Jacobians a second order W method. """, "Rodas4P2", references = """ -- Steinebach G., Rodas23W / Rodas32P - a Rosenbrock-type method for DAEs with additional error estimate +- Steinebach G., Rodas23W / Rodas32P - a Rosenbrock-type method for DAEs with additional error estimate for dense output and Julia implementation, In progress. """, @@ -1095,7 +1135,7 @@ Has improved stability in the adaptive time stepping embedding. """, "Rodas5P", references = """ -- Steinebach G. Construction of Rosenbrock–Wanner method Rodas5P and numerical benchmarks +- Steinebach G. Construction of Rosenbrock–Wanner method Rodas5P and numerical benchmarks within the Julia Differential Equations package. In: BIT Numerical Mathematics, 63(2), 2023 """, @@ -1225,10 +1265,10 @@ references = """ ROS2PRTableau() 2nd order stiffly accurate Rosenbrock method with 3 internal stages with (Rinf=0). -For problems with medium stiffness the convergence behaviour is very poor and it is recommended to use +For problems with medium stiffness the convergence behaviour is very poor and it is recommended to use [`ROS2S`](@ref) instead. -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function ROS2PRTableau() # 2nd order @@ -1248,7 +1288,7 @@ end @doc rosenbrock_docstring( """ 2nd order stiffly accurate Rosenbrock method with 3 internal stages with (Rinf=0). -For problems with medium stiffness the convergence behaviour is very poor and it is recommended to use +For problems with medium stiffness the convergence behaviour is very poor and it is recommended to use [`ROS2S`](@ref) instead. """, "ROS2PR", @@ -1267,7 +1307,7 @@ ROS2PR 2nd order stiffly accurate Rosenbrock-Wanner W-method with 3 internal stages with B_PR consistent of order 2 with (Rinf=0). More Information at https://doi.org/10.24355/dbbs.084-201408121139-0 -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function ROS2STableau() # 2nd order @@ -1335,7 +1375,7 @@ references = """ 3nd order stiffly accurate Rosenbrock-Wanner method with 3 internal stages with B_PR consistent of order 3, which is strongly A-stable with Rinf~=-0.73. -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function ROS3PRTableau() # 3rd order @@ -1371,7 +1411,7 @@ references = """ 3nd order stiffly accurate Rosenbrock method with 3 internal stages with B_PR consistent of order 3, which is strongly A-stable with Rinf~=-0.73 Convergence with order 4 for the stiff case, but has a poor accuracy. -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function Scholz4_7Tableau() # 3rd order @@ -1599,7 +1639,7 @@ references = """ B_PR consistent of order 2 with Rinf=0. The order of convergence decreases if medium stiff problems are considered, but it has good results for very stiff cases. -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function ROS3PRLTableau() # 3rd order @@ -1639,7 +1679,7 @@ references = """ B_PR consistent of order 3. The order of convergence does NOT decreases if medium stiff problems are considered as it does for [`ROS3PRL`](@ref). -Rang, Joachim (2014): The Prothero and Robinson example: +Rang, Joachim (2014): The Prothero and Robinson example: Convergence studies for Runge-Kutta and Rosenbrock-Wanner methods. https://doi.org/10.24355/dbbs.084-201408121139-0 """ function ROS3PRL2Tableau() # 3rd order @@ -1677,7 +1717,7 @@ references = """ 4rd order L-stable Rosenbrock-Krylov method with 4 internal stages, with a 3rd order embedded method which is strongly A-stable with Rinf~=0.55. (when using exact Jacobians) -Tranquilli, Paul and Sandu, Adrian (2014): Rosenbrock--Krylov Methods for Large Systems of Differential Equations +Tranquilli, Paul and Sandu, Adrian (2014): Rosenbrock--Krylov Methods for Large Systems of Differential Equations https://doi.org/10.1137/130923336 """ function ROK4aTableau() # 4rd order @@ -1703,7 +1743,7 @@ with a 3rd order embedded method which is strongly A-stable with Rinf~=0.55. (wh """, "ROK4a", references = """ -- Tranquilli, Paul and Sandu, Adrian (2014): +- Tranquilli, Paul and Sandu, Adrian (2014): Rosenbrock--Krylov Methods for Large Systems of Differential Equations https://doi.org/10.1137/130923336 """) ROK4a diff --git a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl index 75f8489ea0..4f037f089f 100644 --- a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl @@ -35,7 +35,12 @@ end Adaptive timestepping through a divided differences estimate via memory. Strong-stability preserving (SSP).", "ImplicitEuler"; - references = "TBD", + references = "@book{wanner1996solving, + title={Solving ordinary differential equations II}, + author={Wanner, Gerhard and Hairer, Ernst}, + volume={375}, + year={1996}, + publisher={Springer Berlin Heidelberg New York}}", extra_keyword_description = """ - `extrapolant`: TBD - `controller`: TBD @@ -71,7 +76,12 @@ end @doc SDIRK_docstring("A second order A-stable symplectic and symmetric implicit solver. Good for highly stiff equations which need symplectic integration.", "ImplicitMidpoint"; - references = "TBD", + references = "@book{wanner1996solving, + title={Solving ordinary differential equations II}, + author={Wanner, Gerhard and Hairer, Ernst}, + volume={375}, + year={1996}, + publisher={Springer Berlin Heidelberg New York}}", extra_keyword_description = """ - `extrapolant`: TBD - `step_limiter!`: TBD @@ -245,7 +255,10 @@ end @doc SDIRK_docstring("Description TBD", "SDIRK22"; - references = "TBD", + references = "@techreport{kennedy2016diagonally, + title={Diagonally implicit Runge-Kutta methods for ordinary differential equations. A review}, + author={Kennedy, Christopher A and Carpenter, Mark H}, + year={2016}}", extra_keyword_description = """ - `smooth_est`: TBD - `extrapolant`: TBD @@ -284,9 +297,21 @@ function SDIRK22(; step_limiter!) end -@doc SDIRK_docstring("Description TBD", +@doc SDIRK_docstring("""SSPSDIRK is an SSP-optimized SDIRK method, + so it's an implicit SDIRK method for handling stiffness but if the `dt` is below the SSP `coefficient * dt`, + then the SSP property of the SSP integrators (the other page) is satisified. + As such this is a method which is expected to be good on advection-dominated cases where an explicit SSP integrator would be used, + but where reaction equations are sufficient stiff to justify implicit integration.""", "SSPSDIRK2"; - references = "TBD", + references = "@article{ketcheson2009optimal, + title={Optimal implicit strong stability preserving Runge--Kutta methods}, + author={Ketcheson, David I and Macdonald, Colin B and Gottlieb, Sigal}, + journal={Applied Numerical Mathematics}, + volume={59}, + number={2}, + pages={373--392}, + year={2009}, + publisher={Elsevier}}", extra_keyword_description = """ - `smooth_est`: TBD - `extrapolant`: TBD @@ -406,9 +431,17 @@ function KenCarp3(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Third order method.", "CFNLIRK3"; - references = "TBD", + references = "@article{calvo2001linearly, + title={Linearly implicit Runge--Kutta methods for advection--reaction--diffusion equations}, + author={Calvo, MP and De Frutos, J and Novo, J}, + journal={Applied Numerical Mathematics}, + volume={37}, + number={4}, + pages={535--549}, + year={2001}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -485,9 +518,17 @@ function Cash4(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va controller) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Method of order 4.", "SFSDIRK4"; - references = "TBD", + references = "@article{ferracina2008strong, + title={Strong stability of singly-diagonally-implicit Runge--Kutta methods}, + author={Ferracina, Luca and Spijker, MN}, + journal={Applied Numerical Mathematics}, + volume={58}, + number={11}, + pages={1675--1686}, + year={2008}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -514,9 +555,17 @@ function SFSDIRK4(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Method of order 5.", "SFSDIRK5"; - references = "TBD", + references = "@article{ferracina2008strong, + title={Strong stability of singly-diagonally-implicit Runge--Kutta methods}, + author={Ferracina, Luca and Spijker, MN}, + journal={Applied Numerical Mathematics}, + volume={58}, + number={11}, + pages={1675--1686}, + year={2008}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -544,9 +593,17 @@ function SFSDIRK5(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Method of order 6.", "SFSDIRK6"; - references = "TBD", + references = "@article{ferracina2008strong, + title={Strong stability of singly-diagonally-implicit Runge--Kutta methods}, + author={Ferracina, Luca and Spijker, MN}, + journal={Applied Numerical Mathematics}, + volume={58}, + number={11}, + pages={1675--1686}, + year={2008}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -575,9 +632,17 @@ function SFSDIRK6(; chunk_size = Val{0}(), autodiff = Val{true}(), end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Method of order 7.", "SFSDIRK7"; - references = "TBD", + references = "@article{ferracina2008strong, + title={Strong stability of singly-diagonally-implicit Runge--Kutta methods}, + author={Ferracina, Luca and Spijker, MN}, + journal={Applied Numerical Mathematics}, + volume={58}, + number={11}, + pages={1675--1686}, + year={2008}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -605,9 +670,17 @@ function SFSDIRK7(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Method of order 8.", "SFSDIRK8"; - references = "TBD", + references = "@article{ferracina2008strong, + title={Strong stability of singly-diagonally-implicit Runge--Kutta methods}, + author={Ferracina, Luca and Spijker, MN}, + journal={Applied Numerical Mathematics}, + volume={58}, + number={11}, + pages={1675--1686}, + year={2008}, + publisher={Elsevier}}", extra_keyword_description = """ - `extrapolant`: TBD """, @@ -964,9 +1037,18 @@ function KenCarp58(; chunk_size = Val{0}(), autodiff = Val{true}(), end # `smooth_est` is not necessary, as the embedded method is also L-stable -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Optimized ESDIRK tableaus. + Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, + but are still being fully evaluated in context.", "ESDIRK54I8L2SA"; - references = "TBD", + references = """@article{Kennedy2019DiagonallyIR, + title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, + author={Christopher A. Kennedy and Mark H. Carpenter}, + journal={Applied Numerical Mathematics}, + year={2019}, + volume={146}, + pages={221-244} + }""", extra_keyword_description = """ - `extrapolant`: TBD - `controller`: TBD @@ -994,7 +1076,9 @@ function ESDIRK54I8L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Optimized ESDIRK tableaus. + Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, + but are still being fully evaluated in context.", "ESDIRK436L2SA2"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1031,7 +1115,9 @@ function ESDIRK436L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Optimized ESDIRK tableaus. + Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, + but are still being fully evaluated in context.", "ESDIRK437L2SA"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1068,7 +1154,9 @@ function ESDIRK437L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Description TBD.", +@doc SDIRK_docstring("Optimized ESDIRK tableaus. + Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, + but are still being fully evaluated in context.", "ESDIRK547L2SA2"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1105,7 +1193,9 @@ function ESDIRK547L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Description TBD. +@doc SDIRK_docstring("Optimized ESDIRK tableaus. + Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, + but are still being fully evaluated in context. Currently has STABILITY ISSUES, causing it to fail the adaptive tests. Check issue https://github.com/SciML/OrdinaryDiffEq.jl/issues/1933 for more details.", "ESDIRK659L2SA"; diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl index 78c1ea0256..9cbd73a41c 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl @@ -120,10 +120,18 @@ function ESERK4 end """) function ESERK5 end -@doc generic_solver_docstring("""Second order method. description TBD""", +@doc generic_solver_docstring("""Second order method.""", "SERK2", "Stabilized Explicit Method.", - """REF TBD""", + """@article{kleefeld2013serk2v2, + title={SERK2v2: A new second-order stabilized explicit Runge-Kutta method for stiff problems}, + author={Kleefeld, B and Martin-Vaquero, J}, + journal={Numerical Methods for Partial Differential Equations}, + volume={29}, + number={1}, + pages={170--185}, + year={2013}, + publisher={Wiley Online Library}}""", """ - `controller`: TBD - `eigen_est`: function of the form diff --git a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl index 75e02eb4c5..43132f319d 100644 --- a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl @@ -1,7 +1,7 @@ -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("First order explicit symplectic integrator.", "SymplecticEuler", "Symplectic Runge-Kutta Methods", - "REF TBD", "", "") + "https://en.wikipedia.org/wiki/Semi-implicit_Euler_method", "", "") struct SymplecticEuler <: OrdinaryDiffEqPartitionedAlgorithm end verlet1967 = """ @@ -17,19 +17,19 @@ publisher={APS} } """ -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("2nd order explicit symplectic integrator. Requires f_2(t,u) = v, i.e. a second order ODE.", "VelocityVerlet", "Symplectic Runge-Kutta Methods", verlet1967, "", "") struct VelocityVerlet <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("2nd order explicit symplectic integrator.", "VerletLeapfrog", "Symplectic Runge-Kutta Methods", verlet1967, "", "") struct VerletLeapfrog <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("2nd order explicit symplectic integrator.", "PseudoVerletLeapfrog", "Symplectic Runge-Kutta Methods", verlet1967, "", "") @@ -48,13 +48,13 @@ publisher={IOP Publishing} } """ -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 2nd order explicit symplectic integrator.", "McAte2", "Symplectic Runge-Kutta Methods", mclachlan1992, "", "") struct McAte2 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("3rd order explicit symplectic integrator.", "Ruth3", "Symplectic Runge-Kutta Methods", """@article{ruth1983canonical, @@ -67,13 +67,13 @@ struct McAte2 <: OrdinaryDiffEqPartitionedAlgorithm end year={1983}}""", "", "") struct Ruth3 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 3rd order explicit symplectic integrator.", "McAte3", "Symplectic Runge-Kutta Methods", mclachlan1992, "", "") struct McAte3 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("4th order explicit symplectic integrator.", "CandyRoz4", "Symplectic Runge-Kutta Methods", """@article{candy1991symplectic, @@ -87,13 +87,13 @@ struct McAte3 <: OrdinaryDiffEqPartitionedAlgorithm end ublisher={Elsevier}}""", "", "") struct CandyRoz4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("4th order explicit symplectic integrator. Requires quadratic kinetic energy.", "McAte4", "Symplectic Runge-Kutta Methods", mclachlan1992, "", "") struct McAte4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 4th order explicit symplectic integrator.", "CalvoSanz4", "Symplectic Runge-Kutta Methods", """@article{sanz1993symplectic, @@ -108,19 +108,19 @@ struct McAte4 <: OrdinaryDiffEqPartitionedAlgorithm end }""", "", "") struct CalvoSanz4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("4th order explicit symplectic integrator. BROKEN", "McAte42", "Symplectic Runge-Kutta Methods", mclachlan1992, "", "") struct McAte42 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 5th order explicit symplectic integrator. Requires quadratic kinetic energy.", "McAte5", "Symplectic Runge-Kutta Methods", mclachlan1992, "", "") struct McAte5 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("6th order explicit symplectic integrator.", "Yoshida6", "Symplectic Runge-Kutta Methods", """@article{yoshida1990construction, @@ -134,7 +134,7 @@ struct McAte5 <: OrdinaryDiffEqPartitionedAlgorithm end publisher={Elsevier}}""", "", "") struct Yoshida6 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 6th order explicit symplectic integrator.", "KahanLi6", "Symplectic Runge-Kutta Methods", """@article{yoshida1990construction, @@ -148,7 +148,7 @@ struct Yoshida6 <: OrdinaryDiffEqPartitionedAlgorithm end publisher={Elsevier}}""", "", "") struct KahanLi6 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("8th order explicit symplectic integrator.", "McAte8", "Symplectic Runge-Kutta Methods", """@article{mclachlan1995numerical, @@ -163,7 +163,7 @@ struct KahanLi6 <: OrdinaryDiffEqPartitionedAlgorithm end }""", "", "") struct McAte8 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("Optimized efficiency 8th order explicit symplectic integrator.", "KahanLi8", "Symplectic Runge-Kutta Methods", """@article{kahan1997composition, @@ -176,7 +176,7 @@ struct McAte8 <: OrdinaryDiffEqPartitionedAlgorithm end year={1997}}""", "", "") struct KahanLi8 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("DESCRIPTION TBD", +@doc generic_solver_docstring("10th order explicit symplectic integrator.", "SofSpa10", "Symplectic Runge-Kutta Methods", """@article{sofroniou2005derivation, From 16d167a9454e243d97324608a78cd1d31a2bceec Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 13:24:57 +0200 Subject: [PATCH 58/83] docs Linear --- docs/make.jl | 5 ++- docs/src/misc.md | 1 - docs/src/semilinear/Linear.md | 31 ++++++++++++++ docs/src/semilinear/magnus.md | 21 ---------- .../src/OrdinaryDiffEqLinear.jl | 3 +- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 40 ++++++++++++++++++- 6 files changed, 75 insertions(+), 26 deletions(-) create mode 100644 docs/src/semilinear/Linear.md delete mode 100644 docs/src/semilinear/magnus.md diff --git a/docs/make.jl b/docs/make.jl index 579492fb75..45f7d4bbe9 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -31,7 +31,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqPDIRK, OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, - OrdinaryDiffEq.OrdinaryDiffEqBDF], + OrdinaryDiffEq.OrdinaryDiffEqBDF, + OrdinaryDiffEq.OrdinaryDiffEqLinear], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -69,7 +70,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", ], "Semilinear ODE Solvers" => [ "semilinear/exponential_rk.md", - "semilinear/magnus.md" + "semilinear/Linear.md" ], "Misc Solvers" => [ "misc.md" diff --git a/docs/src/misc.md b/docs/src/misc.md index 595e0c88f8..cff4221384 100644 --- a/docs/src/misc.md +++ b/docs/src/misc.md @@ -1,5 +1,4 @@ ```@docs -LinearExponential SplitEuler CompositeAlgorithm PDIRK44 diff --git a/docs/src/semilinear/Linear.md b/docs/src/semilinear/Linear.md new file mode 100644 index 0000000000..fe14d1ffda --- /dev/null +++ b/docs/src/semilinear/Linear.md @@ -0,0 +1,31 @@ +# OrdinaryDiffEqLinear + +Methods for semi-linear differential equations. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqLinear", "LieRK4") +``` + +## Full list of solvers + +```@docs +MagnusMidpoint +MagnusLeapfrog +LieEuler +MagnusGauss4 +MagnusNC6 +MagnusGL6 +MagnusGL8 +MagnusNC8 +MagnusGL4 +RKMK2 +RKMK4 +LieRK4 +CG2 +CG3 +CG4a +MagnusAdapt4 +CayleyEuler +LinearExponential +``` diff --git a/docs/src/semilinear/magnus.md b/docs/src/semilinear/magnus.md deleted file mode 100644 index fa7aee8f64..0000000000 --- a/docs/src/semilinear/magnus.md +++ /dev/null @@ -1,21 +0,0 @@ -# Magnus and Lie Group Integrators - -```@docs -MagnusMidpoint -MagnusLeapfrog -LieEuler -MagnusGauss4 -MagnusNC6 -MagnusGL6 -MagnusGL8 -MagnusNC8 -MagnusGL4 -RKMK2 -RKMK4 -LieRK4 -CG2 -CG3 -CG4a -MagnusAdapt4 -CayleyEuler -``` diff --git a/lib/OrdinaryDiffEqLinear/src/OrdinaryDiffEqLinear.jl b/lib/OrdinaryDiffEqLinear/src/OrdinaryDiffEqLinear.jl index 1edc26727d..e7954b1833 100644 --- a/lib/OrdinaryDiffEqLinear/src/OrdinaryDiffEqLinear.jl +++ b/lib/OrdinaryDiffEqLinear/src/OrdinaryDiffEqLinear.jl @@ -8,7 +8,8 @@ import OrdinaryDiffEqCore: alg_order, alg_extrapolates, dt_required, OrdinaryDiffEqConstantCache, initialize!, perform_step!, @unpack, unwrap_alg, calculate_residuals!, get_fsalfirstlast, - _vec, isdtchangeable, full_cache + _vec, isdtchangeable, full_cache, + generic_solver_docstring using LinearAlgebra: mul!, I using SciMLOperators: AbstractSciMLOperator using ExponentialUtilities diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 64a9b69b71..3cdbc22fea 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -17,18 +17,56 @@ for Alg in [ :CG3, :CG4a ] - @eval struct $Alg <: OrdinaryDiffEqLinearExponentialAlgorithm + @eval begin + @doc generic_solver_docstring("description TBD", + $(string(Alg)), + "Semilinear ODE solver", + "ref TBD", + """ + - `krylov`: TBD + - `m`: TBD + - `iop`: TBD + """, + """ + krylov = false, + m = 30, + iop = 0, + """) + struct $Alg <: OrdinaryDiffEqLinearExponentialAlgorithm krylov::Bool m::Int iop::Int + end end @eval $Alg(; krylov = false, m = 30, iop = 0) = $Alg(krylov, m, iop) end +@doc generic_solver_docstring("description TBD", + "MagnusAdapt4", + "Semilinear ODE solver", + "ref TBD", "", "") struct MagnusAdapt4 <: OrdinaryDiffEqAdaptiveAlgorithm end +@doc generic_solver_docstring("description TBD", + "CayleyEuler", + "Semilinear ODE solver", + "ref TBD", "", "") struct CayleyEuler <: OrdinaryDiffEqAlgorithm end +@doc generic_solver_docstring("description TBD", + "LinearExponential", + "Semilinear ODE solver", + "ref TBD", + """ + - `krylov`: TBD + - `m`: TBD + - `iop`: TBD + """, + """ + krylov = :off, + m = 10, + iop = 0, + """) struct LinearExponential <: OrdinaryDiffEqExponentialAlgorithm{1, false, Val{:forward}, Val{true}, nothing} krylov::Symbol From 80e8b1f26658f458ac54e8a6db711cb3594362f8 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 14:27:30 +0200 Subject: [PATCH 59/83] Fill in linear descriptions --- docs/src/semilinear/Linear.md | 23 +++++++-- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 56 ++++++++++++---------- 2 files changed, 50 insertions(+), 29 deletions(-) diff --git a/docs/src/semilinear/Linear.md b/docs/src/semilinear/Linear.md index fe14d1ffda..b9fbd87954 100644 --- a/docs/src/semilinear/Linear.md +++ b/docs/src/semilinear/Linear.md @@ -9,23 +9,40 @@ first_steps("OrdinaryDiffEqLinear", "LieRK4") ## Full list of solvers +### Time and State-Independent Solvers + +```@docs +LinearExponential +``` + +### Time-Dependent and State-Independent Solvers + ```@docs MagnusMidpoint MagnusLeapfrog -LieEuler MagnusGauss4 MagnusNC6 MagnusGL6 MagnusGL8 MagnusNC8 MagnusGL4 +``` + +### State-Dependent Solvers + +```@docs +LieEuler RKMK2 RKMK4 LieRK4 CG2 -CG3 CG4a MagnusAdapt4 CayleyEuler -LinearExponential ``` + +### Time and State-Dependent Operators + +```@docs +CG3 +``` \ No newline at end of file diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 3cdbc22fea..1f213c97ee 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -1,27 +1,26 @@ # Linear Methods -for Alg in [ - :MagnusMidpoint, - :MagnusLeapfrog, - :LieEuler, - :MagnusGauss4, - :MagnusNC6, - :MagnusGL6, - :MagnusGL8, - :MagnusNC8, - :MagnusGL4, - :RKMK2, - :RKMK4, - :LieRK4, - :CG2, - :CG3, - :CG4a -] +for (Alg, Description, Ref) in [ + (:MagnusMidpoint, "Second order Magnus Midpoint method.", "ref TBD"), + (:MagnusLeapfrog, "Second order Magnus Leapfrog method.", "ref TBD"), + (:LieEuler, "description", "ref TBD"), + (:MagnusGauss4, "Fourth order Magnus method approximated using a two stage Gauss quadrature.", "ref TBD"), + (:MagnusNC6, "Sixth order Magnus method approximated using Newton-Cotes quadrature.", "ref TBD"), + (:MagnusGL6, "Sixth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), + (:MagnusGL8, "Eighth order Magnus method approximated using Newton-Cotes quadrature.", "ref TBD"), + (:MagnusNC8, "Eighth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), + (:MagnusGL4, "Fourth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), + (:RKMK2, "Second order Runge–Kutta–Munthe-Kaas method.", "ref TBD"), + (:RKMK4, "Fourth order Runge–Kutta–Munthe-Kaas method.", "ref TBD"), + (:LieRK4, "Fourth order Lie Runge-Kutta method.", "ref TBD"), + (:CG2, "Second order Crouch–Grossman method.", "ref TBD"), + (:CG3, "Third order Crouch-Grossman method.", "ref TBD"), + (:CG4a, " Fourth order Crouch-Grossman method.", "ref TBD")] @eval begin - @doc generic_solver_docstring("description TBD", + @doc generic_solver_docstring($Description, $(string(Alg)), "Semilinear ODE solver", - "ref TBD", + $Ref, """ - `krylov`: TBD - `m`: TBD @@ -31,7 +30,7 @@ for Alg in [ krylov = false, m = 30, iop = 0, - """) + """) struct $Alg <: OrdinaryDiffEqLinearExponentialAlgorithm krylov::Bool m::Int @@ -41,26 +40,31 @@ for Alg in [ @eval $Alg(; krylov = false, m = 30, iop = 0) = $Alg(krylov, m, iop) end -@doc generic_solver_docstring("description TBD", +@doc generic_solver_docstring("Fourth Order Adaptive Magnus method.", "MagnusAdapt4", "Semilinear ODE solver", "ref TBD", "", "") struct MagnusAdapt4 <: OrdinaryDiffEqAdaptiveAlgorithm end -@doc generic_solver_docstring("description TBD", +@doc generic_solver_docstring("First order method using Cayley transformations.", "CayleyEuler", "Semilinear ODE solver", "ref TBD", "", "") struct CayleyEuler <: OrdinaryDiffEqAlgorithm end -@doc generic_solver_docstring("description TBD", +@doc generic_solver_docstring("Exact solution formula for linear, time-independent problems.", "LinearExponential", "Semilinear ODE solver", "ref TBD", """ - - `krylov`: TBD - - `m`: TBD - - `iop`: TBD + - `krylov`: + - `:off`: cache the operator beforehand. Requires Matrix(A) method defined for the operator A. + - `:simple`: uses simple Krylov approximations with fixed subspace size m. + - `:adaptive`: uses adaptive Krylov approximations with internal timestepping. + - `m`: Controls the size of Krylov subspace if `krylov=:simple`, and the initial subspace size if `krylov=:adaptive`. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure + Note that if the linear operator/Jacobian is hermitian, + then the Lanczos algorithm will always be used and the IOP setting is ignored. """, """ krylov = :off, From c51322d1672735654d3f66a6e9484e8e87427f5c Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 16:44:23 +0200 Subject: [PATCH 60/83] docs ExponentialRK --- docs/make.jl | 6 +- docs/src/semilinear/ExponentialRK.md | 39 +++++++ docs/src/semilinear/exponential_rk.md | 18 --- .../src/OrdinaryDiffEqExponentialRK.jl | 3 +- .../src/algorithms.jl | 109 ++++++++++++++---- 5 files changed, 133 insertions(+), 42 deletions(-) create mode 100644 docs/src/semilinear/ExponentialRK.md delete mode 100644 docs/src/semilinear/exponential_rk.md diff --git a/docs/make.jl b/docs/make.jl index 45f7d4bbe9..5c15f03d29 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -32,7 +32,9 @@ makedocs(sitename = "OrdinaryDiffEq.jl", OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, OrdinaryDiffEq.OrdinaryDiffEqBDF, - OrdinaryDiffEq.OrdinaryDiffEqLinear], + OrdinaryDiffEq.OrdinaryDiffEqLinear, + OrdinaryDiffEq.OrdinaryDiffEqExponentialRK, + ], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -69,7 +71,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "imex/imex_sdirk.md" ], "Semilinear ODE Solvers" => [ - "semilinear/exponential_rk.md", + "semilinear/ExponentialRK.md", "semilinear/Linear.md" ], "Misc Solvers" => [ diff --git a/docs/src/semilinear/ExponentialRK.md b/docs/src/semilinear/ExponentialRK.md new file mode 100644 index 0000000000..30acf79764 --- /dev/null +++ b/docs/src/semilinear/ExponentialRK.md @@ -0,0 +1,39 @@ +# OrdinaryDiffEqExponentialRK + +Methods for semi-linear differential equations. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqExponentialRK", "Exprb43") +``` + +## Full list of solvers + +```@docs +LawsonEuler +NorsettEuler +ETD2 +ETDRK2 +ETDRK3 +ETDRK4 +HochOst4 +``` + +### Adaptive Exponential Rosenbrock Methods + +```@docs +Exprb32 +Exprb43 +``` + +### Exponential Propagation Iterative Runge-Kutta Methods (EPIRK) + +```@docs +Exp4 +EPIRK4s3A +EPIRK4s3B +EPIRK5s3 +EXPRB53s3 +EPIRK5P1 +EPIRK5P2 +``` \ No newline at end of file diff --git a/docs/src/semilinear/exponential_rk.md b/docs/src/semilinear/exponential_rk.md deleted file mode 100644 index 320ad68ad6..0000000000 --- a/docs/src/semilinear/exponential_rk.md +++ /dev/null @@ -1,18 +0,0 @@ -# Exponential Runge-Kutta Integrators - -```@docs -LawsonEuler -NorsettEuler -ETD2 -ETDRK2 -ETDRK3 -ETDRK4 -HochOst4 -Exp4 -EPIRK4s3A -EPIRK4s3B -EPIRK5s3 -EXPRB53s3 -EPIRK5P1 -EPIRK5P2 -``` diff --git a/lib/OrdinaryDiffEqExponentialRK/src/OrdinaryDiffEqExponentialRK.jl b/lib/OrdinaryDiffEqExponentialRK/src/OrdinaryDiffEqExponentialRK.jl index 5e0043aa35..98fde5722c 100644 --- a/lib/OrdinaryDiffEqExponentialRK/src/OrdinaryDiffEqExponentialRK.jl +++ b/lib/OrdinaryDiffEqExponentialRK/src/OrdinaryDiffEqExponentialRK.jl @@ -9,7 +9,8 @@ import OrdinaryDiffEqCore: alg_order, alg_adaptive_order, ismultistep, OrdinaryDiffEqAdaptiveExponentialAlgorithm, CompositeAlgorithm, ExponentialAlgorithm, fsal_typeof, isdtchangeable, calculate_residuals, calculate_residuals!, - full_cache, get_fsalfirstlast + full_cache, get_fsalfirstlast, + generic_solver_docstring import OrdinaryDiffEqCore using RecursiveArrayTools using MuladdMacro, FastBroadcast diff --git a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl index 800176cdc1..cef401fba5 100644 --- a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl @@ -1,14 +1,40 @@ -for Alg in [:LawsonEuler, :NorsettEuler, :ETDRK2, :ETDRK3, :ETDRK4, :HochOst4] - """ - Hochbruck, Marlis, and Alexander Ostermann. “Exponential Integrators.” Acta - Numerica 19 (2010): 209–286. doi:10.1017/S0962492910000048. - """ - @eval struct $Alg{CS, AD, FDT, ST, CJ} <: +REF1 = """ +Hochbruck, Marlis, and Alexander Ostermann. “Exponential Integrators.” Acta + Numerica 19 (2010): 209–286. doi:10.1017/S0962492910000048. +""" +for (Alg, Description, Ref) in [ + (:LawsonEuler, "First order exponential Euler scheme.", REF1), + (:NorsettEuler, "First order exponential-RK scheme. Alias: `ETD1`", REF1), + (:ETDRK2, "2nd order exponential-RK scheme.", REF1), + (:ETDRK3, "3rd order exponential-RK scheme.", REF1), + (:ETDRK4, "4th order exponential-RK scheme", REF1), + (:HochOst4, "4th order exponential-RK scheme with stiff order 4.", REF1), + ] + + @eval begin + @doc generic_solver_docstring($Description, + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `krylov`: Determines whether Krylov approximation or operator caching is used, the latter only available for semilinear problems. + `krylov=true` is much faster for larger systems and is thus recommended whenever there are >100 ODEs. + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + krylov = false, + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} - krylov::Bool - m::Int - iop::Int - end + krylov::Bool + m::Int + iop::Int + end + end @eval function $Alg(; krylov = false, m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, chunk_size = Val{0}(), @@ -22,11 +48,27 @@ end const ETD1 = NorsettEuler # alias -for Alg in [:Exprb32, :Exprb43] - @eval struct $Alg{CS, AD, FDT, ST, CJ} <: - OrdinaryDiffEqAdaptiveExponentialAlgorithm{CS, AD, FDT, ST, CJ} - m::Int - iop::Int +for (Alg, Description, Ref) in [ + (:Exprb32, "3rd order adaptive Exponential-Rosenbrock scheme.", "ref TBD"), + (:Exprb43, "4th order adaptive Exponential-Rosenbrock scheme.", "ref TBD")] + @eval begin @doc generic_solver_docstring($Description, + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: + OrdinaryDiffEqAdaptiveExponentialAlgorithm{CS, AD, FDT, ST, CJ} + m::Int + iop::Int + end end @eval function $Alg(; m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, chunk_size = Val{0}(), @@ -37,12 +79,37 @@ for Alg in [:Exprb32, :Exprb43] iop) end end -for Alg in [:Exp4, :EPIRK4s3A, :EPIRK4s3B, :EPIRK5s3, :EXPRB53s3, :EPIRK5P1, :EPIRK5P2] - @eval struct $Alg{CS, AD, FDT, ST, CJ} <: - OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} - adaptive_krylov::Bool - m::Int - iop::Int +for (Alg, Description, Ref) in [ + (:Exp4, "4th order EPIRK scheme.", "REF TBD") + (:EPIRK4s3A, "4th order EPIRK scheme with stiff order 4.", "REF TBD") + (:EPIRK4s3B, "4th order EPIRK scheme with stiff order 4.", "REF TBD") + (:EPIRK5s3, "5th order “horizontal” EPIRK scheme with stiff order 5. Broken.", "REF TBD") + (:EXPRB53s3, "5th order EPIRK scheme with stiff order 5.", "REF TBD") + (:EPIRK5P1, "5th order EPIRK scheme", "REF TBD") + (:EPIRK5P2, "5th order EPIRK scheme", "REF TBD") + ] + @eval begin + @doc generic_solver_docstring($Description, + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `adaptive_krylov`: Determines if the adaptive Krylov algorithm with timestepping of Neisen & Wright is used. + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + adaptive_krylov = true, + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: + OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} + adaptive_krylov::Bool + m::Int + iop::Int + end end @eval function $Alg(; adaptive_krylov = true, m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, From 6a0478fa5628c8ec9a6428228b54a90939feaa55 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 21:00:19 +0200 Subject: [PATCH 61/83] StabalizedIRK docs --- docs/src/implicit/StabalizedIRK.md | 20 +++++++++++++++++++ .../src/OrdinaryDiffEqStabilizedIRK.jl | 3 ++- .../src/algorithms.jl | 9 +++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 docs/src/implicit/StabalizedIRK.md diff --git a/docs/src/implicit/StabalizedIRK.md b/docs/src/implicit/StabalizedIRK.md new file mode 100644 index 0000000000..719c6308da --- /dev/null +++ b/docs/src/implicit/StabalizedIRK.md @@ -0,0 +1,20 @@ +# OrdinaryDiffEqStabalizedIRK + +Explicit stabilized methods utilize an upper bound on the spectral radius of the Jacobian. +Users can supply an upper bound by specifying the keyword argument `eigen_est`, for example + +```julia +`eigen_est = (integrator) -> integrator.eigen_est = upper_bound` +``` + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqStabalizedIRK", "IRKC") +``` + +## Full list of solvers + +```@docs +IRKC +``` + diff --git a/lib/OrdinaryDiffEqStabilizedIRK/src/OrdinaryDiffEqStabilizedIRK.jl b/lib/OrdinaryDiffEqStabilizedIRK/src/OrdinaryDiffEqStabilizedIRK.jl index cd2cfa4a5f..f16310de7e 100644 --- a/lib/OrdinaryDiffEqStabilizedIRK/src/OrdinaryDiffEqStabilizedIRK.jl +++ b/lib/OrdinaryDiffEqStabilizedIRK/src/OrdinaryDiffEqStabilizedIRK.jl @@ -10,7 +10,8 @@ import OrdinaryDiffEqCore: alg_order, alg_maximum_order, OrdinaryDiffEqAdaptiveAlgorithm, OrdinaryDiffEqAdaptiveImplicitAlgorithm, alg_cache, _unwrap_val, DEFAULT_PRECS, @cache, - _reshape, _vec, full_cache, get_fsalfirstlast + _reshape, _vec, full_cache, get_fsalfirstlast, + generic_solver_docstring using OrdinaryDiffEqDifferentiation: dolinsolve, update_W! using OrdinaryDiffEqNonlinearSolve: NLNewton, nlsolve!, isnewton, build_nlsolver, diff --git a/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl index 1a59689554..e4b2465860 100644 --- a/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl @@ -1,3 +1,12 @@ +@doc generic_solver_docstring("Description TBD", + "IRKC", + "Stabalized Implicit Runge Kutta method.", + "REF TBD", + "- `eigen_est`: function of the form + `(integrator) -> integrator.eigen_est = upper_bound`, + where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. + If `eigen_est` is not provided, `upper_bound` will be estimated using the power iteration.", + "eigen_est = nothing,") struct IRKC{CS, AD, F, F2, P, FDT, ST, CJ, K, T, E} <: OrdinaryDiffEqNewtonAdaptiveAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From 79e620e6d69e307a83bc784e8bcb1cf33137ef9e Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 21:45:22 +0200 Subject: [PATCH 62/83] more StabalizedIRK docs --- docs/make.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/make.jl b/docs/make.jl index 5c15f03d29..30456158ff 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -63,6 +63,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "implicit/PDIRK.md", "implicit/Rosenbrock.md", "implicit/StabalizedRK.md", + "implicit/StabalizedIRK.md", "implicit/BDF.md", "implicit/Extrapolation.md" ], From 0bb488d6deaceb75791049bda71d8532d51b165e Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 21:45:39 +0200 Subject: [PATCH 63/83] proper symplectic example --- docs/src/explicit/SymplecticRK.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/src/explicit/SymplecticRK.md b/docs/src/explicit/SymplecticRK.md index a2f5e4488f..baf51afd47 100644 --- a/docs/src/explicit/SymplecticRK.md +++ b/docs/src/explicit/SymplecticRK.md @@ -7,9 +7,31 @@ Then there's a linear drift due to numerical error of this trajectory over time Normal integrators tend to have a quadratic (or more) drift, and do not have any good global guarantees about this phase space path (just local). What means is that symplectic integrators tend to capture the long-time patterns better than normal integrators because of this lack of drift and this almost guarantee of periodicity. -```@eval -first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqSymplecticRK", "McAte2") +## Installation +To be able to access the solvers in `OrdinaryDiffEqSymplecticRK`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqSymplecticRK") +``` +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage +```julia +using OrdinaryDiffEqSymplecticRK +function HH_acceleration!(dv, v, u, p, t) + x, y = u + dx, dy = dv + dv[1] = -x - 2x * y + dv[2] = y^2 - y - x^2 +end +initial_positions = [0.0, 0.1] +initial_velocities = [0.5, 0.0] +tspan = (0.0, 1.0) +prob = SecondOrderODEProblem(HH_acceleration!, initial_velocities, initial_positions, tspan) +sol = solve(prob, KahanLi8(), dt = 1 / 10) ``` ## Full list of solvers From a3b98bf3478aac9b6b38b03058aff4ac86f7198f Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 22:12:47 +0200 Subject: [PATCH 64/83] proper RKN example --- docs/src/explicit/RKN.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/src/explicit/RKN.md b/docs/src/explicit/RKN.md index 29f8fd755f..8de647ab66 100644 --- a/docs/src/explicit/RKN.md +++ b/docs/src/explicit/RKN.md @@ -2,9 +2,30 @@ Second order solvers. -```@eval -first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqRKN", "Nystrom4") +To be able to access the solvers in `OrdinaryDiffEqRKN`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqRKN") +``` +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage +```julia +using OrdinaryDiffEqOrdinaryDiffEqRKN +function HH_acceleration!(dv, v, u, p, t) + x, y = u + dx, dy = dv + dv[1] = -x - 2x * y + dv[2] = y^2 - y - x^2 +end +initial_positions = [0.0, 0.1] +initial_velocities = [0.5, 0.0] +tspan = (0.0, 1.0) +prob = SecondOrderODEProblem(HH_acceleration!, initial_velocities, initial_positions, tspan) +sol = solve(prob, Nystrom4(), dt = 1 / 10) ``` ## Full list of solvers From 0c4e998302c770bf30c0d2861491b19182851dae Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 22:43:14 +0200 Subject: [PATCH 65/83] docs IMEXMultistep --- docs/make.jl | 55 +++++++++---------- docs/src/imex/IMEXMultistep.md | 10 ++++ docs/src/imex/imex_multistep.md | 6 -- docs/src/imex/imex_sdirk.md | 6 -- docs/src/implicit/BDF.md | 10 ++++ docs/src/misc.md | 1 - .../src/OrdinaryDiffEqIMEXMultistep.jl | 3 +- 7 files changed, 49 insertions(+), 42 deletions(-) create mode 100644 docs/src/imex/IMEXMultistep.md delete mode 100644 docs/src/imex/imex_multistep.md delete mode 100644 docs/src/imex/imex_sdirk.md diff --git a/docs/make.jl b/docs/make.jl index 30456158ff..f6c0be3544 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -8,32 +8,32 @@ makedocs(sitename = "OrdinaryDiffEq.jl", clean = true, doctest = false, modules = [OrdinaryDiffEq, - OrdinaryDiffEq.OrdinaryDiffEqExtrapolation, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedRK, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, - OrdinaryDiffEq.OrdinaryDiffEqLowStorageRK, - OrdinaryDiffEq.OrdinaryDiffEqSSPRK, - OrdinaryDiffEq.OrdinaryDiffEqFeagin, - OrdinaryDiffEq.OrdinaryDiffEqSymplecticRK, - OrdinaryDiffEq.OrdinaryDiffEqRKN, - OrdinaryDiffEq.OrdinaryDiffEqTsit5, - OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, - OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, - OrdinaryDiffEq.OrdinaryDiffEqVerner, - OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, - OrdinaryDiffEq.OrdinaryDiffEqNordsieck, - OrdinaryDiffEq.OrdinaryDiffEqPRK, - OrdinaryDiffEq.OrdinaryDiffEqRKN, - OrdinaryDiffEq.OrdinaryDiffEqSDIRK, - OrdinaryDiffEq.OrdinaryDiffEqBDF, - OrdinaryDiffEq.OrdinaryDiffEqDefault, - OrdinaryDiffEq.OrdinaryDiffEqFIRK, - OrdinaryDiffEq.OrdinaryDiffEqPDIRK, - OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, - OrdinaryDiffEq.OrdinaryDiffEqBDF, - OrdinaryDiffEq.OrdinaryDiffEqLinear, - OrdinaryDiffEq.OrdinaryDiffEqExponentialRK, + OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, + OrdinaryDiffEq.OrdinaryDiffEqBDF, + OrdinaryDiffEq.OrdinaryDiffEqDefault, + OrdinaryDiffEq.OrdinaryDiffEqExplicitRK, + OrdinaryDiffEq.OrdinaryDiffEqExponentialRK, + OrdinaryDiffEq.OrdinaryDiffEqExtrapolation, + OrdinaryDiffEq.OrdinaryDiffEqFeagin, + OrdinaryDiffEq.OrdinaryDiffEqFIRK, + OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, + OrdinaryDiffEq.OrdinaryDiffEqIMEXMultistep, + OrdinaryDiffEq.OrdinaryDiffEqLinear, + OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, + OrdinaryDiffEq.OrdinaryDiffEqLowStorageRK, + OrdinaryDiffEq.OrdinaryDiffEqNordsieck, + OrdinaryDiffEq.OrdinaryDiffEqPDIRK, + OrdinaryDiffEq.OrdinaryDiffEqPRK, + OrdinaryDiffEq.OrdinaryDiffEqQPRK, + OrdinaryDiffEq.OrdinaryDiffEqRKN, + OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, + OrdinaryDiffEq.OrdinaryDiffEqSDIRK, + OrdinaryDiffEq.OrdinaryDiffEqSSPRK, + OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, + OrdinaryDiffEq.OrdinaryDiffEqStabilizedRK, + OrdinaryDiffEq.OrdinaryDiffEqSymplecticRK, + OrdinaryDiffEq.OrdinaryDiffEqTsit5, + OrdinaryDiffEq.OrdinaryDiffEqVerner, ], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", @@ -68,8 +68,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "implicit/Extrapolation.md" ], "IMEX Solvers" => [ - "imex/imex_multistep.md", - "imex/imex_sdirk.md" + "imex/IMEXMultistep.md" ], "Semilinear ODE Solvers" => [ "semilinear/ExponentialRK.md", diff --git a/docs/src/imex/IMEXMultistep.md b/docs/src/imex/IMEXMultistep.md new file mode 100644 index 0000000000..6dbfb33398 --- /dev/null +++ b/docs/src/imex/IMEXMultistep.md @@ -0,0 +1,10 @@ +# IMEX Multistep Methods + +This article is a stub and likely needs a specialized example. + +## Full list of solvers + +```@docs +CNAB2 +CNLF2 +``` diff --git a/docs/src/imex/imex_multistep.md b/docs/src/imex/imex_multistep.md deleted file mode 100644 index d809534362..0000000000 --- a/docs/src/imex/imex_multistep.md +++ /dev/null @@ -1,6 +0,0 @@ -# IMEX Multistep Methods - -```@docs -CNAB2 -CNLF2 -``` diff --git a/docs/src/imex/imex_sdirk.md b/docs/src/imex/imex_sdirk.md deleted file mode 100644 index 24cfca1446..0000000000 --- a/docs/src/imex/imex_sdirk.md +++ /dev/null @@ -1,6 +0,0 @@ -# IMEX SDIRK Methods - -```@docs -IMEXEuler -IMEXEulerARK -``` diff --git a/docs/src/implicit/BDF.md b/docs/src/implicit/BDF.md index 20b1bf9c30..0e494c7c1f 100644 --- a/docs/src/implicit/BDF.md +++ b/docs/src/implicit/BDF.md @@ -20,14 +20,24 @@ QBDF2 MEBDF2 FBDF ``` + ### IMEX Multistep + ```@docs SBDF SBDF2 SBDF3 SBDF4 ``` +### IMEX SDIRK + +```@docs +IMEXEuler +IMEXEulerARK +``` + ### DAE + ```@docs DImplicitEuler DABDF2 diff --git a/docs/src/misc.md b/docs/src/misc.md index cff4221384..bbf99e06f7 100644 --- a/docs/src/misc.md +++ b/docs/src/misc.md @@ -1,5 +1,4 @@ ```@docs SplitEuler CompositeAlgorithm -PDIRK44 ``` diff --git a/lib/OrdinaryDiffEqIMEXMultistep/src/OrdinaryDiffEqIMEXMultistep.jl b/lib/OrdinaryDiffEqIMEXMultistep/src/OrdinaryDiffEqIMEXMultistep.jl index 020d094b37..567e6b5eae 100644 --- a/lib/OrdinaryDiffEqIMEXMultistep/src/OrdinaryDiffEqIMEXMultistep.jl +++ b/lib/OrdinaryDiffEqIMEXMultistep/src/OrdinaryDiffEqIMEXMultistep.jl @@ -4,7 +4,8 @@ import OrdinaryDiffEqCore: alg_order, issplit, OrdinaryDiffEqNewtonAlgorithm, _u DEFAULT_PRECS, OrdinaryDiffEqConstantCache, OrdinaryDiffEqMutableCache, @cache, alg_cache, initialize!, perform_step!, @unpack, - full_cache, get_fsalfirstlast + full_cache, get_fsalfirstlast, + generic_solver_docstring using FastBroadcast import OrdinaryDiffEqCore From 8eaa4ea04a881ca6371abccb26dffb11d8437972 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 22:43:28 +0200 Subject: [PATCH 66/83] more references --- .../src/algorithms.jl | 36 ++++-- .../src/algorithms.jl | 8 ++ lib/OrdinaryDiffEqLinear/src/algorithms.jl | 105 +++++++++++++++--- 3 files changed, 123 insertions(+), 26 deletions(-) diff --git a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl index cef401fba5..973285b58e 100644 --- a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl @@ -48,9 +48,15 @@ end const ETD1 = NorsettEuler # alias + +REF2 = """ +Hochbruck, M., & Ostermann, A. (2010). Exponential integrators. Acta Numerica, 19, 209-286. (https://doi.org/10.1017/S0962492910000048) +""" + + for (Alg, Description, Ref) in [ - (:Exprb32, "3rd order adaptive Exponential-Rosenbrock scheme.", "ref TBD"), - (:Exprb43, "4th order adaptive Exponential-Rosenbrock scheme.", "ref TBD")] + (:Exprb32, "3rd order adaptive Exponential-Rosenbrock scheme.", REF2), + (:Exprb43, "4th order adaptive Exponential-Rosenbrock scheme.", REF2)] @eval begin @doc generic_solver_docstring($Description, $(string(Alg)), "Semilinear ODE solver", @@ -79,14 +85,26 @@ for (Alg, Description, Ref) in [ iop) end end + +REF3 = """ +Hochbruck, M., Lubich, C., & Selhofer, H. (1998). Exponential integrators for large systems of differential equations. SIAM Journal on Scientific Computing, 19(5), 1552-1574. (https://doi.org/10.1137/S1064827595295337) +""" + +REF4 = """ +Rainwater, G., & Tokman, M. (2016). A new approach to constructing efficient stiffly accurate EPIRK methods. Journal of Computational Physics, 323, 283-309. (https://doi.org/10.1016/j.jcp.2016.07.026) +""" +REF5 = """ +Tokman, M., Loffeld, J., & Tranquilli, P. (2012). New Adaptive Exponential Propagation Iterative Methods of Runge--Kutta Type. SIAM Journal on Scientific Computing, 34(5), A2650-A2669. (https://doi.org/10.1137/110849961) +""" + for (Alg, Description, Ref) in [ - (:Exp4, "4th order EPIRK scheme.", "REF TBD") - (:EPIRK4s3A, "4th order EPIRK scheme with stiff order 4.", "REF TBD") - (:EPIRK4s3B, "4th order EPIRK scheme with stiff order 4.", "REF TBD") - (:EPIRK5s3, "5th order “horizontal” EPIRK scheme with stiff order 5. Broken.", "REF TBD") - (:EXPRB53s3, "5th order EPIRK scheme with stiff order 5.", "REF TBD") - (:EPIRK5P1, "5th order EPIRK scheme", "REF TBD") - (:EPIRK5P2, "5th order EPIRK scheme", "REF TBD") + (:Exp4, "4th order EPIRK scheme.", REF3) + (:EPIRK4s3A, "4th order EPIRK scheme with stiff order 4.", REF4) + (:EPIRK4s3B, "4th order EPIRK scheme with stiff order 4.", REF4) + (:EPIRK5s3, "5th order “horizontal” EPIRK scheme with stiff order 5. Broken.", REF4) + (:EXPRB53s3, "5th order EPIRK scheme with stiff order 5.", REF4) + (:EPIRK5P1, "5th order EPIRK scheme", REF5) + (:EPIRK5P2, "5th order EPIRK scheme", REF5) ] @eval begin @doc generic_solver_docstring($Description, diff --git a/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl b/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl index 2aca6a5bd6..8fdf516d34 100644 --- a/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl +++ b/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl @@ -1,5 +1,9 @@ # IMEX Multistep methods +@doc generic_solver_docstring("Description TBD", + "CNAB2", + "IMEX Multistep method.", + "REF TBD", "", "") struct CNAB2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -21,6 +25,10 @@ function CNAB2(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va extrapolant) end +@doc generic_solver_docstring("TBD", + "CNLF2", + "IMEX Multistep method.", + "REF TBD", "", "") struct CNLF2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 1f213c97ee..5b7a1d4ca0 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -1,30 +1,97 @@ # Linear Methods +REF1 = """ +@article{celledoni2014introduction, + title={An introduction to Lie group integrators--basics, new developments and applications}, + author={Celledoni, Elena and Marthinsen, H{\aa}kon and Owren, Brynjulf}, + journal={Journal of Computational Physics}, + volume={257}, + pages={1040--1061}, + year={2014}, + publisher={Elsevier} +} +""" +REF2 = """ +@article{crouch1993numerical, + title={Numerical integration of ordinary differential equations on manifolds}, + author={Crouch, Peter E and Grossman, R}, + journal={Journal of Nonlinear Science}, + volume={3}, + pages={1--33}, + year={1993}, + publisher={Springer} +} +""" +REF3 = """ +@article{blanes2000improved, + title={Improved high order integrators based on the Magnus expansion}, + author={Blanes, Sergio and Casas, Fernando and Ros, Javier}, + journal={BIT Numerical Mathematics}, + volume={40}, + number={3}, + pages={434--450}, + year={2000}, + publisher={Springer} +} +""" +REF4 = """ +@article{blanes2009magnus, + title={The Magnus expansion and some of its applications}, + author={Blanes, Sergio and Casas, Fernando and Oteo, Jose-Angel and Ros, Jos{\'e}}, + journal={Physics reports}, + volume={470}, + number={5-6}, + pages={151--238}, + year={2009}, + publisher={Elsevier} +} +""" +REF5 = """ +@article{hairer2011solving, + title={Solving differential equations on manifolds}, + author={Hairer, Ernst}, + journal={Lecture notes}, + year={2011} +} +""" +REF6 = """ +@article{jackiewicz2000construction, + title={Construction of Runge--Kutta methods of Crouch--Grossman type of high order}, + author={Jackiewicz, Zdzislaw and Marthinsen, Arne and Owren, Brynjulf}, + journal={Advances in Computational Mathematics}, + volume={13}, + pages={405--415}, + year={2000}, + publisher={Springer} +} +""" for (Alg, Description, Ref) in [ (:MagnusMidpoint, "Second order Magnus Midpoint method.", "ref TBD"), (:MagnusLeapfrog, "Second order Magnus Leapfrog method.", "ref TBD"), - (:LieEuler, "description", "ref TBD"), - (:MagnusGauss4, "Fourth order Magnus method approximated using a two stage Gauss quadrature.", "ref TBD"), - (:MagnusNC6, "Sixth order Magnus method approximated using Newton-Cotes quadrature.", "ref TBD"), - (:MagnusGL6, "Sixth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), - (:MagnusGL8, "Eighth order Magnus method approximated using Newton-Cotes quadrature.", "ref TBD"), - (:MagnusNC8, "Eighth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), - (:MagnusGL4, "Fourth order Magnus method approximated using Gauss-Legendre quadrature.", "ref TBD"), - (:RKMK2, "Second order Runge–Kutta–Munthe-Kaas method.", "ref TBD"), - (:RKMK4, "Fourth order Runge–Kutta–Munthe-Kaas method.", "ref TBD"), - (:LieRK4, "Fourth order Lie Runge-Kutta method.", "ref TBD"), - (:CG2, "Second order Crouch–Grossman method.", "ref TBD"), - (:CG3, "Third order Crouch-Grossman method.", "ref TBD"), - (:CG4a, " Fourth order Crouch-Grossman method.", "ref TBD")] + (:LieEuler, "description", REF1), + (:MagnusGauss4, "Fourth order Magnus method approximated using a two stage Gauss quadrature.", REF5), + (:MagnusNC6, "Sixth order Magnus method approximated using Newton-Cotes quadrature.", REF3), + (:MagnusGL6, "Sixth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), + (:MagnusGL8, "Eighth order Magnus method approximated using Newton-Cotes quadrature.", REF3), + (:MagnusNC8, "Eighth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), + (:MagnusGL4, "Fourth order Magnus method approximated using Gauss-Legendre quadrature.", REF4), + (:RKMK2, "Second order Runge–Kutta–Munthe-Kaas method.", REF1), + (:RKMK4, "Fourth order Runge–Kutta–Munthe-Kaas method.", REF1), + (:LieRK4, "Fourth order Lie Runge-Kutta method.", REF1), + (:CG2, "Second order Crouch–Grossman method.", REF1), + (:CG3, "Third order Crouch-Grossman method.", REF2), + (:CG4a, " Fourth order Crouch-Grossman method.", REF6)] @eval begin @doc generic_solver_docstring($Description, $(string(Alg)), "Semilinear ODE solver", $Ref, """ - - `krylov`: TBD - - `m`: TBD - - `iop`: TBD + - `krylov`: Determines whether Krylov approximation or operator caching is used, the latter only available for semilinear problems. + `krylov=true` is much faster for larger systems and is thus recommended whenever there are >100 ODEs. + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. """, """ krylov = false, @@ -55,7 +122,11 @@ struct CayleyEuler <: OrdinaryDiffEqAlgorithm end @doc generic_solver_docstring("Exact solution formula for linear, time-independent problems.", "LinearExponential", "Semilinear ODE solver", - "ref TBD", + "@book{strogatz2018nonlinear, + title={Nonlinear dynamics and chaos: with applications to physics, biology, chemistry, and engineering}, + author={Strogatz, Steven H}, + year={2018}, + publisher={CRC press}}", """ - `krylov`: - `:off`: cache the operator beforehand. Requires Matrix(A) method defined for the operator A. From 6d90f74deed42a6caa343c28c88479a6effe8eaa Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 22:52:10 +0200 Subject: [PATCH 67/83] docs QPRK --- docs/make.jl | 1 + docs/src/explicit/QPRK.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+) create mode 100644 docs/src/explicit/QPRK.md diff --git a/docs/make.jl b/docs/make.jl index f6c0be3544..04e64eb6e6 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -55,6 +55,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/RKN.md", "explicit/SymplecticRK.md", "explicit/PRK.md", + "explicit/QPRK.md", "explicit/Extrapolation.md", ], "Implicit Solvers" => [ diff --git a/docs/src/explicit/QPRK.md b/docs/src/explicit/QPRK.md new file mode 100644 index 0000000000..2a4af88cfe --- /dev/null +++ b/docs/src/explicit/QPRK.md @@ -0,0 +1,14 @@ +# OrdinaryDiffEqQPRK + +This article is a stub. + +```@eval +first_steps = evalfile("./common_first_steps.jl") +first_steps("OrdinaryDiffEqQPRK", "QPRK98") +``` + +## Full list of solvers + +```@docs +QPRK98 +``` From b6242f01a44887b71a97629c28cbf86dd71fd718 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Wed, 21 Aug 2024 23:02:37 +0200 Subject: [PATCH 68/83] format --- docs/make.jl | 56 ++--- docs/src/explicit/Extrapolation.md | 2 +- docs/src/explicit/Nordsieck.md | 1 - docs/src/explicit/RKN.md | 2 + docs/src/explicit/SymplecticRK.md | 5 +- docs/src/implicit/BDF.md | 3 +- docs/src/implicit/Extrapolation.md | 4 +- docs/src/implicit/FIRK.md | 2 +- docs/src/implicit/PDIRK.md | 6 +- docs/src/implicit/Rosenbrock.md | 2 +- docs/src/implicit/SDIRK.md | 4 +- docs/src/implicit/StabalizedIRK.md | 1 - docs/src/implicit/StabalizedRK.md | 1 - docs/src/semilinear/ExponentialRK.md | 2 +- docs/src/semilinear/Linear.md | 2 +- lib/OrdinaryDiffEqBDF/src/algorithms.jl | 47 ++-- lib/OrdinaryDiffEqCore/src/doc_utils.jl | 10 +- .../src/algorithms.jl | 163 ++++++------ .../src/algorithms.jl | 10 +- lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 15 +- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 28 ++- .../src/algorithms.jl | 237 +++++++++--------- lib/OrdinaryDiffEqNordsieck/src/algorithms.jl | 12 +- lib/OrdinaryDiffEqPDIRK/src/algorithms.jl | 3 +- lib/OrdinaryDiffEqRKN/src/algorithms.jl | 52 ++-- .../src/OrdinaryDiffEqRosenbrock.jl | 38 +-- lib/OrdinaryDiffEqSDIRK/src/algorithms.jl | 87 ++++--- lib/OrdinaryDiffEqSSPRK/src/algorithms.jl | 12 +- .../src/algorithms.jl | 23 +- .../src/algorithms.jl | 78 +++--- 30 files changed, 487 insertions(+), 421 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 04e64eb6e6..7ccbffccb4 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -8,33 +8,33 @@ makedocs(sitename = "OrdinaryDiffEq.jl", clean = true, doctest = false, modules = [OrdinaryDiffEq, - OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, - OrdinaryDiffEq.OrdinaryDiffEqBDF, - OrdinaryDiffEq.OrdinaryDiffEqDefault, - OrdinaryDiffEq.OrdinaryDiffEqExplicitRK, - OrdinaryDiffEq.OrdinaryDiffEqExponentialRK, - OrdinaryDiffEq.OrdinaryDiffEqExtrapolation, - OrdinaryDiffEq.OrdinaryDiffEqFeagin, - OrdinaryDiffEq.OrdinaryDiffEqFIRK, - OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, - OrdinaryDiffEq.OrdinaryDiffEqIMEXMultistep, - OrdinaryDiffEq.OrdinaryDiffEqLinear, - OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, - OrdinaryDiffEq.OrdinaryDiffEqLowStorageRK, - OrdinaryDiffEq.OrdinaryDiffEqNordsieck, - OrdinaryDiffEq.OrdinaryDiffEqPDIRK, - OrdinaryDiffEq.OrdinaryDiffEqPRK, - OrdinaryDiffEq.OrdinaryDiffEqQPRK, - OrdinaryDiffEq.OrdinaryDiffEqRKN, - OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, - OrdinaryDiffEq.OrdinaryDiffEqSDIRK, - OrdinaryDiffEq.OrdinaryDiffEqSSPRK, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, - OrdinaryDiffEq.OrdinaryDiffEqStabilizedRK, - OrdinaryDiffEq.OrdinaryDiffEqSymplecticRK, - OrdinaryDiffEq.OrdinaryDiffEqTsit5, - OrdinaryDiffEq.OrdinaryDiffEqVerner, - ], + OrdinaryDiffEq.OrdinaryDiffEqAdamsBashforthMoulton, + OrdinaryDiffEq.OrdinaryDiffEqBDF, + OrdinaryDiffEq.OrdinaryDiffEqDefault, + OrdinaryDiffEq.OrdinaryDiffEqExplicitRK, + OrdinaryDiffEq.OrdinaryDiffEqExponentialRK, + OrdinaryDiffEq.OrdinaryDiffEqExtrapolation, + OrdinaryDiffEq.OrdinaryDiffEqFeagin, + OrdinaryDiffEq.OrdinaryDiffEqFIRK, + OrdinaryDiffEq.OrdinaryDiffEqHighOrderRK, + OrdinaryDiffEq.OrdinaryDiffEqIMEXMultistep, + OrdinaryDiffEq.OrdinaryDiffEqLinear, + OrdinaryDiffEq.OrdinaryDiffEqLowOrderRK, + OrdinaryDiffEq.OrdinaryDiffEqLowStorageRK, + OrdinaryDiffEq.OrdinaryDiffEqNordsieck, + OrdinaryDiffEq.OrdinaryDiffEqPDIRK, + OrdinaryDiffEq.OrdinaryDiffEqPRK, + OrdinaryDiffEq.OrdinaryDiffEqQPRK, + OrdinaryDiffEq.OrdinaryDiffEqRKN, + OrdinaryDiffEq.OrdinaryDiffEqRosenbrock, + OrdinaryDiffEq.OrdinaryDiffEqSDIRK, + OrdinaryDiffEq.OrdinaryDiffEqSSPRK, + OrdinaryDiffEq.OrdinaryDiffEqStabilizedIRK, + OrdinaryDiffEq.OrdinaryDiffEqStabilizedRK, + OrdinaryDiffEq.OrdinaryDiffEqSymplecticRK, + OrdinaryDiffEq.OrdinaryDiffEqTsit5, + OrdinaryDiffEq.OrdinaryDiffEqVerner + ], warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], @@ -56,7 +56,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", "explicit/SymplecticRK.md", "explicit/PRK.md", "explicit/QPRK.md", - "explicit/Extrapolation.md", + "explicit/Extrapolation.md" ], "Implicit Solvers" => [ "implicit/SDIRK.md", diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index 9a86d024e3..da5af6308e 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -15,4 +15,4 @@ first_steps("OrdinaryDiffEqExtrapolation", "ExtrapolationMidpointDeuflhard") AitkenNeville ExtrapolationMidpointDeuflhard ExtrapolationMidpointHairerWanner -``` \ No newline at end of file +``` diff --git a/docs/src/explicit/Nordsieck.md b/docs/src/explicit/Nordsieck.md index 1008806852..042c12ab83 100644 --- a/docs/src/explicit/Nordsieck.md +++ b/docs/src/explicit/Nordsieck.md @@ -11,7 +11,6 @@ The Nordsieck implementations here are considered experimental implementations o and are generally considered inferior to the fixed-leading history-based BDF implementation of FBDF, and thus for all standard usage we recommend FBDF. However, this algorithm is kept for experimental research and development purposes with the possibility of one day becoming a more discontinuity-aware BDF implementation. - ```@eval first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqNordsieck", "AN5") diff --git a/docs/src/explicit/RKN.md b/docs/src/explicit/RKN.md index 8de647ab66..ea5bc9ed60 100644 --- a/docs/src/explicit/RKN.md +++ b/docs/src/explicit/RKN.md @@ -8,11 +8,13 @@ To be able to access the solvers in `OrdinaryDiffEqRKN`, you must first install using Pkg Pkg.add("OrdinaryDiffEqRKN") ``` + This will only install the solvers listed at the bottom of this page. If you want to explore other solvers for your problem, you will need to install some of the other libraries listed in the navigation bar on the left. ## Example usage + ```julia using OrdinaryDiffEqOrdinaryDiffEqRKN function HH_acceleration!(dv, v, u, p, t) diff --git a/docs/src/explicit/SymplecticRK.md b/docs/src/explicit/SymplecticRK.md index baf51afd47..f5556da346 100644 --- a/docs/src/explicit/SymplecticRK.md +++ b/docs/src/explicit/SymplecticRK.md @@ -5,20 +5,23 @@ Because of discretization error, when it is solving a Hamiltonian system it does Instead, that trajectory itself is perturbed `O(Δtn)` for the order n from the true trajectory. Then there's a linear drift due to numerical error of this trajectory over time Normal integrators tend to have a quadratic (or more) drift, and do not have any good global guarantees about this phase space path (just local). -What means is that symplectic integrators tend to capture the long-time patterns better than normal integrators because of this lack of drift and this almost guarantee of periodicity. +What means is that symplectic integrators tend to capture the long-time patterns better than normal integrators because of this lack of drift and this almost guarantee of periodicity. ## Installation + To be able to access the solvers in `OrdinaryDiffEqSymplecticRK`, you must first install them use the Julia package manager: ```julia using Pkg Pkg.add("OrdinaryDiffEqSymplecticRK") ``` + This will only install the solvers listed at the bottom of this page. If you want to explore other solvers for your problem, you will need to install some of the other libraries listed in the navigation bar on the left. ## Example usage + ```julia using OrdinaryDiffEqSymplecticRK function HH_acceleration!(dv, v, u, p, t) diff --git a/docs/src/implicit/BDF.md b/docs/src/implicit/BDF.md index 0e494c7c1f..7079b6156f 100644 --- a/docs/src/implicit/BDF.md +++ b/docs/src/implicit/BDF.md @@ -29,6 +29,7 @@ SBDF2 SBDF3 SBDF4 ``` + ### IMEX SDIRK ```@docs @@ -42,4 +43,4 @@ IMEXEulerARK DImplicitEuler DABDF2 DFBDF -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/Extrapolation.md b/docs/src/implicit/Extrapolation.md index 031ac91534..a909fd3b57 100644 --- a/docs/src/implicit/Extrapolation.md +++ b/docs/src/implicit/Extrapolation.md @@ -2,7 +2,7 @@ Solvers based on within method parallelism. These solvers perform well for medium sized systems of ordinary differential equations, of about 20 to 500 equations, -at low tolerances. +at low tolerances. ```@eval first_steps = evalfile("./common_first_steps.jl") @@ -16,4 +16,4 @@ ImplicitEulerExtrapolation ImplicitDeuflhardExtrapolation ImplicitHairerWannerExtrapolation ImplicitEulerBarycentricExtrapolation -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md index c27aafe27c..c8d8a2d7fb 100644 --- a/docs/src/implicit/FIRK.md +++ b/docs/src/implicit/FIRK.md @@ -33,4 +33,4 @@ first_steps("OrdinaryDiffEqFIRK", "RadauIIA5") RadauIIA3 RadauIIA5 RadauIIA9 -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/PDIRK.md b/docs/src/implicit/PDIRK.md index 65e3b24737..dba01b2405 100644 --- a/docs/src/implicit/PDIRK.md +++ b/docs/src/implicit/PDIRK.md @@ -9,15 +9,15 @@ There are some advantages to this, as no SDIRK method can be a higher order than 5, while DIRK methods generally can have arbitrarily high order and lower error coefficients, leading to lower errors at larger dt sizes. -With the right construction of the tableau, +With the right construction of the tableau, these matrices can be factorized and the underlying steps can be computed in parallel, which is why these are the parallel DIRK methods. !!! warning "Experimental" + `OrdinaryDiffEqPDIRK` is experimental, as there are no parallel DIRK tableaus that achieve good performance in the literature. - ```@eval first_steps = evalfile("./common_first_steps.jl") first_steps("OrdinaryDiffEqPDIRK", "PDIRK44") @@ -27,4 +27,4 @@ first_steps("OrdinaryDiffEqPDIRK", "PDIRK44") ```@docs PDIRK44 -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/Rosenbrock.md b/docs/src/implicit/Rosenbrock.md index 116dd934ec..7c5e8b6646 100644 --- a/docs/src/implicit/Rosenbrock.md +++ b/docs/src/implicit/Rosenbrock.md @@ -49,4 +49,4 @@ Velds4 GRK4T GRK4A Ros4LStab -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/SDIRK.md b/docs/src/implicit/SDIRK.md index 4e373d83d9..478b306f07 100644 --- a/docs/src/implicit/SDIRK.md +++ b/docs/src/implicit/SDIRK.md @@ -31,7 +31,9 @@ Hairer42 Kvaerno4 Kvaerno5 ``` + ### IMEX SDIRK + ```@docs KenCarp4 KenCarp47 @@ -42,4 +44,4 @@ ESDIRK436L2SA2 ESDIRK437L2SA ESDIRK547L2SA2 ESDIRK659L2SA -``` \ No newline at end of file +``` diff --git a/docs/src/implicit/StabalizedIRK.md b/docs/src/implicit/StabalizedIRK.md index 719c6308da..f1b1db489c 100644 --- a/docs/src/implicit/StabalizedIRK.md +++ b/docs/src/implicit/StabalizedIRK.md @@ -17,4 +17,3 @@ first_steps("OrdinaryDiffEqStabalizedIRK", "IRKC") ```@docs IRKC ``` - diff --git a/docs/src/implicit/StabalizedRK.md b/docs/src/implicit/StabalizedRK.md index 91e8daabb7..d1e62c1137 100644 --- a/docs/src/implicit/StabalizedRK.md +++ b/docs/src/implicit/StabalizedRK.md @@ -22,4 +22,3 @@ SERK2 ESERK4 ESERK5 ``` - diff --git a/docs/src/semilinear/ExponentialRK.md b/docs/src/semilinear/ExponentialRK.md index 30acf79764..8d1cc523ae 100644 --- a/docs/src/semilinear/ExponentialRK.md +++ b/docs/src/semilinear/ExponentialRK.md @@ -36,4 +36,4 @@ EPIRK5s3 EXPRB53s3 EPIRK5P1 EPIRK5P2 -``` \ No newline at end of file +``` diff --git a/docs/src/semilinear/Linear.md b/docs/src/semilinear/Linear.md index b9fbd87954..8ecc791343 100644 --- a/docs/src/semilinear/Linear.md +++ b/docs/src/semilinear/Linear.md @@ -45,4 +45,4 @@ CayleyEuler ```@docs CG3 -``` \ No newline at end of file +``` diff --git a/lib/OrdinaryDiffEqBDF/src/algorithms.jl b/lib/OrdinaryDiffEqBDF/src/algorithms.jl index ca15fc2a49..1cb80c7a20 100644 --- a/lib/OrdinaryDiffEqBDF/src/algorithms.jl +++ b/lib/OrdinaryDiffEqBDF/src/algorithms.jl @@ -1,8 +1,8 @@ function BDF_docstring(description::String, - name::String; - references::String = "", - extra_keyword_description::String = "", - extra_keyword_default::String = "") + name::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") keyword_default = """ chunk_size = Val{0}(), autodiff = true, @@ -30,8 +30,8 @@ function BDF_docstring(description::String, ) end - -@doc BDF_docstring("An adaptive order 2 L-stable fixed leading coefficient multistep BDF method.", +@doc BDF_docstring( + "An adaptive order 2 L-stable fixed leading coefficient multistep BDF method.", "ABDF2", references = """ E. Alberdi Celayaa, J. J. Anza Aguirrezabalab, P. Chatzipantelidisc. Implementation of @@ -81,11 +81,11 @@ function ABDF2(; chunk_size = Val{0}(), autodiff = true, standardtag = Val{true} smooth_est, extrapolant, controller, step_limiter!) end - -@doc BDF_docstring("Implicit-explicit (IMEX) method designed for SplitODEFunction equations, - which reduce the size of the implicit handling to a subset of the equations. - It's similar to the additive Runge-Kutta methods in splitting mode, - like `KenCarp4`, but instead using a multistep BDF approach", +@doc BDF_docstring( + "Implicit-explicit (IMEX) method designed for SplitODEFunction equations, +which reduce the size of the implicit handling to a subset of the equations. +It's similar to the additive Runge-Kutta methods in splitting mode, +like `KenCarp4`, but instead using a multistep BDF approach", "SBDF", references = """@article{ascher1995implicit, title={Implicit-explicit methods for time-dependent partial differential equations}, @@ -205,8 +205,9 @@ See also `SBDF`. """ SBDF4(; kwargs...) = SBDF(4; kwargs...) -@doc BDF_docstring("An adaptive order 1 quasi-constant timestep L-stable numerical differentiation function (NDF) method. - Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850.", +@doc BDF_docstring( + "An adaptive order 1 quasi-constant timestep L-stable numerical differentiation function (NDF) method. +Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850.", "QNDF1", references = """@article{shampine1997matlab, title={The matlab ode suite}, @@ -260,7 +261,8 @@ function QNDF1(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va step_limiter!) end -@doc BDF_docstring("An adaptive order 2 quasi-constant timestep L-stable numerical differentiation function (NDF) method.", +@doc BDF_docstring( + "An adaptive order 2 quasi-constant timestep L-stable numerical differentiation function (NDF) method.", "QNDF2", references = """@article{shampine1997matlab, title={The matlab ode suite}, @@ -314,8 +316,9 @@ function QNDF2(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va step_limiter!) end -@doc BDF_docstring("An adaptive order quasi-constant timestep NDF method. - Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", +@doc BDF_docstring( + "An adaptive order quasi-constant timestep NDF method. +Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", "QNDF", references = """@article{shampine1997matlab, title={The matlab ode suite}, @@ -417,9 +420,10 @@ function MEBDF2(; chunk_size = Val{0}(), autodiff = true, standardtag = Val{true extrapolant) end -@doc BDF_docstring("An adaptive order quasi-constant timestep NDF method. - Fixed leading coefficient BDF. - Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", +@doc BDF_docstring( + "An adaptive order quasi-constant timestep NDF method. +Fixed leading coefficient BDF. +Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword argument for a tuple of kappa coefficients).", "FBDF", references = """@article{shampine2002solving, title={Solving 0= F (t, y (t), y′(t)) in Matlab}, @@ -551,8 +555,9 @@ See also `SBDF`, `IMEXEuler`. """ IMEXEulerARK(; kwargs...) = SBDF(1; ark = true, kwargs...) -@doc BDF_docstring("Implicit Euler for implicit DAE form. - It uses an apriori error estimator for adaptivity based on a finite differencing approximation from SPICE.", +@doc BDF_docstring( + "Implicit Euler for implicit DAE form. +It uses an apriori error estimator for adaptivity based on a finite differencing approximation from SPICE.", "DImplicitEuler", extra_keyword_description = """ - `nlsolve`: TBD diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index c323a91d71..71aabd288b 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -75,11 +75,11 @@ function explicit_rk_docstring(description::String, ) end function differentiation_rk_docstring(description::String, - name::String, - solver_class::String; - references::String = "", - extra_keyword_description::String = "", - extra_keyword_default::String = "") + name::String, + solver_class::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") keyword_default = """ chunk_size = Val{0}(), autodiff = true, diff --git a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl index 973285b58e..6f83541846 100644 --- a/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExponentialRK/src/algorithms.jl @@ -3,38 +3,37 @@ Hochbruck, Marlis, and Alexander Ostermann. “Exponential Integrators.” Acta Numerica 19 (2010): 209–286. doi:10.1017/S0962492910000048. """ for (Alg, Description, Ref) in [ - (:LawsonEuler, "First order exponential Euler scheme.", REF1), - (:NorsettEuler, "First order exponential-RK scheme. Alias: `ETD1`", REF1), - (:ETDRK2, "2nd order exponential-RK scheme.", REF1), - (:ETDRK3, "3rd order exponential-RK scheme.", REF1), - (:ETDRK4, "4th order exponential-RK scheme", REF1), - (:HochOst4, "4th order exponential-RK scheme with stiff order 4.", REF1), - ] - + (:LawsonEuler, "First order exponential Euler scheme.", REF1), + (:NorsettEuler, "First order exponential-RK scheme. Alias: `ETD1`", REF1), + (:ETDRK2, "2nd order exponential-RK scheme.", REF1), + (:ETDRK3, "3rd order exponential-RK scheme.", REF1), + (:ETDRK4, "4th order exponential-RK scheme", REF1), + (:HochOst4, "4th order exponential-RK scheme with stiff order 4.", REF1) +] @eval begin - @doc generic_solver_docstring($Description, - $(string(Alg)), - "Semilinear ODE solver", - $Ref, - """ - - `krylov`: Determines whether Krylov approximation or operator caching is used, the latter only available for semilinear problems. - `krylov=true` is much faster for larger systems and is thus recommended whenever there are >100 ODEs. - - `m`: Controls the size of Krylov subspace. - - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). - Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. - """, - """ - krylov = false, - m = 30, - iop = 0, - """) - struct $Alg{CS, AD, FDT, ST, CJ} <: - OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} - krylov::Bool - m::Int - iop::Int - end + @doc generic_solver_docstring($Description, + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `krylov`: Determines whether Krylov approximation or operator caching is used, the latter only available for semilinear problems. + `krylov=true` is much faster for larger systems and is thus recommended whenever there are >100 ODEs. + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + krylov = false, + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: + OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} + krylov::Bool + m::Int + iop::Int end + end @eval function $Alg(; krylov = false, m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, chunk_size = Val{0}(), @@ -48,33 +47,32 @@ end const ETD1 = NorsettEuler # alias - REF2 = """ Hochbruck, M., & Ostermann, A. (2010). Exponential integrators. Acta Numerica, 19, 209-286. (https://doi.org/10.1017/S0962492910000048) """ - for (Alg, Description, Ref) in [ - (:Exprb32, "3rd order adaptive Exponential-Rosenbrock scheme.", REF2), - (:Exprb43, "4th order adaptive Exponential-Rosenbrock scheme.", REF2)] - @eval begin @doc generic_solver_docstring($Description, - $(string(Alg)), - "Semilinear ODE solver", - $Ref, - """ - - `m`: Controls the size of Krylov subspace. - - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). - Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. - """, - """ - m = 30, - iop = 0, - """) - struct $Alg{CS, AD, FDT, ST, CJ} <: - OrdinaryDiffEqAdaptiveExponentialAlgorithm{CS, AD, FDT, ST, CJ} - m::Int - iop::Int - end + (:Exprb32, "3rd order adaptive Exponential-Rosenbrock scheme.", REF2), + (:Exprb43, "4th order adaptive Exponential-Rosenbrock scheme.", REF2)] + @eval begin + @doc generic_solver_docstring($Description, + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: + OrdinaryDiffEqAdaptiveExponentialAlgorithm{CS, AD, FDT, ST, CJ} + m::Int + iop::Int + end end @eval function $Alg(; m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, chunk_size = Val{0}(), @@ -97,37 +95,40 @@ REF5 = """ Tokman, M., Loffeld, J., & Tranquilli, P. (2012). New Adaptive Exponential Propagation Iterative Methods of Runge--Kutta Type. SIAM Journal on Scientific Computing, 34(5), A2650-A2669. (https://doi.org/10.1137/110849961) """ -for (Alg, Description, Ref) in [ - (:Exp4, "4th order EPIRK scheme.", REF3) - (:EPIRK4s3A, "4th order EPIRK scheme with stiff order 4.", REF4) - (:EPIRK4s3B, "4th order EPIRK scheme with stiff order 4.", REF4) - (:EPIRK5s3, "5th order “horizontal” EPIRK scheme with stiff order 5. Broken.", REF4) - (:EXPRB53s3, "5th order EPIRK scheme with stiff order 5.", REF4) - (:EPIRK5P1, "5th order EPIRK scheme", REF5) - (:EPIRK5P2, "5th order EPIRK scheme", REF5) - ] +for (Alg, Description, Ref) in [(:Exp4, "4th order EPIRK scheme.", REF3) + (:EPIRK4s3A, + "4th order EPIRK scheme with stiff order 4.", REF4) + (:EPIRK4s3B, + "4th order EPIRK scheme with stiff order 4.", REF4) + (:EPIRK5s3, + "5th order “horizontal” EPIRK scheme with stiff order 5. Broken.", + REF4) + (:EXPRB53s3, + "5th order EPIRK scheme with stiff order 5.", REF4) + (:EPIRK5P1, "5th order EPIRK scheme", REF5) + (:EPIRK5P2, "5th order EPIRK scheme", REF5)] @eval begin @doc generic_solver_docstring($Description, - $(string(Alg)), - "Semilinear ODE solver", - $Ref, - """ - - `adaptive_krylov`: Determines if the adaptive Krylov algorithm with timestepping of Neisen & Wright is used. - - `m`: Controls the size of Krylov subspace. - - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). - Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. - """, - """ - adaptive_krylov = true, - m = 30, - iop = 0, - """) - struct $Alg{CS, AD, FDT, ST, CJ} <: - OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} - adaptive_krylov::Bool - m::Int - iop::Int - end + $(string(Alg)), + "Semilinear ODE solver", + $Ref, + """ + - `adaptive_krylov`: Determines if the adaptive Krylov algorithm with timestepping of Neisen & Wright is used. + - `m`: Controls the size of Krylov subspace. + - `iop`: If not zero, determines the length of the incomplete orthogonalization procedure (IOP). + Note that if the linear operator/Jacobian is hermitian, then the Lanczos algorithm will always be used and the IOP setting is ignored. + """, + """ + adaptive_krylov = true, + m = 30, + iop = 0, + """) + struct $Alg{CS, AD, FDT, ST, CJ} <: + OrdinaryDiffEqExponentialAlgorithm{CS, AD, FDT, ST, CJ} + adaptive_krylov::Bool + m::Int + iop::Int + end end @eval function $Alg(; adaptive_krylov = true, m = 30, iop = 0, autodiff = true, standardtag = Val{true}(), concrete_jac = nothing, diff --git a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl index cf3b25a816..e96b6457a9 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl @@ -10,10 +10,11 @@ reference = """@inproceedings{elrod2022parallelizing, year={2022}, organization={IEEE}} """ -@doc generic_solver_docstring("Euler extrapolation using Aitken-Neville with the Romberg Sequence.", +@doc generic_solver_docstring( + "Euler extrapolation using Aitken-Neville with the Romberg Sequence.", "AitkenNeville", "Parallelized Explicit Extrapolation Method.", - reference , + reference, """ - `max_order`: TBD - `min_order`: TBD @@ -33,8 +34,9 @@ Base.@kwdef struct AitkenNeville{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarSt threading::TO = false end -@doc differentiation_rk_docstring("Extrapolation of implicit Euler method with Romberg sequence. - Similar to Hairer's SEULEX.", +@doc differentiation_rk_docstring( + "Extrapolation of implicit Euler method with Romberg sequence. +Similar to Hairer's SEULEX.", "ImplicitEulerExtrapolation", "Parallelized Explicit Extrapolation Method.", references = reference, diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index a7195de431..3f88dbd907 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -28,8 +28,9 @@ extra_keyword_default = """ smooth_est = true, step_limiter! = trivial_limiter!""" -@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. - Similar to Hairer's SEULEX.", +@doc differentiation_rk_docstring( + "An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +Similar to Hairer's SEULEX.", "RadauIIA3", "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, @@ -70,8 +71,9 @@ function RadauIIA3(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. - Similar to Hairer's SEULEX.", +@doc differentiation_rk_docstring( + "An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +Similar to Hairer's SEULEX.", "RadauIIA5", "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, @@ -114,8 +116,9 @@ function RadauIIA5(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end -@doc differentiation_rk_docstring("An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. - Similar to Hairer's SEULEX.", +@doc differentiation_rk_docstring( + "An A-B-L stable fully implicit Runge-Kutta method with internal tableau complex basis transform for efficiency. +Similar to Hairer's SEULEX.", "RadauIIA9", "Fully-Implicit Runge-Kutta Method."; references = hairer1999stiff, diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 5b7a1d4ca0..940151cd72 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -69,12 +69,19 @@ for (Alg, Description, Ref) in [ (:MagnusMidpoint, "Second order Magnus Midpoint method.", "ref TBD"), (:MagnusLeapfrog, "Second order Magnus Leapfrog method.", "ref TBD"), (:LieEuler, "description", REF1), - (:MagnusGauss4, "Fourth order Magnus method approximated using a two stage Gauss quadrature.", REF5), - (:MagnusNC6, "Sixth order Magnus method approximated using Newton-Cotes quadrature.", REF3), - (:MagnusGL6, "Sixth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), - (:MagnusGL8, "Eighth order Magnus method approximated using Newton-Cotes quadrature.", REF3), - (:MagnusNC8, "Eighth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), - (:MagnusGL4, "Fourth order Magnus method approximated using Gauss-Legendre quadrature.", REF4), + (:MagnusGauss4, + "Fourth order Magnus method approximated using a two stage Gauss quadrature.", + REF5), + (:MagnusNC6, + "Sixth order Magnus method approximated using Newton-Cotes quadrature.", REF3), + (:MagnusGL6, + "Sixth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), + (:MagnusGL8, + "Eighth order Magnus method approximated using Newton-Cotes quadrature.", REF3), + (:MagnusNC8, + "Eighth order Magnus method approximated using Gauss-Legendre quadrature.", REF3), + (:MagnusGL4, + "Fourth order Magnus method approximated using Gauss-Legendre quadrature.", REF4), (:RKMK2, "Second order Runge–Kutta–Munthe-Kaas method.", REF1), (:RKMK4, "Fourth order Runge–Kutta–Munthe-Kaas method.", REF1), (:LieRK4, "Fourth order Lie Runge-Kutta method.", REF1), @@ -99,9 +106,9 @@ for (Alg, Description, Ref) in [ iop = 0, """) struct $Alg <: OrdinaryDiffEqLinearExponentialAlgorithm - krylov::Bool - m::Int - iop::Int + krylov::Bool + m::Int + iop::Int end end @eval $Alg(; krylov = false, m = 30, iop = 0) = $Alg(krylov, m, iop) @@ -119,7 +126,8 @@ struct MagnusAdapt4 <: OrdinaryDiffEqAdaptiveAlgorithm end "ref TBD", "", "") struct CayleyEuler <: OrdinaryDiffEqAlgorithm end -@doc generic_solver_docstring("Exact solution formula for linear, time-independent problems.", +@doc generic_solver_docstring( + "Exact solution formula for linear, time-independent problems.", "LinearExponential", "Semilinear ODE solver", "@book{strogatz2018nonlinear, diff --git a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl index fe3822254f..e86126fd32 100644 --- a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl @@ -469,15 +469,15 @@ end "Low-Storage Method 4-stage, third order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK43_2", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK43_2{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -495,15 +495,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3C", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3C{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -521,15 +521,15 @@ end "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK95_4S", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4S{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -547,15 +547,15 @@ end "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK95_4C", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4C{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -573,15 +573,15 @@ end "Low-Storage Method 9-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK95_4M", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK95_4M{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -599,15 +599,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3C_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3C_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -625,15 +625,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3M_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3M_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -651,15 +651,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3N_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3N_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -677,15 +677,15 @@ end "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK85_4C_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4C_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -703,15 +703,15 @@ end "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK85_4M_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4M_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -729,15 +729,15 @@ end "Low-Storage Method 8-stage, fifth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK85_4P_3R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK85_4P_3R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -755,15 +755,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3N_4R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3N_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -781,15 +781,15 @@ end "Low-Storage Method 5-stage, fourth order low-storage scheme, optimized for compressible Navier–Stokes equations. ", "CKLLSRK54_3M_4R", -references = """@article{kennedy2000low, - title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, - author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, - journal={Applied numerical mathematics}, - volume={35}, - number={3}, - pages={177--219}, - year={2000}, - publisher={Elsevier}}""") + references = """@article{kennedy2000low, + title={Low-storage, explicit Runge--Kutta schemes for the compressible Navier--Stokes equations}, + author={Kennedy, Christopher A and Carpenter, Mark H and Lewis, R Michael}, + journal={Applied numerical mathematics}, + volume={35}, + number={3}, + pages={177--219}, + year={2000}, + publisher={Elsevier}}""") Base.@kwdef struct CKLLSRK54_3M_4R{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAdaptiveAlgorithm stage_limiter!::StageLimiter = trivial_limiter! @@ -1060,7 +1060,8 @@ end #SSP Optimized Runge-Kutta Methods -@doc explicit_rk_docstring("Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", +@doc explicit_rk_docstring( + "Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", "KYK2014DGSSPRK_3S2", references = """@article{kubatko2014optimal, title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, diff --git a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl index fe4b0bbc51..c8e49d97a7 100644 --- a/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl +++ b/lib/OrdinaryDiffEqNordsieck/src/algorithms.jl @@ -1,8 +1,9 @@ # Adams/BDF methods in Nordsieck forms -@doc generic_solver_docstring("""An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form. - !!! warning "Experimental" - `AN5` is experimental, the solver `VCABM` is generally preferred. - """, +@doc generic_solver_docstring( + """An adaptive 5th order fixed-leading coefficient Adams method in Nordsieck form. +!!! warning "Experimental" + `AN5` is experimental, the solver `VCABM` is generally preferred. +""", "AN5", "Adaptive step size Adams explicit Method", "", @@ -11,6 +12,7 @@ struct AN5 <: OrdinaryDiffEqAdaptiveAlgorithm end """ !!! warning "Experimental" + `JVODE` is experimental, the solver `VCABM` is generally preferred. """ struct JVODE{bType, aType} <: OrdinaryDiffEqAdamsVarOrderVarStepAlgorithm @@ -27,11 +29,13 @@ function JVODE(algorithm = :Adams; bias1 = 6, bias2 = 6, bias3 = 10, end """ !!! warning "Experimental" + `JVODE` is experimental, the solver `VCABM` is generally preferred. """ JVODE_Adams(; kwargs...) = JVODE(:Adams; kwargs...) """ !!! warning "Experimental" + `JVODE` is experimental, the solver `FBDF` is generally preferred. """ JVODE_BDF(; kwargs...) = JVODE(:BDF; kwargs...) diff --git a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl index 8dc282a034..5725d73247 100644 --- a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl @@ -1,4 +1,5 @@ -@doc differentiation_rk_docstring("A 2 processor 4th order diagonally non-adaptive implicit method.", +@doc differentiation_rk_docstring( + "A 2 processor 4th order diagonally non-adaptive implicit method.", "PDIRK44", "Parallel Diagonally Implicit Runge-Kutta Method."; references = """"@article{iserles1990theory, diff --git a/lib/OrdinaryDiffEqRKN/src/algorithms.jl b/lib/OrdinaryDiffEqRKN/src/algorithms.jl index f072820973..3c8bb658af 100644 --- a/lib/OrdinaryDiffEqRKN/src/algorithms.jl +++ b/lib/OrdinaryDiffEqRKN/src/algorithms.jl @@ -1,5 +1,6 @@ -@doc generic_solver_docstring("Method of order three, which minimizes the amount of evaluated functions in each step. Fixed time steps only. - Second order ODE should not depend on the first derivative.", +@doc generic_solver_docstring( + "Method of order three, which minimizes the amount of evaluated functions in each step. Fixed time steps only. +Second order ODE should not depend on the first derivative.", "IRKN3", "Improved Runge-Kutta-Nyström method", "@article{rabiei2012numerical, @@ -8,10 +9,11 @@ publisher={Citeseer}}", "", "") struct IRKN3 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("A 4th order explicit method which can be applied directly on second order ODEs. - Can only be used with fixed time steps. - In case the ODE Problem is not dependent on the first derivative consider using - [`Nystrom4VelocityIndependent`](@ref) to increase performance.", +@doc generic_solver_docstring( + "A 4th order explicit method which can be applied directly on second order ODEs. +Can only be used with fixed time steps. +In case the ODE Problem is not dependent on the first derivative consider using +[`Nystrom4VelocityIndependent`](@ref) to increase performance.", "Nystrom4", "Improved Runge-Kutta-Nyström method", "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. @@ -19,8 +21,9 @@ struct IRKN3 <: OrdinaryDiffEqPartitionedAlgorithm end Springer-Verlag.", "", "") struct Nystrom4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("A 4th order explicit method which can be applied directly to second order ODEs. - In particular, this method allows the acceleration equation to depend on the velocity.", +@doc generic_solver_docstring( + "A 4th order explicit method which can be applied directly to second order ODEs. +In particular, this method allows the acceleration equation to depend on the velocity.", "FineRKN4", "Improved Runge-Kutta-Nyström method", "@article{fine1987low, @@ -34,8 +37,9 @@ struct Nystrom4 <: OrdinaryDiffEqPartitionedAlgorithm end publisher={Springer}}", "", "") struct FineRKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -@doc generic_solver_docstring("A 5th order explicit method which can be applied directly to second order ODEs. - In particular, this method allows the acceleration equation to depend on the velocity.", +@doc generic_solver_docstring( + "A 5th order explicit method which can be applied directly to second order ODEs. +In particular, this method allows the acceleration equation to depend on the velocity.", "FineRKN5", "Improved Runge-Kutta-Nyström method", "@article{fine1987low, @@ -49,9 +53,10 @@ struct FineRKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end publisher={Springer}}", "", "") struct FineRKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -@doc generic_solver_docstring("A 4th order explicit method. - Used directly on second order ODEs, where the acceleration is independent from velocity - (ODE Problem is not dependent on the first derivative).", +@doc generic_solver_docstring( + "A 4th order explicit method. +Used directly on second order ODEs, where the acceleration is independent from velocity +(ODE Problem is not dependent on the first derivative).", "Nystrom4VelocityIndependent", "Improved Runge-Kutta-Nyström method", "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. @@ -72,9 +77,10 @@ struct Nystrom4VelocityIndependent <: OrdinaryDiffEqPartitionedAlgorithm end publisher={Citeseer}}", "", "") struct IRKN4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("A 5th order explicit method. - Used directly on second order ODEs, where the acceleration is independent from velocity - (ODE Problem is not dependent on the first derivative).", +@doc generic_solver_docstring( + "A 5th order explicit method. +Used directly on second order ODEs, where the acceleration is independent from velocity +(ODE Problem is not dependent on the first derivative).", "Nystrom5VelocityIndependent", "Improved Runge-Kutta-Nyström method", "E. Hairer, S.P. Norsett, G. Wanner, (1993) Solving Ordinary Differential Equations I. @@ -109,8 +115,9 @@ struct DPRKN4 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end publisher={Springer}}", "", "") struct DPRKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -@doc generic_solver_docstring("6th order explicit method. - The second order ODE should not depend on the first derivative. Free 6th order interpolant", +@doc generic_solver_docstring( + "6th order explicit method. +The second order ODE should not depend on the first derivative. Free 6th order interpolant", "DPRKN6", "Improved Runge-Kutta-Nyström method", "@article{Dormand1987FamiliesOR, @@ -218,11 +225,12 @@ struct ERKN5 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end pages={113753}}", "", "") struct ERKN7 <: OrdinaryDiffEqAdaptivePartitionedAlgorithm end -@doc generic_solver_docstring("3 stage fourth order method to solve second order linear inhomogeneous IVPs. - Does not include an adaptive method. Solves for for d-dimensional differential systems of second order linear inhomogeneous equations. +@doc generic_solver_docstring( + "3 stage fourth order method to solve second order linear inhomogeneous IVPs. +Does not include an adaptive method. Solves for for d-dimensional differential systems of second order linear inhomogeneous equations. - !!! warning - This method is only fourth order for these systems, the method is second order otherwise!", +!!! warning +This method is only fourth order for these systems, the method is second order otherwise!", "RKN4", "Improved Runge-Kutta-Nyström method", "@article{MONTIJANO2024115533, diff --git a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl index 5228b77e1a..3ea885ffdf 100644 --- a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl +++ b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl @@ -84,25 +84,25 @@ function rosenbrock_docstring(description::String, extra_keyword_description = "", extra_keyword_default = "", with_step_limiter = false) - keyword_default = """ - chunk_size = Val{0}(), - standardtag = Val{true}(), - autodiff = Val{true}(), - concrete_jac = nothing, - diff_type = Val{:central}, - linsolve = nothing, - precs = DEFAULT_PRECS, - """ * extra_keyword_default - - keyword_default_description = """ - - `chunk_size`: TBD - - `standardtag`: TBD - - `autodiff`: boolean to control if the Jacobian should be computed via AD or not - - `concrete_jac`: function of the form `jac!(J, u, p, t)` - - `diff_type`: TBD - - `linsolve`: custom solver for the inner linear systems - - `precs`: custom preconditioner for the inner linear solver - """ * extra_keyword_description + keyword_default = """ + chunk_size = Val{0}(), + standardtag = Val{true}(), + autodiff = Val{true}(), + concrete_jac = nothing, + diff_type = Val{:central}, + linsolve = nothing, + precs = DEFAULT_PRECS, + """ * extra_keyword_default + + keyword_default_description = """ + - `chunk_size`: TBD + - `standardtag`: TBD + - `autodiff`: boolean to control if the Jacobian should be computed via AD or not + - `concrete_jac`: function of the form `jac!(J, u, p, t)` + - `diff_type`: TBD + - `linsolve`: custom solver for the inner linear systems + - `precs`: custom preconditioner for the inner linear solver + """ * extra_keyword_description if with_step_limiter keyword_default *= "step_limiter! = OrdinaryDiffEq.trivial_limiter!,\n" diff --git a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl index 4f037f089f..232dd2cd3d 100644 --- a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl @@ -1,8 +1,8 @@ function SDIRK_docstring(description::String, - name::String; - references::String = "", - extra_keyword_description::String = "", - extra_keyword_default::String = "") + name::String; + references::String = "", + extra_keyword_description::String = "", + extra_keyword_default::String = "") keyword_default = """ chunk_size = Val{0}(), autodiff = true, @@ -113,12 +113,12 @@ function ImplicitMidpoint(; chunk_size = Val{0}(), autodiff = Val{true}(), step_limiter!) end - -@doc SDIRK_docstring("""Second order A-stable symmetric ESDIRK method. - "Almost symplectic" without numerical dampening. - Also known as Crank-Nicolson when applied to PDEs. Adaptive timestepping via divided - differences approximation to the second derivative terms in the local truncation error - estimate (the SPICE approximation strategy).""", +@doc SDIRK_docstring( + """Second order A-stable symmetric ESDIRK method. +"Almost symplectic" without numerical dampening. +Also known as Crank-Nicolson when applied to PDEs. Adaptive timestepping via divided +differences approximation to the second derivative terms in the local truncation error +estimate (the SPICE approximation strategy).""", "Trapezoid"; references = "Andre Vladimirescu. 1994. The Spice Book. John Wiley & Sons, Inc., New York, NY, USA.", extra_keyword_description = """ @@ -297,11 +297,12 @@ function SDIRK22(; step_limiter!) end -@doc SDIRK_docstring("""SSPSDIRK is an SSP-optimized SDIRK method, - so it's an implicit SDIRK method for handling stiffness but if the `dt` is below the SSP `coefficient * dt`, - then the SSP property of the SSP integrators (the other page) is satisified. - As such this is a method which is expected to be good on advection-dominated cases where an explicit SSP integrator would be used, - but where reaction equations are sufficient stiff to justify implicit integration.""", +@doc SDIRK_docstring( + """SSPSDIRK is an SSP-optimized SDIRK method, +so it's an implicit SDIRK method for handling stiffness but if the `dt` is below the SSP `coefficient * dt`, +then the SSP property of the SSP integrators (the other page) is satisified. +As such this is a method which is expected to be good on advection-dominated cases where an explicit SSP integrator would be used, +but where reaction equations are sufficient stiff to justify implicit integration.""", "SSPSDIRK2"; references = "@article{ketcheson2009optimal, title={Optimal implicit strong stability preserving Runge--Kutta methods}, @@ -344,7 +345,6 @@ function SSPSDIRK2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end - @doc SDIRK_docstring("An A-L stable stiffly-accurate 3rd order ESDIRK method.", "Kvaerno3"; references = "@article{kvaerno2004singly, @@ -390,7 +390,8 @@ function Kvaerno3(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -@doc SDIRK_docstring("An A-L stable stiffly-accurate 3rd order ESDIRK method with splitting.", +@doc SDIRK_docstring( + "An A-L stable stiffly-accurate 3rd order ESDIRK method with splitting.", "KenCarp3"; references = "@book{kennedy2001additive, title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, @@ -631,7 +632,6 @@ function SFSDIRK6(; chunk_size = Val{0}(), autodiff = Val{true}(), extrapolant) end - @doc SDIRK_docstring("Method of order 7.", "SFSDIRK7"; references = "@article{ferracina2008strong, @@ -870,7 +870,8 @@ function Kvaerno5(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -@doc SDIRK_docstring("An A-L stable stiffly-accurate 4th order ESDIRK method with splitting.", +@doc SDIRK_docstring( + "An A-L stable stiffly-accurate 4th order ESDIRK method with splitting.", "KenCarp4"; references = "@book{kennedy2001additive, title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, @@ -913,7 +914,8 @@ end TruncatedStacktraces.@truncate_stacktrace KenCarp4 -@doc SDIRK_docstring("An A-L stable stiffly-accurate 4th order seven-stage ESDIRK method with splitting.", +@doc SDIRK_docstring( + "An A-L stable stiffly-accurate 4th order seven-stage ESDIRK method with splitting.", "KenCarp47"; references = "@article{kennedy2019higher, title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, @@ -954,7 +956,8 @@ function KenCarp47(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("An A-L stable stiffly-accurate 5th order ESDIRK method with splitting.", +@doc SDIRK_docstring( + "An A-L stable stiffly-accurate 5th order ESDIRK method with splitting.", "KenCarp5"; references = "@book{kennedy2001additive, title={Additive Runge-Kutta schemes for convection-diffusion-reaction equations}, @@ -995,7 +998,8 @@ function KenCarp5(; chunk_size = Val{0}(), autodiff = Val{true}(), smooth_est, extrapolant, controller, step_limiter!) end -@doc SDIRK_docstring("An A-L stable stiffly-accurate 5th order eight-stage ESDIRK method with splitting.", +@doc SDIRK_docstring( + "An A-L stable stiffly-accurate 5th order eight-stage ESDIRK method with splitting.", "KenCarp58"; references = "@article{kennedy2019higher, title={Higher-order additive Runge--Kutta schemes for ordinary differential equations}, @@ -1037,9 +1041,10 @@ function KenCarp58(; chunk_size = Val{0}(), autodiff = Val{true}(), end # `smooth_est` is not necessary, as the embedded method is also L-stable -@doc SDIRK_docstring("Optimized ESDIRK tableaus. - Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, - but are still being fully evaluated in context.", +@doc SDIRK_docstring( + "Optimized ESDIRK tableaus. +Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, +but are still being fully evaluated in context.", "ESDIRK54I8L2SA"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1076,9 +1081,10 @@ function ESDIRK54I8L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Optimized ESDIRK tableaus. - Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, - but are still being fully evaluated in context.", +@doc SDIRK_docstring( + "Optimized ESDIRK tableaus. +Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, +but are still being fully evaluated in context.", "ESDIRK436L2SA2"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1115,9 +1121,10 @@ function ESDIRK436L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Optimized ESDIRK tableaus. - Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, - but are still being fully evaluated in context.", +@doc SDIRK_docstring( + "Optimized ESDIRK tableaus. +Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, +but are still being fully evaluated in context.", "ESDIRK437L2SA"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1154,9 +1161,10 @@ function ESDIRK437L2SA(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Optimized ESDIRK tableaus. - Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, - but are still being fully evaluated in context.", +@doc SDIRK_docstring( + "Optimized ESDIRK tableaus. +Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, +but are still being fully evaluated in context.", "ESDIRK547L2SA2"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, @@ -1193,11 +1201,12 @@ function ESDIRK547L2SA2(; chunk_size = Val{0}(), autodiff = Val{true}(), controller) end -@doc SDIRK_docstring("Optimized ESDIRK tableaus. - Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, - but are still being fully evaluated in context. - Currently has STABILITY ISSUES, causing it to fail the adaptive tests. - Check issue https://github.com/SciML/OrdinaryDiffEq.jl/issues/1933 for more details.", +@doc SDIRK_docstring( + "Optimized ESDIRK tableaus. +Updates of the original KenCarp tableau expected to achieve lower error for the same steps in theory, +but are still being fully evaluated in context. +Currently has STABILITY ISSUES, causing it to fail the adaptive tests. +Check issue https://github.com/SciML/OrdinaryDiffEq.jl/issues/1933 for more details.", "ESDIRK659L2SA"; references = """@article{Kennedy2019DiagonallyIR, title={Diagonally implicit Runge–Kutta methods for stiff ODEs}, diff --git a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl index 8f9ee62222..3bda97a6a6 100644 --- a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl @@ -320,7 +320,9 @@ function SSPRK33(stage_limiter!, step_limiter! = trivial_limiter!) step_limiter!, False()) end -@doc explicit_rk_docstring("Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", "SHLDDRK_2N", +@doc explicit_rk_docstring( + "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", + "SHLDDRK_2N", references = "@article{stanescu19982n, title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, author={Stanescu, D and Habashi, WG}, @@ -342,7 +344,9 @@ function SHLDDRK_2N(stage_limiter!, step_limiter! = trivial_limiter!) False()) end -@doc explicit_rk_docstring("Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", "KYKSSPRK42", +@doc explicit_rk_docstring( + "Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", + "KYKSSPRK42", references = "@article{kubatko2014optimal, title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, author={Kubatko, Ethan J and Yeager, Benjamin A and Ketcheson, David I}, @@ -363,7 +367,9 @@ function KYKSSPRK42(stage_limiter!, step_limiter! = trivial_limiter!) False()) end -@doc explicit_rk_docstring("Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", "SHLDDRK52", +@doc explicit_rk_docstring( + "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", + "SHLDDRK52", references = "@article{stanescu19982n, title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, author={Stanescu, D and Habashi, WG}, diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl index 9cbd73a41c..a33b72f562 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl @@ -1,6 +1,7 @@ -@doc generic_solver_docstring("""Second order method. Exhibits high stability for real eigenvalues - and is smoothened to allow for moderate sized complex eigenvalues.""", +@doc generic_solver_docstring( + """Second order method. Exhibits high stability for real eigenvalues +and is smoothened to allow for moderate sized complex eigenvalues.""", "ROCK2", "Stabilized Explicit Method.", """Assyr Abdulle, Alexei A. Medovikov. Second Order Chebyshev Methods based on Orthogonal Polynomials. @@ -27,8 +28,9 @@ function ROCK2(; min_stages = 0, max_stages = 200, eigen_est = nothing) ROCK2(min_stages, max_stages, eigen_est) end -@doc generic_solver_docstring("""Fourth order method. Exhibits high stability for real eigenvalues - and is smoothened to allow for moderate sized complex eigenvalues.""", +@doc generic_solver_docstring( + """Fourth order method. Exhibits high stability for real eigenvalues +and is smoothened to allow for moderate sized complex eigenvalues.""", "ROCK4", "Stabilized Explicit Method.", """Assyr Abdulle. Fourth Order Chebyshev Methods With Recurrence Relation. 2002 Society for @@ -67,7 +69,8 @@ for Alg in [:ESERK4, :ESERK5, :RKC] end end -@doc generic_solver_docstring("""Second order method. Exhibits high stability for real eigenvalues.""", +@doc generic_solver_docstring( + """Second order method. Exhibits high stability for real eigenvalues.""", "RKC", "Stabilized Explicit Method.", """B. P. Sommeijer, L. F. Shampine, J. G. Verwer. RKC: An Explicit Solver for Parabolic PDEs, @@ -84,8 +87,9 @@ end """) function RKC end -@doc generic_solver_docstring("""Fourth order method. Exhibits high stability for real eigenvalues - and is smoothened to allow for moderate sized complex eigenvalues.""", +@doc generic_solver_docstring( + """Fourth order method. Exhibits high stability for real eigenvalues +and is smoothened to allow for moderate sized complex eigenvalues.""", "ESERK4", "Stabilized Explicit Method.", """J. Martín-Vaquero, B. Kleefeld. Extrapolated stabilized explicit Runge-Kutta methods, @@ -102,8 +106,9 @@ function RKC end """) function ESERK4 end -@doc generic_solver_docstring("""Fifth order method. Exhibits high stability for real eigenvalues - and is smoothened to allow for moderate sized complex eigenvalues.""", +@doc generic_solver_docstring( + """Fifth order method. Exhibits high stability for real eigenvalues +and is smoothened to allow for moderate sized complex eigenvalues.""", "ESERK5", "Stabilized Explicit Method.", """J. Martín-Vaquero, A. Kleefeld. ESERK5: A fifth-order extrapolated stabilized explicit Runge-Kutta method, diff --git a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl index 43132f319d..cdbc53d2e1 100644 --- a/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSymplecticRK/src/algorithms.jl @@ -1,7 +1,7 @@ @doc generic_solver_docstring("First order explicit symplectic integrator.", - "SymplecticEuler", - "Symplectic Runge-Kutta Methods", - "https://en.wikipedia.org/wiki/Semi-implicit_Euler_method", "", "") + "SymplecticEuler", + "Symplectic Runge-Kutta Methods", + "https://en.wikipedia.org/wiki/Semi-implicit_Euler_method", "", "") struct SymplecticEuler <: OrdinaryDiffEqPartitionedAlgorithm end verlet1967 = """ @@ -17,22 +17,23 @@ publisher={APS} } """ -@doc generic_solver_docstring("2nd order explicit symplectic integrator. Requires f_2(t,u) = v, i.e. a second order ODE.", - "VelocityVerlet", - "Symplectic Runge-Kutta Methods", - verlet1967, "", "") +@doc generic_solver_docstring( + "2nd order explicit symplectic integrator. Requires f_2(t,u) = v, i.e. a second order ODE.", + "VelocityVerlet", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct VelocityVerlet <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("2nd order explicit symplectic integrator.", - "VerletLeapfrog", - "Symplectic Runge-Kutta Methods", - verlet1967, "", "") + "VerletLeapfrog", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct VerletLeapfrog <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("2nd order explicit symplectic integrator.", - "PseudoVerletLeapfrog", - "Symplectic Runge-Kutta Methods", - verlet1967, "", "") + "PseudoVerletLeapfrog", + "Symplectic Runge-Kutta Methods", + verlet1967, "", "") struct PseudoVerletLeapfrog <: OrdinaryDiffEqPartitionedAlgorithm end mclachlan1992 = """ @@ -48,10 +49,11 @@ publisher={IOP Publishing} } """ -@doc generic_solver_docstring("Optimized efficiency 2nd order explicit symplectic integrator.", - "McAte2", - "Symplectic Runge-Kutta Methods", - mclachlan1992, "", "") +@doc generic_solver_docstring( + "Optimized efficiency 2nd order explicit symplectic integrator.", + "McAte2", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte2 <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("3rd order explicit symplectic integrator.", @@ -67,10 +69,11 @@ struct McAte2 <: OrdinaryDiffEqPartitionedAlgorithm end year={1983}}""", "", "") struct Ruth3 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("Optimized efficiency 3rd order explicit symplectic integrator.", - "McAte3", - "Symplectic Runge-Kutta Methods", - mclachlan1992, "", "") +@doc generic_solver_docstring( + "Optimized efficiency 3rd order explicit symplectic integrator.", + "McAte3", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte3 <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("4th order explicit symplectic integrator.", @@ -87,13 +90,15 @@ struct McAte3 <: OrdinaryDiffEqPartitionedAlgorithm end ublisher={Elsevier}}""", "", "") struct CandyRoz4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("4th order explicit symplectic integrator. Requires quadratic kinetic energy.", - "McAte4", - "Symplectic Runge-Kutta Methods", - mclachlan1992, "", "") +@doc generic_solver_docstring( + "4th order explicit symplectic integrator. Requires quadratic kinetic energy.", + "McAte4", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte4 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("Optimized efficiency 4th order explicit symplectic integrator.", +@doc generic_solver_docstring( + "Optimized efficiency 4th order explicit symplectic integrator.", "CalvoSanz4", "Symplectic Runge-Kutta Methods", """@article{sanz1993symplectic, @@ -109,15 +114,16 @@ struct McAte4 <: OrdinaryDiffEqPartitionedAlgorithm end struct CalvoSanz4 <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("4th order explicit symplectic integrator. BROKEN", - "McAte42", - "Symplectic Runge-Kutta Methods", - mclachlan1992, "", "") + "McAte42", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte42 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("Optimized efficiency 5th order explicit symplectic integrator. Requires quadratic kinetic energy.", - "McAte5", - "Symplectic Runge-Kutta Methods", - mclachlan1992, "", "") +@doc generic_solver_docstring( + "Optimized efficiency 5th order explicit symplectic integrator. Requires quadratic kinetic energy.", + "McAte5", + "Symplectic Runge-Kutta Methods", + mclachlan1992, "", "") struct McAte5 <: OrdinaryDiffEqPartitionedAlgorithm end @doc generic_solver_docstring("6th order explicit symplectic integrator.", @@ -134,7 +140,8 @@ struct McAte5 <: OrdinaryDiffEqPartitionedAlgorithm end publisher={Elsevier}}""", "", "") struct Yoshida6 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("Optimized efficiency 6th order explicit symplectic integrator.", +@doc generic_solver_docstring( + "Optimized efficiency 6th order explicit symplectic integrator.", "KahanLi6", "Symplectic Runge-Kutta Methods", """@article{yoshida1990construction, @@ -163,7 +170,8 @@ struct KahanLi6 <: OrdinaryDiffEqPartitionedAlgorithm end }""", "", "") struct McAte8 <: OrdinaryDiffEqPartitionedAlgorithm end -@doc generic_solver_docstring("Optimized efficiency 8th order explicit symplectic integrator.", +@doc generic_solver_docstring( + "Optimized efficiency 8th order explicit symplectic integrator.", "KahanLi8", "Symplectic Runge-Kutta Methods", """@article{kahan1997composition, From e244bfb7088d0751af79d9e35472d74f749b8280 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 12:34:15 +0200 Subject: [PATCH 69/83] add more refs --- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 940151cd72..974103155b 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -66,8 +66,8 @@ REF6 = """ """ for (Alg, Description, Ref) in [ - (:MagnusMidpoint, "Second order Magnus Midpoint method.", "ref TBD"), - (:MagnusLeapfrog, "Second order Magnus Leapfrog method.", "ref TBD"), + (:MagnusMidpoint, "Second order Magnus Midpoint method.", "https://joshuagoings.com/2017/06/15/magnus/"), + (:MagnusLeapfrog, "Second order Magnus Leapfrog method.", "https://joshuagoings.com/2017/06/15/magnus/"), (:LieEuler, "description", REF1), (:MagnusGauss4, "Fourth order Magnus method approximated using a two stage Gauss quadrature.", From 743844eacad5627205f70013fca4dd9bda237ce7 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 16:37:42 +0200 Subject: [PATCH 70/83] QPRK description --- docs/src/explicit/QPRK.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/src/explicit/QPRK.md b/docs/src/explicit/QPRK.md index 2a4af88cfe..2251baa961 100644 --- a/docs/src/explicit/QPRK.md +++ b/docs/src/explicit/QPRK.md @@ -1,6 +1,7 @@ # OrdinaryDiffEqQPRK -This article is a stub. +Explicit solvers optimized for a certain number of parallel calls of the system of ordinary differential equations `f`. +Particularly good at low tolerances, when using quad-precision arithmetic, `Float128`. ```@eval first_steps = evalfile("./common_first_steps.jl") From 30b24125481b79ff0cacd31b6db3a441d5bf26f0 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 16:37:58 +0200 Subject: [PATCH 71/83] more references --- .../src/algorithms.jl | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl b/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl index 8fdf516d34..69e0d7ab57 100644 --- a/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl +++ b/lib/OrdinaryDiffEqIMEXMultistep/src/algorithms.jl @@ -1,9 +1,25 @@ # IMEX Multistep methods -@doc generic_solver_docstring("Description TBD", +@doc generic_solver_docstring("Crank-Nicholson Adams-Bashforth 2.", "CNAB2", "IMEX Multistep method.", - "REF TBD", "", "") + "@article{jorgenson2014unconditional, + title={Unconditional stability of a Crank-Nicolson Adams-Bashforth 2 numerical method}, + author={JORGENSON, ANDREW D}, + journal={A (A- C)}, + volume={1}, + number={2}, + pages={1}, + year={2014}} + @article{he2010numerical, + title={Numerical implementation of the Crank--Nicolson/Adams--Bashforth scheme for the time-dependent Navier--Stokes equations}, + author={He, Yinnian and Li, Jian}, + journal={International journal for numerical methods in fluids}, + volume={62}, + number={6}, + pages={647--659}, + year={2010}, + publisher={Wiley Online Library}}", "", "") struct CNAB2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F @@ -25,10 +41,25 @@ function CNAB2(; chunk_size = Val{0}(), autodiff = Val{true}(), standardtag = Va extrapolant) end -@doc generic_solver_docstring("TBD", +@doc generic_solver_docstring("Crank-Nicholson Leapfrong 2.", "CNLF2", "IMEX Multistep method.", - "REF TBD", "", "") + "@article{han2020second, + title={A second order, linear, unconditionally stable, Crank--Nicolson--Leapfrog scheme for phase field models of two-phase incompressible flows}, + author={Han, Daozhi and Jiang, Nan}, + journal={Applied Mathematics Letters}, + volume={108}, + pages={106521}, + year={2020}, + publisher={Elsevier}} + @article{jiang2015crank, + title={A Crank--Nicolson Leapfrog stabilization: Unconditional stability and two applications}, + author={Jiang, Nan and Kubacki, Michaela and Layton, William and Moraiti, Marina and Tran, Hoang}, + journal={Journal of Computational and Applied Mathematics}, + volume={281}, + pages={263--276}, + year={2015}, + publisher={Elsevier}}", "", "") struct CNLF2{CS, AD, F, F2, P, FDT, ST, CJ} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} linsolve::F From ed0a1389f2e4ebc048249b068839af1975bc41eb Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 16:53:10 +0200 Subject: [PATCH 72/83] add proper linear example --- docs/src/semilinear/Linear.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/src/semilinear/Linear.md b/docs/src/semilinear/Linear.md index 8ecc791343..b17d4366a4 100644 --- a/docs/src/semilinear/Linear.md +++ b/docs/src/semilinear/Linear.md @@ -2,9 +2,35 @@ Methods for semi-linear differential equations. -```@eval -first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqLinear", "LieRK4") +## Installation + +To be able to access the solvers in `OrdinaryDiffEqLinear`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqLinear") +``` + +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage + +```julia +using OrdinaryDiffEqLinear, SciMLOperators +function update_func(A, u, p, t) + A[1, 1] = 0 + A[2, 1] = sin(u[1]) + A[1, 2] = -1 + A[2, 2] = 0 +end +A0 = ones(2, 2) +A = DiffEqArrayOperator(A0, update_func = update_func) +u0 = ones(2) +tspan = (0.0, 30.0) +prob = ODEProblem(A, u0, tspan) +sol = solve(prob, LieRK4(), dt = 1 / 4) ``` ## Full list of solvers From e5bd78b35b115d9abce7434ece8f54fad622acda Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 17:12:07 +0200 Subject: [PATCH 73/83] add proper ExponentialRK example --- docs/src/semilinear/ExponentialRK.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/src/semilinear/ExponentialRK.md b/docs/src/semilinear/ExponentialRK.md index 8d1cc523ae..9e0b5aabc9 100644 --- a/docs/src/semilinear/ExponentialRK.md +++ b/docs/src/semilinear/ExponentialRK.md @@ -2,9 +2,31 @@ Methods for semi-linear differential equations. -```@eval -first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqExponentialRK", "Exprb43") +## Installation + +To be able to access the solvers in `OrdinaryDiffEqLinear`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqExponentialRK") +``` + +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage + +```julia +using OrdinaryDiffEqExponentialRK, SciMLOperators +A = [2.0 -1.0; -1.0 2.0] +linnonlin_f1 = MatrixOperator(A) +linnonlin_f2 = (du, u, p, t) -> du .= 1.01 .* u +linnonlin_fun_iip = SplitFunction(linnonlin_f1, linnonlin_f2) +tspan = (0.0, 1.0) +u0 = [0.1, 0.1] +prob = SplitODEProblem(linnonlin_fun_iip, u0, tspan) +sol = solve(prob, ETDRK4(), dt = 1 / 4) ``` ## Full list of solvers From fba9d1f00013aacaea1840c9c968375f52943970 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 18:26:47 +0200 Subject: [PATCH 74/83] add proper IMEX example --- docs/src/imex/IMEXMultistep.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/src/imex/IMEXMultistep.md b/docs/src/imex/IMEXMultistep.md index 6dbfb33398..d8e5a30f01 100644 --- a/docs/src/imex/IMEXMultistep.md +++ b/docs/src/imex/IMEXMultistep.md @@ -1,6 +1,31 @@ -# IMEX Multistep Methods +# OrdinaryDiffEqIMEXMultistep -This article is a stub and likely needs a specialized example. +Solvers if your system of ordinary differential equations can be split up into the sum of a stiff and non-stiff part. + +## Installation + +To be able to access the solvers in `OrdinaryDiffEqIMEXMultistep`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqIMEXMultistep") +``` + +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage + +```julia +using OrdinaryDiffEqIMEXMultistep +f1 = (u, p, t) -> 2u +f2 = (u, p, t) -> 2u +u0 = 1.0 +tspan = (0.0, 1.0) +prob = SplitODEProblem(f1, f2, u0, tspan) +sol = solve(prob,CNAB2(), dt = 1 / 10) +``` ## Full list of solvers From cf5fbf48a511b4dc464ccc1c0cdbface535412ad Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Thu, 22 Aug 2024 18:26:53 +0200 Subject: [PATCH 75/83] add more references --- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 974103155b..0c5b5c5193 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -123,7 +123,14 @@ struct MagnusAdapt4 <: OrdinaryDiffEqAdaptiveAlgorithm end @doc generic_solver_docstring("First order method using Cayley transformations.", "CayleyEuler", "Semilinear ODE solver", - "ref TBD", "", "") + "@article{iserles2000lie, + title={Lie-group methods}, + author={Iserles, Arieh and Munthe-Kaas, Hans Z and Norsett, Syvert P and Zanna, Antonella}, + journal={Acta numerica}, + volume={9}, + pages={215--365}, + year={2000}, + publisher={Cambridge University Press}}", "", "") struct CayleyEuler <: OrdinaryDiffEqAlgorithm end @doc generic_solver_docstring( From eb395b6d2311e15bc2fcb333235f973336b1e164 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 24 Aug 2024 16:23:38 +0200 Subject: [PATCH 76/83] add more references --- lib/OrdinaryDiffEqLinear/src/algorithms.jl | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/lib/OrdinaryDiffEqLinear/src/algorithms.jl b/lib/OrdinaryDiffEqLinear/src/algorithms.jl index 0c5b5c5193..55ca35eb49 100644 --- a/lib/OrdinaryDiffEqLinear/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLinear/src/algorithms.jl @@ -117,7 +117,15 @@ end @doc generic_solver_docstring("Fourth Order Adaptive Magnus method.", "MagnusAdapt4", "Semilinear ODE solver", - "ref TBD", "", "") + "@article{li2008adaptive, + title={Adaptive explicit Magnus numerical method for nonlinear dynamical systems}, + author={Li, Wen-cheng and Deng, Zi-chen}, + journal={Applied Mathematics and Mechanics}, + volume={29}, + number={9}, + pages={1111--1118}, + year={2008}, + publisher={Springer}}", "", "") struct MagnusAdapt4 <: OrdinaryDiffEqAdaptiveAlgorithm end @doc generic_solver_docstring("First order method using Cayley transformations.", From 08744bc60a5b31a713f115d05dd7c8553f24e013 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 24 Aug 2024 16:23:47 +0200 Subject: [PATCH 77/83] add proper StabalizedIRK example --- docs/src/implicit/StabalizedIRK.md | 42 +++++++++++++++++-- .../src/algorithms.jl | 2 +- 2 files changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/src/implicit/StabalizedIRK.md b/docs/src/implicit/StabalizedIRK.md index f1b1db489c..25e4aaca1f 100644 --- a/docs/src/implicit/StabalizedIRK.md +++ b/docs/src/implicit/StabalizedIRK.md @@ -1,15 +1,49 @@ # OrdinaryDiffEqStabalizedIRK -Explicit stabilized methods utilize an upper bound on the spectral radius of the Jacobian. +Stabilized Explicit Runge-Kutta methods, +like Runge-Kutta-Chebyshev methods and ROCK methods +are explicit methods which chain together many stages in a specific way to get large stability regions. +they are made in such a way to converge to a large stability region, +and thus suitable to stiff equations. +However, they converge to having a large stability region in the direction of the negative real axis, +and thus are only stable on a subset of stiff equations which are not dominated by large complex eigenvalues in the Jacobian. + +Stabilized implicit methods try to mitigate this problem by being an IMEX type scheme, +requiring a SplitODEProblem where the splitting is designed to treat the large complex eigenvalues implicitly +while treating the large real eigenvalues using a fast explicit stabilized RK type of method. + +These methods utilize an upper bound on the spectral radius of the Jacobian. Users can supply an upper bound by specifying the keyword argument `eigen_est`, for example ```julia `eigen_est = (integrator) -> integrator.eigen_est = upper_bound` ``` -```@eval -first_steps = evalfile("./common_first_steps.jl") -first_steps("OrdinaryDiffEqStabalizedIRK", "IRKC") +## Installation + +To be able to access the solvers in `OrdinaryDiffEqStabalizedIRK`, you must first install them use the Julia package manager: + +```julia +using Pkg +Pkg.add("OrdinaryDiffEqStabalizedIRK") +``` + +This will only install the solvers listed at the bottom of this page. +If you want to explore other solvers for your problem, +you will need to install some of the other libraries listed in the navigation bar on the left. + +## Example usage + +```julia +using OrdinaryDiffEqStabilizedIRK +A = randn(20, 20) +B = randn(20, 20) +f1 = (u, p, t) -> A * u +f2 = (u, p, t) -> B * u +u0 = randn(20, 1) +tspan = (0.0, 1.0) +prob = SplitODEProblem(f1, f2, u0, tspan) +sol = solve(prob, IRKC()) ``` ## Full list of solvers diff --git a/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl index e4b2465860..85cf0825fa 100644 --- a/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedIRK/src/algorithms.jl @@ -1,4 +1,4 @@ -@doc generic_solver_docstring("Description TBD", +@doc generic_solver_docstring("Implicit Runge-Kutta-Chebyshev method.", "IRKC", "Stabalized Implicit Runge Kutta method.", "REF TBD", From d2f81417003707e27b50d9364390399cb7a96513 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 24 Aug 2024 16:59:40 +0200 Subject: [PATCH 78/83] finish PRK keywords --- lib/OrdinaryDiffEqPRK/src/algorithms.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/OrdinaryDiffEqPRK/src/algorithms.jl b/lib/OrdinaryDiffEqPRK/src/algorithms.jl index ee1d0ff1c6..5d69e69f29 100644 --- a/lib/OrdinaryDiffEqPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPRK/src/algorithms.jl @@ -10,8 +10,8 @@ pages={49--82}, year={1995}, publisher={SIAM}}""", - "- `threading`: TBD", - "threading = true,") + "- `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads.", + "thread = OrdinaryDiffEq.True(),") Base.@kwdef struct KuttaPRK2p5{TO} <: OrdinaryDiffEqAlgorithm threading::TO = true end From 1f08cee3b56eb0ea630b31d1e3b40a48066db333 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 24 Aug 2024 17:00:07 +0200 Subject: [PATCH 79/83] finish explicit Extrapolation keywords --- .../src/algorithms.jl | 89 ++++++++++--------- 1 file changed, 45 insertions(+), 44 deletions(-) diff --git a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl index e96b6457a9..205e8e1f3d 100644 --- a/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl +++ b/lib/OrdinaryDiffEqExtrapolation/src/algorithms.jl @@ -10,22 +10,23 @@ reference = """@inproceedings{elrod2022parallelizing, year={2022}, organization={IEEE}} """ + @doc generic_solver_docstring( "Euler extrapolation using Aitken-Neville with the Romberg Sequence.", "AitkenNeville", "Parallelized Explicit Extrapolation Method.", reference, """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. """, """ max_order::Int = 10, min_order::Int = 1, init_order = 3, - threading = false + thread = OrdinaryDiffEq.False(), """) Base.@kwdef struct AitkenNeville{TO} <: OrdinaryDiffEqExtrapolationVarOrderVarStepAlgorithm max_order::Int = 10 @@ -41,17 +42,17 @@ Similar to Hairer's SEULEX.", "Parallelized Explicit Extrapolation Method.", references = reference, extra_keyword_description = """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. """, extra_keyword_default = """ max_order = 12, min_order = 3, init_order = 5, - threading = false, + thread = OrdinaryDiffEq.False(), sequence = :harmonic """) struct ImplicitEulerExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: @@ -111,18 +112,18 @@ end "Parallelized Explicit Extrapolation Method.", reference, """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD - - `sequence_factor`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. + - `sequence_factor`: denotes which even multiple of sequence to take while evaluating internal discretizations. """, """ max_order = 10, min_order = 1, init_order = 5, - threading = true, + thread = OrdinaryDiffEq.True(), sequence = :harmonic, sequence_factor = 2, """) @@ -181,17 +182,17 @@ end "Parallelized Explicit Extrapolation Method.", references = reference, extra_keyword_description = """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. """, extra_keyword_default = """ max_order = 10, min_order = 1, init_order = 5, - threading = false, + thread = OrdinaryDiffEq.False(), sequence = :harmonic, """) struct ImplicitDeuflhardExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: @@ -255,18 +256,18 @@ end "Parallelized Explicit Extrapolation Method.", reference, """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD - - `sequence_factor`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. + - `sequence_factor`: denotes which even multiple of sequence to take while evaluating internal discretizations. """, """ max_order = 10, min_order = 2, init_order = 5, - threading = true, + thread = OrdinaryDiffEq.True(), sequence = :harmonic, sequence_factor = 2, """) @@ -328,17 +329,17 @@ end "Parallelized Explicit Extrapolation Method.", references = reference, extra_keyword_description = """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. """, extra_keyword_default = """ max_order = 10, min_order = 2, init_order = 5, - threading = false, + thread = OrdinaryDiffEq.False(), sequence = :harmonic, """) struct ImplicitHairerWannerExtrapolation{CS, AD, F, P, FDT, ST, CJ, TO} <: @@ -404,18 +405,18 @@ end "Parallelized Explicit Extrapolation Method.", references = reference, extra_keyword_description = """ - - `max_order`: TBD - - `min_order`: TBD - - `init_order`: TBD - - `threading`: TBD - - `sequence`: TBD - - `sequence_factor`: TBD + - `max_order`: maximum order of the adaptive order algorithm. + - `min_order`: minimum order of the adaptive order algorithm. + - `init_order`: initial order of the adaptive order algorithm. + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. + - `sequence`: the step-number sequences, also called the subdividing sequence. Possible values are `:harmonic`, `:romberg` or `:bulirsch`. + - `sequence_factor`: denotes which even multiple of sequence to take while evaluating internal discretizations. """, extra_keyword_default = """ max_order = 10, min_order = 3, init_order = 5, - threading = false, + thread = OrdinaryDiffEq.False(), sequence = :harmonic, sequence_factor = 2, """) From 0cd03e0af900481615abea2dcf4cb5b6ebe6a401 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Sat, 24 Aug 2024 17:31:33 +0200 Subject: [PATCH 80/83] collapse docstrings by default --- docs/src/explicit/AdamsBashforthMoulton.md | 3 +++ docs/src/explicit/Extrapolation.md | 3 +++ docs/src/explicit/Feagin.md | 3 +++ docs/src/explicit/HighOrderRK.md | 3 +++ docs/src/explicit/LowOrderRK.md | 3 +++ docs/src/explicit/LowStorageRK.md | 3 +++ docs/src/explicit/Nordsieck.md | 3 +++ docs/src/explicit/PRK.md | 3 +++ docs/src/explicit/QPRK.md | 3 +++ docs/src/explicit/RKN.md | 3 +++ docs/src/explicit/SSPRK.md | 3 +++ docs/src/explicit/SymplecticRK.md | 3 +++ docs/src/explicit/Tsit5.md | 3 +++ docs/src/explicit/Verner.md | 3 +++ docs/src/imex/IMEXMultistep.md | 3 +++ docs/src/implicit/BDF.md | 3 +++ docs/src/implicit/Extrapolation.md | 3 +++ docs/src/implicit/FIRK.md | 3 +++ docs/src/implicit/PDIRK.md | 3 +++ docs/src/implicit/Rosenbrock.md | 4 ++++ docs/src/implicit/SDIRK.md | 3 +++ docs/src/implicit/StabalizedIRK.md | 3 +++ docs/src/implicit/StabalizedRK.md | 3 +++ docs/src/semilinear/ExponentialRK.md | 3 +++ docs/src/semilinear/Linear.md | 3 +++ 25 files changed, 76 insertions(+) diff --git a/docs/src/explicit/AdamsBashforthMoulton.md b/docs/src/explicit/AdamsBashforthMoulton.md index f1e6638cfc..ec9b392aab 100644 --- a/docs/src/explicit/AdamsBashforthMoulton.md +++ b/docs/src/explicit/AdamsBashforthMoulton.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqAdamsBashforthMoulton Multistep methods, useful for integrating a very expensive to evaluate non-stiff system of differential equations. diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index da5af6308e..892a99e60f 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqExtrapolation Solvers based on within method parallelism. diff --git a/docs/src/explicit/Feagin.md b/docs/src/explicit/Feagin.md index 5790939f17..13fc1b4cad 100644 --- a/docs/src/explicit/Feagin.md +++ b/docs/src/explicit/Feagin.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqFeagin Preferred solvers for non-stiff problems at very low tolerance, `<1e-30`. diff --git a/docs/src/explicit/HighOrderRK.md b/docs/src/explicit/HighOrderRK.md index e509405580..0401afd5ce 100644 --- a/docs/src/explicit/HighOrderRK.md +++ b/docs/src/explicit/HighOrderRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqHighOrderRK Solvers for non-stiff problems at low tolerance. diff --git a/docs/src/explicit/LowOrderRK.md b/docs/src/explicit/LowOrderRK.md index 39d48a1438..0e6041773e 100644 --- a/docs/src/explicit/LowOrderRK.md +++ b/docs/src/explicit/LowOrderRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqLowOrderRK If [`OrdinaryDiffEqTsit5`](@ref OrdinaryDiffEqTsit5) is not working well for your non-stiff problem at default and higher tolerance, diff --git a/docs/src/explicit/LowStorageRK.md b/docs/src/explicit/LowStorageRK.md index 3bd22b9941..127f6fbb8a 100644 --- a/docs/src/explicit/LowStorageRK.md +++ b/docs/src/explicit/LowStorageRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqLowStorageRK These methods are designed to have reduced register requirements, allowing for larger sets of ODEs to more diff --git a/docs/src/explicit/Nordsieck.md b/docs/src/explicit/Nordsieck.md index 042c12ab83..12d571bc47 100644 --- a/docs/src/explicit/Nordsieck.md +++ b/docs/src/explicit/Nordsieck.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqNordsieck The Nordsieck form is an alternative representation of multistep methods which, diff --git a/docs/src/explicit/PRK.md b/docs/src/explicit/PRK.md index 13e1406ed6..6e28579d67 100644 --- a/docs/src/explicit/PRK.md +++ b/docs/src/explicit/PRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqPRK Explicit solvers optimized for a certain number of parallel calls of the system of ordinary differential equations `f`. diff --git a/docs/src/explicit/QPRK.md b/docs/src/explicit/QPRK.md index 2251baa961..937ee6fc4c 100644 --- a/docs/src/explicit/QPRK.md +++ b/docs/src/explicit/QPRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqQPRK Explicit solvers optimized for a certain number of parallel calls of the system of ordinary differential equations `f`. diff --git a/docs/src/explicit/RKN.md b/docs/src/explicit/RKN.md index ea5bc9ed60..e2f297e93d 100644 --- a/docs/src/explicit/RKN.md +++ b/docs/src/explicit/RKN.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqRKN Second order solvers. diff --git a/docs/src/explicit/SSPRK.md b/docs/src/explicit/SSPRK.md index e5f52c55d1..de235d181f 100644 --- a/docs/src/explicit/SSPRK.md +++ b/docs/src/explicit/SSPRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqSSPRK SSPRK methods are Runge-Kutta methods which support the "strongly preserving property" (SSP). diff --git a/docs/src/explicit/SymplecticRK.md b/docs/src/explicit/SymplecticRK.md index f5556da346..2bf5913910 100644 --- a/docs/src/explicit/SymplecticRK.md +++ b/docs/src/explicit/SymplecticRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqSymplecticRK A symplectic integrator is an integrator whose solution resides on a symplectic manifold. diff --git a/docs/src/explicit/Tsit5.md b/docs/src/explicit/Tsit5.md index 9494c4e118..8971b1e72f 100644 --- a/docs/src/explicit/Tsit5.md +++ b/docs/src/explicit/Tsit5.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # [OrdinaryDiffEqTsit5](@id OrdinaryDiffEqTsit5) Recommended solver for most non-stiff problems at default and higher tolerance. diff --git a/docs/src/explicit/Verner.md b/docs/src/explicit/Verner.md index 21425524be..083f737163 100644 --- a/docs/src/explicit/Verner.md +++ b/docs/src/explicit/Verner.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # [OrdinaryDiffEqVerner](@id OrdinaryDiffEqVerner) Preferred solvers for non-stiff problems at low tolerance. diff --git a/docs/src/imex/IMEXMultistep.md b/docs/src/imex/IMEXMultistep.md index d8e5a30f01..c844278c16 100644 --- a/docs/src/imex/IMEXMultistep.md +++ b/docs/src/imex/IMEXMultistep.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqIMEXMultistep Solvers if your system of ordinary differential equations can be split up into the sum of a stiff and non-stiff part. diff --git a/docs/src/implicit/BDF.md b/docs/src/implicit/BDF.md index 7079b6156f..ac223b4a85 100644 --- a/docs/src/implicit/BDF.md +++ b/docs/src/implicit/BDF.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqBDF Multistep methods, good for large stiff systems. diff --git a/docs/src/implicit/Extrapolation.md b/docs/src/implicit/Extrapolation.md index a909fd3b57..3ed339d39a 100644 --- a/docs/src/implicit/Extrapolation.md +++ b/docs/src/implicit/Extrapolation.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # [OrdinaryDiffEqExtrapolation](@id StiffExtrapolation) Solvers based on within method parallelism. diff --git a/docs/src/implicit/FIRK.md b/docs/src/implicit/FIRK.md index c8d8a2d7fb..44fe2461b0 100644 --- a/docs/src/implicit/FIRK.md +++ b/docs/src/implicit/FIRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqFIRK FIRK methods are fully implicit Runge-Kutta methods. diff --git a/docs/src/implicit/PDIRK.md b/docs/src/implicit/PDIRK.md index dba01b2405..7edc74a0e5 100644 --- a/docs/src/implicit/PDIRK.md +++ b/docs/src/implicit/PDIRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqPDIRK PDIRK methods are parallel DIRK methods. diff --git a/docs/src/implicit/Rosenbrock.md b/docs/src/implicit/Rosenbrock.md index 7c5e8b6646..fc9087a408 100644 --- a/docs/src/implicit/Rosenbrock.md +++ b/docs/src/implicit/Rosenbrock.md @@ -1,3 +1,7 @@ + +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqRosenbrock Methods for small and medium sized stiff systems of differential equations. diff --git a/docs/src/implicit/SDIRK.md b/docs/src/implicit/SDIRK.md index 478b306f07..204c91a7f5 100644 --- a/docs/src/implicit/SDIRK.md +++ b/docs/src/implicit/SDIRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqSDIRK This article is a stub. diff --git a/docs/src/implicit/StabalizedIRK.md b/docs/src/implicit/StabalizedIRK.md index 25e4aaca1f..f956ff1aa1 100644 --- a/docs/src/implicit/StabalizedIRK.md +++ b/docs/src/implicit/StabalizedIRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqStabalizedIRK Stabilized Explicit Runge-Kutta methods, diff --git a/docs/src/implicit/StabalizedRK.md b/docs/src/implicit/StabalizedRK.md index d1e62c1137..2e20b12479 100644 --- a/docs/src/implicit/StabalizedRK.md +++ b/docs/src/implicit/StabalizedRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqStabalizedRK Explicit stabilized methods utilize an upper bound on the spectral radius of the Jacobian. diff --git a/docs/src/semilinear/ExponentialRK.md b/docs/src/semilinear/ExponentialRK.md index 9e0b5aabc9..fed72b79be 100644 --- a/docs/src/semilinear/ExponentialRK.md +++ b/docs/src/semilinear/ExponentialRK.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqExponentialRK Methods for semi-linear differential equations. diff --git a/docs/src/semilinear/Linear.md b/docs/src/semilinear/Linear.md index b17d4366a4..149c2f99f5 100644 --- a/docs/src/semilinear/Linear.md +++ b/docs/src/semilinear/Linear.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # OrdinaryDiffEqLinear Methods for semi-linear differential equations. From a94970ae9bb8c5a73818514499eeab349fbb1fdf Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 26 Aug 2024 01:35:00 +0200 Subject: [PATCH 81/83] Add more descriptions to keywords --- docs/make.jl | 3 +- lib/OrdinaryDiffEqBDF/src/algorithms.jl | 77 ++++++++--- lib/OrdinaryDiffEqCore/src/doc_utils.jl | 61 ++++++++- lib/OrdinaryDiffEqFIRK/src/algorithms.jl | 12 +- lib/OrdinaryDiffEqPDIRK/src/algorithms.jl | 4 +- .../src/OrdinaryDiffEqRosenbrock.jl | 122 ++++++++++++++++-- lib/OrdinaryDiffEqSDIRK/src/algorithms.jl | 79 +++++++++--- .../src/algorithms.jl | 8 +- 8 files changed, 295 insertions(+), 71 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 7ccbffccb4..087a184f8c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -38,7 +38,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl", warnonly = [:docs_block, :missing_docs, :eval_block], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], - canonical = "https://ordinarydiffeq.sciml.ai/stable/"), + canonical = "https://ordinarydiffeq.sciml.ai/stable/", + size_threshold_ignore = ["implicit\\Rosenbrock.md"]), pages = [ "OrdinaryDiffEq.jl: ODE solvers and utilities" => "index.md", "Usage" => "usage.md", diff --git a/lib/OrdinaryDiffEqBDF/src/algorithms.jl b/lib/OrdinaryDiffEqBDF/src/algorithms.jl index 1cb80c7a20..494bbcfa8a 100644 --- a/lib/OrdinaryDiffEqBDF/src/algorithms.jl +++ b/lib/OrdinaryDiffEqBDF/src/algorithms.jl @@ -11,19 +11,64 @@ function BDF_docstring(description::String, diff_type = Val{:forward}, linsolve = nothing, precs = DEFAULT_PRECS, - """ * extra_keyword_default + """ * "\n" * extra_keyword_default keyword_default_description = """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD - - `precs`: TBD - """ * extra_keyword_description - + - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()` + and thus uses the internal ForwardDiff.jl algorithm for the choice. + - `autodiff`: Specifies whether to use automatic differentiation via + [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite + differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). + Defaults to `Val{true}()` for automatic differentiation. + - `standardtag`: Specifies whether to use package-specific tags instead of the + ForwardDiff default function-specific tags. For more information, see + [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/). + Defaults to `Val{true}()`. + - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to + `nothing`, which means it will be chosen true/false depending on circumstances + of the solver, such as whether a Krylov subspace method is used for `linsolve`. + - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`. + Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and + `Val{:complex}`. + - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver. + For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify + `$name(linsolve = KLUFactorization()`). + When `nothing` is passed, uses `DefaultLinearSolver`. + - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/) + can be used as a left or right preconditioner. + Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` + function where the arguments are defined as: + - `W`: the current Jacobian of the nonlinear system. Specified as either + ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will + commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy + representation of the operator. Users can construct the W-matrix on demand + by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching + the `jac_prototype`. + - `du`: the current ODE derivative + - `u`: the current ODE state + - `p`: the ODE parameters + - `t`: the current ODE time + - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since + the last call to `precs`. It is recommended that this is checked to only + update the preconditioner when `newW == true`. + - `Plprev`: the previous `Pl`. + - `Prprev`: the previous `Pr`. + - `solverdata`: Optional extra data the solvers can give to the `precs` function. + Solver-dependent and subject to change. + The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners. + To specify one-sided preconditioning, simply return `nothing` for the preconditioner + which is not used. Additionally, `precs` must supply the dispatch: + ```julia + Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata) + ``` + which is used in the solver setup phase to construct the integrator + type with the preconditioners `(Pl,Pr)`. + The default is `precs=DEFAULT_PRECS` where the default preconditioner function + is defined as: + ```julia + DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing + ``` + """ * "/n" * extra_keyword_description generic_solver_docstring( description, name, "Multistep Method.", references, keyword_default_description, keyword_default @@ -45,7 +90,7 @@ end - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ κ = nothing, @@ -224,7 +269,7 @@ Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850.", - `extrapolant`: TBD - `kappa`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ nlsolve = NLNewton(), @@ -279,7 +324,7 @@ end - `extrapolant`: TBD - `kappa`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ nlsolve = NLNewton(), @@ -337,7 +382,7 @@ Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword arg - `extrapolant`: TBD - `kappa`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ κ = nothing, @@ -436,7 +481,7 @@ Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword arg - `nlsolve`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` - `max_order`: TBD """, extra_keyword_default = """ diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl index 71aabd288b..75eb00dc7d 100644 --- a/lib/OrdinaryDiffEqCore/src/doc_utils.jl +++ b/lib/OrdinaryDiffEqCore/src/doc_utils.jl @@ -91,13 +91,60 @@ function differentiation_rk_docstring(description::String, """ * extra_keyword_default keyword_default_description = """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD + - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()` + and thus uses the internal ForwardDiff.jl algorithm for the choice. + - `autodiff`: Specifies whether to use automatic differentiation via + [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite + differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). + Defaults to `Val{true}()` for automatic differentiation. + - `standardtag`: Specifies whether to use package-specific tags instead of the + ForwardDiff default function-specific tags. For more information, see + [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/). + Defaults to `Val{true}()`. + - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to + `nothing`, which means it will be chosen true/false depending on circumstances + of the solver, such as whether a Krylov subspace method is used for `linsolve`. + - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`. + Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and + `Val{:complex}`. + - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver. + For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify + `$name(linsolve = KLUFactorization()`). + When `nothing` is passed, uses `DefaultLinearSolver`. + - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/) + can be used as a left or right preconditioner. + Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` + function where the arguments are defined as: + - `W`: the current Jacobian of the nonlinear system. Specified as either + ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will + commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy + representation of the operator. Users can construct the W-matrix on demand + by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching + the `jac_prototype`. + - `du`: the current ODE derivative + - `u`: the current ODE state + - `p`: the ODE parameters + - `t`: the current ODE time + - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since + the last call to `precs`. It is recommended that this is checked to only + update the preconditioner when `newW == true`. + - `Plprev`: the previous `Pl`. + - `Prprev`: the previous `Pr`. + - `solverdata`: Optional extra data the solvers can give to the `precs` function. + Solver-dependent and subject to change. + The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners. + To specify one-sided preconditioning, simply return `nothing` for the preconditioner + which is not used. Additionally, `precs` must supply the dispatch: + ```julia + Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata) + ``` + which is used in the solver setup phase to construct the integrator + type with the preconditioners `(Pl,Pr)`. + The default is `precs=DEFAULT_PRECS` where the default preconditioner function + is defined as: + ```julia + DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing + ``` """ * extra_keyword_description generic_solver_docstring( diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl index 3f88dbd907..844f50ea96 100644 --- a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl @@ -11,20 +11,10 @@ hairer1999stiff = """@article{hairer1999stiff, extra_keyword_description = """ - `extrapolant`: TBD - - `fast_convergence_cutoff`: TBD - - `new_W_γdt_cutoff`: TBD - - `controller`: TBD - - `κ`: TBD - - `maxiters`: TBD - `smooth_est`: TBD - - `step_limiter!`: TBD""" + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`""" extra_keyword_default = """ extrapolant = :dense, - fast_convergence_cutoff = 1 // 5, - new_W_γdt_cutoff = 1 // 5, - controller = :Predictive, - κ = nothing, - maxiters = 10, smooth_est = true, step_limiter! = trivial_limiter!""" diff --git a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl index 5725d73247..0e93763cfd 100644 --- a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl @@ -14,12 +14,12 @@ extra_keyword_description = """ - `nlsolve`: TBD, - `extrapolant`: TBD, - - `threading`: TBD, + - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads. """, extra_keyword_default = """ nlsolve = NLNewton(), extrapolant = :constant, - threading = true, + thread = OrdinaryDiffEq.True(), """) struct PDIRK44{CS, AD, F, F2, P, FDT, ST, CJ, TO} <: OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ} diff --git a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl index 3ea885ffdf..d009f9c7a3 100644 --- a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl +++ b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl @@ -58,13 +58,60 @@ function rosenbrock_wanner_docstring(description::String, """ * extra_keyword_default keyword_default_description = """ - - `chunk_size`: TBD - - `standardtag`: TBD - - `autodiff`: boolean to control if the Jacobian should be computed via AD or not - - `concrete_jac`: function of the form `jac!(J, u, p, t)` - - `diff_type`: TBD - - `linsolve`: custom solver for the inner linear systems - - `precs`: custom preconditioner for the inner linear solver + - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()` + and thus uses the internal ForwardDiff.jl algorithm for the choice. + - `standardtag`: Specifies whether to use package-specific tags instead of the + ForwardDiff default function-specific tags. For more information, see + [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/). + Defaults to `Val{true}()`. + - `autodiff`: Specifies whether to use automatic differentiation via + [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite + differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). + Defaults to `Val{true}()` for automatic differentiation. + - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to + `nothing`, which means it will be chosen true/false depending on circumstances + of the solver, such as whether a Krylov subspace method is used for `linsolve`. + - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`. + Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and + `Val{:complex}`. + - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver. + For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify + `$name(linsolve = KLUFactorization()`). + When `nothing` is passed, uses `DefaultLinearSolver`. + - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/) + can be used as a left or right preconditioner. + Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` + function where the arguments are defined as: + - `W`: the current Jacobian of the nonlinear system. Specified as either + ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will + commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy + representation of the operator. Users can construct the W-matrix on demand + by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching + the `jac_prototype`. + - `du`: the current ODE derivative + - `u`: the current ODE state + - `p`: the ODE parameters + - `t`: the current ODE time + - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since + the last call to `precs`. It is recommended that this is checked to only + update the preconditioner when `newW == true`. + - `Plprev`: the previous `Pl`. + - `Prprev`: the previous `Pr`. + - `solverdata`: Optional extra data the solvers can give to the `precs` function. + Solver-dependent and subject to change. + The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners. + To specify one-sided preconditioning, simply return `nothing` for the preconditioner + which is not used. Additionally, `precs` must supply the dispatch: + ```julia + Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata) + ``` + which is used in the solver setup phase to construct the integrator + type with the preconditioners `(Pl,Pr)`. + The default is `precs=DEFAULT_PRECS` where the default preconditioner function + is defined as: + ```julia + DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing + ``` """ * extra_keyword_description if with_step_limiter @@ -85,13 +132,60 @@ function rosenbrock_docstring(description::String, extra_keyword_default = "", with_step_limiter = false) keyword_default = """ - chunk_size = Val{0}(), - standardtag = Val{true}(), - autodiff = Val{true}(), - concrete_jac = nothing, - diff_type = Val{:central}, - linsolve = nothing, - precs = DEFAULT_PRECS, + - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()` + and thus uses the internal ForwardDiff.jl algorithm for the choice. + - `standardtag`: Specifies whether to use package-specific tags instead of the + ForwardDiff default function-specific tags. For more information, see + [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/). + Defaults to `Val{true}()`. + - `autodiff`: Specifies whether to use automatic differentiation via + [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite + differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). + Defaults to `Val{true}()` for automatic differentiation. + - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to + `nothing`, which means it will be chosen true/false depending on circumstances + of the solver, such as whether a Krylov subspace method is used for `linsolve`. + - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`. + Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and + `Val{:complex}`. + - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver. + For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify + `$name(linsolve = KLUFactorization()`). + When `nothing` is passed, uses `DefaultLinearSolver`. + - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/) + can be used as a left or right preconditioner. + Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` + function where the arguments are defined as: + - `W`: the current Jacobian of the nonlinear system. Specified as either + ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will + commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy + representation of the operator. Users can construct the W-matrix on demand + by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching + the `jac_prototype`. + - `du`: the current ODE derivative + - `u`: the current ODE state + - `p`: the ODE parameters + - `t`: the current ODE time + - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since + the last call to `precs`. It is recommended that this is checked to only + update the preconditioner when `newW == true`. + - `Plprev`: the previous `Pl`. + - `Prprev`: the previous `Pr`. + - `solverdata`: Optional extra data the solvers can give to the `precs` function. + Solver-dependent and subject to change. + The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners. + To specify one-sided preconditioning, simply return `nothing` for the preconditioner + which is not used. Additionally, `precs` must supply the dispatch: + ```julia + Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata) + ``` + which is used in the solver setup phase to construct the integrator + type with the preconditioners `(Pl,Pr)`. + The default is `precs=DEFAULT_PRECS` where the default preconditioner function + is defined as: + ```julia + DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing + ``` """ * extra_keyword_default keyword_default_description = """ diff --git a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl index 232dd2cd3d..226f92e57f 100644 --- a/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSDIRK/src/algorithms.jl @@ -15,14 +15,61 @@ function SDIRK_docstring(description::String, """ * extra_keyword_default keyword_default_description = """ - - `chunk_size`: TBD - - `autodiff`: TBD - - `standardtag`: TBD - - `concrete_jac`: TBD - - `diff_type`: TBD - - `linsolve`: TBD - - `precs`: TBD - - `nlsolve`: TBD + - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()` + and thus uses the internal ForwardDiff.jl algorithm for the choice. + - `autodiff`: Specifies whether to use automatic differentiation via + [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite + differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). + Defaults to `Val{true}()` for automatic differentiation. + - `standardtag`: Specifies whether to use package-specific tags instead of the + ForwardDiff default function-specific tags. For more information, see + [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/). + Defaults to `Val{true}()`. + - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to + `nothing`, which means it will be chosen true/false depending on circumstances + of the solver, such as whether a Krylov subspace method is used for `linsolve`. + - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`. + Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and + `Val{:complex}`. + - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver. + For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify + `$name(linsolve = KLUFactorization()`). + When `nothing` is passed, uses `DefaultLinearSolver`. + - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/) + can be used as a left or right preconditioner. + Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)` + function where the arguments are defined as: + - `W`: the current Jacobian of the nonlinear system. Specified as either + ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will + commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy + representation of the operator. Users can construct the W-matrix on demand + by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching + the `jac_prototype`. + - `du`: the current ODE derivative + - `u`: the current ODE state + - `p`: the ODE parameters + - `t`: the current ODE time + - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since + the last call to `precs`. It is recommended that this is checked to only + update the preconditioner when `newW == true`. + - `Plprev`: the previous `Pl`. + - `Prprev`: the previous `Pr`. + - `solverdata`: Optional extra data the solvers can give to the `precs` function. + Solver-dependent and subject to change. + The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners. + To specify one-sided preconditioning, simply return `nothing` for the preconditioner + which is not used. Additionally, `precs` must supply the dispatch: + ```julia + Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata) + ``` + which is used in the solver setup phase to construct the integrator + type with the preconditioners `(Pl,Pr)`. + The default is `precs=DEFAULT_PRECS` where the default preconditioner function + is defined as: + ```julia + DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing + ``` + - `nlsolve`: TBD """ * extra_keyword_description generic_solver_docstring( @@ -44,7 +91,7 @@ end extra_keyword_description = """ - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ extrapolant = :constant, @@ -84,7 +131,7 @@ end publisher={Springer Berlin Heidelberg New York}}", extra_keyword_description = """ - `extrapolant`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ extrapolant = :linear, @@ -124,7 +171,7 @@ estimate (the SPICE approximation strategy).""", extra_keyword_description = """ - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ extrapolant = :linear, @@ -174,7 +221,7 @@ end - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ smooth_est = true, @@ -221,7 +268,7 @@ TruncatedStacktraces.@truncate_stacktrace TRBDF2 - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ smooth_est = true, @@ -263,7 +310,7 @@ end - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ smooth_est = true, @@ -360,7 +407,7 @@ end - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ smooth_est = true, @@ -402,7 +449,7 @@ end - `smooth_est`: TBD - `extrapolant`: TBD - `controller`: TBD - - `step_limiter!`: TBD + - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)` """, extra_keyword_default = """ smooth_est = true, diff --git a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl index a33b72f562..7102b4ab26 100644 --- a/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqStabilizedRK/src/algorithms.jl @@ -7,8 +7,8 @@ and is smoothened to allow for moderate sized complex eigenvalues.""", """Assyr Abdulle, Alexei A. Medovikov. Second Order Chebyshev Methods based on Orthogonal Polynomials. Numerische Mathematik, 90 (1), pp 1-18, 2001. doi: https://dx.doi.org/10.1007/s002110100292""", """ - - `min_stages`: TBD - - `max_stages`: TBD + - `min_stages`: The minimum degree of the Chebyshev polynomial. + - `max_stages`: The maximumdegree of the Chebyshev polynomial. - `eigen_est`: function of the form `(integrator) -> integrator.eigen_est = upper_bound`, where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. @@ -37,8 +37,8 @@ and is smoothened to allow for moderate sized complex eigenvalues.""", Industrial and Applied Mathematics Journal on Scientific Computing, 23(6), pp 2041-2054, 2001. doi: https://doi.org/10.1137/S1064827500379549""", """ - - `min_stages`: TBD - - `max_stages`: TBD + - `min_stages`: The minimum degree of the Chebyshev polynomial. + - `max_stages`: The maximumdegree of the Chebyshev polynomial. - `eigen_est`: function of the form `(integrator) -> integrator.eigen_est = upper_bound`, where `upper_bound` is an estimated upper bound on the spectral radius of the Jacobian matrix. From 393a3385e297440daa3402a0b53f9eca4201b6f3 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 26 Aug 2024 01:50:47 +0200 Subject: [PATCH 82/83] cross platform size_treshhold_ignore --- docs/make.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 087a184f8c..c89cfdf07d 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -39,7 +39,7 @@ makedocs(sitename = "OrdinaryDiffEq.jl", format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], canonical = "https://ordinarydiffeq.sciml.ai/stable/", - size_threshold_ignore = ["implicit\\Rosenbrock.md"]), + size_threshold_ignore = [joinpath("implicit", "Rosenbrock.md")]), pages = [ "OrdinaryDiffEq.jl: ODE solvers and utilities" => "index.md", "Usage" => "usage.md", From 45f4d139fa5a00d2980dec42a12799f2892cd417 Mon Sep 17 00:00:00 2001 From: Christopher Rackauckas Date: Mon, 26 Aug 2024 06:30:58 -0400 Subject: [PATCH 83/83] Fix some algorithm locations --- docs/src/explicit/Extrapolation.md | 8 +-- docs/src/explicit/LowStorageRK.md | 3 +- docs/src/explicit/SSPRK.md | 3 +- .../src/algorithms.jl | 48 ++++++++++++------ lib/OrdinaryDiffEqSSPRK/src/algorithms.jl | 50 +++++-------------- 5 files changed, 53 insertions(+), 59 deletions(-) diff --git a/docs/src/explicit/Extrapolation.md b/docs/src/explicit/Extrapolation.md index 892a99e60f..d7af024207 100644 --- a/docs/src/explicit/Extrapolation.md +++ b/docs/src/explicit/Extrapolation.md @@ -3,9 +3,11 @@ CollapsedDocStrings = true ``` # OrdinaryDiffEqExtrapolation -Solvers based on within method parallelism. -The explicit solvers are outclassed by other explicit methods. -However, some [stiff extrapolation](@ref StiffExtrapolation) methods perform very well. +Solvers based on within method parallelism, allowing multithreading of the solution across +different values of `f`. +The explicit extrapolation solvers are generally outclassed by other explicit methods. +However, some [stiff extrapolation](@ref StiffExtrapolation) methods perform very well if +the problem is sufficiently stiff. ```@eval first_steps = evalfile("./common_first_steps.jl") diff --git a/docs/src/explicit/LowStorageRK.md b/docs/src/explicit/LowStorageRK.md index 127f6fbb8a..6b99b8664c 100644 --- a/docs/src/explicit/LowStorageRK.md +++ b/docs/src/explicit/LowStorageRK.md @@ -60,5 +60,6 @@ RDPK3Sp510 RDPK3SpFSAL510 HSLDDRK64 NDBLSRK134 -KYK2014DGSSPRK_3S2 +SHLDDRK_2N +SHLDDRK52 ``` diff --git a/docs/src/explicit/SSPRK.md b/docs/src/explicit/SSPRK.md index de235d181f..18d6ae71a4 100644 --- a/docs/src/explicit/SSPRK.md +++ b/docs/src/explicit/SSPRK.md @@ -23,6 +23,7 @@ SSPRK22 SSPRK33 SSPRK53 KYKSSPRK42 +KYK2014DGSSPRK_3S2 SSPRK53_2N1 SSPRK53_2N2 SSPRK53_H @@ -36,6 +37,4 @@ SSPRKMSVS32 SSPRK932 SSPRK54 SSPRK104 -SHLDDRK_2N -SHLDDRK52 ``` diff --git a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl index e86126fd32..fb4252531e 100644 --- a/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqLowStorageRK/src/algorithms.jl @@ -1058,28 +1058,44 @@ function NDBLSRK134(stage_limiter!, step_limiter! = trivial_limiter!; williamson_condition) end -#SSP Optimized Runge-Kutta Methods - @doc explicit_rk_docstring( - "Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", - "KYK2014DGSSPRK_3S2", - references = """@article{kubatko2014optimal, - title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, - author={Kubatko, Ethan J and Yeager, Benjamin A and Ketcheson, David I}, - journal={Journal of Scientific Computing}, - volume={60}, - pages={313--344}, - year={2014}, - publisher={Springer}}""") -Base.@kwdef struct KYK2014DGSSPRK_3S2{StageLimiter, StepLimiter, Thread} <: - OrdinaryDiffEqAlgorithm + "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", + "SHLDDRK_2N", + references = "@article{stanescu19982n, + title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, + author={Stanescu, D and Habashi, WG}, + journal={Journal of Computational Physics}, + volume={143}, + number={2}, + pages={674--681}, + year={1998}, + publisher={Elsevier}}") +Base.@kwdef struct SHLDDRK_2N{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() end # for backwards compatibility -function KYK2014DGSSPRK_3S2(stage_limiter!, step_limiter! = trivial_limiter!) - KYK2014DGSSPRK_3S2(stage_limiter!, +function SHLDDRK_2N(stage_limiter!, step_limiter! = trivial_limiter!) + SHLDDRK_2N(stage_limiter!, step_limiter!, False()) end + +@doc explicit_rk_docstring( + "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", + "SHLDDRK52", + references = "@article{stanescu19982n, + title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, + author={Stanescu, D and Habashi, WG}, + journal={Journal of Computational Physics}, + volume={143}, + number={2}, + pages={674--681}, + year={1998}, + publisher={Elsevier}}") +Base.@kwdef struct SHLDDRK52{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm + stage_limiter!::StageLimiter = trivial_limiter! + step_limiter!::StepLimiter = trivial_limiter! + thread::Thread = False() +end diff --git a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl index 3bda97a6a6..f28ca2b71a 100644 --- a/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl +++ b/lib/OrdinaryDiffEqSSPRK/src/algorithms.jl @@ -320,30 +320,6 @@ function SSPRK33(stage_limiter!, step_limiter! = trivial_limiter!) step_limiter!, False()) end -@doc explicit_rk_docstring( - "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", - "SHLDDRK_2N", - references = "@article{stanescu19982n, - title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, - author={Stanescu, D and Habashi, WG}, - journal={Journal of Computational Physics}, - volume={143}, - number={2}, - pages={674--681}, - year={1998}, - publisher={Elsevier}}") -Base.@kwdef struct SHLDDRK_2N{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm - stage_limiter!::StageLimiter = trivial_limiter! - step_limiter!::StepLimiter = trivial_limiter! - thread::Thread = False() -end -# for backwards compatibility -function SHLDDRK_2N(stage_limiter!, step_limiter! = trivial_limiter!) - SHLDDRK_2N(stage_limiter!, - step_limiter!, - False()) -end - @doc explicit_rk_docstring( "Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", "KYKSSPRK42", @@ -368,18 +344,18 @@ function KYKSSPRK42(stage_limiter!, step_limiter! = trivial_limiter!) end @doc explicit_rk_docstring( - "Low dissipation and dispersion Runge-Kutta schemes for computational acoustics", - "SHLDDRK52", - references = "@article{stanescu19982n, - title={2N-storage low dissipation and dispersion Runge-Kutta schemes for computational acoustics}, - author={Stanescu, D and Habashi, WG}, - journal={Journal of Computational Physics}, - volume={143}, - number={2}, - pages={674--681}, - year={1998}, - publisher={Elsevier}}") -Base.@kwdef struct SHLDDRK52{StageLimiter, StepLimiter, Thread} <: OrdinaryDiffEqAlgorithm + "Optimal strong-stability-preserving Runge-Kutta time discretizations for discontinuous Galerkin methods", + "KYK2014DGSSPRK_3S2", + references = """@article{kubatko2014optimal, + title={Optimal strong-stability-preserving Runge--Kutta time discretizations for discontinuous Galerkin methods}, + author={Kubatko, Ethan J and Yeager, Benjamin A and Ketcheson, David I}, + journal={Journal of Scientific Computing}, + volume={60}, + pages={313--344}, + year={2014}, + publisher={Springer}}""") +Base.@kwdef struct KYK2014DGSSPRK_3S2{StageLimiter, StepLimiter, Thread} <: + OrdinaryDiffEqAlgorithm stage_limiter!::StageLimiter = trivial_limiter! step_limiter!::StepLimiter = trivial_limiter! thread::Thread = False() @@ -389,4 +365,4 @@ function KYK2014DGSSPRK_3S2(stage_limiter!, step_limiter! = trivial_limiter!) KYK2014DGSSPRK_3S2(stage_limiter!, step_limiter!, False()) -end \ No newline at end of file +end