SciMLFunctions (Jacobians, Sparsity, Etc.)

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 SciMLFunction types which can be passed to the problems.

Definition of the AbstractSciMLFunction Interface

The following standard principles should be adhered to across all AbstractSciMLFunction instantiations.

Generic Usage Rules

Generic solver code must treat an AbstractSciMLFunction as a callable container and query its capability traits before using optional callbacks. The portable contract is:

call the function using the signature documented by its function family; do not infer the signature from the concrete wrapper's fields;
use isinplace(f) to select the mutating or returning call convention;
use has_jac, has_jvp, has_vjp, has_paramjac, has_observed, and the related has_* traits before reading an optional callback;
use unwrapped_f(f) only when an operation explicitly needs the underlying callable, and preserve the wrapper's in-place convention after wrapping;
treat optional callbacks as absent when the corresponding trait is false, rather than assuming a field exists on every concrete subtype.

An implementation of a new function container should be testable through these generic operations alone. A downstream package should therefore be able to write code such as:

function evaluate_model(f::SciMLBase.AbstractSciMLFunction, u, p, t)
    return (; value = f(u, p, t), has_jac = SciMLBase.has_jac(f))
end

The concrete function type remains responsible for documenting callback arguments, return values, and field layout. Generic code must not reach into those fields to discover capabilities.

Common Function Choice Definitions

The full interface available to the solvers is as follows:

jac: The Jacobian of the differential equation with respect to the state variable u at a time t with parameters p.
paramjac: The Jacobian of the differential equation with respect to p at state u at time t.
analytic: Defines an analytical solution using u0 at time t with p which will cause the solvers to return errors. Used for testing.
syms: Allows you to name your variables for automatic names in plots and other output.
jac_prototype: Defines the type to be used for any internal Jacobians within the solvers.
sparsity: Defines the sparsity pattern to be used for the sparse differentiation schemes. By default this is equal to jac_prototype. See the sparsity handling portion of this page for more information.
colorvec: The coloring pattern used by the sparse differentiator. See the sparsity handling portion of this page for more information.
observed: A function which allows for generating other observables from a solution.

Each function type additionally has some specific arguments, refer to their documentation for details.

In-place Specification and No-Recompile Mode

Each SciMLFunction type can be called with an "is inplace" (iip) choice.

ODEFunction(f)
ODEFunction{iip}(f)

which is a boolean for whether the function is in the inplace form (mutating to change the first value). This is automatically determined using the methods table but note that for full type-inferability of the AbstractSciMLProblem this iip-ness should be specified.

In-place Trait Contract

Every concrete AbstractSciMLFunction{iip} subtype must encode whether its primary callback mutates its first argument in the iip parameter. Generic solver and extension code must obtain this information through isinplace(f), rather than inspecting fields or type parameters. The generic trait returns true for in-place and false for out-of-place function containers; callers can therefore support new concrete subtypes without adding type-specific dispatches.

Specialization Choices

Each SciMLFunction type allows for specialization choices

ODEFunction{iip, specialization}(f)

which designates how the compiler should specialize on the model function f. For more details on specialization choices, see the SciMLProblems page.

Specifying Jacobian Types

The jac field of an inplace style SciMLFunction has the signature jac(J,u,p,t), which updates the Jacobian J in-place. The intended type for J can sometimes be inferred (e.g. when it is just a dense Matrix), but not in general. To supply the type information, you can provide a jac_prototype in the function's constructor.

The following example creates an inplace ODEFunction whose Jacobian is a Diagonal:

using LinearAlgebra
f = (du, u, p, t) -> du .= t .* u
jac = (J, u, p, t) -> (J[1, 1] = t; J[2, 2] = t; J)
jp = Diagonal(zeros(2))
fun = ODEFunction(f; jac, jac_prototype = jp)

The prototype declares Jacobian shape, element type, and structure. It must support the operations required by the selected differentiation and linear solver, including writes for an in-place jac and any multiplication, diagonal-shift, or factorization operations that solver performs. Solvers may copy, allocate with similar, or convert the prototype, so code must not rely on its object identity or aliasing behavior.

When jac_prototype is an AbstractSciMLOperator and jac is omitted, the constructor creates a Jacobian update using update_coefficients! for the in-place form and update_coefficients for the out-of-place form. Refer to the SciMLOperators section for more information on setting up time/parameter dependent operators. The operator types and traits named here are re-exported by SciMLBase, so using SciMLBase is enough to build them; see Reexported API for the exact list and for what has to be imported from SciMLOperators directly.

Sparsity Handling

Solver packages select differentiation backends through their algorithm and option interfaces. Depending on that choice, they may use finite differences, automatic differentiation, sparse coloring, explicit derivative functions, or matrix-free Jacobian-vector and vector-Jacobian products. The function wrapper provides structural information without requiring a particular backend package.

Set jac_prototype to the concrete matrix or operator representation that should be used for the Jacobian. Set sparsity to the structural nonzero pattern used for sparse differentiation; it defaults to jac_prototype when omitted. Set colorvec to a column-color vector compatible with both that pattern and the selected backend, or leave it as nothing so coloring can be computed when needed. A prototype and color vector are performance and representation contracts, not substitutes for operations required by the selected linear solver.

Function Wrapper Rules

SciMLBase provides small wrapper types that turn an ODE-style model function into a one-variable callable for derivative code. These wrappers close over the fixed arguments and expose only the argument being differentiated.

Time wrappers fix u and p, then expose t.
State wrappers fix t and p, then expose u.
isinplace(wrapper) preserves the in-place convention detected from the wrapped function.
In-place wrappers support caller-provided output arrays. Their one-argument convenience calls allocate an output with similar to match the exposed state.
Wrapper trait queries forward to the underlying function where applicable, so derivative code should query traits instead of inspecting wrapper fields.

Traits

SciMLBase.isinplace — Function

isinplace(
    f, inplace_param_number, fname = "f", iip_preferred = true;
    has_two_dispatches = true,
    outofplace_param_number = inplace_param_number - 1
)
isinplace(f::AbstractSciMLFunction[, inplace_param_number])

Check whether a user callback follows the in-place SciML convention.

For an AbstractSciMLFunction, isinplace returns the iip type parameter without inspecting methods. For an ordinary callable, it inspects the method table and compares available arities to the expected in-place and out-of-place signatures.

Arguments

f: An AbstractSciMLFunction or callback whose calling convention is being queried.
inplace_param_number: Number of positional arguments in the in-place callback signature. For example, an ODE right-hand side uses 4 for f!(du, u, p, t).
fname: Name used to identify f in an argument-convention error.
iip_preferred: Convention selected when f provides both accepted arities.

Keywords

has_two_dispatches: Whether the interface accepts both in-place and out-of-place callback signatures. Set this to false for interfaces with only one accepted arity, such as optimization objectives.
isoptimization: Whether errors should use optimization-specific wording.
outofplace_param_number: Number of positional arguments in the out-of-place callback signature. It defaults to inplace_param_number - 1; the ODE out-of-place form is therefore f(u, p, t).

Returns

Returns true for the in-place convention and false for the out-of-place convention. Concrete AbstractSciMLFunction subtypes must expose their convention through this trait; generic solver code must query isinplace(f) and must not inspect subtype fields or type parameters directly.

If neither accepted arity is present, isinplace throws a function-argument error that uses fname to identify the offending callback. If both accepted arities are present, iip_preferred = true chooses the in-place interpretation and iip_preferred = false chooses the out-of-place interpretation.

Examples

f!(du, u, p, t) = (du .= u)
f(u, p, t) = u

isinplace(f!, 4) # true
isinplace(f, 4)  # false

See also