Ensembles

EnsembleProblem: stores a GeometricEquation together with multiple sets of initial conditions and/or parameters, a time span for integration and a time step size.

An EnsembleProblem is initialized by providing a GeometricEquation, an integration time span (typically a tuple with two values, start and end time, respectively), a timestep, and one of the three following options:

• a vector of initial conditions and a vector of parameter sets, with both vectors having the same length,
• a vector of initial conditions and a single set of parameters,
• a single initial condition and a vector of parameter sets.

Each initial condition is a NamedTuple that contains one field for each state variable. Each parameter set is either a NamedTuple containing the equation's parameters or NullParameters indicating that the equation does not have any parameters.

The different constructors then generate two vectors, one for the initial conditions and one for the parameters, where each pair of the corresponding entries defines one problem. In the first case, the respective constructor just checks if both vectors are of the same size. In the second case, the respective constructor creates a parameter vector, where each entry holds the same parameter set. In the third case, the respective constructor creates an initial condition vector, where each entry holds the same initial conditions. One may be inclined to think that the first and second constructor lead to a waste of memory, but in reality the respective vectors only hold references to the same initial conditons or parameters. Thus the data is not actually duplicated.

Each pair of initial conditions and parameters is referred to as sample. The methods

length(::EnsembleProblem)
nsamples(::EnsembleProblem)

return the number of samples in a EnsembleProblem. A single initial condition or parameter set can be retrieved by the methods

initial_condition(::EnsembleProblem, i)
parameter(::EnsembleProblem, i)

where i is the index of the sample. Typically, however, e.g. when integrating all samples of an EnsembleProblem with GeometricIntegrators, it is more convenient to retrieve the corresponding GeometricProblem via the method

problem(::EnsembleProblem, i)

The EnsembleProblem also allows to iterate over all samples, e.g.

for problem in ensemble
    # ...
    # integrate problem
    # ...
end

where ensemble is an EnsembleProblem and problem is the corresponding GeometricProblem.

Parameters

• ST <: GeometricEquation: super type, used for dispatch
• DT <: Number: data type
• TT <: Real: time step type
• AT <: AbstractArray{DT}: array type of state variable
• equType <: GeometricEquation: equation type
• functionsType <: NamedTuple: types of all function methods
• solutionsType <: NamedTuple: types of all solution methods
• icsType <: AbstractVector{<:NamedTuple}: types of all initial conditions
• parType <: AbstractVector{<:OptionalParameters}: parameters type

Fields

• equation: reference to the parent equation object holding the vector fields, etc.
• functions: methods for all vector fields, etc., that define the problem
• solutions: methods for all solutions, etc., if defined
• tspan: time span for problem (t₀,t₁)
• tstep: time step to be used in simulation
• ics: vector of NamedTuple containing the initial conditions, each NamedTuple must contain one field for each state variable
• parameters: vector of either NamedTuple containing the equation's parameters or NullParameters indicating that the equation does not have any parameters

Constructors

The EnsembleProblem provides the following constructors:

EnsembleProblem(equ, tspan, tstep, ics::AbstractVector{<:NamedTuple}, parameters::AbstractVector{<:OptionalParameters})
EnsembleProblem(equ, tspan, tstep, ics::AbstractVector{<:NamedTuple}, parameters::OptionalParameters=NullParameters())
EnsembleProblem(equ, tspan, tstep, ics::NamedTuple, parameters::AbstractVector{<:OptionalParameters})
EnsembleProblem(equ, tspan, tstep, ics, ::Nothing) = 
    EnsembleProblem(equ, tspan, tstep, ics, NullParameters())
EnsembleProblem(equ, tspan, tstep, ics; parameters = NullParameters()) = 
    EnsembleProblem(equ, tspan, tstep, ics, parameters)

• equ is a subtype of GeometricEquation
• tspan is a tuple (t₀,t₁) of the integration time span with t₀ the start time and t₁ the end time
• tstep is the time step, typically a value of some AbstractFloat subtype
• ics are the initial conditions, either a single set or a vector of multiple sets
• parameters are the static parameters of the problem, either a single set or a vector of multiple sets

ODEEnsemble: Ordinary Differential Equation Ensemble

Ordinary differential equations define an initial value problem of the form

\[\dot{q} (t) = v(t, q(t)) ,\]

with vector field $v$.

The dynamical variables $q$ take values in $\mathbb{R}^{d}$.

Constructors

ODEEnsemble(v, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
ODEEnsemble(v, tspan, tstep, q₀::AbstractVector{<: StateVariable}; kwargs...)
ODEEnsemble(v, tspan, tstep, q₀::AbstractVector{<: AbstractArray}; kwargs...)

where v is the function computing the vector field, tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is an AbstractVector of NamedTuple, each with an entry q of type StateVariable. The initial condition q₀ can also be prescribed as an AbstractVector of StateVariable or AbstractArray{<:Number}. For the interface of the function v see ODE.

For possible keyword arguments see the documentation on EnsembleProblem subtypes.

PODEEnsemble: Partitioned Ordinary Differential Equation Ensemble

A partitioned ordinary differential equation is an initial value problem of the form

\[\begin{aligned} \dot{q} (t) &= v(t, q(t), p(t)) , \\ \dot{p} (t) &= f(t, q(t), p(t)) , \end{aligned}\]

with vector fields $v$ and $f$.

The dynamical variables $(q,p)$ take values in $\mathbb{R}^{d} \times \mathbb{R}^{d}$.

Constructors

PODEEnsemble(v, f, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
PODEEnsemble(v, f, tspan, tstep, q₀::AbstractVector{<: StateVariable}, p₀::AbstractVector{<: StateVariable}; kwargs...)
PODEEnsemble(v, f, tspan, tstep, q₀::AbstractVector{<: AbstractArray}, p₀::AbstractVector{<: AbstractArray}; kwargs...)

where v and f are the function computing the vector fields, tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is an AbstractVector of NamedTuple, each with entries q and p. The initial conditions q₀ and p₀ can also be prescribed, each as an AbstractVector of StateVariable or AbstractArray{<:Number}. For the interfaces of the functions v and f see PODE.

For possible keyword arguments see the documentation on EnsembleProblem subtypes.

HODEEnsemble: Hamiltonian Ordinary Differential Equation Ensemble

A canonical Hamiltonian system of equations is special case of a partitioned ordinary differential equation,

\[\begin{aligned} \dot{q} (t) &= v(t, q(t), p(t)) , \\ \dot{p} (t) &= f(t, q(t), p(t)) , \end{aligned}\]

with vector fields $v$ and $f$, given by

\[\begin{aligned} v &= \frac{\partial H}{\partial p} , & f &= - \frac{\partial H}{\partial q} . \end{aligned}\]

The dynamical variables $(q,p)$ take values in $T^{*} Q \simeq \mathbb{R}^{d} \times \mathbb{R}^{d}$.

Constructors

HODEEnsemble(v, f, hamiltonian, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
HODEEnsemble(v, f, hamiltonian, tspan, tstep, q₀::AbstractVector{<: StateVariable}, p₀::AbstractVector{<: StateVariable}; kwargs...)
HODEEnsemble(v, f, hamiltonian, tspan, tstep, q₀::AbstractVector{<: AbstractArray}, p₀::AbstractVector{<: AbstractArray}; kwargs...)

where v and f are the function computing the vector fields, hamiltonian returns the value of the Hamiltonian (i.e. the total energy), tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is an AbstractVector of NamedTuple, each with entries q and p. The initial conditions q₀ and p₀ can also be prescribed, each as an AbstractVector of StateVariable or AbstractArray{<:Number}. For the interfaces of the functions v, f and hamiltonian see HODE.

For possible keyword arguments see the documentation on EnsembleProblem subtypes.

IODEEnsemble: Implicit Ordinary Differential Equation Ensemble

An implicit ordinary differential equations is an initial value problem of the form

\[\begin{aligned} \dot{q} (t) &= v(t) , \\ \dot{p} (t) &= f(t, q(t), v(t)) , \\ p(t) &= ϑ(t, q(t), v(t)) , \end{aligned}\]

with force field $f$, the momentum defined by $p$. This is a special case of a differential algebraic equation with dynamical variables $(q,p)$ and algebraic variable $v$, that is determined such that the constraint $p(t) = ϑ(t, q(t), v(t))$ is satisfied.

Many integrators perform a projection step in order to enforce this constraint. To this end, the system is extended to

\[\begin{aligned} \dot{q} (t) &= v(t) + λ(t) , \\ \dot{p} (t) &= f(t, q(t), v(t)) + g(t, q(t), v(t), λ(t)) , \\ p(t) &= ϑ(t, q(t), v(t)) , \end{aligned}\]

where the vector field defining the projection step is usually given as

\[\begin{aligned} g(t, q(t), v(t), λ(t)) &= λ(t) \cdot \nabla ϑ(t, q(t), v(t)) . \end{aligned}\]

The dynamical variables $(q,p)$ take values in $\mathbb{R}^{d} \times \mathbb{R}^{d}$. The algebraic variable $λ$ takes values in $\mathbb{R}^{m}$.

Constructors

IODEEnsemble(ϑ, f, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
IODEEnsemble(ϑ, f, tspan, tstep, q₀::AbstractVector{<: StateVariable}, p₀::AbstractVector{<: StateVariable}, λ₀::AbstractVector{<: AlgebraicVariable}; kwargs...)
IODEEnsemble(ϑ, f, tspan, tstep, q₀::AbstractVector{<: AbstractArray}, p₀::AbstractVector{<: AbstractArray}, λ₀::AbstractVector{<: AbstractArray}; kwargs...)
IODEEnsemble(ϑ, f, g, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
IODEEnsemble(ϑ, f, g, tspan, tstep, q₀::AbstractVector{<: StateVariable}, p₀::AbstractVector{<: StateVariable}, λ₀::AbstractVector{<: AlgebraicVariable}; kwargs...)
IODEEnsemble(ϑ, f, g, tspan, tstep, q₀::AbstractVector{<: AbstractArray}, p₀::AbstractVector{<: AbstractArray}, λ₀::AbstractVector{<: AbstractArray}; kwargs...)

The functions ϑ, f and g compute the momentum and the vector fields, respectively.

tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is a NamedTuple with entries q, p and λ. ics is an AbstractVector of NamedTuple, each with entries q, p and λ. The initial conditions q₀, p₀ and λ₀ can also be prescribed, each as an AbstractVector of StateVariable or AbstractArray{<:Number}. For the interfaces of the functions ϑ, f and g see IODE.

In addition to the standard keyword arguments for EquationProblem subtypes, an IODEEnsemble accepts functions v̄ and f̄ for the computation of initial guesses for the vector fields with default values v̄ = _iode_default_v̄ and f̄ = f.

For possible keyword arguments see the documentation on EnsembleProblem subtypes.

LODEEnsemble: Lagrangian Ordinary Differential Equation Ensemble

A Lagrangian system of equations is a special case of an implicit ordinary differential equations, that is an implicit initial value problem of the form

\[\begin{aligned} \dot{q} (t) &= v(t) , \\ \dot{p} (t) &= f(t, q(t), v(t)) , \\ p(t) &= ϑ(t, q(t), v(t)) , \end{aligned}\]

with momentum $p$ and force field $f$, given by

\[\begin{aligned} p &= \frac{\partial L}{\partial v} , & f &= \frac{\partial L}{\partial q} . \end{aligned}\]

This is a special case of an implicit ordinary differential equation, that is defined by a Lagrangian, as well as a special case of a differential algebraic equation with dynamical variables $(q,p)$ and algebraic variable $v$, that is determined such that the constraint $p(t) = ϑ(t, q(t), v(t))$ is satisfied.

Many integrators perform a projection step in order to enforce this constraint. To this end, the system is extended to

\[\begin{aligned} \dot{q} (t) &= v(t) + \lambda(t) , \\ \dot{p} (t) &= f(t, q(t), v(t)) + g(t, q(t), v(t), \lambda(t)) , \\ p(t) &= ϑ(t, q(t), v(t)) , \end{aligned}\]

where the vector field defining the projection step is usually given as

\[\begin{aligned} g(t, q(t), v(t), λ(t)) &= λ(t) \cdot \nabla ϑ(t, q(t), v(t)) . \end{aligned}\]

The dynamical variables $(q,p)$ take values in $T^{*} Q \simeq \mathbb{R}^{d} \times \mathbb{R}^{d}$. The algebraic variable $λ$ takes values in $\mathbb{R}^{m}$.

Constructors

LODEProblem(ϑ, f, ω, l, tspan, tstep, ics; kwargs...)
LODEProblem(ϑ, f, ω, l, tspan, tstep, q₀::StateVariable, p₀::StateVariable, λ₀::AlgebraicVariable; kwargs...)
LODEProblem(ϑ, f, ω, l, tspan, tstep, q₀::AbstractArray, p₀::AbstractArray, λ₀::AbstractArray = zero(q₀); kwargs...)
LODEProblem(ϑ, f, g, ω, l, tspan, tstep, ics; kwargs...)
LODEProblem(ϑ, f, g, ω, l, tspan, tstep, q₀::StateVariable, p₀::StateVariable, λ₀::AlgebraicVariable; kwargs...)
LODEProblem(ϑ, f, g, ω, l, tspan, tstep, q₀::AbstractArray, p₀::AbstractArray, λ₀::AbstractArray = zero(q₀); kwargs...)

where ϑ, f and g are the functions computing the momentum and the vector fields, respectively, ω determines the symplectic matrix, and l returns the Lagrangian, tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is a NamedTuple with entries q, p and λ. The initial conditions q₀, p₀ and λ₀ can also be prescribed directly, with StateVariable an AbstractArray{<:Number}, where λ₀ can also be omitted. For the interfaces of the functions ϑ, f, g, ω and l see LODE.

In addition to the standard keyword arguments for EquationProblem subtypes, a LODEProblem accepts functions v̄ and f̄ for the computation of initial guesses for the vector fields with default values v̄ = _lode_default_v̄ and f̄ = f.

Initial conditions have to be prescribed for (q,p). If instead initial conditions are available only for (q,v), the function ϑ can be called to compute the corresponding initial value of p.

SODEEnsemble: Split Ordinary Differential Equation Ensemble

Defines an initial value problem

\[\dot{q} (t) = v(t, q(t)) , \qquad q(t_{0}) = q_{0} ,\]

with vector field $v$, initial condition $q_{0}$ and the solution $q$ taking values in $\mathbb{R}^{d}$. Here, the vector field $v$ is given as a sum of vector fields

\[v (t) = v_1 (t) + ... + v_r (t) .\]

The dynamical variables $q$ take values in $\mathbb{R}^{d}$.

Constructors

SODEEnsemble(v, q, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
SODEEnsemble(v, q, tspan, tstep, q₀::AbstractVector{<: StateVariable}; kwargs...)
SODEEnsemble(v, q, tspan, tstep, q₀::AbstractVector{<: AbstractArray}; kwargs...)
SODEEnsemble(v, tspan, tstep, ics::AbstractVector{<: NamedTuple}; kwargs...)
SODEEnsemble(v, tspan, tstep, q₀::AbstractVector{<: StateVariable}; kwargs...)
SODEEnsemble(v, tspan, tstep, q₀::AbstractVector{<: AbstractArray}; kwargs...)

where v is a tuple of functions computing the vector fields for each substep, q is an optional tuple of functions computing the solution for each substep, tspan is the time interval (t₀,t₁) for the problem to be solved in, tstep is the time step to be used in the simulation, and ics is an AbstractVector of NamedTuple, each with an entry q of type StateVariable. The initial condition q₀ can also be prescribed as an AbstractVector of StateVariable or AbstractArray{<:Number}. For the interface of the functions v and q see SODE.

For possible keyword arguments see the documentation on EnsembleProblem subtypes.