# NonlinearFunctions 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.NonlinearFunction`

— Type`NonlinearFunction{iip,F,TMM,Ta,Tt,TJ,JVP,VJP,JP,SP,TW,TWt,TPJ,S,O,TCV} <: AbstractNonlinearFunction{iip,recompile}`

A representation of an 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, recompile}(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 = __has_syms(f) ? f.syms : nothing,
indepsym= __has_indepsym(f) ? f.indepsym : 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)`

or`J=jac(u,p)`

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

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

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

or`Jv=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 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)`

: 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.`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.

**recompile: 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.