# Dynamical, Hamiltonian and 2nd Order ODE Problems

`SciMLBase.DynamicalODEProblem`

— TypeDefines an 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:

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

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 `SecondOrderODEProblem`

s 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. $\int 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.

`SciMLBase.SecondOrderODEProblem`

— TypeDefines 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:

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

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.

`SciMLBase.DynamicalODEFunction`

— Type`DynamicalODEFunction{iip,F1,F2,TMM,Ta,Tt,TJ,JVP,VJP,JP,SP,TW,TWt,TPJ,S,S2,S3,O,TCV} <: AbstractODEFunction{iip,specialize}`

A representation of an ODE function `f`

, defined by:

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

as a partitioned ODE:

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

and all of its related functions, such as the Jacobian of `f`

, its gradient with respect to time, and more. For all cases, `u0`

is the initial condition, `p`

are the parameters, and `t`

is the independent variable.

**Constructor**

```
DynamicalODEFunction{iip,specialize}(f1,f2;
mass_matrix = __has_mass_matrix(f) ? f.mass_matrix : I,
analytic = __has_analytic(f) ? f.analytic : nothing,
tgrad= __has_tgrad(f) ? f.tgrad : nothing,
jac = __has_jac(f) ? f.jac : nothing,
jvp = __has_jvp(f) ? f.jvp : nothing,
vjp = __has_vjp(f) ? f.vjp : nothing,
jac_prototype = __has_jac_prototype(f) ? f.jac_prototype : nothing,
sparsity = __has_sparsity(f) ? f.sparsity : jac_prototype,
paramjac = __has_paramjac(f) ? f.paramjac : nothing,
syms = __has_syms(f) ? f.syms : nothing,
indepsym= __has_indepsym(f) ? f.indepsym : nothing,
paramsyms = __has_paramsyms(f) ? f.paramsyms : nothing,
colorvec = __has_colorvec(f) ? f.colorvec : nothing,
sys = __has_sys(f) ? f.sys : nothing)
```

Note that only the functions `f_i`

themselves are required. These functions should be given as `f_i!(du,u,p,t)`

or `du = f_i(u,p,t)`

. See the section on `iip`

for more details on in-place vs out-of-place handling.

All of the remaining functions are optional for improving or accelerating the usage of `f`

. These include:

`mass_matrix`

: the mass matrix`M_i`

represented in the ODE function. Can be used to determine that the equation is actually a differential-algebraic equation (DAE) if`M`

is singular. Note that in this case special solvers are required, see the DAE solver page for more details: https://docs.sciml.ai/DiffEqDocs/stable/solvers/dae*solve/. Must be an AbstractArray or an AbstractSciMLOperator. Should be given as a tuple of mass matrices, i.e. `(M*1, M_2)` for the mass matrices of equations 1 and 2 respectively.`analytic(u0,p,t)`

: used to pass an analytical solution function for the analytical solution of the ODE. Generally only used for testing and development of the solvers.`tgrad(dT,u,p,t)`

or dT=tgrad(u,p,t): returns $\frac{\partial f(u,p,t)}{\partial t}$`jac(J,u,p,t)`

or`J=jac(u,p,t)`

: returns $\frac{df}{du}$`jvp(Jv,v,u,p,t)`

or`Jv=jvp(v,u,p,t)`

: returns the directional derivative$\frac{df}{du} v$`vjp(Jv,v,u,p,t)`

or`Jv=vjp(v,u,p,t)`

: returns the adjoint derivative$\frac{df}{du}^\ast v$`jac_prototype`

: a prototype matrix matching the type that matches the Jacobian. For example, if the Jacobian is tridiagonal, then an appropriately sized`Tridiagonal`

matrix can be used as the prototype and integrators will specialize on this structure where possible. Non-structured sparsity patterns should use a`SparseMatrixCSC`

with a correct sparsity pattern for the Jacobian. The default is`nothing`

, which means a dense Jacobian.`paramjac(pJ,u,p,t)`

: returns the parameter Jacobian $\frac{df}{dp}$.`syms`

: the symbol names for the elements of the equation. This should match`u0`

in size. For example, if`u0 = [0.0,1.0]`

and`syms = [:x, :y]`

, this will apply a canonical naming to the values, allowing`sol[:x]`

in the solution and automatically naming values in plots.`indepsym`

: the canonical naming for the independent variable. Defaults to nothing, which internally uses`t`

as the representation in any plots.`paramsyms`

: the symbol names for the parameters of the equation. This should match`p`

in size. For example, if`p = [0.0, 1.0]`

and`paramsyms = [:a, :b]`

, this will apply a canonical naming to the values, allowing`sol[:a]`

in the solution.`colorvec`

: a color vector according to the SparseDiffTools.jl definition for the sparsity pattern of the`jac_prototype`

. This specializes the Jacobian construction when using finite differences and automatic differentiation to be computed in an accelerated manner based on the sparsity pattern. Defaults to`nothing`

, which means a color vector will be internally computed on demand when required. The cost of this operation is highly dependent on the sparsity pattern.

**iip: In-Place vs Out-Of-Place**

For more details on this argument, see the ODEFunction documentation.

**specialize: Controlling Compilation and Specialization**

For more details on this argument, see the ODEFunction documentation.

**Fields**

The fields of the DynamicalODEFunction type directly match the names of the inputs.

## Solution Type

Dynamical ODE solutions return an `ODESolution`

. For more information, see the ODE problem definition page for the `ODESolution`

docstring.

## Hamiltonian Problems

`HamiltonianProblem`

s are provided by DiffEqPhysics.jl and provide an easy way to define equations of motion from the corresponding Hamiltonian. To define a `HamiltonianProblem`

one only needs to specify the Hamiltonian:

\[H(p,q)\]

and autodifferentiation (via ForwardDiff.jl) will create the appropriate equations.

### Constructors

`HamiltonianProblem{T}(H,p0,q0,tspan,param=nothing;kwargs...)`

### Fields

`H`

: The Hamiltonian`H(p,q,params)`

which returns a scalar.`p0`

: The initial momentums.`q0`

: The initial positions.`tspan`

: The timespan for the problem.`param`

: Defaults to`nothing`

.`param`

will be passed to`H`

's`params`

.