MTK: updated documentation?

Specific Domains Modelling & Simulations
1

I am trying to use ModelingToolkit (MTK). In the first example in the documentation,

using ModelingToolkit, Plots, OrdinaryDiffEq
using ModelingToolkit: t_nounits as t, D_nounits as D
@mtkmodel FOL begin
    @parameters begin
        τ = 3.0 # parameters
    end
    @variables begin
        x(t) = 0.0 # dependent variables
    end
    @equations begin
        D(x) ~ (1 - x) / τ
    end
end

@mtkcompile fol = FOL()

This example doesn’t run with the latest version of MTK: I get an error message that @mtkmodel is not defined in Main.

OK – based on previous discussion, I know that MTK is in a transition to a new way to describe components – but my understanding was that the “old way” would still work, but with a warning. The new style works, though:

@component function FOL(;name)
    params = @parameters begin
        τ = 3.0 # parameters
    end
    vars = @variables begin
        x(t) = 0.0 # dependent variables
    end
    eqs = [
        D(x) ~ (1 - x) / τ
    ]
    System(eqs, t, vars, params; name)
end

@mtkcompile fol = FOL()

Question: Where is the “new style” documented?? Although I know the basics of the new style, it is not easy to guess how to make acausal models. E.g., @components doesn’t exist any more, the error message tells me.

1 Like
2

Is it a bug in the documentation deploy on github ? Because releasing a breaking release without documenting it properly (in the official documentation) is reckless for a package as important as MTK. That piles up on the reasons why I still don’t consider MTK as a mature package.

1 Like
3

ModelingToolkit recently updated to a v11 release and deprecated the @mtkmodel macro, see ModelingToolkit.jl/NEWS.md at master · SciML/ModelingToolkit.jl for more information. It seems the MTK docs are not out yet for v11 (you can see the release version in the bottom dropdown menu).

1 Like
4

I wouldn’t be so categorical: I think the developers have done excellent work in a relatively short time span. And I like the improvements I see; I hope these will solve some problems of the past (from my experience), like better handling of initialization with guesses, improved linearization; I love the moving of “analysis points” out of the standard library and to the general tool. In comparison, when I used OpenModelica the first time (ca. 2003-2004), it could only handle models with a couple of states.

Still, I look forward to seeing some updated documentation.

2 Likes
5

OK… Microsoft Copilot suggested the following modification of the Acausal example in the documentation… (the first couple of attempts failed, but by providing it with the error messages, this code works) :slight_smile:

using ModelingToolkit, Plots, OrdinaryDiffEq
using ModelingToolkit: t_nounits as t, D_nounits as D

@connector function Pin(; name)
    sts = @variables v(t) [guess = 1.0]  i(t) [guess = 1.0, connect = Flow]
    ODESystem(Equation[], t, sts, []; name = name)
end

@component function Ground(; name)
    @named g = Pin()
    eqs = [g.v ~ 0]
    compose(ODESystem(eqs, t, [], []; name = name), g)
end

@component function OnePort(; name)
    @named p = Pin()
    @named n = Pin()
    sts = @variables v(t) [guess = 1.0]  i(t) [guess = 1.0]
    eqs = [
        v ~ p.v - n.v
        0 ~ p.i + n.i
        i ~ p.i
    ]
    compose(ODESystem(eqs, t, sts, []; name = name), p, n)
end

@component function Resistor(; name, R = 1.0)
    @named oneport = OnePort()
    @unpack v, i = oneport
    ps = @parameters R = R
    eqs = [v ~ i * R]
    extend(ODESystem(eqs, t, [], ps; name = name), oneport)
end

@component function Capacitor(; name, C = 1.0)
    @named oneport = OnePort()
    @unpack v, i = oneport
    ps = @parameters C = C
    eqs = [D(v) ~ i / C]
    extend(ODESystem(eqs, t, [], ps; name = name), oneport)
end

@component function ConstantVoltage(; name, V = 1.0)
    @named oneport = OnePort()
    @unpack v = oneport
    ps = @parameters V = V
    eqs = [V ~ v]
    extend(ODESystem(eqs, t, [], ps; name = name), oneport)
end

# --- Build the RC circuit ---

R = 2.0
C = 1.0
V = 1.0

@named resistor  = Resistor(R = R)
@named capacitor = Capacitor(C = C)
@named source    = ConstantVoltage(V = V)
@named ground    = Ground()

rc_eqs = [
    connect(source.p, resistor.p)
    connect(resistor.n, capacitor.p)
    connect(capacitor.n, source.n)
    connect(capacitor.n, ground.g)
]

@named _rc_model = ODESystem(rc_eqs, t)
@named rc_model  = compose(_rc_model, [resistor, capacitor, source, ground])

sys = structural_simplify(rc_model)

u0 = [
    capacitor.v => 0.0
]

prob = ODEProblem(sys, u0, (0, 10.0))
sol  = solve(prob, Tsit5())
plot(sol)
6

The new docs just need some downstream stuff updated in order to build. Should happen rather soon.

2 Likes
7

I should say that I struggle somewhat with understanding when I can use @mtkcompile, when I should use structural_simplify, and – is there mtkcompile?? I had a “session” with MS Copilot on this, and didn’t get much wiser.

8

There is no more structural_simplify, use mtkcompile. Or the macro @mtkcompile

from ModelingToolkit.jl/NEWS.md at b8940e544bbf04f518a8f5d5bc340fd90db68133 · SciML/ModelingToolkit.jl · GitHub

New mtkcompile and @mtkcompile

structural_simplify is now renamed to mtkcompile. @mtkbuild is renamed to
@mtkcompile. Their functionality remains the same. However, instead of a second
positional argument structural_simplify(sys, (inputs, outputs)) the inputs and outputs
should be specified via keyword arguments as mtkcompile(sys; inputs, outputs, disturbance_inputs).