Internal Details

This is a page for detailing some of the inner workings to help future contributors to the library.

Observables and Variable Elimination

In the variable "elimination" algorithms, what is actually done is that variables are removed from being states and equations are moved into the observed category of the system. The observed equations are explicit algebraic equations which are then substituted out to completely eliminate these variables from the other equations, allowing the system to act as though these variables no longer exist.

However, as a user may have wanted to interact with such variables, for example, plotting their output, these relationships are stored and are then used to generate the observed equation found in the SciMLFunction interface, so that sol[x] lazily reconstructs the observed variable when necessary. In this sense, there is an equivalence between observables and the variable elimination system.

The procedure for variable elimination inside structural_simplify is

1. ModelingToolkit.initialize_system_structure.
2. ModelingToolkit.alias_elimination. This step moves equations into observed(sys).
3. ModelingToolkit.dae_index_lowering by means of pantelides! (if the system is an ODESystem).
4. ModelingToolkit.tearing.

Preparing a system for simulation

Before a simulation or optimization can be performed, the symbolic equations stored in an AbstractSystem must be converted into executable code. This step is typically occurs after the simplification explained above, and is performed when an instance of a SciMLBase.SciMLProblem, such as a ODEProblem, is constructed. The call chain typically looks like this, with the function names in the case of an ODESystem indicated in parenthesis

1. Problem constructor (ODEProblem)
2. Build an DEFunction (process_DEProblem -> ODEFunction
3. Write actual executable code (generate_function)

Apart from generate_function, which generates the dynamics function, ODEFunction also builds functions for observed equations (build_explicit_observed_function) and jacobians (generate_jacobian) etc. These are all stored in the ODEFunction.