Model building reference

This page lists functionality and utilities related to building hierarchical models. It is recommended to read the page on the System before this.

Common definitions of t and D

ModelingToolkit provides common definitions for the independent variable t (time) and the derivative with respect to it D.

Users are recommended to use the appropriate common definition in their models. The required definitions can be imported with convenient aliased names. For example:

using ModelingToolkit: t_nounits as t, D_nounits as D

Allows using t and D to refer to t_nounits and D_nounits respectively.

Hierarchical model composition

The System data structure can represent a tree-like hierarchy of systems for building models from composable blocks. The ModelingToolkit.get_systems function can be used for querying the subsystems of a system. The @component macro should be used when writing building blocks for model composition.

Every constructor function should build either a component or a connector. Components define the dynamics of the system. Connectors are used to connect components together and propagate information between them. See also @connector.

Scoping of variables

When building hierarchical systems, is is often necessary to pass variables from a parent system to the subsystems. If done naively, this will result in the child system assuming it "owns" the variables passed to it and any occurrences of those variables in the child system will be namespaced. To prevent this, ModelingToolkit has the concept of variable scope. The scope allows specifying which system a variable belongs to relative to the system in which it is used.

Note that the scopes must be applied to individual variables and not expressions. For example, ParentScope(x + y) is incorrect. Instead, ParentScope(x) + ParentScope(y) is the correct usage. Applying the same scope (more generally, the same function) to all variables in an expression is a common task, and ModelingToolkit exposes a utility for the same:

It is still tedious to manually use apply_to_variables on any symbolic expression passed to a subsystem. The @named macro automatically wraps all symbolic arguments in ParentScope and uses the identifier being assigned as the name of the system.

Exploring the tree structure

The System type implements the AbstractTrees interface. This can be used to explore the hierarchical structure.

Connection semantics

ModelingToolkit implements connection semantics similar to those in the Modelica specification. We do not support the concept of inner and outer elements or expandable connectors. Connectors in ModelingToolkit are systems with the appropriate metadata added via the @connector macro.

Connections can be expanded using expand_connections.

Similar to the stream and flow keyword arguments in the specification, ModelingToolkit allows specifying how variables in a connector behave in a connection.

These are specified using the connect metadata. ModelingToolkit also supports instream. Refer to the Modelica specification on Stream connectors for more information.

System composition utilities

substitute_component(
    sys::ModelingToolkitBase.AbstractSystem,
    rule::Pair{T<:ModelingToolkitBase.AbstractSystem, T<:ModelingToolkitBase.AbstractSystem}
) -> Any

Flattening systems

The hierarchical structure can be flattened. This operation is performed during simplification.

System simplification

Systems can be simplified to reformulate them in a way that enables it to be solved numerically, and also perform other optimizations. This is done via the mtkcompile function. Connection expansion and flattening are preprocessing steps of simplification.

function mtkcompile(sys::System; kwargs...)

It is also possible (though not always advisable) to build numerical problems from systems without passing them through mtkcompile. To do this, the system must first be marked as "complete" via the complete function. This process is used to indicate that a system will not be modified further and allows ModelingToolkit to perform any necessary preprocessing to it. mtkcompile calls complete internally.

Exploring the results of simplification

Similar to how full_equations returns the equations of a system with all variables eliminated during mtkcompile substituted, we can perform this substitution on an arbitrary expression.

Experimental simplification

ModelingToolkit may have a variety of experimental simplification passes. These are not enabled by default, but can be used by passing to the additional_passes keyword argument of mtkcompile.

Event handling

Time-dependent systems may have several events. These are used to trigger discontinuities in the model. They compile to standard callbacks from DiffEqCallbacks.jl.

The affect functions for the above callbacks can be symbolic or user-defined functions. Symbolic affects are handled using equations as described in the Events section of the documentation. User-defined functions can be used via ImperativeAffect.

Modelingtoolkitize

ModelingToolkit can take some numerical problems created non-symbolically and build a symbolic representation from them.

Using FMUs

ModelingToolkit is capable of importing FMUs as black-box symbolic models. Currently only a subset of FMU features are supported. This functionality requires importing FMI.jl.

FMIComponent(
    ::Val{Ver};
    fmu,
    tolerance,
    communication_step_size,
    reinitializealg,
    type,
    name
)

Model transformations

ModelingToolkit exposes a variety of transformations that can be applied to models to aid in symbolic analysis.

Hybrid systems

Hybrid systems are dynamical systems involving one or more discrete-time subsystems. These discrete time systems follow clock semantics - they are synchronous systems and the relevant variables are only defined at points where the clock ticks.

While ModelingToolkit is unable to simplify, compile and solve such systems on its own, it has the ability to represent them. Compilation strategies can be implemented independently on top of mtkcompile using the additional_passes functionality.

ModelingToolkit uses the clock definition in SciMLBase

State machines

While ModelingToolkit has the capability to represent state machines, it lacks the ability to compile and simulate them.