GitHub

SciMLProblems

The cornerstone of the SciML common interface is the problem type definition. These definitions are the encoding of mathematical problems into a numerically computable form.

Note About Symbolics and ModelingToolkit

The symbolic analog to the problem interface is the ModelingToolkit AbstractSystem. For example, ODESystem is the symbolic analog to ODEProblem. Each of these system types have a method for constructing the associated problem and function types.

Definition of the AbstractSciMLProblem Interface

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

In-place Specification

Each AbstractSciMLProblem type can be called with an "is inplace" (iip) choice. For example:

ODEProblem(f, u0, tspan, p)
ODEProblem{iip}(f, u0, tspan, p)

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.

Additionally, the functions are fully specialized to reduce the runtimes. If one would instead like to not specialize on the functions to reduce compile time, then one can set recompile to false.

Specialization Levels

Specialization levels in problem definitions are used to control the amount of compilation specialization is performed on the model functions in order to trade off between runtime performance, simplicity, and compile-time performance. The default choice of specialization is AutoSpecialize, which seeks to allow for using fully precompiled solvers in common scenarios but falls back to a runtime-optimal approach when further customization is used.

Specialization levels are given as the second type parameter in AbstractSciMLProblem constructors. For example, this is done via:

ODEProblem{iip, specialization}(f, u0, tspan, p)

Note that iip choice is required for specialization choices to be made.

Specialization Choices

SciMLBase.AbstractSpecialization — Type
abstract type AbstractSpecialization

Supertype for the specialization types. Controls the compilation and function specialization behavior of SciMLFunctions, ultimately controlling the runtime vs compile-time trade-off.

source
SciMLBase.AutoSpecialize — Type
struct AutoSpecialize <: SciMLBase.AbstractSpecialization

The default specialization level for problem functions. AutoSpecialize works by applying a function wrap just-in-time before the solve process to disable just-in-time re-specialization of the solver to the specific choice of model f and thus allow for using a cached solver compilation from a different f. This wrapping process can lead to a small decreased runtime performance with a benefit of a greatly decreased compile-time.

Note About Benchmarking and Runtime Optimality

It is recommended that AutoSpecialize is not used in any benchmarking due to the potential effect of function wrapping on runtimes. AutoSpecialize's use case is targeted at decreased latency for REPL performance and not for cases where where top runtime performance is required (such as in optimization loops). Generally, for non-stiff equations the cost will be minimal and potentially not even measurable. For stiff equations, function wrapping has the limitation that only chunk sized 1 Dual numbers are allowed, which can decrease Jacobian construction performance.

Limitations of AutoSpecialize

The following limitations are not fundamental to the implementation of AutoSpecialize, but are instead chosen as a compromise between default precompilation times and ease of maintenance. Please open an issue to discuss lifting any potential limitations.

  • AutoSpecialize is only setup to wrap the functions from in-place ODEs. Other cases are excluded for the time being due to time limitations.
  • AutoSpecialize will only lead to compilation reuse if the ODEFunction's other functions (such as jac and tgrad) are the default nothing. These could be JIT wrapped as well in a future version.
  • AutoSpecialize'd functions are only compatible with Jacobian calculations performed with chunk size 1, and only with tag DiffEqBase.OrdinaryDiffEqTag(). Thus ODE solvers written on the common interface must be careful to detect the AutoSpecialize case and perform differentiation under these constraints, use finite differencing, or manually unwrap before solving. This will lead to decreased runtime performance for sufficiently large Jacobians.
  • AutoSpecialize only wraps on Julia v1.8 and higher.
  • AutoSpecialize does not handle cases with units. If unitful values are detected, wrapping is automatically disabled.
  • AutoSpecialize only wraps cases for which promote_rule is defined between u0 and dual numbers, u0 and t, and for which ArrayInterface.promote_eltype is defined on u0 to dual numbers.
  • AutoSpecialize only wraps cases for which f.mass_matrix isa UniformScaling, the default.
  • AutoSpecialize does not wrap cases where f isa AbstractSciMLOperator
  • By default, only the u0 isa Vector{Float64}, eltype(tspan) isa Float64, and typeof(p) isa Union{Vector{Float64},SciMLBase.NullParameters} are specialized by the solver libraries. Other forms can be specialized with AutoSpecialize, but must be done in the precompilation of downstream libraries.
  • AutoSpecialized functions are manually unwrapped in adjoint methods in SciMLSensitivity.jl in order to allow compiler support for automatic differentiation. Improved versions of adjoints which decrease the recompilation surface will come in non-breaking updates.

Cases where automatic wrapping is disabled are equivalent to FullSpecialize.

Example

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

# Note this is the same as ODEProblem(f, [1.0], (0.0,1.0))
# If no preferences are set
ODEProblem{true, SciMLBase.AutoSpecialize}(f, [1.0], (0.0,1.0))
source
SciMLBase.NoSpecialize — Type
struct NoSpecialize <: SciMLBase.AbstractSpecialization

NoSpecialize forces SciMLFunctions to not specialize on the types of functions wrapped within it. This ultimately contributes to a form such that every prob.f type is the same, meaning compilation caches are fully reused, with the downside of losing runtime performance. NoSpecialize is the form that most fully trades off runtime for compile time. Unlike AutoSpecialize, NoSpecialize can be used with any SciMLFunction.

Example

f(du,u,p,t) = (du .= u)
ODEProblem{true, SciMLBase.NoSpecialize}(f, [1.0], (0.0,1.0))
source
SciMLBase.FunctionWrapperSpecialize — Type
struct FunctionWrapperSpecialize <: SciMLBase.AbstractSpecialization

FunctionWrapperSpecialize is an eager wrapping choice which performs a function wrapping during the ODEProblem construction. This performs the function wrapping at the earliest possible point, giving the best compile-time vs runtime performance, but with the difficulty that any usage of prob.f needs to account for the function wrapper's presence. While optimal in a performance sense, this method has many usability issues with nonstandard solvers and analyses as it requires unwrapping before re-wrapping for any type changes. Thus this method is not used by default. Given that the compile-time different is almost undetectable from AutoSpecialize, this method is mostly used as a benchmarking reference for speed of light for AutoSpecialize.

Limitations of FunctionWrapperSpecialize

FunctionWrapperSpecialize has all of the limitations of AutoSpecialize, but also includes the limitations:

  • prob.f is directly specialized to the types of (u,p,t), and any usage of prob.f on other types first requires using SciMLBase.unwrapped_f(prob.f) to remove the function wrapper.
  • FunctionWrapperSpecialize can only be used by the ODEProblem constructor. If an ODEFunction is being constructed, the user must manually use DiffEqBase.wrap_iip on f before calling ODEFunction{true,FunctionWrapperSpecialize}(f). This is a fundamental limitation of the approach as the types of (u,p,t) are required in the construction process and not accessible in the AbstractSciMLFunction constructors.

Example

f(du,u,p,t) = (du .= u)
ODEProblem{true, SciMLBase.FunctionWrapperSpecialize}(f, [1.0], (0.0,1.0))
source
SciMLBase.FullSpecialize — Type
struct FullSpecialize <: SciMLBase.AbstractSpecialization

FullSpecialize is an eager specialization choice which directly types the AbstractSciMLFunction struct to match the type of the model f. This forces recompilation of the solver on each new function type f, leading to the most compile times with the benefit of having the best runtime performance.

FullSpecialize should be used in all cases where top runtime performance is required, such as in long-running simulations and benchmarking.

Example

f(du,u,p,t) = (du .= u)
ODEProblem{true, SciMLBase.FullSpecialize}(f, [1.0], (0.0,1.0))
source
Note

The specialization level must be precompile snooped in the appropriate solver package in order to enable the full precompilation and system image generation for zero-latency usage. By default, this is only done with AutoSpecialize and on types u isa Vector{Float64}, eltype(tspan) isa Float64, and p isa Union{Vector{Float64}, SciMLBase.NullParameters}. Precompilation snooping in the solvers can be done using the Preferences.jl setup on the appropriate solver. See the solver library's documentation for more details.

Default Parameters

By default, AbstractSciMLProblem types use the SciMLBase.NullParameters() singleton to define the absence of parameters by default. The reason is because this throws an informative error if the parameter is used or accessed within the user's function, for example, p[1] will throw an informative error about forgetting to pass parameters.

Keyword Argument Splatting

All AbstractSciMLProblem types allow for passing keyword arguments that would get forwarded to the solver. The reason for this is that in many cases, like in EnsembleProblem usage, a AbstractSciMLProblem might be associated with some solver configuration, such as a callback or tolerance. Thus, for flexibility the extra keyword arguments to the AbstractSciMLProblem are carried to the solver.

problem_type

AbstractSciMLProblem types include a non-public API definition of problem_type which holds a trait type corresponding to the way the AbstractSciMLProblem was constructed. For example, if a SecondOrderODEProblem constructor is used, the returned problem is simply a ODEProblem for interoperability with any ODEProblem algorithm. However, in this case the problem_type will be populated with the SecondOrderODEProblem type, indicating the original definition and extra structure.

Remake

SciMLBase.remake — Function
remake(thing; <keyword arguments>)

Re-construct thing with new field values specified by the keyword arguments.

source
remake(prob::AbstractSciMLProblem; u0 = missing, p = missing, interpret_symbolicmap = true, use_defaults = false)

Remake the given problem prob. If u0 or p are given, they will be used instead of the unknowns/parameters of the problem. Either of them can be a symbolic map if the problem has an associated system. If interpret_symbolicmap == false, p will never be interpreted as a symbolic map and used as-is for parameters. use_defaults allows controlling whether the default values from the system will be used to calculate missing values in the symbolic map passed to u0 or p. It is only valid when either u0 or p have been explicitly provided as a symbolic map and the problem has an associated system.

source
remake(func::AbstractSciMLFunction; f = missing, g = missing, f2 = missing, kwargs...)

remake the given func. Return an AbstractSciMLFunction of the same kind, isinplace and specialization as func. Retain the properties of func, except those that are overridden by keyword arguments. For stochastic functions (e.g. SDEFunction) the g keyword argument is used to override func.g. For split functions (e.g. SplitFunction) the f2 keyword argument is used to override func.f2, and f is used for func.f1. If f isa AbstractSciMLFunction and func is not a split function, properties of f will override those of func (but not ones provided via keyword arguments). Properties of f that are nothing will fall back to those in func (unless provided via keyword arguments). If f is a different type of AbstractSciMLFunction from func, the returned function will be of the kind of f unless func is a split function. If func is a split function, f and f2 will be wrapped in the appropriate AbstractSciMLFunction type with the same isinplace and specialization as func.

source
remake(prob::ODEProblem; f = missing, u0 = missing, tspan = missing,
       p = missing, kwargs = missing, _kwargs...)

Remake the given ODEProblem. If u0 or p are given as symbolic maps ModelingToolkit.jl has to be loaded.

source
remake(prob::BVProblem; f = missing, u0 = missing, tspan = missing,
       p = missing, kwargs = missing, problem_type = missing, _kwargs...)

Remake the given BVProblem.

source
remake(prob::SDEProblem; f = missing, g = missing, u0 = missing, tspan = missing,
       p = missing, noise = missing, noise_rate_prototype = missing,
       seed = missing, kwargs = missing, _kwargs...)

Remake the given SDEProblem.

source
remake(prob::OptimizationProblem; f = missing, u0 = missing, p = missing,
    lb = missing, ub = missing, int = missing, lcons = missing, ucons = missing,
    sense = missing, kwargs = missing, _kwargs...)

Remake the given OptimizationProblem. If u0 or p are given as symbolic maps ModelingToolkit.jl has to be loaded.

source
remake(prob::NonlinearProblem; f = missing, u0 = missing, p = missing,
    problem_type = missing, kwargs = missing, _kwargs...)

Remake the given NonlinearProblem. If u0 or p are given as symbolic maps ModelingToolkit.jl has to be loaded.

source
remake(prob::NonlinearLeastSquaresProblem; f = missing, u0 = missing, p = missing,
    kwargs = missing, _kwargs...)

Remake the given NonlinearLeastSquaresProblem.

source
remake(prob::SCCNonlinearProblem; u0 = missing, p = missing, probs = missing,
    parameters_alias = prob.parameters_alias, sys = missing, explicitfuns! = missing)

Remake the given SCCNonlinearProblem. u0 is the state vector for the entire problem, which will be chunked appropriately and used to remake the individual subproblems. p is the parameter object for prob. If parameters_alias, the same parameter object will be used to remake the individual subproblems. Otherwise if p !== missing, this function will error and require that probs be specified. probs is the collection of subproblems. Even if probs is explicitly specified, the value of u0 provided to remake will be used to override the values in probs. sys is the index provider for the full system.

source

For problems that are created from a system (e.g. created through ModelingToolkit.jl) or define a DSL using SymbolicIndexingInterface.SymbolCache, remake can accept symbolic maps as u0 or p. A symbolic map is a Dict or Vector{<:Pair} mapping symbols in u0 or p to their values. These values can be numeric, or expressions of other symbols. Symbolic maps can be complete (specifying a value for each symbol in u0 or p) or partial. For a partial symbolic map, the values of remaining symbols are obtained through the system's defaults (see SymbolicIndexingInterface.default_values) and the existing values in the problem passed to remake.

If the system's defaults contain an expression for the missing symbol, that expression will be used for the value (it is treated as a dependent initialization). Otherwise, the existing value of that symbol in the problem passed to remake is used.

If default_values = true is passed as a keyword argument to remake, then the value contained in the system's defaults is always preferred over the value in the problem.

For example, consider a problem prob with parameters :a, :b, :c having values 1.0, 2.0, 3.0 respectively. Let us also assume that the system contains the defaults Dict(:a => :(2b), :c => 0.1). Then:

  • remake(prob; p = [:b => 2.0]) will result in the values 4.0, 2.0, 3.0 for :a, :b and :c respectively. Note how the numeric default for :c was not respected.
  • remake(prob; p = [:b => 2.0], use_defaults = true) will result in the values 4.0, 2.0, 1.0 for :a, :b and :c respectively.
  • remake(prob; p = [:b => 2.0, :a => 3.0]) will result in the values 3.0, 2.0, 3.0 for :a, :b and :c respectively. Note how the explicitly specified value for :a overrides the dependent default.

Aliasing Specification

An AbstractAliasSpecifier is associated with each SciMLProblem type. Each holds fields specifying which variables to alias when solving. For example, to tell an ODE solver to alias the u0 array, you can use an ODEAliases object, and the alias_u0 keyword argument, e.g. solve(prob,alias = ODEAliases(alias_u0 = true)).

SciMLBase.AbstractAliasSpecifier — Type
abstract type AbstractAliasSpecifier

Used to specify which variables can be aliased in a solve. Every concrete AbstractAliasSpecifier should have at least the fields alias_p and alias_f.

source
SciMLBase.LinearAliasSpecifier — Type

Holds information on what variables to alias when solving a LinearProblem. Conforms to the AbstractAliasSpecifier interface. LinearAliasSpecifier(; alias_A = nothing, alias_b = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_A::Union{Bool, Nothing}: alias the A array.
  • alias_b::Union{Bool, Nothing}: alias the b array.
  • alias::Union{Bool, Nothing}: sets all fields of the LinearAliasSpecifier to alias.

Creates a LinearAliasSpecifier where alias_A and alias_b default to nothing. When alias_A or alias_b is nothing, the default value of the solver is used.

source
Missing docstring.

Missing docstring for SciMLBase.NonlinearAliasSpecifier. Check Documenter's build log for details.

SciMLBase.ODEAliasSpecifier — Type

Holds information on what variables to alias when solving an ODE. Conforms to the AbstractAliasSpecifier interface. ODEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = false, alias_du0 = false, alias_tstops = false, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias_du0::Union{Bool, Nothing}: alias the du0 array for DAEs. Defaults to false.
  • alias_tstops::Union{Bool, Nothing}: alias the tstops array
  • alias::Union{Bool, Nothing}: sets all fields of the ODEAliasSpecifier to alias
source
SciMLBase.SDEAliasSpecifier — Type

Holds information on what variables to alias when solving an SDEProblem. Conforms to the AbstractAliasSpecifier interface. SDEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_tstops = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias_tstops::Union{Bool, Nothing}: alias the tstops array
  • alias_jumps::Union{Bool, Nothing}: alias jump process if wrapped in a JumpProcess
  • alias::Union{Bool, Nothing}: sets all fields of the SDEAliasSpecifier to alias
source
SciMLBase.DDEAliasSpecifier — Type

Holds information on what variables to alias when solving a DDE. Conforms to the AbstractAliasSpecifier interface. DDEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias_du0::Union{Bool, Nothing}: alias the du0 array for DAEs. Defaults to false.
  • alias_tstops::Union{Bool, Nothing}: alias the tstops array
  • alias::Union{Bool, Nothing}: sets all fields of the DDEAliasSpecifier to alias
source
SciMLBase.SDDEAliasSpecifier — Type

Holds information on what variables to alias when solving an SDDEProblem. Conforms to the AbstractAliasSpecifier interface. SDDEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias_tstops::Union{Bool, Nothing}: alias the tstops array
  • alias_jumps::Union{Bool, Nothing}: alias jump process if wrapped in a JumpProcess
  • alias::Union{Bool, Nothing}: sets all fields of the SDDEAliasSpecifier to alias
source
SciMLBase.BVPAliasSpecifier — Type

Holds information on what variables to alias when solving an BVP. Conforms to the AbstractAliasSpecifier interface. BVPAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias_du0::Union{Bool, Nothing}: alias the du0 array for DAEs. Defaults to false.
  • alias_tstops::Union{Bool, Nothing}: alias the tstops array
  • alias::Union{Bool, Nothing}: sets all fields of the BVPAliasSpecifier to alias
source
SciMLBase.OptimizationAliasSpecifier — Type

Holds information on what variables to alias when solving an OptimizationProblem. Conforms to the AbstractAliasSpecifier interface. OptimizationAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = false, alias = nothing)

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias::Union{Bool, Nothing}: sets all fields of the OptimizationAliasSpecifier to alias
source
SciMLBase.IntegralAliasSpecifier — Type

Holds information on what variables to alias when solving an IntegralProblem. Conforms to the AbstractAliasSpecifier interface. IntegralAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)`

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias::Union{Bool, Nothing}: sets all fields of the IntegralAliasSpecifier to alias
source
SciMLBase.DiscreteAliasSpecifier — Type

Holds information on what variables to alias when solving a DiscreteProblem. Conforms to the AbstractAliasSpecifier interface. DiscreteAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)

When a keyword argument is nothing, the default behaviour of the solver is used.

Keywords

  • alias_p::Union{Bool, Nothing}
  • alias_f::Union{Bool, Nothing}
  • alias_u0::Union{Bool, Nothing}: alias the u0 array. Defaults to false .
  • alias::Union{Bool, Nothing}: sets all fields of the DiscreteAliasSpecifier to alias
source

Problem Traits

SciMLBase.isinplace — Method
isinplace(prob::AbstractSciMLProblem)

Determine whether the function of the given problem operates in place or not.

source

AbstractSciMLProblem API

Defaults and Preferences

SpecializationLevel at SciMLBase can be used to set the default specialization level. The following shows how to set the specialization default to FullSpecialize:

using Preferences, UUIDs
set_preferences!(
    UUID("0bca4576-84f4-4d90-8ffe-ffa030f20462"), "SpecializationLevel" => "FullSpecialize")

The default is AutoSpecialize.

Abstract SciMLProblems

SciMLBase.AbstractDEProblem — Type
abstract type AbstractDEProblem <: SciMLBase.AbstractSciMLProblem

Base type for all DifferentialEquations.jl problems. Concrete subtypes of AbstractDEProblem contain the necessary information to fully define a differential equation of the corresponding type.

source
SciMLBase.AbstractODEProblem — Type
abstract type AbstractODEProblem{uType, tType, isinplace} <: SciMLBase.AbstractDEProblem

Base for types which define ODE problems.

source
SciMLBase.AbstractDiscreteProblem — Type
abstract type AbstractDiscreteProblem{uType, tType, isinplace} <: SciMLBase.AbstractODEProblem{uType, tType, isinplace}

Base for types which define discrete problems.

source
SciMLBase.AbstractRODEProblem — Type
abstract type AbstractRODEProblem{uType, tType, isinplace, ND} <: SciMLBase.AbstractDEProblem

Base for types which define RODE problems.

source
SciMLBase.AbstractSDEProblem — Type
abstract type AbstractSDEProblem{uType, tType, isinplace, ND} <: SciMLBase.AbstractRODEProblem{uType, tType, isinplace, ND}

Base for types which define SDE problems.

source
SciMLBase.AbstractDAEProblem — Type
abstract type AbstractDAEProblem{uType, duType, tType, isinplace} <: SciMLBase.AbstractDEProblem

Base for types which define DAE problems.

source
SciMLBase.AbstractDDEProblem — Type
abstract type AbstractDDEProblem{uType, tType, lType, isinplace} <: SciMLBase.AbstractDEProblem

Base for types which define DDE problems.

source
SciMLBase.AbstractBVProblem — Type
abstract type AbstractBVProblem{uType, tType, isinplace, nlls} <: SciMLBase.AbstractODEProblem{uType, tType, isinplace}

Base for types which define BVP problems.

source
SciMLBase.AbstractSDDEProblem — Type
abstract type AbstractSDDEProblem{uType, tType, lType, isinplace, ND} <: SciMLBase.AbstractDEProblem

Base for types which define SDDE problems.

source