ModelingToolkit.jl for equation-based Julia models

The compilation layer in ModelingToolkit.jl

ModelingToolkit.jl addresses a specific gap between writing scientific equations and handing numerical work to a solver. A researcher may begin with named variables, parameters, derivatives, and algebraic relationships. A numerical solver instead needs a problem representation whose equations, state variables, parameters, and solver-relevant operations are arranged correctly. ModelingToolkit places a symbolic compilation layer between those forms.

The `@mtkcompile` macro is central to that process. In the README's Lorenz example, the equations initially contain a second derivative of `x`. Compiling the `System` symbolically lowers that equation to a first-order system before an `ODEProblem` is constructed. Compilation can also generate functions for derived model components such as Jacobians and Hessians. The documentation states that these computations can be automatically sparsified and parallelized, although it does not make a universal performance claim for every generated model.

This makes the package most relevant to users who maintain symbolic models rather than one-off simulations. It also suits systems assembled from physical components and algebraic constraints. Its abstractions are less attractive when a fixed small equation would be clearer written directly as a solver problem.

Symbols, transformations, and solver data flow

The input is a `System` built from symbolic equations. The README imports `t_nounits as t` and `D_nounits as D`, then uses those objects to declare time-dependent variables and differentiate them inside equations. Parameters such as `σ`, `ρ`, and `β` remain distinct from variables, which lets the compiler preserve the distinction when constructing later numerical problems.

Compilation changes the symbolic model rather than merely attaching labels to Julia functions. Examples include lowering a higher-order ODE into a first-order system and applying index reduction to make a differential-algebraic model easier for a solver to handle. The package can generate Jacobian and Hessian functions, with sparsity and parallel execution incorporated into the transformation process. These transformations are more useful than source-level code generation alone because the resulting problem is still connected to the symbolic model.

After compilation, conditions bind variables and parameters to values such as `σ => 28.0`. `ODEProblem(sys, sim_cond, tend; jac = true)` then asks for the compiled system to be used in a problem with a generated Jacobian. The solution object is handled by a solver package from the SciML ecosystem. ModelingToolkit performs the symbolic and symbolic-numeric preparation; the README's example delegates numerical integration to `OrdinaryDiffEqDefault` and plotting to `Plots`.

Starting with the documented Lorenz model

The README directs users to the stable documentation at `https://docs.sciml.ai/ModelingToolkit/stable/` for package usage and installation information. It does not include an installation command, Julia version, or environment setup snippet, so this article does not invent one. The stable documentation is the correct first source for matching the package to the supported Julia environment.

A first use is the README's second-order Lorenz model. The following block declares its parameters and time-dependent variables, defines the equations, and compiles the symbolic system. Readers should see a compiled variable available as `sys`.

using ModelingToolkit
using ModelingToolkit: t_nounits as t, D_nounits as D
@parameters σ ρ β
@variables x(t) y(t) z(t)
eqs = [
    D(D(x)) ~ σ * (y - x),
    D(y) ~ x * (ρ - z) - y,
    D(z) ~ x * y - β * z
]
@mtkcompile sys = System(eqs, t)

The simulation then supplies initial values, parameter values, a time span, and the request for a Jacobian. `solve(prob)` returns the solver result used by the documented plotting call. The example is useful because it shows both sides of the workflow: symbolic preparation first, solver construction second.

Running and inspecting the first simulation

The numerical half of the README example installs concrete values into the compiled model. It imports the default ordinary differential equation solver, creates the initial-condition list, builds the problem, and solves it.

using OrdinaryDiffEqDefault
sim_cond = [
    D(x) => 2.0,
    x => 1.0,
    y => 0.0,
    z => 0.0,
    σ => 28.0,
    ρ => 10.0,
    β => 8 / 3
]
tend = 100.0
prob = ODEProblem(sys, sim_cond, tend; jac = true)
sol = solve(prob)

The reader should inspect `sol` for the requested time span and initial state. The README then uses `Plots` to display two coordinates from the solution. This example uses `x` and `y`, so the plotted pair represents a projection of the trajectory rather than the complete three-variable state.

using Plots
plot(sol, idxs = (x, y))

A genuine constraint appears here: the symbolic model does not remove the need to choose parameters, initial conditions, a time span, and an appropriate numerical solver package. Compilation prepares the model, but it does not replace domain decisions about the experiment or simulation.

Composing Lorenz subsystems through algebraic connections

ModelingToolkit also supports hierarchical composition, not just isolated equations. The README creates two named Lorenz systems and combines them using a `System` whose `systems` field contains both components. An algebraic connection constrains the combined model through `lorenz1.x`, `lorenz2.y`, and an external variable and parameter.

@named lorenz1 = System(eqs, t)
@named lorenz2 = System(eqs, t)
@variables a(t)
@parameters γ
connections = [0 ~ lorenz1.x + lorenz2.y + a * γ]
@mtkcompile connected_lorenz = System(
    connections, t; systems = [lorenz1, lorenz2]
)

The structure matters more than the exact Lorenz equations. Each subsystem owns its variables and parameters, while the connection introduces an equation that couples them. Compiling the parent system produces the combined representation passed to `ODEProblem`. This composition pattern is aimed at larger scientific models assembled from reusable components.

It also introduces validation demands. Names and hierarchy must resolve correctly, and the conditions for coupled variables must be consistent. The README demonstrates composition, but it does not document diagnostics for every connection conflict. Those checks belong in the stable documentation and should be verified for a new model rather than inferred from this short example.

License, releases, and upgrade work

The repository is not archived, and the last push was on 2026-10-16. Its recent release history includes `ModelingToolkit.jl` `v11.45.4` on 2026-10-14, `SciCompDSL-v1.0.5` on 2026-10-14, and `ModelingToolkitBase-v1.77.4` on 2026-10-14. This is recent project activity, but it does not eliminate compatibility work between package versions.

The README distinguishes stable documentation from development documentation. Stable documentation is intended for released usage, while the development documentation contains unreleased features. Code copied from development documentation can therefore differ from the installed package. Upgrades should also account for the related SciML packages that construct problems and execute numerical solvers. The repository includes `Project.toml`, `NEWS.md`, tests, documentation, extensions, and source directories, but the README does not provide a migration procedure or rollback instructions.

GitHub classifies the repository license as a custom license. Any adoption decision must therefore read `LICENSE.md` directly and examine its terms through the reader's own legal process. The documentation URL alone does not settle redistribution, attribution, warranty, or compatibility questions.

Where direct SciML construction is simpler

ModelingToolkit.jl and direct solver-package construction follow different approaches. Direct construction starts with an equation set already shaped for the selected numerical method. ModelingToolkit begins with a symbolic `System` and lets `@mtkcompile` perform transformations, identify the numerical representation, and generate derivative functions before the solver receives the model.

That extra layer is valuable when the symbolic model must be reused, transformed, connected to other systems, or handed different parameter values. Automatic Jacobian generation can also avoid maintaining derivative code by hand. The README states that generated computations can be sparsified and parallelized, so large symbolic models have mechanisms beyond plain equation interpretation.

Direct construction is the more direct alternative for a short, fixed simulation. It avoids introducing symbolic namespaces, compilation, generated derivatives, and model transformations when those features are not needed. ModelingToolkit is also the wrong choice if the model cannot be expressed cleanly as symbolic equations, parameters, variables, and supported relationships. The package should not be treated as a generic numerical replacement for every Julia modeling library; its scope is specifically symbolic-numeric, equation-based modeling within SciML.

Editorial conclusion

Adopt ModelingToolkit.jl when the model is equation-based, reusable across parameters or solver configurations, or large enough for symbolic preprocessing to justify its abstractions. Do not choose it for a small fixed ODE when a direct OrdinaryDiffEq formulation is easier to inspect. Before adoption, verify that the stable documentation matches the selected package version, review the custom LICENSE.md with your own legal process, and confirm that `@mtkcompile` produces the equation forms and generated derivatives required by the intended SciML solver.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. SciML/ModelingToolkit.jl on GitHub