GitHub

Code generation utilities

These are lower-level functions that ModelingToolkit leverages to generate code for building numerical problems.

ModelingToolkitBase.generate_rhs — Function
generate_rhs(
    sys::System;
    implicit_dae,
    scalar,
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    override_discrete,
    cachesyms,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the RHS function for the equations of a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • implicit_dae: Whether the generated function should be in the implicit form. Applicable only for ODEs/DAEs or discrete systems. Instead of f(u, p, t) (f(du, u, p, t) for the in-place form) the function is f(du, u, p, t) (respectively f(resid, du, u, p, t)).
  • override_discrete: Whether to assume the system is discrete regardless of is_discrete_system(sys).
  • scalar: Whether to generate a single-out-of-place function that returns a scalar for the only equation in the system.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_diffusion_function — Function
generate_diffusion_function(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Any, Any}

Generate the diffusion function for the noise equations of a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_jacobian — Function
generate_jacobian(
    sys::System;
    simplify,
    sparse,
    eval_expression,
    eval_module,
    expression,
    wrap_gfw,
    checkbounds,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the jacobian function for the equations of a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • simplify, sparse: Forwarded to calculate_jacobian.
  • checkbounds: Whether to check correctness of indices at runtime if sparse. Also forwarded to build_function_wrapper.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_tgrad — Function
generate_tgrad(
    sys::System;
    simplify,
    eval_expression,
    eval_module,
    expression,
    wrap_gfw,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the tgrad function for the equations of a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_W — Function
generate_W(
    sys::System;
    simplify,
    sparse,
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    checkbounds,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the W = γ * M + J function for the equations of a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • simplify, sparse: Forwarded to calculate_jacobian.
  • checkbounds: Whether to check correctness of indices at runtime if sparse. Also forwarded to build_function_wrapper.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_dae_jacobian — Function
generate_dae_jacobian(
    sys::System;
    simplify,
    sparse,
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the DAE jacobian γ * J′ + J function for the equations of a System. J′ is the jacobian of the equations with respect to the du vector, and J is the standard jacobian.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_history — Function
generate_history(
    sys::System,
    u0;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the history function for a System, given a symbolic representation of the u0 vector prior to the initial time.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_boundary_conditions — Function
generate_boundary_conditions(
    sys::System,
    u0,
    u0_idxs,
    t0;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the boundary condition function for a System given the state vector u0, the indexes of u0 to consider as hard constraints u0_idxs and the initial time t0.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_cost — Function
generate_cost(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Any

Generate the cost function for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_cost_gradient — Function
generate_cost_gradient(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    simplify,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the gradient of the cost function with respect to unknowns for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_cost_hessian — Function
generate_cost_hessian(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    simplify,
    sparse,
    return_sparsity,
    kwargs...
) -> Union{Tuple{Expr, Expr}, Tuple{Tuple{Expr, Expr}, Union{Nothing, SparseArrays.SparseMatrixCSC{Float64, Int64}, Matrix{Float64}}}}

Generate the hessian of the cost function for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • simplify, sparse: Forwarded to calculate_cost_hessian.
  • return_sparsity: Whether to also return the sparsity pattern of the hessian as the second return value.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_cons — Function
generate_cons(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the constraint function for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_constraint_jacobian — Function
generate_constraint_jacobian(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    return_sparsity,
    simplify,
    sparse,
    kwargs...
) -> Union{Tuple{Expr, Expr}, Tuple{Tuple{Expr, Expr}, Any}}

Generate the jacobian of the constraint function for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • simplify, sparse: Forwarded to calculate_constraint_jacobian.
  • return_sparsity: Whether to also return the sparsity pattern of the jacobian as the second return value.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_constraint_hessian — Function
generate_constraint_hessian(
    sys::System;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    return_sparsity,
    simplify,
    sparse,
    kwargs...
) -> Union{Tuple{Expr, Expr}, Tuple{Tuple{Expr, Expr}, Any}}

Generate the hessian of the constraint function for a System.

Keyword Arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.
  • simplify, sparse: Forwarded to calculate_constraint_hessian.
  • return_sparsity: Whether to also return the sparsity pattern of the hessian as the second return value.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_control_jacobian — Function
generate_control_jacobian(
    sys::ModelingToolkitBase.AbstractSystem;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    simplify,
    sparse,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the jacobian function of the equations of sys with respect to the inputs.

Keyword arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.build_explicit_observed_function — Function
build_explicit_observed_function(sys, ts; kwargs...) -> Function(s)

Generates a function that computes the observed value(s) ts in the system sys, while making the assumption that there are no cycles in the equations.

Arguments

  • sys: The system for which to generate the function
  • ts: The symbolic observed values whose value should be computed

Keywords

  • return_inplace = Val(false): If true and the observed value is a vector, then return both the in place and out of place methods. Can take boolean true or false values, but Val(true) or Val(false) is preferred.
  • expression = false: Generates a Julia Exprcomputing the observed value ifexpression` is true
  • eval_expression = false: If true and expression = false, evaluates the returned function in the module eval_module
  • output_type = Array the type of the array generated by a out-of-place vector-valued function
  • param_only = false if true, only allow the generated function to access system parameters
  • inputs = nothing additinoal symbolic variables that should be provided to the generated function
  • disturbance_inputs = nothing symbolic variables representing unknown disturbance inputs (removed from parameters, not added as function arguments)
  • known_disturbance_inputs = nothing symbolic variables representing known disturbance inputs (removed from parameters, added as function arguments)
  • checkbounds = true checks bounds if true when destructuring parameters
  • throw = true if true, throw an error when generating a function for ts that reference variables that do not exist.
  • mkarray: only used if the output is an array (that is, !isscalar(ts) and ts is not a tuple, in which case the result will always be a tuple). Called as mkarray(ts, output_type) where ts are the expressions to put in the array and output_type is the argument of the same name passed to buildexplicitobserved_function.
  • cse = true: Whether to use Common Subexpression Elimination (CSE) to generate a more efficient function.
  • wrap_delays = is_dde(sys): Whether to add an argument for the history function and use it to calculate all delayed variables.

Returns

The return value will be either:

  • a single function f_oop if the input is a scalar or if the input is a Vector but return_inplace is false
  • the out of place and in-place functions (f_ip, f_oop) if return_inplace is true and the input is a Vector

The function(s) f_oop (and potentially f_ip) will be:

  • RuntimeGeneratedFunctions by default,
  • A Julia Expr if expression is true,
  • A directly evaluated Julia function in the module eval_module if eval_expression is true and expression is false.

The signatures will be of the form g(...) with arguments:

  • output for in-place functions
  • unknowns if param_only is false
  • inputs if inputs is an array of symbolic inputs that should be available in ts
  • p... unconditionally; note that in the case of MTKParameters more than one parameters argument may be present, so it must be splatted
  • t if the system is time-dependent; for example systems of nonlinear equations will not have t
  • known_disturbance_inputs if provided; these are disturbance inputs that are known and provided as arguments

For example, a function g(op, unknowns, p..., inputs, t, known_disturbances) will be the in-place function generated if return_inplace is true, ts is a vector, an array of inputs inputs is given, known_disturbance_inputs is provided, and param_only is false for a time-dependent system.

source
ModelingToolkitBase.generate_control_function — Function
generate_control_function(sys::ModelingToolkitBase.AbstractSystem, input_ap_name::Union{Symbol, Vector{Symbol}, AnalysisPoint, Vector{AnalysisPoint}}, dist_ap_name::Union{Symbol, Vector{Symbol}, AnalysisPoint, Vector{AnalysisPoint}}; system_modifier = identity, kwargs)

When called with analysis points as input arguments, we assume that all analysis points corresponds to connections that should be opened (broken). The use case for this is to get rid of input signal blocks, such as Step or Sine, since these are useful for simulation but are not needed when using the plant model in a controller or state estimator.

source
(f_oop, f_ip), x_sym, p_sym, io_sys = generate_control_function(
        sys::System,
        inputs                   = unbound_inputs(sys),
        disturbance_inputs       = disturbances(sys);
        known_disturbance_inputs = nothing,
        implicit_dae             = false,
        simplify                 = false,
        split                    = true,
    )

For a system sys with inputs (as determined by unbound_inputs or user specified), generate functions with additional input argument u

The returned functions are the out-of-place (f_oop) and in-place (f_ip) forms:

f_oop : (x,u,p,t)      -> rhs         # basic form
f_oop : (x,u,p,t,w)    -> rhs         # with known_disturbance_inputs
f_ip  : (xout,x,u,p,t) -> nothing     # basic form
f_ip  : (xout,x,u,p,t,w) -> nothing   # with known_disturbance_inputs

The return values also include the chosen state-realization (the remaining unknowns) x_sym and parameters, in the order they appear as arguments to f.

Disturbance Handling

  • disturbance_inputs: Unknown disturbance inputs. The generated dynamics will preserve any state and dynamics associated with these disturbances, but the disturbance inputs themselves will not be included as function arguments. This is useful for state observers that estimate unmeasured disturbances.

  • known_disturbance_inputs: Known disturbance inputs. The generated dynamics will preserve state and dynamics, and the disturbance inputs will be added as an additional input argument w to the generated function: (x,u,p,t,w)->rhs.

Example

using ModelingToolkitBase: generate_control_function, varmap_to_vars, defaults
f, x_sym, ps = generate_control_function(sys, expression=Val{false}, simplify=false)
p = varmap_to_vars(defaults(sys), ps)
x = varmap_to_vars(defaults(sys), x_sym)
t = 0
f[1](x, inputs, p, t)
source
ModelingToolkitBase.generate_update_A — Function
generate_update_A(
    sys::System,
    A::AbstractMatrix;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    cachesyms,
    kwargs...
)

Given a system sys and the A from calculate_A_b generate the function that updates A given the parameter object.

Keyword arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkitBase.generate_update_b — Function
generate_update_b(
    sys::System,
    b::AbstractVector;
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    cachesyms,
    kwargs...
) -> Tuple{Expr, Expr}

Given a system sys and the b from calculate_A_b generate the function that updates b given the parameter object.

Keyword arguments

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.
  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.
  • 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.

All other keyword arguments are forwarded to build_function_wrapper.

source
ModelingToolkit.generate_semiquadratic_functions — Function
generate_semiquadratic_functions(
    sys::System,
    A,
    B,
    C;
    stiff_linear,
    stiff_quadratic,
    stiff_nonlinear,
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Tuple{Expr, Expr}, Tuple{Expr, Expr}}

Generate f1 and f2 for SemilinearODEFunction (internally represented as a SplitFunction). A, B, C are the matrices returned from calculate_semiquadratic_form. This expects that the system has the necessary extra parmameters added by add_semiquadratic_parameters.

Keyword Arguments

  • 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.

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.

  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.

  • 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.

All other keyword arguments are forwarded to build_function_wrapper. 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.

Warn

This API is experimental and may change in a future non-breaking release.

source
ModelingToolkit.generate_semiquadratic_jacobian — Function
generate_semiquadratic_jacobian(
    sys::System,
    A,
    B,
    C,
    Cjac;
    sparse,
    stiff_linear,
    stiff_quadratic,
    stiff_nonlinear,
    expression,
    wrap_gfw,
    eval_expression,
    eval_module,
    kwargs...
) -> Tuple{Expr, Expr}

Generate the jacobian of f1 for SemilinearODEFunction (internally represented as a SplitFunction). A, B, C are the matrices returned from calculate_semiquadratic_form. Cjac is the jacobian of C with respect to the unknowns of the system, or nothing if C === nothing. This expects that the system has the necessary extra parmameters added by add_semiquadratic_parameters.

Keyword Arguments

  • 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.

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.

  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.

  • 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.

All other keyword arguments are forwarded to build_function_wrapper. 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.

Warn

This API is experimental and may change in a future non-breaking release.

source
ModelingToolkit.get_semiquadratic_W_sparsity — Function
get_semiquadratic_W_sparsity(
    sys::System,
    A,
    B,
    C,
    Cjac;
    stiff_linear,
    stiff_quadratic,
    stiff_nonlinear,
    mm
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Return the sparsity pattern of the jacobian of f1 for SemilinearODEFunction (internally represented as a SplitFunction). A, B, C are the matrices returned from calculate_semiquadratic_form. Cjac is the jacobian of C with respect to the unknowns of the system, or nothing if C === nothing. This expects that the system has the necessary extra parmameters added by add_semiquadratic_parameters.

Keyword Arguments

  • 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.

  • expression: Val{true} if this should return an Expr (or tuple of Exprs) of the generated code. Val{false} otherwise.

  • wrap_gfw: Val{true} if the returned functions should be wrapped in a callable struct to make them callable using the expected syntax. The callable struct itself is internal API. If expression == Val{true}, the returned expression will construct the callable struct. If this function returns a tuple of functions/expressions, both will be identical if wrap_gfw == Val{true}.

  • 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.

  • mm: The mass matrix of sys.

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.

Warn

This API is experimental and may change in a future non-breaking release.

source

For functions such as jacobian calculation which require symbolic computation, there are calculate_* equivalents to obtain the symbolic result without building a function.

ModelingToolkitBase.calculate_tgrad — Function
calculate_tgrad(sys::System; simplify) -> Any

Calculate the gradient of the equations of sys with respect to the independent variable. simplify is forwarded to Symbolics.expand_derivatives.

source
ModelingToolkitBase.calculate_jacobian — Function
calculate_jacobian(
    sys::System;
    sparse,
    simplify,
    dvs
) -> Union{SparseArrays.SparseMatrixCSC{Num, Int64}, Matrix{SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal}}}

Calculate the jacobian of the equations of sys.

Keyword arguments

  • simplify, sparse: Forwarded to Symbolics.jacobian.
  • dvs: The variables with respect to which the jacobian should be computed.
source
Symbolics.jacobian_sparsity — Function
jacobian_sparsity(
    sys::System
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Return the sparsity pattern of the jacobian of sys as a matrix.

source
ModelingToolkitBase.calculate_hessian — Function
calculate_hessian(
    sys::System;
    simplify,
    sparse
) -> Vector{Matrix{Num}}

Return an array of symbolic hessians corresponding to the equations of the system.

Keyword Arguments

  • sparse: Controls whether the symbolic hessians are sparse matrices
  • simplify: Forwarded to Symbolics.hessian
source
Symbolics.hessian_sparsity — Function
hessian_sparsity(
    sys::System
) -> Vector{SparseArrays.SparseMatrixCSC{Float64, Int64}}

Return the sparsity pattern of the hessian of the equations of sys.

source
ModelingToolkitBase.calculate_massmatrix — Function
calculate_massmatrix(
    sys::System;
    simplify
) -> Union{LinearAlgebra.UniformScaling{Bool}, LinearAlgebra.Diagonal{Float64, Vector{Float64}}, Matrix{Float64}}

Calculate the mass matrix of sys. simplify controls whether Symbolics.simplify is applied to the symbolic mass matrix. Returns a Diagonal or LinearAlgebra.I wherever possible.

source
ModelingToolkitBase.calculate_W_prototype — Function
calculate_W_prototype(W_sparsity; u0, sparse) -> Any

Return the matrix to use as the jacobian prototype given the W-sparsity matrix of the system. This is not the same as the jacobian sparsity pattern.

Keyword arguments

  • u0: The u0 vector for the problem.
  • sparse: The prototype is nothing for non-sparse matrices.
source
ModelingToolkitBase.calculate_cost_gradient — Function
calculate_cost_gradient(
    sys::System;
    simplify
) -> Vector{Num}

Calculate the gradient of the consolidated cost of sys with respect to the unknowns. simplify is forwarded to Symbolics.gradient.

source
ModelingToolkitBase.calculate_cost_hessian — Function
calculate_cost_hessian(
    sys::System;
    sparse,
    simplify
) -> Matrix{Num}

Calculate the hessian of the consolidated cost of sys with respect to the unknowns. simplify is forwarded to Symbolics.hessian. sparse controls whether a sparse matrix is returned.

source
ModelingToolkitBase.calculate_constraint_jacobian — Function
calculate_constraint_jacobian(
    sys::System;
    simplify,
    sparse,
    return_sparsity
) -> Any

Return the jacobian of the constraints of sys with respect to unknowns.

Keyword arguments

  • simplify, sparse: Forwarded to Symbolics.jacobian.
  • return_sparsity: Whether to also return the sparsity pattern of the jacobian.
source
ModelingToolkitBase.calculate_constraint_hessian — Function
calculate_constraint_hessian(
    sys::System;
    simplify,
    sparse,
    return_sparsity
) -> Any

Return the hessian of the constraints of sys with respect to unknowns.

Keyword arguments

  • simplify, sparse: Forwarded to Symbolics.hessian.
  • return_sparsity: Whether to also return the sparsity pattern of the hessian.
source
ModelingToolkitBase.calculate_control_jacobian — Function
calculate_control_jacobian(
    sys::ModelingToolkitBase.AbstractSystem;
    sparse,
    simplify
) -> Any

Calculate the jacobian of the equations of sys with respect to the inputs.

Keyword arguments

  • simplify, sparse: Forwarded to Symbolics.jacobian.
source
ModelingToolkitBase.calculate_A_b — Function
calculate_A_b(
    sys::System;
    sparse,
    throw
) -> Union{Nothing, Tuple{Union{SparseArrays.SparseMatrixCSC{SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal}, Int64}, Matrix{SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal}}}, Vector{SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal}}}}

Return matrix A and vector b such that the system sys can be represented as A * x = b where x is unknowns(sys).

Keyword arguments

  • sparse: return a sparse A.
  • throw: whether to throw an error if the system is not affine.
source

All code generation eventually calls build_function_wrapper.

ModelingToolkitBase.build_function_wrapper — Function
build_function_wrapper(
    sys::ModelingToolkitBase.AbstractSystem,
    expr,
    args...;
    p_start,
    p_end,
    non_standard_param_layout,
    wrap_delays,
    histfn,
    histfn_symbolic,
    wrap_code,
    add_observed,
    obsidxs_to_use,
    create_bindings,
    output_type,
    mkarray,
    wrap_mtkparameters,
    extra_assignments,
    cse,
    optimize,
    kwargs...
) -> Tuple{Any, Any}

A wrapper around build_function which performs the necessary transformations for code generation of all types of systems. expr is the expression returned from the generated functions, and args are the arguments.

Keyword Arguments

  • p_start, p_end: Denotes the indexes in args where the buffers of the splatted MTKParameters object are present. These are collapsed into a single argument and destructured inside the function. p_start must also be provided for non-split systems since it is used by wrap_delays.
  • wrap_delays: Whether to transform delayed unknowns of sys present in expr into calls to a history function. The history function is added to the list of arguments right before parameters, at the index p_start.
  • histfn: The history function to use for transforming delayed terms. For any delayed term x(expr), this is called as histfn(p, expr) where p is the parameter object.
  • histfn_symbolic: The symbolic history function variable to add as an argument to the generated function.
  • wrap_code: Forwarded to build_function.
  • add_observed: Whether to add assignment statements for observed equations in the generated code.
  • obsidxs_to_use: An iterable of Int of the specific observed equations to use in this function. This elides automatic observed detection.
  • create_bindings: Whether to explicitly destructure arrays of symbolics present in args in the generated code. If false, all usages of the individual symbolics will instead call getindex on the relevant argument. This is useful if the generated function writes to one of its arguments and expects subsequent code to use the new values. Note that the collapsed MTKParameters argument will always be explicitly destructured regardless of this keyword argument.
  • output_type: The type of the output buffer. If mkarray (see below) is nothing, this will be passed to the similarto argument of build_function. If output_type is Tuple, expr will be wrapped in SymbolicUtils.Code.MakeTuple (regardless of whether it is scalar or an array).
  • mkarray: A function which accepts expr and output_type and returns a code generation object similar to MakeArray or MakeTuple to be used to generate code for expr.
  • wrap_mtkparameters: Whether to collapse parameter buffers for a split system into a argument.
  • extra_assignments: Extra Assignment statements to prefix to expr, after all other assignments.

All other keyword arguments are forwarded to build_function.

source