API

All exported types and functions are considered part of the public API, and thus documented in this manual.

NSDERungeKutta.AdaptiveParametersType
AdaptiveParameters <: AbstractAdaptiveParameters

A composite type for the parameters of an adaptive AbstractRungeKuttaSolver.

Constructors

AdaptiveParameters(εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100)

Arguments

  • εₐ :: Real : absolute tolerance
  • εᵣ :: Real : relative tolerance
  • Mₙ :: Integer : maximum number of iterations
source
NSDERungeKutta.ButcherTableauType
ButcherTableau <: AbstractButcherTableau

A composite type for the Butcher tableau of a Runge-Kutta solver:

\[\begin{array}{c|c} c & A \\ \hline p & b^\intercal \\ q & d^\intercal \end{array}\]

Constructors

ButcherTableau(A, b, c, s, p[, d, q])
ButcherTableau(tableau::AbstractMatrix{<:Real})

Arguments

  • A :: AbstractMatrix{<:Real} : matrix of coefficients
  • b :: AbstractVector{<:Real} : vector of weights
  • c :: AbstractVector{<:Real} : vector of nodes
  • s :: Integer : number of stages
  • p :: Integer : order of accuracy
  • d :: AbstractVector{<:Real} : embedding's vector of weights (can be nothing)
  • q :: Integer : embedding's order of accuracy (can be nothing)
  • b_dense :: AbstractMatrix{<:Real} : matrix where col j is powers of theta for stage j

Functions

butchertableau : return matrix of parameters.

source
NSDERungeKutta.DiagonallyImplicitRungeKuttaSolverType
DiagonallyImplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for diagonally-implicit solvers.

Constructors

DiagonallyImplicitRungeKuttaSolver(tableau, stepsize, newton[, adaptive])
DIRK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters : step-size control for an embedded tableau. Note the current limit: a Newton failure inside an adaptive implicit step is thrown as a NewtonFailure before the controller can reject the step. Automatic retry with a shorter step is not implemented for implicit solvers in this release; the named DIRK/IRK/IERK solvers are fixed-step and are unaffected.

Methods

(solver::DiagonallyImplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::DiagonallyImplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ExplicitRungeKuttaSolverType
ExplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for explicit solvers.

Constructors

ExplicitRungeKuttaSolver(tableau, stepsize[, adaptive])
ERK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ExplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ExplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ExponentialRungeKuttaSolverType
ExponentialRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for one-step exponential Runge-Kutta solvers of semilinear problems u' = Lu + g(t) + fₙₛ(u, t), supplied as a NSDEBase.SplitRightHandSide whose stiff part is a NSDEBase.LinearRightHandSide, or as a plain LinearRightHandSide (on which every scheme propagates the linear flow exactly, up to the Padé accuracy of the precomputed exponential).

Constructors

ExponentialRungeKuttaSolver(tableau, stepsize[, adaptive])
EXPRK(args...; kwargs...)

Arguments

  • tableau :: ExponentialTableau
  • stepsize :: AbstractStepSize
  • adaptive :: Nothing : adaptive stepping is STRUCTURALLY rejected: the φ-coefficient operators are evaluated once at z = h⋅L when the cache is built, which is the entire efficiency argument for these methods at fixed h; recomputing them on every rejected step would defeat it. Passing adaptive parameters throws at construction, mirroring the IMEX solvers.

Methods

(solver::ExponentialRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ExponentialRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ExponentialTableauType
ExponentialTableau <: AbstractRungeKuttaParameters

A composite type for the coefficient functions of a one-step exponential Runge-Kutta method for $u' = Lu + g(t) + f_\text{ns}(u, t)$. Unlike a ButcherTableau, whose entries are numbers, an exponential tableau's entries are OPERATORS — linear combinations of $\varphi$-functions and exponentials evaluated at $z = hL$ — so the tableau stores a coefficient FUNCTION κ and the solver cache evaluates it once per solve.

Following EXPINT's scheme-file convention (with nothing in place of Matlab's []), κ(z) must return the tuple (U, V, A, B) where, for s stages,

  • U :: Vector (length s) : the operators applied to u[n] in each stage,
  • V : the operator applied to u[n] in the update ($e^z$ for every scheme implemented here),
  • A :: Matrix (s × s, strictly lower triangular, nothing for absent entries) : the stage-coupling operators,
  • B :: Vector (length s, nothing for absent entries) : the weights,

so that a step reads $U_i = U_i u_n + h \sum_{j<i} A_{ij} k_j$, $k_i = f_\text{ns}(U_i, t_n + c_i h) + g(t_n + c_i h)$ and $u_{n+1} = V u_n + h \sum_i B_i k_i$.

Arguments

  • name :: Symbol : the method's name.
  • p :: Integer : classical (non-stiff) order.
  • q :: Integer : stiff order in the sense of Hochbruck–Ostermann, as stated in EXPINT's scheme headers. For semilinear stiff PDEs the observed order is governed by q, not p.
  • s :: Integer : number of stages.
  • c :: AbstractVector{<:Real} : quadrature nodes.
  • κ :: Function : the coefficient function described above.
source
NSDERungeKutta.ImplicitExplicitRungeKuttaSolverType
ImplicitExplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for implicit-explicit solvers.

Constructors

ImplicitExplicitRungeKuttaSolver(implicitableau, explicitableau, stepsize, newton[, adaptive])
IERK(args...; kwargs...)

Arguments

  • implicitableau :: AbstractButcherTableau
  • explicitableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ImplicitExplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ImplicitExplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ImplicitRungeKuttaSolverType
ImplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for implicit solvers.

Constructors

ImplicitRungeKuttaSolver(tableau, stepsize, newton[, adaptive])
IRK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ImplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ImplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.NewtonFailureType
NewtonFailure <: Exception

thrown by an implicit Runge-Kutta step when simplified Newton cannot bring the stage residual within tolerance: either Mₙ updates were spent, or the iteration left the finite range. Carries the time t of the step, the stage (0 for a fully coupled IRK system), the number of updates taken, the last residual norm and the tolerance it failed to meet. Catch it to reject or shorten the step; do not use the stage.

Adaptive implicit solvers do not yet recover from this on their own: the exception is raised before the step-size controller sees the step. That is a known limit of this release, not a promise the controller makes.

source
NSDERungeKutta.NewtonParametersType
NewtonParameters <: AbstractNewtonParameters

A composite type for the parameters of simplified Newton.

Constructors

NewtonParameters(; εᵣ=1e-8, εₐ=1e-12, Mₙ=10)

Arguments

  • εᵣ :: Real : relative tolerance
  • εₐ :: Real : absolute tolerance
  • Mₙ :: Integer : maximum number of Newton updates

A stage is accepted when its nonlinear RESIDUAL r — the amount by which the current iterate fails the stage equation — satisfies ‖r‖ ≤ εₐ + εᵣ·scale, where scale is the larger of the iterate's norm and the norm of the right-hand side it is compared against. The residual is what is checked, not the size of the last update: a tiny update is also what a stalled or badly-scaled iteration produces, so on its own it proves nothing. Non-finite iterates or residuals are never accepted. If Mₙ updates pass without acceptance, the step throws a NewtonFailure; an unconverged stage is never used.

Tolerances must be finite and non-negative; Mₙ ≥ 1.

The default εᵣ = 1e-8 is tighter than the 1e-3 of the former increment-based test. This is a deliberate accuracy choice for a bound that now applies to the residual of the iterate actually used; its cost relative to the old test has not been benchmarked.

source
NSDERungeKutta.RungeKuttaSolutionType
RungeKuttaSolution <: AbstractRungeKuttaSolution

A composite type for an AbstractRungeKuttaSolution obtained using an AbstractRungeKuttaSolver.

Constructors

RungeKuttaSolution(u, t, k)
RungeKuttaSolution(problem, solver; dense=false)

Arguments

  • u :: AbstractVector{<:AbstractVector{<:Number}} : numerical solution
  • t :: AbstractVector{<:Real} : time grid
  • k :: AbstractVector{<:AbstractVector{<:AbstractVector{<:Number}}} : stages history (for dense output)

Functions

source
NSDERungeKutta.RungeKuttaSolutionMethod
(solution::RungeKuttaSolution)(tₚ::Real, f::Function)

uses Hermite's cubic splines to interpolate solution and approximate its value at tₚ. Note that it needs the derivative function f(u, t), e.g. from an NSDEBase.AbstractRightHandSide subtype.

source
NSDERungeKutta.RungeKuttaSolutionMethod
(solution::RungeKuttaSolution)(tₚ::Real, tableau::AbstractButcherTableau)

Evaluates the dense output solution at tₚ using the stored stages and tableau coefficients.

source
NSDERungeKutta.StepSizeType
StepSize <: AbstractStepSize

A composite type for the step-size a Runge-Kutta solver.

Constructors

StepSize(h::Real)

Functions

stepsize : returns (last) step-size

source
NSDERungeKutta.StepSizesType
StepSizes

The REALISED step-size history of an adaptive run (opt-in via save_stepsizes = true):

  • accepted[i] is exactly the i-th step taken, so hs.accepted == diff(solution.t) — the record is what happened, never the controller's proposal for the next attempt.
  • rejected[i] holds the step sizes tried and REJECTED before accepted step i (the values that failed, not the reduced retries they triggered). A trailing empty bin is opened at every acceptance, so length(rejected) == length(accepted) + 1 and the last bin is empty at the end of a completed run.
source
Base.firstindexMethod
firstindex(solution::RungeKuttaSolution)

returns the first index of solution.

source
Base.getindexMethod
getindex(solution::RungeKuttaSolution, v::AbstractUnitRange) :: RungeKuttaSolution

returns a new RungeKuttaSolution containing the fields of solution at the contiguous nodes v, together with the stage history of the length(v) − 1 intervals between them (when solution is dense).

source
Base.getindexMethod
getindex(solution::RungeKuttaSolution, v::AbstractVector) :: RungeKuttaSolution

returns a new RungeKuttaSolution containing the fields of solution at the nodes v. For a non-contiguous selection of a dense solution the stored stage polynomials do not describe the gaps between the chosen nodes, so the request is refused with an ArgumentError; slice solution.u and solution.t directly if only the nodes are wanted.

source
Base.getindexMethod
getindex(solution::RungeKuttaSolution, i::Integer) :: RungeKuttaSolution

returns a new RungeKuttaSolution containing the fields of solution at node i. A single node carries no interval, so the slice has no dense stage history even when solution does.

source
Base.lastindexMethod
lastindex(solution::RungeKuttaSolution)

returns the last index of solution.

source
Base.lengthMethod
length(solution::RungeKuttaSolution)

returns the number of time steps in solution.

source
Base.setindex!Method
setindex!(solution::RungeKuttaSolution, values::RungeKuttaSolution, v::AbstractVector)

stores the nodes of values at the nodes v of solution. On a non-dense target any v is accepted. On a dense target the write must cover the WHOLE solution — v equal to 1:length(solution) and values dense with the matching length(v) − 1 interval stages — so that nodes and stages are replaced together; anything less is refused (see the note above). All checks run before anything is modified.

source
Base.setindex!Method
setindex!(solution::RungeKuttaSolution, values::RungeKuttaSolution, i::Integer)

stores the single node held by values (e.g. from getindex) at node i of a non-dense solution. A dense solution refuses the write (see the note on partial writes above).

source
Base.setindex!Method
setindex!(solution::RungeKuttaSolution, values::Tuple, i::Integer)

stores (u, t) from values at node i of a non-dense solution. A dense solution refuses the write (see the note on partial writes above).

source
Base.sizeMethod
size(solution::RungeKuttaSolution)

returns a tuple containing the number of variables and time steps in solution.

source
NSDEBase.initialize_cacheMethod
initialize_cache(problem::AbstractInitialValueProblem, solver::AbstractRungeKuttaSolver)

builds a cache for a Runge-Kutta solver.

source
NSDEBase.initialize_solutionMethod
initialize_solution(problem::AbstractInitialValueProblem, solver::AbstractRungeKuttaSolver; kwargs...)

builds an empty solution object for a Runge-Kutta solver.

source
NSDEBase.solve!Method
solve!(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem, solver::AbstractRungeKuttaSolver) :: RungeKuttaSolution

computes the solution of problem using solver, allocating a new cache.

source
NSDEBase.solve!Method
solve!(cache::AbstractRungeKuttaCache, solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem, solver::AbstractRungeKuttaSolver) :: RungeKuttaSolution

computes the solution of problem using solver and a pre-allocated cache.

source
NSDEBase.solveMethod
solve(problem::AbstractInitialValueProblem, solver::AbstractRungeKuttaSolver; dense::Bool=false, kwargs...) :: RungeKuttaSolution

computes the solution of problem using solver.

source
NSDERungeKutta.DIRKMethod
DiagonallyImplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for diagonally-implicit solvers.

Constructors

DiagonallyImplicitRungeKuttaSolver(tableau, stepsize, newton[, adaptive])
DIRK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters : step-size control for an embedded tableau. Note the current limit: a Newton failure inside an adaptive implicit step is thrown as a NewtonFailure before the controller can reject the step. Automatic retry with a shorter step is not implemented for implicit solvers in this release; the named DIRK/IRK/IERK solvers are fixed-step and are unaffected.

Methods

(solver::DiagonallyImplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::DiagonallyImplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.DP54Method
DormandPrince54(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
DP54(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 5th-order Dormand-Prince method with 4th-order error estimate.

source
NSDERungeKutta.DormandPrince54Method
DormandPrince54(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
DP54(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 5th-order Dormand-Prince method with 4th-order error estimate.

source
NSDERungeKutta.ERKMethod
ExplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for explicit solvers.

Constructors

ExplicitRungeKuttaSolver(tableau, stepsize[, adaptive])
ERK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ExplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ExplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ETD2RKMethod
ETD2RK(; h::Real=0.0) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the 2-stage ETD2RK method (Cox & Matthews 2002, eq. 26), classical order 2, stiff order 2.

Deliberate deviation from the EXPINT source

EXPINT's shipped etd2rk.m (rev. 1.6) sets b = {φ₁ - 2φ₂, φ₂}, which violates the first order condition Σᵢ bᵢ(z) = φ₁(z) — the sum comes to φ₁ - φ₂ — so the shipped scheme is not even consistent (numerically it stalls at order 0 with an O(1) bias). The file is a chimera of the Hochbruck–Ostermann one-parameter family: b₁ = φ₁ - 2φ₂ belongs to the midpoint variant (c₂ = ½, weights [φ₁ - 2φ₂, 2φ₂]), while the stages it ships (U₂ = eᶻ, a₂₁ = φ₁, c₂ = 1) belong to the endpoint variant with weights [φ₁ - φ₂, φ₂] — note the file even computes φ₁(z/2) and never uses it, a leftover of the midpoint form. This port implements the endpoint variant with the CORRECT weights, matching Cox & Matthews.

source
NSDERungeKutta.ETD4RKMethod
ETD4RK(; h::Real=0.0) :: ExponentialRungeKuttaSolver
ETDRK4(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the classic 4-stage Cox–Matthews method (Cox & Matthews 2002), classical order 4, stiff order 2 (the well-documented order reduction on stiff semilinear problems; see Krogstad 2005 and HochbruckOstermann4 for stiff orders 3 and 4).

source
NSDERungeKutta.ETDEulerMethod
NorsettEuler(; h::Real=0.0) :: ExponentialRungeKuttaSolver
ETDEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver
ExponentialEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the Nørsett–Euler method (also known as ETD-Euler, exponentially fitted Euler, or filtered Euler), classical order 1, stiff order 1. Exact for constant non-stiff parts at any step size, since b₁ = φ₁ integrates a constant integrand exactly.

source
NSDERungeKutta.ETDRK4Method
ETD4RK(; h::Real=0.0) :: ExponentialRungeKuttaSolver
ETDRK4(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the classic 4-stage Cox–Matthews method (Cox & Matthews 2002), classical order 4, stiff order 2 (the well-documented order reduction on stiff semilinear problems; see Krogstad 2005 and HochbruckOstermann4 for stiff orders 3 and 4).

source
NSDERungeKutta.EXPRKMethod
ExponentialRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for one-step exponential Runge-Kutta solvers of semilinear problems u' = Lu + g(t) + fₙₛ(u, t), supplied as a NSDEBase.SplitRightHandSide whose stiff part is a NSDEBase.LinearRightHandSide, or as a plain LinearRightHandSide (on which every scheme propagates the linear flow exactly, up to the Padé accuracy of the precomputed exponential).

Constructors

ExponentialRungeKuttaSolver(tableau, stepsize[, adaptive])
EXPRK(args...; kwargs...)

Arguments

  • tableau :: ExponentialTableau
  • stepsize :: AbstractStepSize
  • adaptive :: Nothing : adaptive stepping is STRUCTURALLY rejected: the φ-coefficient operators are evaluated once at z = h⋅L when the cache is built, which is the entire efficiency argument for these methods at fixed h; recomputing them on every rejected step would defeat it. Passing adaptive parameters throws at construction, mirroring the IMEX solvers.

Methods

(solver::ExponentialRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ExponentialRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.ExponentialEulerMethod
NorsettEuler(; h::Real=0.0) :: ExponentialRungeKuttaSolver
ETDEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver
ExponentialEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the Nørsett–Euler method (also known as ETD-Euler, exponentially fitted Euler, or filtered Euler), classical order 1, stiff order 1. Exact for constant non-stiff parts at any step size, since b₁ = φ₁ integrates a constant integrand exactly.

source
NSDERungeKutta.F45Method
Fehlberg45(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
F45(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 4th-order Fehlberg method with 5th-order error estimate.

source
NSDERungeKutta.F78Method
Fehlberg78(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
F78(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 7th-order Fehlberg method with 8th-order error estimate.

source
NSDERungeKutta.Fehlberg45Method
Fehlberg45(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
F45(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 4th-order Fehlberg method with 5th-order error estimate.

source
NSDERungeKutta.Fehlberg78Method
Fehlberg78(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
F78(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 7th-order Fehlberg method with 8th-order error estimate.

source
NSDERungeKutta.HeunEulerMethod
HeunEuler(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 2nd-order Heun-Euler method with 1st-order error estimate.

source
NSDERungeKutta.HochOst4Method
HochbruckOstermann4(; h::Real=0.0) :: ExponentialRungeKuttaSolver
HochOst4(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the 5-stage exponential Runge-Kutta method of Hochbruck & Ostermann (2005, p. 19), classical order 4 and STIFF order 4 — the method of choice for stiff semilinear PDEs among the schemes implemented here.

source
NSDERungeKutta.HochbruckOstermann4Method
HochbruckOstermann4(; h::Real=0.0) :: ExponentialRungeKuttaSolver
HochOst4(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the 5-stage exponential Runge-Kutta method of Hochbruck & Ostermann (2005, p. 19), classical order 4 and STIFF order 4 — the method of choice for stiff semilinear PDEs among the schemes implemented here.

source
NSDERungeKutta.IERKMethod
ImplicitExplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for implicit-explicit solvers.

Constructors

ImplicitExplicitRungeKuttaSolver(implicitableau, explicitableau, stepsize, newton[, adaptive])
IERK(args...; kwargs...)

Arguments

  • implicitableau :: AbstractButcherTableau
  • explicitableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ImplicitExplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ImplicitExplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.IMEXSSP3_332Method
IMEXSSP3_332(; h::Real=0.0, εᵣ::Real=1e-8, εₐ::Real=1e-12, Mₙ::Integer=10) :: ImplicitExplicitRungeKuttaSolver

returns an ImplicitExplicitRungeKuttaSolver for the 2nd-order IMEX-SSP3(3,3,2) L-stable scheme. (In the SSPk(s,σ,p) naming, k is the SSP order of the explicit part and the final p is the order of the IMEX scheme itself: this one pairs the 3rd-order SSPRK3 explicit part with an L-stable implicit part into an order-2 scheme.)

source
NSDERungeKutta.IRKMethod
ImplicitRungeKuttaSolver <: AbstractRungeKuttaSolver

A composite type for implicit solvers.

Constructors

ImplicitRungeKuttaSolver(tableau, stepsize, newton[, adaptive])
IRK(args...; kwargs...)

Arguments

  • tableau :: AbstractButcherTableau
  • stepsize :: AbstractStepSize
  • newton :: AbstractNewtonParameters
  • adaptive :: AbstractAdaptiveParameters

Methods

(solver::ImplicitRungeKuttaSolver)(solution::AbstractRungeKuttaSolution, problem::AbstractInitialValueProblem) :: RungeKuttaSolution
(solver::ImplicitRungeKuttaSolver)(problem::AbstractInitialValueProblem) :: RungeKuttaSolution

returns the solution of a problem using solver.

source
NSDERungeKutta.NorsettEulerMethod
NorsettEuler(; h::Real=0.0) :: ExponentialRungeKuttaSolver
ETDEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver
ExponentialEuler(args...; kwargs...) :: ExponentialRungeKuttaSolver

returns an ExponentialRungeKuttaSolver for the Nørsett–Euler method (also known as ETD-Euler, exponentially fitted Euler, or filtered Euler), classical order 1, stiff order 1. Exact for constant non-stiff parts at any step size, since b₁ = φ₁ integrates a constant integrand exactly.

source
NSDERungeKutta.V65Method
Verner65(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
V65(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 6th-order Verner method with 5th-order error estimate.

source
NSDERungeKutta.Verner65Method
Verner65(; h::Real=0.0, εₐ::Real=0.0, εᵣ::Real=1e-5, Mₙ::Integer=100, save_stepsizes::Bool=false) :: ExplicitRungeKuttaSolver
V65(args...; kwargs...) :: ExplicitRungeKuttaSolver

returns an ExplicitRungeKuttaSolver for the 6th-order Verner method with 5th-order error estimate.

source
NSDERungeKutta.adaptivestep!Method
adaptivestep!(cache, solution, solver, adaptive::AbstractAdaptiveParameters)

the generic embedded-pair step-size controller. It reads only the stages k and counters from the cache and the embedded weights d from the tableau, so it is family-agnostic: any solver whose tableau carries an embedded pair gets adaptivity from this one method. (Construction-time check_adaptive guarantees d and q are present whenever this is reached.)

source
NSDERungeKutta.check_adaptiveMethod
check_adaptive(tableau::AbstractButcherTableau, adaptive) :: Nothing

throws an ArgumentError if adaptive parameters are given but tableau carries no embedded pair (d, q). Adaptive stepping needs an embedded method; failing at construction beats silently stepping at fixed size.

source
NSDERungeKutta.compensated_sumMethod
compensated_sum(sum::T, addend::T, error::Ref{T}) where T<:AbstractFloat

Adds addend to sum using the Kahan-Babuška-Neumaier algorithm to minimize floating-point round-off error. The accumulated error is stored in the error Ref.

source
NSDERungeKutta.directldiv!Method
directldiv!(M, v)

In-place left-division v = M \ v for a factorisation M. Identical to LinearAlgebra.ldiv!(M, v) except for factorisation types that ship without a two-argument in-place method — notably SparseArrays.CHOLMOD.Factor, which factorize returns for symmetric positive-definite SPARSE matrices (i.e. every method-of-lines Laplacian fed to the direct-linear DIRK/IERK/IRK branches as I - hA⋅L) and which supports only \ (checked through Julia 1.13). The fallback allocates one vector per call; the per-step factorize sitting next to every call site already allocates strictly more, so the hot-path cost is unchanged in order. CHOLMOD's \ also handles a complex right-hand side against a real factor (real/imaginary split), covering the iscomplex spectral path.

source
NSDERungeKutta.expphifunctionsFunction
expphifunctions(z, K::Integer; d::Integer=13) :: Tuple

evaluates $e^z$ TOGETHER with $\varphi_1(z), \dots, \varphi_K(z)$, returning the tuple (ez, φ) where φ is the Vector that phifunctions returns. The exponential is the one carried through the scaling-and-squaring chain, NOT a reconstruction from the identity $e^z = z\varphi_1(z) + I$. The distinction matters under strong damping: the reconstruction is only ABSOLUTELY accurate — once $\lVert e^z \rVert$ falls below the unit roundoff of $\lVert z\varphi_1(z) \rVert$ (real spectrum below about $-37$) it returns 0 or roundoff junk with UNBOUNDED relative error — whereas the squaring chain starts from $z_s\varphi_1(z_s) + I$ at the scaled argument, where $\lVert e^{z_s} \rVert \ge e^{-4}$ is far above roundoff, and repeated squaring preserves relative accuracy down to the underflow threshold ($e^{-700}$ to $\sim 10^{-13}$ relative). Solver coefficients built from this function damp stiff modes to their true $e^{h\lambda}$ instead of a $10^{-16}$ roundoff floor.

Dispatch mirrors phifunctions: Number, Diagonal (elementwise), dense AbstractMatrix, and sparse (diagonal sparse → Diagonal; general sparse densified).

source
NSDERungeKutta.extractMethod
extract(solution::RungeKuttaSolution, v::AbstractVector) :: RungeKuttaSolution

returns the variables of solution indicated by the indices v.

source
NSDERungeKutta.extractMethod
extract(solution::RungeKuttaSolution, i::Integer) :: RungeKuttaSolution

returns the i-th variable of solution. i = 0 returns t.

source
NSDERungeKutta.extractMethod
extract(solution::RungeKuttaSolution) :: RungeKuttaSolution

returns all variables of solution, including t.

source
NSDERungeKutta.fixedstep_countMethod
fixedstep_count(solver, t0, tN) :: Int

the number of steps M after which a FIXED-step schedule t0 + M h reaches tN, or 0 when it does not: the step does not divide the span, or the solver is adaptive (its schedule is not known in advance).

Divisibility is judged on the LOCAL quotient q = (tN − t0) / h alone: q must sit within a few ulps of itself of an integer. Nothing here depends on the absolute time origin — an ulp of |t0| can be larger than h far from the origin, and any allowance in those units would wave through a schedule that misses tN by a real fraction of a step. Where the span subtraction is inexact the test can only fail to recognise a dividing schedule, which falls back to the ordinary end-of-loop policy (a final node at or beyond tN).

source
NSDERungeKutta.newton_acceptMethod
newton_accept(rnorm, tol) :: Bool

true only for a FINITE residual norm within a finite tolerance. Inf ≤ Inf and NaN comparisons are both false here on purpose.

source
NSDERungeKutta.newton_toleranceMethod
newton_tolerance(newton, xnorm, fnorm) :: Real

the residual bound εₐ + εᵣ·max(xnorm, fnorm), or NaN if either scale is not finite (which no residual can satisfy).

source
NSDERungeKutta.padecoefficientsMethod
padecoefficients(d::Integer, K::Integer)

returns the numerator and denominator coefficient vectors (each of length $d + 1$, constant term first) of the renormalised diagonal $(d,d)$-Padé approximants to $\varphi_1, \dots, \varphi_K$, via W. Wright's recurrences as implemented in EXPINT's pade_cof. The common normalisation cancels in the division; the value at 0 is $\varphi_k(0) = 1/k!$ by construction. All arithmetic is floating-point from the outset: the leading constant $(2d+1)!/d!$ overflows Int64 already at $d = 13$.

source
NSDERungeKutta.phifunctionsFunction
phifunctions(z, K::Integer; d::Integer=13) :: Vector

evaluates the exponential-integrator functions

\[\varphi_k(z) = \frac{1}{(k-1)!} \int_0^1 e^{z(1-\theta)} \theta^{k-1} \, \mathrm{d}\theta, \qquad \varphi_k(0) = \frac{1}{k!},\]

for $k = 1, \dots, K$, returning them as a Vector in ascending order. The algorithm is the diagonal $(d,d)$-Padé approximation with scaling and squaring from the EXPINT package (Berland, Skaflestad & Wright, ACM TOMS 33(1), 2007), using W. Wright's renormalised coefficient recurrences and squaring formulae. It is a faithful port of EXPINT's phipade.m with these deliberate deviations:

  • No persistent global cache: in EXPINT, phipade memoises across calls via persistent state. Here the SOLVER CACHE owns the computed operators (they are evaluated once per solve at $z = h L$), which is deterministic and thread-safe — global memoisation would be a data race under threaded Parareal.
  • Polynomials are evaluated by an even/odd-split Horner rule rather than the Golub–Van Loan partitioned scheme of mat_pol; at the degrees used here ($d \le 13$) the two coincide in operation count and differ only by roundoff-neutral reassociation.
  • $e^z$ is recovered from the identity $z\varphi_1(z) + I$ instead of a separate matrix exponential, consistent with the squaring stage.
  • The default Padé degree is $d = 13$ rather than EXPINT's 7. EXPINT's default trades accuracy near the scaling threshold (relative errors up to $\sim 10^{-10}$ at $\lVert z \rVert_\infty \approx 4$) for per-call speed, and its own highest-order scheme (hochost4) overrides it to 13. Here the coefficients are evaluated ONCE per solve, so the speed argument vanishes and $d = 13$ holds the boundary error at roundoff ($\lesssim 3 \times 10^{-14}$ in testing).

Arguments

  • z : evaluation point, one of Number, Diagonal (evaluated elementwise — the fast path for spectral discretisations), dense AbstractMatrix, or sparse. Sparse DIAGONAL matrices are converted to Diagonal; general sparse matrices are densified, since $\varphi_k$ of a sparse matrix is dense anyway. Krylov $\varphi$-actions for genuinely large sparse operators are out of scope of this direct method.
  • K : highest $\varphi$ index required.
  • d : degree of the diagonal Padé approximant (default 13; see above).
source
NSDERungeKutta.stability_functionMethod
stability_function(Z::AbstractMatrix, tableau::AbstractButcherTableau) :: AbstractMatrix
stability_function(Z::AbstractMatrix, solver::AbstractRungeKuttaSolver) :: AbstractMatrix

Computes the matrix stability function $R(Z) = I + (b^\top \otimes Z) (I \otimes I - A \otimes Z)^{-1} (\mathbb{1} \otimes I)$. This builds and solves a Kronecker system of size $sN \times sN$; avoid for large systems.

source
NSDERungeKutta.stability_functionMethod
stability_function(z::Number, tableau::AbstractButcherTableau) :: Number
stability_function(z::Number, solver::AbstractRungeKuttaSolver) :: Number

Computes the scalar stability function $R(z) = 1 + z b^\top (I - zA)^{-1} \mathbb{1}$.

source