Engee documentation

RODE Problems

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 and the initial condition which define an ODE:

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 the specialization levels section of the SciMLBase 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 DiffEqFunctions 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 page

  • 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.

RODEFunction{iip,F,TMM,Ta,Tt,TJ,JVP,VJP,JP,SP,TW,TWt,TPJ,S,S2,S3,O,TCV} <: AbstractRODEFunction{iip,specialize}

A representation of a RODE function f, defined by:

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

RODEFunction{iip,specialize}(f;
                           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,
                           analytic_full = __has_analytic_full(f) ? f.analytic_full : false)

Note that only the function f itself is required. This function should be given as f!(du,u,p,t,W) or du = f(u,p,t,W). 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 represented in the RODE function. Can be used to determine that the equation is actually a random differential-algebraic equation (RDAE) if M is singular.

  • analytic: (u0,p,t,W)oranalytic(sol): used to pass an analytical solution function for the analytical solution of the RODE. Generally only used for testing and development of the solvers. The exact form depends on the fieldanalytic_full`.

  • analytic_full: a boolean to indicate whether to use the form analytic(u0,p,t,W) (if false) or the form analytic!(sol) (if true). The former is expected to return the solution u(t) of the equation, given the initial condition u0, the parameter p, the current time t and the value W=W(t) of the noise at the given time t. The latter case is useful when the solution of the RODE depends on the whole history of the noise, which is available in sol.W.W, at times sol.W.t. In this case, analytic(sol) must mutate explicitly the field sol.u_analytic with the corresponding expected solution at sol.W.t or sol.t.

  • tgrad(dT,u,p,t,W) or dT=tgrad(u,p,t,W): returns

  • jac(J,u,p,t,W) or J=jac(u,p,t,W): returns

  • jvp(Jv,v,u,p,t,W) or Jv=jvp(v,u,p,t,W): returns the directional derivative$\frac{df}{du} v$

  • vjp(Jv,v,u,p,t,W) or Jv=vjp(v,u,p,t,W): 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,W): returns the parameter Jacobian .

  • 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 RODEFunction type directly match the names of the inputs.

Solution Type

struct RODESolution{T, N, uType, uType2, DType, tType, randType, P, A, IType, S, AC<:Union{Nothing, Vector{Int64}}} <: SciMLBase.AbstractRODESolution{T, N, uType}

Representation of the solution to an stochastic differential equation defined by an SDEProblem, or of a random ordinary differential equation defined by an RODEProblem.

DESolution Interface

For more information on interacting with DESolution types, check out the Solution Handling page of the DifferentialEquations.jl documentation.

https://docs.sciml.ai/DiffEqDocs/stable/basics/solution/

Fields

  • u: the representation of the SDE or RODE solution. Given as an array of solutions, where u[i] corresponds to the solution at time t[i]. It is recommended in most cases one does not access sol.u directly and instead use the array interface described in the Solution Handling page of the DifferentialEquations.jl documentation.

  • t: the time points corresponding to the saved values of the ODE solution.

  • W: the representation of the saved noise process from the solution. See the Noise Processes page of the DifferentialEquations.jl. Note that this noise is only saved in full if save_noise=true in the solver.

  • prob: the original SDEProblem/RODEProblem that was solved.

  • alg: the algorithm type used by the solver.

  • stats: statistics of the solver, such as the number of function evaluations required, number of Jacobians computed, and more.

  • retcode: the return code from the solver. Used to determine whether the solver solved successfully, whether it terminated early due to a user-defined callback, or whether it exited due to an error. For more details, see the return code documentation.