ModelingToolkit.jl Documentation

ModelingToolkit.jl is a high-performance symbolic-numeric modeling language designed for scientific computing and scientific machine learning. It combines symbolic computational algebra (using Symbolics.jl) with causal (Simulink-style) and acausal (Modelica-style) equation-based modeling.

Key capabilities include:

• Symbolic Preprocessing: Automatic model transformation, simplification, and index reduction of differential-algebraic equations (DAEs).
• Composition: Building complex models by connecting components using a lazy connection system.
• Hybrid Modeling: Transforming systems of DAEs into optimization problems or vice-versa.
• Parallelism: Pervasive parallelism in both symbolic computations and generated code.
• Extensibility: Written in pure Julia, allowing users to add new simplification rules and transformations easily.

ModelingToolkit.jl supports four backends for solving dynamic optimization problems using collocation. The choice of backend determines how you pass the optimizer and how collocation methods are specified:

1. JuMP and CasADi: Require an ODE tableau (constructed via DiffEqDevTools.constructX()). They expect the optimizer to be passed differently:
   • JuMP: Pass the optimizer object directly (e.g., Ipopt.Optimizer).
   • CasADi: Pass the solver name as a String (e.g., "ipopt").
2. InfiniteOpt and Pyomo: Have built-in collocation methods and do not require an external ODE tableau.
   • InfiniteOpt: Pass the optimizer object directly. Defaults to FiniteDifference(Backward()) (implicit Euler) if no method is provided.
   • Pyomo: Pass the solver name as a String. Defaults to LagrangeRadau(3) if no method is provided.

When initializing an ODEProblem, the system must be well-formed (the number of equations must match the number of unknowns).

• Underdetermined systems: Occur when you provide fewer conditions than required. ModelingToolkit will issue a warning. The system can still be solved, but the solution may not be unique.
• Overdetermined systems: Occur when you provide more conditions than can be satisfied. If the conditions are analytically impossible to satisfy, the solver will return SciMLBase.ReturnCode.InitialFailure.

To change the behavior for non-fully determined systems:

• Use fully_determined = true in the ODEProblem constructor to receive an error instead of a warning.
• Use warn_initialize_determined = false to suppress warnings about non-fully determined systems.

When defining variables in a discrete system, you can provide default values. These are treated as the value of the variable at all past timesteps.

For example, in a Fibonacci sequence model:

@variables x(t) = 1.0
@mtkcompile sys = System([x ~ x(k - 1) + x(k - 2)], t)

In this case, the default value 1.0 is applied to all past timesteps. Therefore, x(k-1) and x(k-2) both evaluate to 1.0, making the initial value of x(k) equal to 2.0.

When connecting input signals to a model, use analysis points (e.g., :u, :d1). This allows you to treat these connections as symbolic attachment points. This is critical for:

1. Linearization: You can linearize the model as if the signals were not connected (unbound inputs).
2. Function Generation: You can generate a Julia function for the dynamics in the form f(x, u, p, t, w), where u (control) and w (disturbances) are separate arguments, effectively treating the signals as external inputs.

using ControlSystemsBase, ControlSystemsMTK
# Linearize the model from inputs (u, d1, d2) to outputs (inertia velocities)
P = named_ss(model, [ssys.u, ssys.d1, ssys.d2],
    [ssys.system_model.inertia1.w, ssys.system_model.inertia2.w])
bodeplot(P, plotphase = false)

There is no dedicated 'disturbance library', but you can model any disturbance with a rational spectrum using standard blocks from the Blocks module.

Commonly used blocks for disturbance modeling include:

• Integrator: Suitable for low-frequency components (e.g., slowly drifting signals).
• TransferFunction: For frequency-domain specifications.
• StateSpace: For general linear dynamical systems.

For complex filter design (highpass, lowpass, bandpass), it is recommended to use ControlSystems.jl or ControlSystemsMTK.jl to design the system and then integrate it into your MTK model.

Linear analysis in ModelingToolkit involves linearizing a nonlinear model and analyzing the resulting linear dynamical system. This is facilitated by the AnalysisPoint concept. An AnalysisPoint acts as a causal junction (like an arrow in a block diagram) inserted between components.

Analysis points can be created in two ways:

1. Explicitly: Using the AnalysisPoint constructor.
2. Automatically: By providing a name as the middle argument in a connect call.

Important: Causality Analysis points are causal. The order of arguments in connect determines the direction of information flow. connect(out, :name, in) is different from connect(in, :name, out).

ModelingToolkit.jl is an acausal modeling environment, while Causal.jl is a causal modeling environment.

Key differences:

• System Promotion: In Causal.jl, connecting different types (e.g., an SDE driving an ODE) uses different solver methods in tandem. In ModelingToolkit.jl, such connections promote the entire system to an SDE, which can improve accuracy and stability at the potential cost of performance.
• Algebraic Loops: Causal.jl breaks algebraic loops using inexact heuristics (similar to Simulink). ModelingToolkit.jl treats algebraic loops exactly by including them as algebraic equations in the generated model.