Building and solving numerical problems

Systems are numerically solved by building and solving the appropriate problem type. Numerical solvers expect to receive functions taking a predefeined set of arguments and returning specific values. This format of argument and return value depends on the function and the problem. ModelingToolkit is capable of compiling and generating code for a variety of such numerical problems.

In-place and out-of-place problems

Every problem and function constructor takes an iip type parameter selecting an in-place or out-of-place formulation. Problem constructors called without it defer the choice to construction time using a sentinel type.

ModelingToolkitBase.Both — Type

Both

Sentinel type used as the iip type parameter in problem constructors when the caller did not explicitly specify in-place vs. out-of-place behavior. The actual value is resolved at construction time: iip = false when the operating-point op is a StaticArray, and iip = true otherwise.

Dynamical systems

SciMLBase.ODEFunction — Type

SciMLBase.ODEFunction(sys::System; kwargs...)
SciMLBase.ODEFunction{iip}(sys::System; kwargs...)
SciMLBase.ODEFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.ODEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ODEFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.ODEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
jac: Whether to symbolically compute and generate code for the jacobian function.
tgrad: Whether to symbolically compute and generate code for the tgrad function.
paramjac: Whether to symbolically compute and generate code for the jacobian of the ODE right-hand side with respect to the parameters. Column j of the result is the derivative with respect to entry j of SciMLStructures.canonicalize(SciMLStructures.Tunable(), p)[1].
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.ODEFunction struct constructor.

SciMLBase.ODEFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds an ODEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above. Useful for callers that already hold (or want to share/reuse) an options struct, since — unlike the kwargs... wrapper — this method does not need to re-validate or re-assemble the option set.

SciMLBase.ODEProblem — Type

SciMLBase.SciMLBase.ODEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.ODEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.ODEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.ODEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ODEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.ODEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.ODEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.ODEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.DAEFunction — Type

SciMLBase.DAEFunction(sys::System; kwargs...)
SciMLBase.DAEFunction{iip}(sys::System; kwargs...)
SciMLBase.DAEFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.DAEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DAEFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DAEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
jac: Whether to symbolically compute and generate code for the jacobian function.
tgrad: Whether to symbolically compute and generate code for the tgrad function.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.DAEFunction struct constructor.

SciMLBase.DAEFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds a DAEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.DAEProblem — Type

SciMLBase.SciMLBase.DAEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DAEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DAEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.DAEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DAEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.DAEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DAEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.DAEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

ModelingToolkit.SemilinearODEFunction — Type

ModelingToolkit.SemilinearODEFunction(sys::System; kwargs...)
ModelingToolkit.SemilinearODEFunction{iip}(sys::System; kwargs...)
ModelingToolkit.SemilinearODEFunction{iip, specialize}(sys::System; kwargs...)

Create a ModelingToolkit.SemilinearODEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the ModelingToolkit.SemilinearODEFunction.

This is a special form of an ODE which uses a SplitFunction internally. The equations are separated into linear, quadratic and general terms and phrased as matrix operations. See calculate_semiquadratic_form for information on how the equations are split. This formulation allows leveraging split ODE solvers such as KenCarp4 and is useful for systems where the stiff and non-stiff terms can be separated out in such a manner. Typically the linear part of the equations is the stiff part, but the keywords stiff_linear, stiff_quadratic and stiff_nonlinear can be used to control which parts are considered as stiff.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a ModelingToolkit.SemilinearODEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
jac: Whether to symbolically compute and generate code for the jacobian function.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.
stiff_linear: Whether the linear part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no linear part.
stiff_quadratic: Whether the quadratic part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no quadratic part.
stiff_nonlinear: Whether the non-linear non-quadratic part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no such non-linear non-quadratic part.
kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the ModelingToolkit.SemilinearODEFunction struct constructor. Note that all three of stiff_linear, stiff_quadratic, stiff_nonlinear cannot be identical, and at least two of A, B, C returned from calculate_semiquadratic_form must be non-nothing. In other words, both of the functions in the split form must be non-empty.

SemilinearODEFunction{iip, specialize}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds a SemilinearODEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

ModelingToolkit.SemilinearODEProblem — Type

SciMLBase.ModelingToolkit.SemilinearODEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.ModelingToolkit.SemilinearODEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.ModelingToolkit.SemilinearODEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a ModelingToolkit.SemilinearODEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the ModelingToolkit.SemilinearODEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in ModelingToolkit.SemilinearODEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

This is a special form of an ODE which uses a SplitFunction internally. The equations are separated into linear, quadratic and general terms and phrased as matrix operations. See calculate_semiquadratic_form for information on how the equations are split. This formulation allows leveraging split ODE solvers such as KenCarp4 and is useful for systems where the stiff and non-stiff terms can be separated out in such a manner. Typically the linear part of the equations is the stiff part, but the keywords stiff_linear, stiff_quadratic and stiff_nonlinear can be used to control which parts are considered as stiff.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a ModelingToolkit.SemilinearODEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
stiff_linear: Whether the linear part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no linear part.
stiff_quadratic: Whether the quadratic part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no quadratic part.
stiff_nonlinear: Whether the non-linear non-quadratic part of the equations should be part of the stiff function in the split form. Has no effect if the equations have no such non-linear non-quadratic part.

All other keyword arguments are forwarded to the ModelingToolkit.SemilinearODEFunction constructor. Note that all three of stiff_linear, stiff_quadratic, stiff_nonlinear cannot be identical, and at least two of A, B, C returned from calculate_semiquadratic_form must be non-nothing. In other words, both of the functions in the split form must be non-empty.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.SDEFunction — Type

SciMLBase.SDEFunction(sys::System; kwargs...)
SciMLBase.SDEFunction{iip}(sys::System; kwargs...)
SciMLBase.SDEFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.SDEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.SDEFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SDEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
jac: Whether to symbolically compute and generate code for the jacobian function.
tgrad: Whether to symbolically compute and generate code for the tgrad function.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.SDEFunction struct constructor.

SciMLBase.SDEFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds an SDEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.SDEProblem — Type

SciMLBase.SciMLBase.SDEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.SDEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.SDEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.SDEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.SDEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.SDEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SDEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.SDEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.DDEFunction — Type

SciMLBase.DDEFunction(sys::System; kwargs...)
SciMLBase.DDEFunction{iip}(sys::System; kwargs...)
SciMLBase.DDEFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.DDEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DDEFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DDEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.DDEFunction struct constructor.

SciMLBase.DDEFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions)

Public entry point that builds a DDEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.DDEProblem — Type

SciMLBase.SciMLBase.DDEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DDEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DDEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.DDEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DDEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.DDEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DDEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.DDEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.SDDEFunction — Type

SciMLBase.SDDEFunction(sys::System; kwargs...)
SciMLBase.SDDEFunction{iip}(sys::System; kwargs...)
SciMLBase.SDDEFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.SDDEFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.SDDEFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SDDEFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.SDDEFunction struct constructor.

SciMLBase.SDDEFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions)

Public entry point that builds an SDDEFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.SDDEProblem — Type

SciMLBase.SciMLBase.SDDEProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.SDDEProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.SDDEProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.SDDEProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.SDDEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.SDDEProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SDDEProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.SDDEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

JumpProcesses.JumpProblem — Type

SciMLBase.JumpProcesses.JumpProblem(sys::System, op, tspan::NTuple{2}; kwargs...)
SciMLBase.JumpProcesses.JumpProblem{iip}(sys::System, op, tspan::NTuple{2}; kwargs...)
SciMLBase.JumpProcesses.JumpProblem{iip, specialize}(sys::System, op, tspan::NTuple{2}; kwargs...)

Build a JumpProcesses.JumpProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the inner SciMLFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in JumpProcesses.JumpProblem. Any values not provided will fallback to the corresponding default (if present).

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a JumpProcesses.JumpProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the inner SciMLFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.BVProblem — Type

SciMLBase.SciMLBase.BVProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.BVProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.BVProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.BVProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ODEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.BVProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

Boundary value conditions are supplied to Systems in the form of a list of constraints. These equations should specify values that state variables should take at specific points, as in x(0.5) ~ 1). More general constraints that should hold over the entire solution, such as x(t)^2 + y(t)^2, should be specified as one of the equations used to build the System.

If a System without constraints is specified, it will be treated as an initial value problem.

    @parameters g t_c = 0.5
    @variables x(..) y(t) λ(t)
    eqs = [D(D(x(t))) ~ λ * x(t)
           D(D(y)) ~ λ * y - g
           x(t)^2 + y^2 ~ 1]
    cstr = [x(0.5) ~ 1]
    @mtkcompile pend = System(eqs, t; constraints = cstrs)

    tspan = (0.0, 1.5)
    u0map = [x(t) => 0.6, y => 0.8]
    parammap = [g => 1]
    guesses = [λ => 1]

    bvp = SciMLBase.BVProblem{true, SciMLBase.AutoSpecialize}(pend, u0map, tspan, parammap; guesses, check_length = false)

If the System has algebraic equations, like x(t)^2 + y(t)^2, the resulting BVProblem must be solved using BVDAE solvers, such as Ascher.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.BVProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.ODEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.DiscreteFunction — Type

SciMLBase.DiscreteFunction(sys::System; kwargs...)
SciMLBase.DiscreteFunction{iip}(sys::System; kwargs...)
SciMLBase.DiscreteFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.DiscreteFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DiscreteFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DiscreteFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.DiscreteFunction struct constructor.

SciMLBase.DiscreteFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions)

Public entry point that builds a DiscreteFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.DiscreteProblem — Type

SciMLBase.SciMLBase.DiscreteProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DiscreteProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.DiscreteProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.DiscreteProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.DiscreteFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.DiscreteProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.DiscreteProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.DiscreteFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.ImplicitDiscreteFunction — Type

SciMLBase.ImplicitDiscreteFunction(sys::System; kwargs...)
SciMLBase.ImplicitDiscreteFunction{iip}(sys::System; kwargs...)
SciMLBase.ImplicitDiscreteFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.ImplicitDiscreteFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ImplicitDiscreteFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.ImplicitDiscreteFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.ImplicitDiscreteFunction struct constructor.

SciMLBase.ImplicitDiscreteFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions)

Public entry point that builds an ImplicitDiscreteFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.ImplicitDiscreteProblem — Type

SciMLBase.SciMLBase.ImplicitDiscreteProblem(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.ImplicitDiscreteProblem{iip}(sys::System, op, [tspan::NTuple{2}]; kwargs...)
SciMLBase.SciMLBase.ImplicitDiscreteProblem{iip, specialize}(sys::System, op, [tspan::NTuple{2}]; kwargs...)

Build a SciMLBase.ImplicitDiscreteProblem given a system sys and operating point op and timespan tspan. iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ImplicitDiscreteFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.ImplicitDiscreteProblem. Any values not provided will fallback to the corresponding default (if present).

tspan is optional. When omitted, the timespan stored in sys is used - the one given by the tspan keyword argument of System and returned by ModelingToolkitBase.get_tspan. Omitting it for a system that has no timespan throws an error.

ModelingToolkitBase will build an initialization problem where all initial values for unknowns or observables of sys (either explicitly provided or in defaults) will be constraints. To remove an initial condition in the defaults (without providing a replacement) give the corresponding variable a value of nothing in the operating point. The initialization problem will also run parameter initialization. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.
callback: An extra callback or CallbackSet to add to the problem, in addition to the ones defined symbolically in the system.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.ImplicitDiscreteProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks

All other keyword arguments are forwarded to the SciMLBase.ImplicitDiscreteFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

Linear and Nonlinear systems

SciMLBase.NonlinearFunction — Type

SciMLBase.NonlinearFunction(sys::System; kwargs...)
SciMLBase.NonlinearFunction{iip}(sys::System; kwargs...)
SciMLBase.NonlinearFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.NonlinearFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.NonlinearFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.NonlinearFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.
resid_prototype: The prototype of the residual function f for a problem involving a nonlinear solve where the residual and u0 have different sizes.
jac: Whether to symbolically compute and generate code for the jacobian function.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.NonlinearFunction struct constructor.

SciMLBase.NonlinearFunction{iip, spec}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds a NonlinearFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.NonlinearProblem — Type

SciMLBase.SciMLBase.NonlinearProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.NonlinearProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.NonlinearProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.NonlinearProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.NonlinearFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.NonlinearProblem. Any values not provided will fallback to the corresponding default (if present).

ModelingToolkitBase will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x, it must be used as Initial(x) in the equation. For example, an equation to be used to solve for parameter p in terms of unknowns x and y must be provided as Initial(x) + Initial(y) ~ p instead of x + y ~ p. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.NonlinearProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the SciMLBase.NonlinearFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.AbstractNonlinearProblem — Method

SciMLBase.AbstractNonlinearProblem(sys::System, op; kwargs...)

Build a nonlinear problem from sys, automatically selecting the concrete type via get_nonlinear_problem_type: a SciMLBase.HomotopyProblem when sys contains Modelica homotopy(actual, simplified) nodes (so the equations are solved by continuation from the simplified form), otherwise a plain SciMLBase.NonlinearProblem. Keyword arguments are forwarded to the selected constructor; λspan only applies to the HomotopyProblem branch.

SciMLBase.HomotopyProblem — Type

SciMLBase.HomotopyProblem(sys::System, op; λspan = (0.0, 1.0), kwargs...)
SciMLBase.HomotopyProblem{iip}(sys::System, op; λspan = (0.0, 1.0), kwargs...)
SciMLBase.HomotopyProblem{iip, spec}(sys::System, op; λspan = (0.0, 1.0), kwargs...)

Build a SciMLBase.HomotopyProblem from a System whose equations contain Modelica homotopy(actual, simplified) nodes (Modelica spec 3.7.4.2). As with the other problem constructors, the zero-parameter form derives in-place-ness from op and the {iip} form uses the requested iip (which is what the initialization path passes through).

The standard nonlinear residual is built from sys (and used only to obtain u0, p, the observed function, and the residual prototype), then the residual is regenerated with every homotopy(actual, simplified) replaced by the convex blend (1 - λ)*simplified + λ*actual and compiled as f(u, p, λ). λ is an explicit trailing argument — it is never added to the system's parameters, and p passes through untouched — so the result solves by natural-parameter continuation (NonlinearSolveBase.HomotopySweep), sweeping λ across λspan (default (0.0, 1.0), i.e. from simplified to actual).

sys must be completed and must contain at least one homotopy node (use SciMLBase.NonlinearProblem otherwise, or AbstractNonlinearProblem to select automatically). The jacobian/sparsity of the standard build are deliberately dropped: they encode the λ = 1 (opaque-actual) system and would be wrong mid-sweep.

Note

expression = Val{true} (codegen-to-Expr) is not yet supported for the homotopy constructor; this can be added in a future PR.

SciMLBase.SCCNonlinearProblem — Type

SciMLBase.SciMLBase.SCCNonlinearProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.SCCNonlinearProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.SCCNonlinearProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.SCCNonlinearProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.NonlinearFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.SCCNonlinearProblem. Any values not provided will fallback to the corresponding default (if present).

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SCCNonlinearProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the SciMLBase.NonlinearFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.NonlinearLeastSquaresProblem — Type

SciMLBase.SciMLBase.NonlinearLeastSquaresProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.NonlinearLeastSquaresProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.NonlinearLeastSquaresProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.NonlinearLeastSquaresProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.NonlinearFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.NonlinearLeastSquaresProblem. Any values not provided will fallback to the corresponding default (if present).

ModelingToolkitBase will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x, it must be used as Initial(x) in the equation. For example, an equation to be used to solve for parameter p in terms of unknowns x and y must be provided as Initial(x) + Initial(y) ~ p instead of x + y ~ p. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.NonlinearLeastSquaresProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the SciMLBase.NonlinearFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.SteadyStateProblem — Type

SciMLBase.SciMLBase.SteadyStateProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.SteadyStateProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.SteadyStateProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.SteadyStateProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ODEFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.SteadyStateProblem. Any values not provided will fallback to the corresponding default (if present).

ModelingToolkitBase will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x, it must be used as Initial(x) in the equation. For example, an equation to be used to solve for parameter p in terms of unknowns x and y must be provided as Initial(x) + Initial(y) ~ p instead of x + y ~ p. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.SteadyStateProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the SciMLBase.ODEFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.IntervalNonlinearFunction — Type

SciMLBase.IntervalNonlinearFunction(sys::System; kwargs...)
SciMLBase.IntervalNonlinearFunction{iip}(sys::System; kwargs...)
SciMLBase.IntervalNonlinearFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.IntervalNonlinearFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.IntervalNonlinearFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.IntervalNonlinearFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.IntervalNonlinearFunction struct constructor.

SciMLBase.IntervalNonlinearFunction(sys::System, opts::SciMLFunctionOptions)

Public entry point that builds an IntervalNonlinearFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.IntervalNonlinearProblem — Type

SciMLBase.SciMLBase.IntervalNonlinearProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.IntervalNonlinearProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.IntervalNonlinearProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.IntervalNonlinearProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.IntervalNonlinearFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.IntervalNonlinearProblem. Any values not provided will fallback to the corresponding default (if present).

ModelingToolkitBase will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x, it must be used as Initial(x) in the equation. For example, an equation to be used to solve for parameter p in terms of unknowns x and y must be provided as Initial(x) + Initial(y) ~ p instead of x + y ~ p. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.IntervalNonlinearProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the SciMLBase.IntervalNonlinearFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

ModelingToolkitBase.HomotopyContinuationProblem — Type

HomotopyContinuationProblem(sys::System, args...; kwargs...)

Construct a homotopy-continuation problem from a nonlinear sys. This problem type is intended for solvers that track solution paths from a start system to the target system.

Example

@variables x = 1.0
@mtkcompile sys = System([x^2 - 1 ~ 0])
prob = HomotopyContinuationProblem(sys, [])

See NonlinearProblem for the standard nonlinear-problem constructor.

SciMLBase.HomotopyNonlinearFunction — Type

SciMLBase.HomotopyNonlinearFunction(sys::System; kwargs...)
SciMLBase.HomotopyNonlinearFunction{iip}(sys::System; kwargs...)
SciMLBase.HomotopyNonlinearFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.HomotopyNonlinearFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.HomotopyNonlinearFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.HomotopyNonlinearFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

fraction_cancel_fn: Function used to simplify fractions in polynomial expressions.
kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.HomotopyNonlinearFunction struct constructor.

SciMLBase.LinearProblem — Type

SciMLBase.SciMLBase.LinearProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.LinearProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.LinearProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.LinearProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the ModelingToolkitBase.LinearFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.LinearProblem. Any values not provided will fallback to the corresponding default (if present).

ModelingToolkitBase will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x, it must be used as Initial(x) in the equation. For example, an equation to be used to solve for parameter p in terms of unknowns x and y must be provided as Initial(x) + Initial(y) ~ p instead of x + y ~ p. See the Initialization documentation for more information.

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.LinearProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.

All other keyword arguments are forwarded to the ModelingToolkitBase.LinearFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

Problem type metadata

Systems can carry a problem_type that is forwarded to the constructed problem. This is how discretization packages attach their own metadata to a generated problem and recover it downstream, for example to wrap a solution in a richer solution type.

ModelingToolkitBase.ProblemTypeCtx — Type

Metadata key for systems containing the problem_type to be passed to the problem constructor, where applicable. For example, if getmetadata(sys, ProblemTypeCtx, nothing) is CustomType() then ODEProblem(sys, ...).problem_type will be CustomType() instead of StandardODEProblem.

Optimization and optimal control

SciMLBase.OptimizationFunction — Type

SciMLBase.OptimizationFunction(sys::System; kwargs...)
SciMLBase.OptimizationFunction{iip}(sys::System; kwargs...)
SciMLBase.OptimizationFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.OptimizationFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.OptimizationFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.OptimizationFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.
jac: Whether to symbolically compute and generate code for the jacobian function.
grad: Whether the symbolically compute and generate code for the gradient of the cost function with respect to unknowns.
hess: Whether to symbolically compute and generate code for the hessian function.
cons_h: Whether to symbolically compute and generate code for the hessian function of constraints. Since the constraint function is vector-valued, the hessian is a vector of hessian matrices.
cons_j: Whether to symbolically compute and generate code for the jacobian function of constraints.
adtype: The choice of AD backend to use for derivatives of the objective and constraints, given as an ADTypes.AbstractADType such as AutoForwardDiff() or AutoEnzyme(). This is stored as the adtype field of the resulting function, which Optimization.jl dispatches on when instantiating it for a solver. Defaults to SciMLBase.NoAD(), which defers the choice of backend to the solver. adtype can also be passed as the second positional argument of OptimizationFunction, matching the SciMLBase.OptimizationFunction constructor. It is independent of grad, hess, cons_j and cons_h, which control symbolic generation of derivative functions.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.
cons_sparse: Identical to the sparse keyword, but specifically for jacobian/hessian functions of the constraints.
weights: An optional vector of weights for scalarizing a system with multiple costs. If provided, the generated objective is sum(weights .* get_costs(sys)) plus the recursively consolidated costs of all subsystems, replacing the system's consolidate function for this lowering. weights must have one entry per top-level cost of sys. Entries may be real numbers or symbolic parameters of sys; symbolic weights must be declared as @parameters of the system so that they are part of the parameter object and can be updated via remake between solves.
kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.OptimizationFunction struct constructor.

SciMLBase.OptimizationFunction{iip}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds an OptimizationFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

SciMLBase.OptimizationProblem — Type

SciMLBase.SciMLBase.OptimizationProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.OptimizationProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.OptimizationProblem{iip, specialize}(sys::System, op; kwargs...)

Build a SciMLBase.OptimizationProblem given a system sys and operating point op . iip is a boolean indicating whether the problem should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.OptimizationFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.OptimizationProblem. Any values not provided will fallback to the corresponding default (if present).

Keyword arguments

eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
check_initialization_units: Enable or disable unit checks when constructing the initialization problem.
tofloat: Passed to varmap_to_vars when building the parameter vector of a non-split system.
u0_eltype: The eltype of the u0 vector. If nothing, finds the promoted floating point type from op.
u0_constructor: A function to apply to the u0 value returned from varmap_to_vars. to construct the final u0 value.
p_constructor: A function to apply to each array buffer created when constructing the parameter object.
warn_cyclic_dependency: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.
circular_dependency_max_cycle_length: Maximum length of cycle to check for. Only applicable if warn_cyclic_dependency == true.
circular_dependency_max_cycles: Maximum number of cycles to check for. Only applicable if warn_cyclic_dependency == true.
substitution_limit: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
missing_guess_value: An instance of MissingGuessValue which indicates what happens when the initialization problem is missing guess values for variables.
initsys_mtkcompile_kwargs: A NamedTuple of keyword arguments to pass to mtkcompile when it is called on the initialization system.

check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.OptimizationProblem and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise.
weights: An optional vector of weights for scalarizing a system with multiple costs. If provided, the generated objective is sum(weights .* get_costs(sys)) plus the recursively consolidated costs of all subsystems, replacing the system's consolidate function for this lowering. weights must have one entry per top-level cost of sys. Entries may be real numbers or symbolic parameters of sys; symbolic weights must be declared as @parameters of the system so that they are part of the parameter object and can be updated via remake between solves.
adtype: Forwarded to the OptimizationFunction constructor; sets the adtype field of the resulting function.

All other keyword arguments are forwarded to the SciMLBase.OptimizationFunction constructor.

Extended docs

The following API is internal and may change or be removed without notice. Its usage is highly discouraged.

build_initializeprob: If false, avoids building the initialization problem.
check_length: Whether to check the number of equations along with number of unknowns and length of u0 vector for consistency. If false, do not check with equations. This is forwarded to check_eqs_u0.
return_operating_point: Whether to also return the updated operating point.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

SciMLBase.ODEInputFunction — Type

SciMLBase.ODEInputFunction(sys::System; kwargs...)
SciMLBase.ODEInputFunction{iip}(sys::System; kwargs...)
SciMLBase.ODEInputFunction{iip, specialize}(sys::System; kwargs...)

Create a SciMLBase.ODEInputFunction from the given sys. iip is a boolean indicating whether the function should be in-place. specialization is a SciMLBase.AbstractSpecalize subtype indicating the level of specialization of the SciMLBase.ODEInputFunction.

Beyond the arguments listed below, this constructor accepts all keyword arguments supported by the DifferentialEquations.jl solve function. For a complete list and detailed descriptions, see the DifferentialEquations.jl solve documentation.

Keyword arguments

u0: The u0 vector for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_u0.
p: The parameter object for the corresponding problem, if available. Can be obtained using ModelingToolkitBase.get_p.
t: The initial time for the corresponding problem, if available.
eval_expression: Whether to compile any functions via eval or RuntimeGeneratedFunctions.
eval_module: If eval_expression == true, the module to eval into. Otherwise, the module in which to generate the RuntimeGeneratedFunction.
checkbounds: Whether to enable bounds checking in the generated code.
simplify: Whether to simplify any symbolically computed jacobians/hessians/etc. This typically improves performance of the generated code but reduces readability.
sparse: Whether to generate jacobian/hessian/etc. functions that return/operate on sparse matrices. Also controls whether the mass matrix is sparse, wherever applicable.
check_compatibility: Whether to check if the given system sys contains all the information necessary to create a SciMLBase.ODEInputFunction and no more. If disabled, assumes that sys at least contains the necessary information.
expression: Val{true} to return an Expr that constructs the corresponding problem instead of the problem itself. Val{false} otherwise. Constructing the expression does not support callbacks
inputs: The variables in the input vector. The system must have been simplified using mtkcompile with these variables passed as inputs.
disturbance_inputs: The disturbance input variables. The system must have been simplified using mtkcompile with these variables passed as disturbance_inputs.
jac: Whether to symbolically compute and generate code for the jacobian function.
tgrad: Whether to symbolically compute and generate code for the tgrad function.
controljac: Whether to symbolically compute and generate code for the jacobian of the ODE with respect to the inputs.
sparsity: Whether to provide symbolically compute and provide sparsity patterns for the jacobian/hessian/etc.

kwargs...: Additional keyword arguments passed to the solver

All other keyword arguments are forwarded to the SciMLBase.ODEInputFunction struct constructor.

SciMLBase.ODEInputFunction{iip, specialize}(sys::System, opts::SciMLFunctionOptions; kwargs...)

Public entry point that builds an ODEInputFunction directly from a pre-assembled SciMLFunctionOptions, bypassing the kwargs... wrapper above.

ModelingToolkitBase.constraints_to_penalties — Function

constraints_to_penalties(sys::System; weights = 1.0)

Return a new System in which every constraint of sys - including those of its subsystems - is removed from constraints and appended to costs as a weighted quadratic penalty term. This is the "classical PINN" formulation of a constrained problem: all constraint residuals are folded into the objective, producing an unconstrained system that can be solved by optimizers which do not accept explicit cons/lcons/ucons constraints.

Equation constraints l ~ r contribute weights[i] * (l - r)^2.
Inequality constraints contribute weights[i] * max(residual, 0)^2, where residual is the constraint rewritten in canonical residual ≲ 0 form via Symbolics.canonical_form, so only violations of the constraint are penalized.

weights may be a scalar applied to every constraint, or a vector with one entry per element of constraints(sys), which orders a system's own constraints before its subsystems'. Symbolic weights (e.g. penalty parameters that should be tunable through the problem's parameter object) that are not already parameters or unknowns of the system are automatically added to its parameters.

Penalty terms are appended to costs(sys) and are therefore combined with the rest of the objective through the system's consolidate function. Note that a finite weights makes the constraint satisfaction soft: increasing the magnitude of the weights enforces the constraints more tightly at the cost of a stiffer objective.

Example

using ModelingToolkitBase
@variables x
@named sys = OptimizationSystem((x - 2)^2, [x], []; constraints = [x ≲ 1])
pen_sys = constraints_to_penalties(complete(sys); weights = 1.0e3)

The state vector and parameter object

Typically the unknowns of the system are present as a Vector of the appropriate length in the numerical problem. The state vector can also be constructed manually without building a problem.

ModelingToolkitBase.get_u0 — Function

get_u0(
    sys::ModelingToolkitBase.AbstractSystem,
    varmap;
    kwargs...
) -> Any

Return the u0 vector for the given system sys and variable-value mapping varmap. All keyword arguments are forwarded to varmap_to_vars.

ModelingToolkitBase.varmap_to_vars — Function

varmap_to_vars(
    varmap::AbstractDict,
    vars::Vector;
    ir,
    tofloat,
    use_union,
    container_type,
    buffer_eltype,
    toterm,
    check,
    allow_symbolic,
    is_initializeprob,
    substitution_limit,
    missing_values
) -> Any

Return an array of values where the ith element corresponds to the value of vars[i] in varmap. Will mutate varmap by symbolically substituting it into itself.

Keyword arguments:

container_type: The type of the returned container.
allow_symbolic: Whether the returned container of values can have symbolic expressions.
buffer_eltype: The eltype of the returned container if !allow_symbolic. If Nothing, automatically promotes the values in the container to a common eltype.
tofloat: Whether to promote values to floating point numbers if buffer_eltype == Nothing.
use_union: Whether to allow using a Union as the eltype if buffer_eltype == Nothing.
toterm: The toterm function for canonicalizing keys of varmap. A value of nothing disables this process.
check: Whether to check if all of vars are keys of varmap.
is_initializeprob: Whether an initialization problem is being constructed. Used for better error messages.
substitution_limit: The maximum number of times to recursively substitute varmap into itself to get a numeric value for each variable in vars.

The parameters of a split system are stored in a custom data structure called MTKParameters. ModelingToolkit problem constructors use SciMLBase.AutoDespecialize by default. Solvers that support this policy wrap the parameters in SciMLBase.DespecializedParameters at solve time so compiled code can be reused across parameter-buffer layouts. Explicit AutoSpecialize and FullSpecialize problems retain their existing behavior. These objects should only be interacted with through their defined public API. SymbolicIndexingInterface.jl contains functionality useful for this purpose.

ModelingToolkitBase.MTKParameters — Type

function MTKParameters(sys::AbstractSystem, p, u0 = Dict(); t0 = nothing)

Create an MTKParameters object for the system sys. p (u0) are symbolic maps from parameters (unknowns) to their values. The values can also be symbolic expressions, which are evaluated given the values of other parameters/unknowns. u0 is only required if the values of parameters depend on the unknowns. t0 is the initial time, for time- dependent systems. It is only required if the symbolic expressions also use the independent variable of the system.

This requires that complete has been called on the system (usually via mtkcompile or @mtkcompile) and the keyword split = true was passed (which is the default behavior).

ModelingToolkitBase.get_p — Function

get_p(
    sys::ModelingToolkitBase.AbstractSystem,
    varmap;
    split,
    kwargs...
) -> Any

Return the p object for the given system sys and variable-value mapping varmap. All keyword arguments are forwarded to MTKParameters for split systems and varmap_to_vars for non-split systems.

The following functions are useful when working with MTKParameters objects, and especially the Tunables portion. For more information about the "portions" of MTKParameters, refer to the SciMLStructures.jl documentation.

ModelingToolkitBase.reorder_dimension_by_tunables! — Function

reorder_dimension_by_tunables!(dest::AbstractArray, sys::AbstractSystem, arr::AbstractArray, syms; dim = 1)

Assuming the order of values in dimension dim of arr correspond to the order of tunable parameters in the system, reorder them according to the order described in syms. syms must be a permutation of tunable_parameters(sys). The result is written to dest. The size of dest and arr must be equal. Return dest.

See also: MTKParameters, tunable_parameters, reorder_dimension_by_tunables.

ModelingToolkitBase.reorder_dimension_by_tunables — Function

reorder_dimension_by_tunables(sys::AbstractSystem, arr::AbstractArray, syms; dim = 1)

Out-of-place version of reorder_dimension_by_tunables!.

Initialization

ModelingToolkitBase.generate_initializesystem — Function

generate_initializesystem(
    sys::ModelingToolkitBase.AbstractSystem;
    time_dependent_init,
    kwargs...
) -> Any

Generate the initialization system for sys. The initialization system is a system of nonlinear equations that solve for the full set of initial conditions of sys given specified constraints.

The initialization system can be of two types: time-dependent and time-independent. Time-dependent initialization systems solve for the initial values of unknowns as well as the values of solvable parameters of the system. Time-independent initialization systems only solve for solvable parameters of the system.

Keyword arguments

time_dependent_init: Whether to create an initialization system for a time-dependent system. A time-dependent initialization requires a time-dependent sys, but a time- independent initialization can be created regardless.
op: The operating point of user-specified initial conditions of variables in sys.
initialization_eqs: Additional initialization equations to use apart from those in initialization_equations(sys).
guesses: Additional guesses to use apart from those in guesses(sys).
default_dd_guess: Default guess for dummy derivative variables in time-dependent initialization.
algebraic_only: If false, does not use initialization equations (provided via the keyword or part of the system) to construct initialization.
name: The name of the initialization system.

All other keyword arguments are forwarded to the System constructor.

ModelingToolkitBase.InitializationProblem — Type

InitializationProblem(sys::AbstractSystem, t, op = Dict(); kwargs...)
InitializationProblem{iip}(sys::AbstractSystem, t, op = Dict(); kwargs...)
InitializationProblem{iip, specialize}(sys::AbstractSystem, t, op = Dict(); kwargs...)

Generate a LinearProblem, NonlinearProblem, SCCNonlinearProblem, NonlinearLeastSquaresProblem or SciMLBase.HomotopyProblem to represent a consistent initialization of sys given the initial time t and operating point op. The initial time can be nothing for time-independent systems. A LinearProblem is used when the initialization system is linear (affine). A SciMLBase.HomotopyProblem is used when the (square) initialization system contains Modelica homotopy(actual, simplified) nodes, so the initialization is solved by continuation from the simplified form (see homotopy).

Keyword arguments

guesses: The guesses for variables in the system, used as initial values for the initialization problem.
warn_initialize_determined: Warn if the initialization system is under/over-determined.
initialization_eqs: Extra equations to use in the initialization problem.
fully_determined: Override whether the initialization system is fully determined.
use_scc: Whether to use SCCNonlinearProblem for initialization if the system is fully determined.
time_dependent_init: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistent u0, whereas a time-independent one only runs parameter initialization.
algebraic_only: Whether to build the initialization problem using only algebraic equations.
allow_incomplete: Whether to allow incomplete initialization problems.

All other keyword arguments are forwarded to the wrapped problem constructor.

ModelingToolkit.analyze_initialization_jacobian — Function

analyze_initialization_jacobian(prob; rtol = 1e-8, atol = 0.0, threshold = 1e-3, verbose = true, autodiff = nothing)

Diagnose rank deficiency of a system's initialization problem by inspecting the singular value decomposition of its residual Jacobian, and report both the unknowns that span its (right) null space and the equations that are locally redundant (its left null space).

When the initialization system is rank deficient the solve can converge to different solutions, or fail, depending on the solver and on the (often nondeterministic) ordering of the assembled unknowns/equations — a common source of intermittent initialization failures: some orderings land on a singular realization and throw, others succeed. This utility makes the offending degrees of freedom explicit:

Underdetermined unknowns (right null space): directions along which the initialization is free to move. Pinning these unknowns (or adding equations that constrain them) makes the initialization well-posed and deterministic.
Redundant equations (left null space): combinations of initialization equations whose Jacobian rows are linearly dependent at u0, i.e. equations that do not locally constrain any additional degree of freedom. These explain why an initialization can have more equations than unknowns yet still be underdetermined.

It evaluates the Jacobian of the initialization residual at the initial guess u0 and computes its SVD. By default the Jacobian is formed by central finite differences, which reuses the already-compiled residual function; pass an ADTypes backend via autodiff (e.g. AutoForwardDiff()) to differentiate through DifferentiationInterface instead, at the cost of compiling the residual for the backend's number types. prob may be a problem that carries initialization data (e.g. an ODEProblem/DAEProblem built from a System), or an initialization NonlinearProblem/NonlinearLeastSquaresProblem directly.

Arguments

prob: A problem with initialization data, or an initialization NonlinearProblem/NonlinearLeastSquaresProblem.

Keywords

rtol: a singular value σ is treated as zero when σ ≤ max(atol, rtol * σmax), where σmax is the largest singular value. Increase it to also surface near-singular directions.
atol: absolute singular-value threshold (see rtol).
threshold: only unknowns/equations whose participation exceeds this value are reported.
verbose: print a human-readable report.
autodiff: nothing (default) computes the Jacobian by central finite differences with step cbrt(eps), whose truncation error is far below the default rank tolerance and whose first call avoids recompiling the generated residual (the dominant cost of dual-number AD on large systems). Alternatively an ADTypes backend evaluated through DifferentiationInterface.

Returns

A NamedTuple(; jacobian, singular_values, rank, nullity, redundancy, underdetermined_unknowns, redundant_equations).

nullity = ncols - rank is the number of underdetermined directions and redundancy = nrows - rank the number of redundant equations.
underdetermined_unknowns is a vector of unknown => weight pairs and redundant_equations a vector of equation => weight pairs, each sorted by decreasing weight ∈ [0, 1]. The weight is the diagonal of the corresponding null-space projector (the squared row norm over an orthonormal basis of the right/left null space): how strongly that unknown/equation participates in the underdetermined/redundant directions, independent of the arbitrary basis chosen within the null space.

A nullity of 0 means the Jacobian has full column rank at u0 (no underdetermined unknowns); a redundancy of 0 means full row rank (no redundant equations).

Examples

analysis = analyze_initialization_jacobian(prob)
analysis.nullity, analysis.redundancy

Note

The Jacobian is evaluated at a single point (u0), so this reports the local rank structure there. A structurally well-posed initialization can still be numerically rank deficient at a particular operating point, and vice versa.

ModelingToolkitBase.MissingGuessValue — Module

MissingGuessValue

A Moshi.jl enum to allow choosing what happens with missing guess values when building a numerical problem from a System.

Variants

MissingGuessValue.Constant(val::Number): Missing guesses are set to the given value val.
MissingGuessValue.Random(rng::AbstractRNG): Missing guesses are set to rand(rng).
MissingGuessValue.HashedRandom: Missing guesses are set to a deterministically determined random-like value based on the hash of the variable name
MissingGuessValue.Error(): Missing guess values cause an error.

Returns

A MissingGuessValue variant accepted by the missing_guess_value keyword of numerical problem constructors.

Examples

using ModelingToolkitBase

MissingGuessValue.Constant(0.0)

Linear analysis

ModelingToolkit.linearization_function — Function

lin_fun, simplified_sys = linearization_function(sys::AbstractSystem, inputs, outputs; simplify = false, initialize = true, initialization_solver_alg = nothing, kwargs...)

Return a function that linearizes the system sys. The function linearize provides a higher-level and easier to use interface.

lin_fun is a function (variables, p, t) -> (; f_x, f_z, g_x, g_z, f_u, g_u, h_x, h_z, h_u), i.e., it returns a NamedTuple with the Jacobians of f,g,h for the nonlinear sys (technically for simplified_sys) on the form

\[\begin{aligned} ẋ &= f(x, z, u) \\ 0 &= g(x, z, u) \\ y &= h(x, z, u) \end{aligned}\]

where x are differential unknown variables, z algebraic variables, u inputs and y outputs. To obtain a linear statespace representation, see linearize. The input argument variables is a vector defining the operating point, corresponding to unknowns(simplified_sys) and p is a vector corresponding to the parameters of simplified_sys. Note: all variables in inputs have been converted to parameters in simplified_sys.

The simplified_sys has undergone ModelingToolkitBase.mtkcompile and had any occurring input or output variables replaced with the variables provided in arguments inputs and outputs. The unknowns of this system also indicate the order of the unknowns that holds for the linearized matrices.

Arguments:

sys: A System of ODEs. This function will automatically apply simplification passes on sys and return the resulting simplified_sys.
inputs: A vector of variables that indicate the inputs of the linearized input-output model.
outputs: A vector of variables that indicate the outputs of the linearized input-output model.
simplify: Apply simplification in tearing.
initialize: If true, a check is performed to ensure that the operating point is consistent (satisfies algebraic equations). If the op is not consistent, initialization is performed.
initialization_solver_alg: A NonlinearSolve algorithm to use for solving for a feasible set of state and algebraic variables that satisfies the specified operating point.
autodiff: An ADType supported by DifferentiationInterface.jl to use for calculating the necessary jacobians. Defaults to using AutoForwardDiff()
ignore_system_initial_conditions: Whether to ignore initial_conditions(sys) and only use op.
kwargs: Are passed on to find_solvables!

See also linearize which provides a higher-level interface.

ModelingToolkit.LinearizationProblem — Type

mutable struct LinearizationProblem{F<:ModelingToolkit.LinearizationFunction, T}

A problem for repeatedly linearizing a ModelingToolkit system at changing operating points.

Use LinearizationProblem with a system, inputs, and outputs to construct a problem. It supports symbolic indexing, allowing selected state and parameter values to be updated efficiently between calls to CommonSolve.solve. Mutate t to evaluate the linearization at a different value of the system's independent variable.

Fields

f::F: The generated linearization function that evaluates the system and stores its symbolic-indexing data.
t::T: The current value of the system's independent variable. This field may be mutated between calls to CommonSolve.solve.

ModelingToolkit.LinearizationOpPoint — Type

LinearizationOpPoint(sol, t; op = Dict()) -> LinearizationOpPoint

Wrap an ODESolution and one or more time points as an operating point for linearize. The operating point contains the values of differential state variables and parameters in sol at t; initialization determines any algebraic variables.

When t is an AbstractVector, linearize calls linearization_function once and evaluates the linearization at each time point, returning vectors of matrices and extras.

Arguments

sol::SciMLBase.AbstractODESolution: Solution supplying state and parameter values.
t: A time point or vector of time points at which to evaluate sol.

Keywords

op::AbstractDict = Dict(): Additional operating-point values that override values from sol, such as parameters introduced by loop_openings.

Returns

LinearizationOpPoint: An operating-point specification accepted by linearize.

Examples

op = LinearizationOpPoint(sol, [0.0, 1.0]; op = Dict(opened_signal => 0.0))
matrices, simplified_sys, extras = linearize(sys, inputs, outputs; op)

Fields

sol::SciMLBase.AbstractODESolution: The solution to extract operating point values from.

t::Any: The time point (or vector of time points) at which to evaluate the solution.

op::AbstractDict: Additional operating-point values merged into the solution-derived operating point at each time point (takes precedence over solution-derived values).

ModelingToolkit.linearize — Function

(; A, B, C, D), simplified_sys, extras = linearize(sys, inputs, outputs;    t=0.0, op = Dict(), allow_input_derivatives = false, zero_dummy_der=false, kwargs...)
(; A, B, C, D), extras                 = linearize(simplified_sys, lin_fun; t=0.0, op = Dict(), allow_input_derivatives = false, zero_dummy_der=false)

Linearize sys between inputs and outputs, both vectors of variables. Return a NamedTuple with the matrices of a linear statespace representation on the form

\[\begin{aligned} ẋ &= Ax + Bu\\ y &= Cx + Du \end{aligned}\]

The first signature automatically calls linearization_function internally, while the second signature expects the outputs of linearization_function as input.

op denotes the operating point around which to linearize. If none is provided, the default values of sys are used.

If allow_input_derivatives = false, an error will be thrown if input derivatives ($u̇$) appear as inputs in the linearized equations. If input derivatives are allowed, the returned B matrix will be of double width, corresponding to the input [u; u̇].

zero_dummy_der can be set to automatically set the operating point to zero for all dummy derivatives.

The return value extras is a NamedTuple (; x, p, t) containing the result of the initialization problem that was solved to determine the operating point.

See also linearization_function which provides a lower-level interface, linearize_symbolic and ModelingToolkit.reorder_unknowns.

See extended help for an example.

The implementation and notation follows that of "Linear Analysis Approach for Modelica Models", Allain et al. 2009

Extended help

This example builds the following feedback interconnection and linearizes it from the input of F to the output of P.


  r ┌─────┐       ┌─────┐     ┌─────┐
───►│     ├──────►│     │  u  │     │
    │  F  │       │  C  ├────►│  P  │ y
    └─────┘     ┌►│     │     │     ├─┬─►
                │ └─────┘     └─────┘ │
                │                     │
                └─────────────────────┘

using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D
function plant(; name)
    @variables x(t) = 1
    @variables u(t)=0 y(t)=0
    eqs = [D(x) ~ -x + u
           y ~ x]
    System(eqs, t; name = name)
end

function ref_filt(; name)
    @variables x(t)=0 y(t)=0
    @variables u(t)=0 [input = true]
    eqs = [D(x) ~ -2 * x + u
           y ~ x]
    System(eqs, t, name = name)
end

function controller(kp; name)
    @variables y(t)=0 r(t)=0 u(t)=0
    @parameters kp = kp
    eqs = [
        u ~ kp * (r - y),
    ]
    System(eqs, t; name = name)
end

@named f = ref_filt()
@named c = controller(1)
@named p = plant()

connections = [f.y ~ c.r # filtered reference to controller reference
               c.u ~ p.u # controller output to plant input
               p.y ~ c.y]

@named cl = System(connections, t, systems = [f, c, p])

lsys0, ssys = linearize(cl, [f.u], [p.x])
desired_order = [f.x, p.x]
lsys = ModelingToolkit.reorder_unknowns(lsys0, unknowns(ssys), desired_order)

@assert lsys.A == [-2 0; 1 -2]
@assert lsys.B == [1; 0;;]
@assert lsys.C == [0 1]
@assert lsys.D[] == 0

## Symbolic linearization
lsys_sym, _ = ModelingToolkit.linearize_symbolic(cl, [f.u], [p.x])

@assert substitute(lsys_sym.A, ModelingToolkit.defaults(cl)) == lsys.A

ModelingToolkit.linearize_symbolic — Function

matrices, simplified_sys = linearize_symbolic(sys::AbstractSystem, inputs, outputs;
    simplify = false,
    allow_input_derivatives = false,
    eval_expression = false,
    eval_module = @__MODULE__,
    split = true,
    kwargs...)

Symbolically linearize sys between inputs and outputs.

Unlike linearize, this uses Symbolics.jacobian and returns symbolic matrices instead of numerical matrices evaluated at an operating point.

Arguments

sys: the system to linearize. This function calls ModelingToolkitBase.mtkcompile internally.
inputs: input variables used as the columns of the B and D matrices.
outputs: output variables used as the rows of the C and D matrices.

Keyword Arguments

simplify: whether to run additional symbolic simplification during compilation.
allow_input_derivatives: whether differentiated inputs may appear in the linearized equations. If true, B and D include extra columns for those derivatives.
eval_expression: whether generated expressions are evaluated directly instead of using runtime-generated functions.
eval_module: the module used when eval_expression = true.
split: whether generated functions use a tuple of parameters or splatted parameters.
kwargs...: additional keyword arguments forwarded to ModelingToolkitBase.mtkcompile.

Returns

A pair (matrices, simplified_sys). matrices is a NamedTuple containing A, B, C, and D, plus the symbolic Jacobian blocks f_x, f_z, g_x, g_z, f_u, g_u, h_x, h_z, and h_u of

\[\begin{aligned} ẋ &= f(x, z, u) \\ 0 &= g(x, z, u) \\ y &= h(x, z, u) \end{aligned}\]

Here x are differential unknowns, z are algebraic unknowns, u are inputs, and y are outputs.

Examples

using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D

@variables x(t) = 1.0 u(t) = 0.0 y(t) = 0.0
eqs = [D(x) ~ -x + u,
       y ~ x]
@named sys = System(eqs, t)

matrices, simplified_sys = ModelingToolkit.linearize_symbolic(sys, [u], [y])
matrices.A

See also linearize, linearization_function, and reorder_unknowns.

There are also utilities for manipulating the results of these analyses in a symbolic context.

ModelingToolkit.similarity_transform — Function

(; Ã, B̃, C̃, D̃) = similarity_transform(sys, T; unitary=false)

Transform the state coordinates of a linear state-space model.

Arguments

sys: a NamedTuple with matrices A, B, C, and D, as returned by linearize or linearize_symbolic.
T: the coordinate transformation matrix where T * x̃ = x.

Keyword Arguments

unitary: if true, use the adjoint T' instead of factoring and solving with T.

Returns

A NamedTuple(; A, B, C, D) containing

Ã = T⁻¹AT
B̃ = T⁻¹ B
C̃ = CT
D̃ = D

Examples

sys = (; A = [-1.0 0.0; 0.0 -2.0], B = [1.0; 0.0;;],
       C = [0.0 1.0], D = zeros(1, 1))
T = [0.0 1.0; 1.0 0.0]

transformed = ModelingToolkit.similarity_transform(sys, T; unitary = true)

ModelingToolkit.reorder_unknowns — Function

reorder_unknowns(sys::NamedTuple, old, new)

Permute the state ordering of a linearized system.

Arguments

sys: a NamedTuple with matrices A, B, C, and D, as returned by linearize or linearize_symbolic.
old: the current state order, typically unknowns(simplified_sys).
new: the desired state order. It must contain the same entries as old.

Returns

A NamedTuple(; A, B, C, D) whose state-space matrices use the order new.

Examples

lsys, ssys = linearize(pid, [reference.u, measurement.u], [ctr_output.u])
desired_order = [int.x, der.x] # Unknowns that are present in unknowns(ssys)
lsys = ModelingToolkit.reorder_unknowns(lsys, unknowns(ssys), desired_order)

See also similarity_transform.