Nonlinear Functions and Jacobian Types
The SciML ecosystem provides an extensive interface for declaring extra functions associated with the differential equation's data. In traditional libraries, there is usually only one option: the Jacobian. However, we allow for a large array of pre-computed functions to speed up the calculations. This is offered via the NonlinearFunction
types, which can be passed to the problems.
Function Type Definitions
SciMLBase.IntervalNonlinearFunction
— TypeDocStringExtensions.TypeDefinition()
A representation of an interval nonlinear system of equations f
, defined by:
\[f(t,p) = u = 0\]
and all of its related functions. For all cases, p
are the parameters and t
is the interval variable.
Constructor
IntervalNonlinearFunction{iip, specialize}(f;
analytic = __has_analytic(f) ? f.analytic : nothing,
syms = nothing,
paramsyms = nothing,
sys = __has_sys(f) ? f.sys : nothing)
Note that only the function f
itself is required. This function should be given as f!(u,t,p)
or u = f(t,p)
. 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:
analytic(p)
: used to pass an analytical solution function for the analytical solution of the ODE. Generally only used for testing and development of the solvers.syms
: the symbol names for the elements of the equation. This should matchu0
in size. For example, ifu0 = [0.0,1.0]
andsyms = [:x, :y]
, this will apply a canonical naming to the values, allowingsol[:x]
in the solution and automatically naming values in plots.paramsyms
: the symbol names for the parameters of the equation. This should matchp
in size. For example, ifp = [0.0, 1.0]
andparamsyms = [:a, :b]
, this will apply a canonical naming to the values, allowingsol[:a]
in the solution.
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 IntervalNonlinearFunction type directly match the names of the inputs.
SciMLBase.NonlinearFunction
— TypeDocStringExtensions.TypeDefinition()
A representation of a nonlinear system of equations f
, defined by:
\[0 = f(u,p)\]
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
NonlinearFunction{iip, specialize}(f;
analytic = __has_analytic(f) ? f.analytic : 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 = nothing,
paramsyms = nothing,
colorvec = __has_colorvec(f) ? f.colorvec : nothing,
sys = __has_sys(f) ? f.sys : nothing)
Note that only the function f
itself is required. This function should be given as f!(du,u,p)
or du = f(u,p)
. 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:
analytic(u0,p)
: used to pass an analytical solution function for the analytical solution of the ODE. Generally only used for testing and development of the solvers.jac(J,u,p)
orJ=jac(u,p)
: returns $\frac{df}{du}$jvp(Jv,v,u,p)
orJv=jvp(v,u,p)
: returns the directional derivative$\frac{df}{du} v$vjp(Jv,v,u,p)
orJv=vjp(v,u,p)
: 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 sizedTridiagonal
matrix can be used as the prototype and integrators will specialize on this structure where possible. Non-structured sparsity patterns should use aSparseMatrixCSC
with a correct sparsity pattern for the Jacobian. The default isnothing
, which means a dense Jacobian.paramjac(pJ,u,p)
: returns the parameter Jacobian $\frac{df}{dp}$.syms
: the symbol names for the elements of the equation. This should matchu0
in size. For example, ifu0 = [0.0,1.0]
andsyms = [:x, :y]
, this will apply a canonical naming to the values, allowingsol[:x]
in the solution and automatically naming values in plots.paramsyms
: the symbol names for the parameters of the equation. This should matchp
in size. For example, ifp = [0.0, 1.0]
andparamsyms = [:a, :b]
, this will apply a canonical naming to the values, allowingsol[:a]
in the solution.colorvec
: a color vector according to the SparseDiffTools.jl definition for the sparsity pattern of thejac_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 tonothing
, 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 NonlinearFunction type directly match the names of the inputs.