Differential Equation Problem Types

Defines an ordinary differential equation (ODE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/ode_types/

Mathematical Specification of an ODE Problem

To define an ODE Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define an ODE:

\[M \frac{du}{dt} = f(u,p,t)\]

There are two different ways of specifying f:

• f(du,u,p,t): in-place. Memory-efficient when avoiding allocations. Best option for most cases unless mutation is not allowed.
• f(u,p,t): returning du. Less memory-efficient way, particularly suitable when mutation is not allowed (e.g. with certain automatic differentiation packages such as Zygote).

u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

For the mass matrix $M$, see the documentation of ODEFunction.

Problem Type

Constructors

ODEProblem can be constructed by first building an ODEFunction or by simply passing the ODE right-hand side to the constructor. The constructors are:

• ODEProblem(f::ODEFunction,u0,tspan,p=NullParameters();kwargs...)
• ODEProblem{isinplace,specialize}(f,u0,tspan,p=NullParameters();kwargs...) : Defines the ODE with the specified functions. isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See the Specialization Levels for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the ODEFunction documentation.

Fields

• f: The function in the ODE.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The parameters.
• kwargs: The keyword arguments passed onto the solves.

Example Problem

using SciMLBase
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]
    return
end
u0 = [1.0;0.0;0.0]
tspan = (0.0, 100.0)
prob = ODEProblem(lorenz!, u0, tspan)

# Test that it worked
using OrdinaryDiffEq
sol = solve(prob, Tsit5())
using Plots; plot(sol, vars = (1, 2, 3))

More Example Problems

Example problems can be found in DiffEqProblemLibrary.jl.

To use a sample problem, such as prob_ode_linear, you can do something like:

#] add ODEProblemLibrary
using ODEProblemLibrary
prob = ODEProblemLibrary.prob_ode_linear
sol = solve(prob)

ImmutableODEProblem(f::ODEFunction, u0, tspan, p = NullParameters(), callback = CallbackSet())

Define an ODE problem from an ODEFunction.

struct StandardODEProblem

Marker for the standard first-order ODE problem representation.

StandardODEProblem() is the default problem_type metadata stored by ODEProblem and ImmutableODEProblem when a problem is represented directly as du/dt = f(u, p, t) or M * du/dt = f(u, p, t). It distinguishes this layout from specialized ODE encodings, such as dynamical, split, second-order, or incrementing representations, while keeping all of them under the common AbstractODEProblem interface.

Users normally do not need to construct this marker directly. Solver implementations may test problem_type(prob) isa StandardODEProblem when they need behavior specific to the standard ODE layout; generic ODE code should prefer the AbstractODEProblem interface and problem traits.

Defines a dynamical ordinary differential equation (ODE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/dynamical_types/

Dynamical ordinary differential equations, such as those arising from the definition of a Hamiltonian system or a second order ODE, have a special structure that can be utilized in the solution of the differential equation. On this page, we describe how to define second order differential equations for their efficient numerical solution.

Mathematical Specification of a Dynamical ODE Problem

These algorithms require a Partitioned ODE of the form:

\[\begin{align*} \frac{dv}{dt} &= f_1(u,t) \\ \frac{du}{dt} &= f_2(v) \\ \end{align*}\]

This is a Partitioned ODE partitioned into two groups, so the functions should be specified as f1(dv,v,u,p,t) and f2(du,v,u,p,t) (in the inplace form), where f1 is independent of v (unless specified by the solver), and f2 is independent of u and t. This includes discretizations arising from SecondOrderODEProblems where the velocity is not used in the acceleration function, and Hamiltonians where the potential is (or can be) time-dependent, but the kinetic energy is only dependent on v.

Note that some methods assume that the integral of f2 is a quadratic form. That means that f2 = v'*M*v, i.e. $∫ f_2 = \frac{1}{2} m v^2$, giving du = v. This is equivalent to saying that the kinetic energy is related to $v^2$. The methods which require this assumption will lose accuracy if this assumption is violated. Methods listed make note of this requirement with "Requires quadratic kinetic energy".

Constructor

DynamicalODEProblem(f::DynamicalODEFunction, v0, u0, tspan, p = NullParameters(); kwargs...)
DynamicalODEProblem{isinplace}(f1, f2, v0, u0, tspan, p = NullParameters(); kwargs...)

Defines the ODE with the specified functions. isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

Fields

• f1 and f2: The functions in the ODE.
• v0 and u0: The initial conditions.
• tspan: The timespan for the problem.
• p: The parameters for the problem. Defaults to NullParameters
• kwargs: The keyword arguments passed onto the solves.

Defines a second order ordinary differential equation (ODE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/dynamical_types/

Mathematical Specification of a 2nd Order ODE Problem

To define a 2nd Order ODE Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define an ODE:

\[u'' = f(u',u,p,t)\]

f should be specified as f(du,u,p,t) (or in-place as f(ddu,du,u,p,t)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

From this form, a dynamical ODE:

\[\begin{align*} v' &= f(v,u,p,t) \\ u' &= v \end{align*}\]

is generated.

Constructors

SecondOrderODEProblem{isinplace}(f, du0, u0, tspan, callback = CallbackSet())

Defines the ODE with the specified functions.

Fields

• f: The function for the second derivative.
• du0: The initial derivative.
• u0: The initial condition.
• tspan: The timespan for the problem.
• callback: A callback to be applied to every solver which uses the problem. Defaults to nothing.

abstract type AbstractSplitODEProblem

Marker supertype for split ODE problem layouts.

Subtypes identify ODEs whose right-hand side is supplied as a split function, usually to expose additive, linear, stiff, or nonstiff structure to solvers. Split constructors expose this marker through problem_type while using the ordinary ODEProblem storage layout.

Defines a split ordinary differential equation (ODE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/split_ode_types/

Mathematical Specification of a Split ODE Problem

To define a SplitODEProblem, you simply need to give two functions $f_1$ and $f_2$ along with an initial condition $u_0$ which define an ODE:

\[\frac{du}{dt} = f_1(u,p,t) + f_2(u,p,t)\]

f should be specified as f(u,p,t) (or in-place as f(du,u,p,t)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

Many splits are at least partially linear. That is the equation:

\[\frac{du}{dt} = Au + f_2(u,p,t)\]

For how to define a linear function A, see the documentation for the AbstractSciMLOperator.

Constructors

SplitODEProblem(f::SplitFunction, u0, tspan, p = NullParameters(); kwargs...)
SplitODEProblem{isinplace}(f1, f2, u0, tspan, p = NullParameters(); kwargs...)

The isinplace parameter can be omitted and will be determined using the signature of f2. Note that both f1 and f2 should support the in-place style if isinplace is true or they should both support the out-of-place style if isinplace is false. You cannot mix up the two styles.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

Under the hood, a SplitODEProblem is just a regular ODEProblem whose f is a SplitFunction. Therefore, you can solve a SplitODEProblem using the same solvers for ODEProblem. Solver packages document which methods specialize on split structure.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f1, f2: The functions in the ODE.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The parameters for the problem. Defaults to NullParameters
• kwargs: The keyword arguments passed onto the solves.

IncrementingODEProblem(f, u0, tspan, p = NullParameters(); kwargs...)
IncrementingODEProblem{iip}(f, u0, tspan, p = NullParameters(); kwargs...)

Construct an experimental ODE problem for a model function that can update an existing derivative buffer in an incrementing form.

The constructor wraps f in an IncrementingODEFunction, exposes an IncrementingODEProblem{iip} tag through problem_type, and returns a standard ODEProblem. The result therefore follows the ordinary ODE problem field, symbolic-indexing, keyword-forwarding, and solve interfaces.

Low-storage solvers commonly use the in-place convention f(du, u, p, t, alpha, beta), with the contract du = alpha * F(u, p, t) + beta * du. SciMLBase forwards these calls but does not synthesize the scaling operation; the wrapped model function must implement the call forms required by the selected solver.

Use the explicit IncrementingODEProblem{iip} form when optional arguments or multiple methods make the mutation convention ambiguous to arity-based inference.

Defines a discrete dynamical system problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/discrete_types/

Mathematical Specification of a Discrete Problem

To define a Discrete Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define a function map:

\[u_{n+1} = f(u_n, p, t_{n+1})\]

f should be specified as f(un,p,t) (or in-place as f(unp1,un,p,t)), and u_0 should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well. $u_{n+1}$ only depends on the previous iteration $u_{n}$ and $t_{n+1}$. The default $t_{n+1}$ of FunctionMap is $t_n = t_0 + n*dt$ (with dt=1 being the default). For continuous-time Markov chains, this is the time at which the change is occurring.

Note that if the discrete solver is set to have scale_by_time=true, then the problem is interpreted as the map:

\[u_{n+1} = u_n + dt \, f(u_n, p, t_{n+1})\]

Problem Type

Constructors

• DiscreteProblem(f::ODEFunction,u0,tspan,p=NullParameters();kwargs...) : Defines the discrete problem with the specified functions.
• DiscreteProblem{isinplace,specialize}(f,u0,tspan,p=NullParameters();kwargs...) : Defines the discrete problem with the specified functions.
• DiscreteProblem{isinplace,specialize}(u0,tspan,p=NullParameters();kwargs...) : Defines the discrete problem with the identity map.

isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See Specialization Levels for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f: The function in the map.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The parameters for the problem. Defaults to NullParameters
• kwargs: The keyword arguments passed onto the solves.

Note About Timing

Note that if no dt and not tstops is given, it's assumed that dt=1 and thus tspan=(0,n) will solve for n iterations. If in the solver dt is given, then the number of iterations will change. And if tstops is not empty, the solver will revert to the standard behavior of fixed timestep methods, which is "step to each tstop".

Defines a discrete dynamical system problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/discrete_types/

Mathematical Specification of a ImplicitDiscrete Problem

To define an ImplicitDiscrete Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define a function map:

\[f(u_{n+1}, u_n, p, t_{n+1}, \text{integ}) = 0\]

f should be specified as f(un,p,t) (or in-place as f(unp1,un,p,t)), and u_0 should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well. $u_{n+1}$ only depends on the previous iteration $u_{n}$ and $t_{n+1}$. The default $t_{n+1}$ is chosen adaptively, and when $dt$ is specified, we have $t_n = t_0 + n*dt$. integ contains the fields:

• dt: the time step

Problem Type

Constructors

• ImplicitDiscreteProblem(f::ImplicitDiscreteFunction, u0, tspan, p = NullParameters(); kwargs...) : Defines the discrete problem with the specified functions.
• ImplicitDiscreteProblem{isinplace, specialize}(f, u0, tspan, p = NullParameters(); kwargs...) : Defines the discrete problem with the specified functions.
• ImplicitDiscreteProblem{isinplace, specialize}(u0, tspan, p = NullParameters(); kwargs...) : Defines the discrete problem with the identity map.

isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See Specialization Levels for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f: The function in the map.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The parameters for the problem. Defaults to NullParameters
• kwargs: The keyword arguments passed onto the solves.

Note About Timing

Note that if no dt and not tstops is given, it's assumed that dt=1 and thus tspan=(0,n) will solve for n iterations. If in the solver dt is given, then the number of iterations will change. And if tstops is not empty, the solver will revert to the standard behavior of fixed timestep methods, which is "step to each tstop".

Defines a random ordinary differential equation (RODE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/rode_types/

Mathematical Specification of a RODE Problem

To define a RODE Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define an ODE:

\[\frac{du}{dt} = f(u,p,t,W(t))\]

where W(t) is a random process. f should be specified as f(u,p,t,W) (or in-place as f(du,u,p,t,W)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

Constructors

• RODEProblem(f::RODEFunction, u0, tspan, p = NullParameters(); noise = WHITE_NOISE, rand_prototype = nothing, callback = nothing)
• RODEProblem{isinplace, specialize}(f, u0, tspan, p = NullParameters(); noise = WHITE_NOISE, rand_prototype = nothing, callback = nothing, mass_matrix = I) : Defines the RODE with the specified functions. The default noise is WHITE_NOISE. isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See Specialization Levels for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f: The drift function in the SDE.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The optional parameters for the problem. Defaults to NullParameters.
• noise: The noise process applied to the noise upon generation. Defaults to Gaussian white noise. For information on defining different noise processes, see the noise process documentation.
• rand_prototype: A prototype type instance for the noise vector. It defaults to nothing, which means the problem should be interpreted as having a noise vector whose size matches u0.
• kwargs: The keyword arguments passed onto the solves.

Defines an stochastic differential equation (SDE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/sde_types/

Mathematical Specification of a SDE Problem

To define an SDE Problem, you simply need to give the forcing function f, the noise function g, and the initial condition u₀ which define an SDE:

\[du = f(u,p,t) \, dt + ∑ᵢ gᵢ(u,p,t) \, dWⁱ\]

f and g should be specified as f(u,p,t) and g(u,p,t) respectively, and u₀ should be an AbstractArray whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well. A vector of gs can also be defined to determine an SDE of higher Ito dimension.

Problem Type

Wraps the data which defines an SDE problem

\[u = f(u,p,t) \, dt + ∑ᵢ gᵢ(u,p,t) \, dWⁱ\]

with initial condition u0.

Constructors

• SDEProblem(f::SDEFunction,u0,tspan,p=NullParameters();noise=WHITE_NOISE,noise_rate_prototype=nothing)
• SDEProblem{isinplace,specialize}(f,g,u0,tspan,p=NullParameters();noise=WHITE_NOISE,noise_rate_prototype=nothing) : Defines the SDE with the specified functions. The default noise is WHITE_NOISE. isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See Specialization Levels for more details. The default is AutoSpecialize.

Parameters are optional, and if not given then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f: The drift function in the SDE.
• g: The noise function in the SDE.
• u0: The initial condition.
• tspan: The timespan for the problem.
• p: The optional parameters for the problem. Defaults to NullParameters.
• noise: The noise process applied to the noise upon generation. Defaults to Gaussian white noise. For information on defining different noise processes, see the noise process documentation.
• noise_rate_prototype: A prototype type instance for the noise rates, that is the output g. It can be any type which overloads A_mul_B! with itself being the middle argument. Commonly, this is a matrix or sparse matrix. If this is not given, it defaults to nothing, which means the problem should be interpreted as having diagonal noise.
• kwargs: The keyword arguments passed onto the solves.

Example Problems

Examples problems can be found in DiffEqProblemLibrary.jl.

To use a sample problem, such as prob_sde_linear, you can do something like:

#] add SDEProblemLibrary
using SDEProblemLibrary
prob = SDEProblemLibrary.prob_sde_linear
sol = solve(prob)

struct SplitSDEProblem{iip} <: SciMLBase.AbstractSplitSDEProblem

Constructor tag for split SDE problems.

SplitSDEProblem{iip} records the in-place convention of the split SDE function while building an SDEProblem whose function is a SplitSDEFunction. The tag is a construction helper, not a separate stored problem object returned by solve.

struct DynamicalSDEProblem{iip} <: SciMLBase.AbstractDynamicalSDEProblem

Constructor tag for dynamical SDE problems.

DynamicalSDEProblem{iip} records the in-place convention used when converting partitioned stochastic dynamics into the common SDEProblem representation. Solver code should normally work with the resulting SDEProblem and its DynamicalSDEFunction.

Defines an implicit ordinary differential equation (ODE) or differential-algebraic equation (DAE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/dae_types/

Mathematical Specification of an DAE Problem

To define a DAE Problem, you simply need to give the function $f$ and the initial condition $u_0$ which define an ODE:

\[0 = f(du,u,p,t)\]

f should be specified as f(du,u,p,t) (or in-place as f(resid,du,u,p,t)). Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

Problem Type

Constructors

• DAEProblem(f::DAEFunction,du0,u0,tspan,p=NullParameters();kwargs...)
• DAEProblem{isinplace,specialize}(f,du0,u0,tspan,p=NullParameters();kwargs...) : Defines the DAE with the specified functions. isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See the specialization levels section of the documentation for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the SciMLFunctions interface page.

Fields

• f: The function in the ODE.
• du0: The initial condition for the derivative.
• u0: The initial condition.
• tspan: The timespan for the problem.
• differential_vars: A logical array which declares which variables are the differential (non-algebraic) vars (i.e. du' is in the equations for this variable). Defaults to nothing. Some solvers may require this be set if an initial condition needs to be determined.
• p: The parameters for the problem. Defaults to NullParameters
• kwargs: The keyword arguments passed onto the solves.

Example Problems

Examples problems can be found in DiffEqProblemLibrary.jl.

To use a sample problem, such as prob_dae_resrob, you can do something like:

#] add DAEProblemLibrary
using DAEProblemLibrary
prob = DAEProblemLibrary.prob_dae_resrob
sol = solve(prob, IDA())

struct StandardDAEProblem

Marker for the standard fully implicit DAE problem representation.

StandardDAEProblem() is the default problem_type metadata stored by DAEProblem when a problem is represented directly as 0 = f(du, u, p, t).

Users normally do not need to construct this marker directly. Solver implementations may test problem_type(prob) isa StandardDAEProblem when they need behavior specific to the standard DAE layout; generic DAE code should prefer the AbstractDAEProblem interface and problem traits.