Structural Transformation

tearing(sys; simplify=false)

Tear the nonlinear equations in system. When simplify=true, we simplify the new residual equations after tearing. End users are encouraged to call mtkcompile instead, which calls this function internally.

Main internal function for structural simplification for DAE systems and discrete systems. Generate dummy derivative variables, new equations in terms of variables, return updated system and tearing state.

Terminology and Definition:

A general DAE is in the form of F(u'(t), u(t), p, t) == 0. We can characterize variables in u(t) into two classes: differential variables (denoted v(t)) and algebraic variables (denoted z(t)). Differential variables are marked as SelectedState and they are differentiated in the DAE system, i.e. v'(t) are all the variables in u'(t) that actually appear in the system. Algebraic variables are variables that are not differential variables.

Arguments

• state: The TearingState of the system.
• var_eq_matching: The maximal matching after state selection.
• full_var_eq_matching: The maximal matching prior to state selection.
• var_sccs: The topologically sorted strongly connected components of the system according to full_var_eq_matching.

dae_index_lowering(sys::System; kwargs...) -> System

Perform the Pantelides algorithm to transform a higher index DAE to an index 1 DAE. kwargs are forwarded to pantelides!. End users are encouraged to call mtkcompile instead, which calls this function internally.

pantelides!(state::TransformationState; kwargs...)

Perform Pantelides algorithm.

dummy_derivative(sys)

Perform index reduction and use the dummy derivative technique to ensure that the system is balanced.

check_consistency(
    state::TransformationState,
    orig_inputs;
    nothrow
) -> Bool

Check the consistency of state, given the inputs orig_inputs. If nothrow == false, throws an error if the system is under-/over-determined or singular. In this case, if the function returns it will return true. If nothrow == true, it will return false instead of throwing an error. The singular case will print a warning.

sorted_incidence_matrix(
    sys::ModelingToolkit.AbstractSystem
) -> Any

Obtain the incidence matrix of the system sorted by the SCCs. Requires that the system is simplified and has a schedule.

computed_highest_diff_variables(structure)

Computes which variables are the "highest-differentiated" for purposes of pantelides. Ordinarily this is relatively straightforward. However, in our case, there is one complicating condition:

We allow variables in the structure graph that don't appear in the
system at all. What we are interested in is the highest-differentiated
variable that actually appears in the system.

This function takes care of these complications are returns a boolean array for every variable, indicating whether it is considered "highest-differentiated".

Rename a Shift variable with negative shift, Shift(t, k)(x(t)) to xₜ₋ₖ(t).

Handle renaming variable names for discrete structural simplification. Three cases:

• positive shift: do nothing
• zero shift: x(t) => Shift(t, 0)(x(t))
• negative shift: rename the variable

Simplify multiple shifts: Shift(t, k1)(Shift(t, k2)(x)) becomes Shift(t, k1+k2)(x).

Distribute a shift applied to a whole expression or equation. Shift(t, 1)(x + y) will become Shift(t, 1)(x) + Shift(t, 1)(y). Only shifts variables whose independent variable is the same t that appears in the Shift (i.e. constants, time-independent parameters, etc. do not get shifted).