Manual: ModelingToolkit Integration

Introduction

This example integrates the simple pendulum and pH neutralization models of the penultimate section and ultimate section, respectively, in the ModelingToolkit (MTK) framework. It then extracts functions with appropriate signature to construct SimModel objects. This object is then used to design controllers similar to the previous sections.

Disclaimer

This simple example is not an official interface to ModelingToolkit.jl. It is provided as a basic starting template to combine both packages. There is no guarantee that it will work for all corner cases.

MTK Model Conversion

We first define two methods that convert MTK model to either a NonLinModel or a NonLinModelDAE, depending on the presence of algebraic equations. The methods rely on input-output systems. The generate_f_h_mtk method extracts the f_mtk! and h_mtk! functions from the MTK model, with combined differential states and algebraic variables in a single vector. The i_alg boolean vector indicates which elements of the state vector are algebraic variables:

using ModelPredictiveControl, ModelingToolkitusing ModelingToolkit: D_nounits as D, t_nounits as tfunction generate_f_h_mtk(model, inputs, outputs, disturbances=nothing)    known_disturbance_inputs = disturbances    (_, f_ip), x_sym, p_sym, io_sys = ModelingToolkit.generate_control_function(        model, inputs; known_disturbance_inputs, split=false, simplify=true    )    i_alg = ModelingToolkit.is_alg_equation.(equations(io_sys))    nd = isnothing(disturbances) ? 0 : length(disturbances)    f_ip_with_d = (nd < 1) ? (ẋ, x, u, p, t, _ ) -> f_ip(ẋ, x, u, p, t) : f_ip    function f_mtk!(ẋ, x, u, d, p)        try            f_ip_with_d(ẋ, x, u, p, nothing, d)        catch err            if err isa MethodError                error("NonLinModel does not support a time argument t in the f "*                    "function, see the constructor docstring for a workaround.")            else                rethrow()            end        end        return nothing    end    (_, h_ip) = ModelingToolkit.build_explicit_observed_function(        io_sys, outputs; inputs, known_disturbance_inputs, return_inplace = true    )    h_ip_with_d = (nd < 1) ? (y, x, u, p, t, _ ) -> h_ip(y, x, u, p, t) : h_ip    u_nothing = fill(nothing, length(inputs))    function h_mtk!(y, x, d, p)        try            # MTK.jl supports a `u` argument in `h_ip` function but not this package. We            # set `u` as a vector of nothing and `h_ip` function will presumably throw            # an MethodError if this argument is used inside the function            h_ip_with_d(y, x, u_nothing, p, nothing, d)        catch err            if err isa MethodError                error("NonLinModel only support strictly proper systems (no "*                      "manipulated input argument u in the output function h)")            else                rethrow()            end        end        return nothing    end    ic = initial_conditions(io_sys)    p_map, x_map = try        (            Dict(sym => ic[sym] for sym in p_sym),            Dict(sym => ic[sym] for sym in x_sym)        )    catch err        if err isa KeyError # the key presumably appears in `bindings(io_sys)`:            error("Non-constant parameter values are not supported (a.k.a. bindings)")        else            rethrow()        end    end    p = ModelingToolkit.varmap_to_vars(p_map, p_sym)    x = ModelingToolkit.varmap_to_vars(x_map, x_sym)    return f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_algend

The generate_model method then constructs an adequate SimModel object that internally separates the differential states and algebraic variables, if any, to comply with this package's interface:

function generate_model(    f_mtk!::F, h_mtk!::H, Ts, i_alg, inputs, outputs, disturbances=nothing;    p=nothing, xs_mtk=zeros(length(i_alg)), unit="s", transcription=OrthogonalCollocation()) where {F<:Function, H<:Function}    nu, ny = length(inputs), length(outputs)    nd = isnothing(disturbances) ? 0 : length(disturbances)    nx_mtk::Int = length(i_alg)    na::Int     = sum(i_alg)    nx::Int     = nx_mtk - na    i_x::Vector{Int} = findall(iszero, i_alg)    i_a::Vector{Int} = findall(isone, i_alg)    if na > 0        function fq!(ẋ, res, x, a, u, d, p)            T = promote_type(eltype(x), eltype(a), eltype(u))            ẋ_mtk, x_mtk = similar(ẋ, T, nx_mtk), similar(x, T, nx_mtk)            x_mtk[i_x] .= x            x_mtk[i_a] .= a            f_mtk!(ẋ_mtk, x_mtk, u, d, p)            ẋ   .= @views ẋ_mtk[i_x]            res .= @views ẋ_mtk[i_a]            return nothing        end        function h!(y, x, a, d, p)            T = promote_type(eltype(x), eltype(a))            x_mtk = similar(x, T, nx_mtk)            x_mtk[i_x] .= x            x_mtk[i_a] .= a            h_mtk!(y, x_mtk, d, p)            return nothing        end        xs_0, as_0 = xs_mtk[i_x], xs_mtk[i_a]        model = NonLinModelDAE(            fq!, h!, Ts, nu, nx, na, ny, nd; p, unit, xs_0, as_0, transcription        )    else        f!, h! = f_mtk!, h_mtk!        xs_0 = xs_mtk        model = NonLinModel(f!, h!, Ts, nu, nx, ny, nd; p, xs_0, unit)    end    return model # deliberately type unstable functionend

Pendulum Model

We first construct and instantiate the pendulum model as a MTK System object:

@parameters g=9.8 L=0.4 K=1.2 m=0.3@variables θ(t)=0 ω(t)=0 τ(t)=0 y(t)eqs = [    D(θ) ~ ω    D(ω) ~ -g/L*sin(θ) - K/m*ω + τ/m/L^2    y ~ θ * 180 / π]@named mtk_model = System(eqs, t)

\[ \begin{align} \frac{\mathrm{d}\theta\left( t \right)}{\mathrm{d}t} &= \omega\left( t \right) \\ \frac{\mathrm{d}\omega\left( t \right)}{\mathrm{d}t} &= \frac{\tau\left( t \right)}{L^{2} ~ m} + \frac{ - K ~ \omega\left( t \right)}{m} + \frac{ - g ~ \sin\left( \theta\left( t \right) \right)}{L} \\ y\left( t \right) &= 57.296 ~ \theta\left( t \right) \end{align} \]

We can now convert the MTK model:

inputs, outputs = [τ], [y]f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(mtk_model, inputs, outputs)[x_sym x]
2×2 Matrix{Any}:
 ω(t)  0.0
 θ(t)  0.0

Since MTK is an acausal modeling framework, we do not have control over the state realization chosen by the package. The content of x_sym above shows it settled for the state vector $\mathbf{x}(t) = [\begin{smallmatrix}ω(t) && θ(t)\end{smallmatrix}]'$, that is, the states of the pendulum section in the reverse order. As the same also applies to the parameters, the p_sym object informs on how the p vector is sorted:

[p_sym p]
4×2 Matrix{Any}:
 K  1.2
 m  0.3
 g  9.8
 L  0.4

We can now construct a SimModel with this specific state realization:

Ts = 0.1model = generate_model(f_mtk!, h_mtk!, Ts, i_alg, inputs, outputs; p)vu, vx, vy = ["\$τ\$ (Nm)"], ["\$ω\$ (rad/s)", "\$θ\$ (rad)"], ["\$θ\$ (°)"]model = setname!(model; u=vu, x=vx, y=vy)
NonLinModel with a sample time Ts = 0.1 s:
├ solver: RungeKutta(4)
├ jacobian: AutoForwardDiff
└ dimensions:
  ├ 1 manipulated inputs u
  ├ 2 states x
  ├ 1 outputs y
  └ 0 measured disturbances d

As expected, the returned model is a NonLinModel object, since the pendulum model has no algebraic equations. We also instantiate a plant model with a 25 % larger friction coefficient $K$:

i_K = findfirst(==("K"), string.(p_sym))p2 = copy(p)p2[i_K] = 1.25*p[i_K]plant = generate_model(f_mtk!, h_mtk!, Ts, i_alg, inputs, outputs; p=p2)plant = setname!(plant; u=vu, x=vx, y=vy)
NonLinModel with a sample time Ts = 0.1 s:
├ solver: RungeKutta(4)
├ jacobian: AutoForwardDiff
└ dimensions:
  ├ 1 manipulated inputs u
  ├ 2 states x
  ├ 1 outputs y
  └ 0 measured disturbances d

Pendulum Controller

We can then reproduce the Kalman filter and the controller design of the penultimate section by reversing the order of σQ vector, because of the different state realization:

α=0.01; σQ=[1.0, 0.1]; σR=[5.0]; nint_u=[1]; σQint_u=[0.1]estim = UnscentedKalmanFilter(model; α, σQ, σR, nint_u, σQint_u)Hp, Hc, Mwt, Nwt = 20, 2, [0.5], [2.5]nmpc = NonLinMPC(estim; Hp, Hc, Mwt, Nwt, Cwt=Inf)umin, umax = [-1.5], [+1.5]nmpc = setconstraint!(nmpc; umin, umax)
NonLinMPC controller with a sample time Ts = 0.1 s:
├ estimator: UnscentedKalmanFilter
├ model: NonLinModel
├ optimizer: Ipopt
├ transcription: SingleShooting
├ gradient: AutoForwardDiff
├ jacobian: AutoForwardDiff
├ hessian: nothing
└ dimensions:
  │ ├ 20 prediction steps Hp
  │ ├  2 control steps Hc
  │ ├  1 manipulated inputs u (1 integrating states)
  │ ├  3 estimated states x̂
  │ ├  1 measured outputs ym (0 integrating states)
  │ ├  0 unmeasured outputs yu
  │ └  0 measured disturbances d
  └ optimization:
    ├  2 decision variables Z̃ (0 slack variable, 0 bounds)
    ├ 40 linear inequality constraints A (0 custom)
    ├  0 linear equality constraints Aeq
    ├  0 nonlinear inequality constraints g (0 custom)
    └  0 nonlinear equality constraints geq

The 180° setpoint response is identical:

using PlotsN = 35res_ry = sim!(nmpc, N, [180.0], plant=plant, x_0=[0, 0], x̂_0=[0, 0, 0])end #p = plot(res_ry)

plot1_MTK

and also the output disturbance rejection:

res_yd = sim!(nmpc, N, [180.0], plant=plant, x_0=[0, π], x̂_0=[0, π, 0], y_step=[10])p = plot(res_yd)

plot2_MTK

Neutralization Reactor Model

This example repeats the neutralization reactor setup from the previous section but with MTK. The observer and controller are non-adaptive to simplify the design. Instead of estimating the acid feed concentration, an integrating state is added at the manipulated input $q_{Bin}$.

The MTK model of the neutralization reactor from the last section is constructed as follows:

@parameters c_Ain=0.1 c_Bin=0.1 Kw=1e-14 Ka=1.75e-5 V=1000@variables q_Ain(t)=10@variables c_A(t)=0.025 c_B(t)=0.025 q_Bin(t)=10 pH(t)=7.0@variables q_out(t) c_Aout(t) c_Bout(t)eqs = [    D(c_A) ~ 60/V*(q_Ain * c_Ain - q_out * c_Aout)    D(c_B) ~ 60/V*(q_Bin * c_Bin - q_out * c_Bout)    0      ~ 10^(-pH) + c_B - (Kw / 10^(-pH)) - (Ka * c_A / (Ka + 10^(-pH)))    q_out  ~ q_Ain + q_Bin    c_Aout ~ c_A    c_Bout ~ c_B]@named mtk_model = System(eqs, t)

\[ \begin{align} \frac{\mathrm{d}\mathtt{c\_A}\left( t \right)}{\mathrm{d}t} &= \frac{60 ~ \left( \mathtt{c\_Ain} ~ \mathtt{q\_Ain}\left( t \right) - \mathtt{c\_Aout}\left( t \right) ~ \mathtt{q\_out}\left( t \right) \right)}{V} \\ \frac{\mathrm{d}\mathtt{c\_B}\left( t \right)}{\mathrm{d}t} &= \frac{60 ~ \left( \mathtt{c\_Bin} ~ \mathtt{q\_Bin}\left( t \right) - \mathtt{c\_Bout}\left( t \right) ~ \mathtt{q\_out}\left( t \right) \right)}{V} \\ 0 &= 10^{ - \mathtt{pH}\left( t \right)} + \mathtt{c\_B}\left( t \right) + \frac{ - \mathtt{Kw}}{10^{ - \mathtt{pH}\left( t \right)}} + \frac{ - \mathtt{Ka} ~ \mathtt{c\_A}\left( t \right)}{\mathtt{Ka} + 10^{ - \mathtt{pH}\left( t \right)}} \\ \mathtt{q\_out}\left( t \right) &= \mathtt{q\_Ain}\left( t \right) + \mathtt{q\_Bin}\left( t \right) \\ \mathtt{c\_Aout}\left( t \right) &= \mathtt{c\_A}\left( t \right) \\ \mathtt{c\_Bout}\left( t \right) &= \mathtt{c\_B}\left( t \right) \end{align} \]

The substitution $a_H = 10^{-\mathrm{pH}}$ is explicitly applied in the algebraic equation to improve the numerical conditioning of the system. The converted model is:

inputs, outputs, disturbances = [q_Bin], [pH], [q_Ain]f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(    mtk_model, inputs, outputs, disturbances)[x_sym x]
3×2 Matrix{Any}:
 c_B(t)  0.025
 c_A(t)  0.025
 pH(t)   7.0

The content of x_sym shows that it chose for the combined state and algebraic vector this: $[\begin{smallmatrix}c_B(t) && c_A(t) && \mathrm{pH}(t)\end{smallmatrix}]'$. The states are thus in the reverse order of the last section. The order of the parameters is:

[p_sym p]
5×2 Matrix{Any}:
 c_Ain     0.1
 V      1000.0
 c_Bin     0.1
 Kw        1.0e-14
 Ka        1.75e-5

We can now construct a SimModel with this realization:

Ts, unit = 0.5, "h"xs_mtk = xtranscription = TrapezoidalCollocation()model = generate_model(    f_mtk!, h_mtk!, Ts, i_alg, inputs, outputs, disturbances;    p, xs_mtk, unit, transcription)vu, vd = [raw"$q_{Bin}$ (L/min)"], [raw"$q_{Ain}$ (L/min)"]vx, vy = [raw"$c_B$ (mol/L)", raw"$c_A$ (mol/L)"], [raw"$\mathrm{pH}$"]model = setname!(model, u=vu, d=vd, y=vy, x=vx)
NonLinModelDAE with a sample time Ts = 0.5 h:
├ state optimizer: Ipopt
├ output optimizer: Ipopt
├ transcription: TrapezoidalCollocation
├ jacobian: AutoForwardDiff
├ hessian: nothing
└ dimensions:
  │ ├ 1 manipulated inputs u
  │ ├ 2 states x
  │ ├ 1 algebraic variables a
  │ ├ 1 outputs y
  │ └ 1 measured disturbances d
  └ optimization:
    ├ 4 decision variables Z
    ├ 0 linear equality constraints Aeq
    └ 4 nonlinear equality constraints geq

The returned value is a NonLinModelDAE object, as expected. The transient response is identical to the first 10 hours of the open-loop simulations in the last section:

using Plotsu, d, x_0 = [10.0], [10.0], [0.0495, 0.0505]N = 21res = sim!(model, N, u, d; x_0)p = plot(res)

plot3_MTK

Neutralization Reactor Controller

We next configure the MHE, including an integrating state at the manipulated input:

nint_u=[1] # integrating state at the q_Bin inputHe = 8; hessian = trueσQ = [0.5e-3, 0.5e-3]; σR=[0.05]; σP_0 = [0.05, 0.05]; σQint_u=[0.15]; σPint_u_0=[0.075]mhe = MovingHorizonEstimator(model; nint_u, He, hessian, σQ, σR, σP_0, σQint_u, σPint_u_0)using JuMP; unset_time_limit_sec(mhe.optim)     # no wall time limit during optimizationmhe = setconstraint!(mhe, x̂min=[0, 0, -Inf])
MovingHorizonEstimator estimator with a sample time Ts = 0.5 h:
├ model: NonLinModelDAE
├ optimizer: Ipopt 
├ transcription: TrapezoidalCollocation
├ gradient: AutoForwardDiff
├ jacobian: AutoSparse (AutoForwardDiff, TracerSparsityDetector, GreedyColoringAlgorithm)
├ hessian: AutoSparse (AutoForwardDiff, TracerSparsityDetector, GreedyColoringAlgorithm)
├ arrival covariance: SteadyKalmanFilter 
├ direct: true
└ dimensions:
  │ ├ 8 estimation steps He
  │ ├ 1 manipulated inputs u (1 integrating states)
  │ ├ 3 estimated states x̂
  │ ├ 1 algebraic variables a
  │ ├ 1 measured outputs ym (0 integrating states)
  │ ├ 0 unmeasured outputs yu
  │ └ 1 measured disturbances d
  └ optimization:
    ├ 68 decision variables Z̃ (0 slack variable, 18 bounds)
    ├  0 linear inequality constraints A
    ├  8 linear equality constraints Aeq
    ├  0 nonlinear inequality constraints g (0 custom)
    └ 33 nonlinear equality constraints geq

Using the MHE, we configure an NMPC to keep the pH within the desired range:

nmpc = NonLinMPC(mhe, Hp=8, Hc=2, Nwt=[5.0], hessian=true)using JuMP; unset_time_limit_sec(nmpc.optim)  # no wall time limit during optimizationnmpc = setconstraint!(nmpc, ymin=[6], ymax=[8], umin=[0], umax=[20])
NonLinMPC controller with a sample time Ts = 0.5 h:
├ estimator: MovingHorizonEstimator
├ model: NonLinModelDAE
├ optimizer: Ipopt
├ transcription: TrapezoidalCollocation
├ gradient: AutoForwardDiff
├ jacobian: AutoSparse (AutoForwardDiff, TracerSparsityDetector, GreedyColoringAlgorithm)
├ hessian: AutoSparse (AutoForwardDiff, TracerSparsityDetector, GreedyColoringAlgorithm)
└ dimensions:
  │ ├ 8 prediction steps Hp
  │ ├ 2 control steps Hc
  │ ├ 8 estimation steps He
  │ ├ 1 manipulated inputs u (1 integrating states)
  │ ├ 3 estimated states x̂
  │ ├ 1 algebraic variables a
  │ ├ 1 measured outputs ym (0 integrating states)
  │ ├ 0 unmeasured outputs yu
  │ └ 1 measured disturbances d
  └ optimization:
    ├ 43 decision variables Z̃ (1 slack variable, 1 bounds)
    ├ 16 linear inequality constraints A (0 custom)
    ├  8 linear equality constraints Aeq
    ├ 16 nonlinear inequality constraints g (0 custom)
    └ 32 nonlinear equality constraints geq

Finally, we simulate the closed-loop response with a pH setpoint of 7:

ry = [7.0]x_0, x̂_0 = [0.04, 0.07], [0.025, 0.025, 0]res = sim!(nmpc, N, ry, d; x_0, x̂_0)p = plot(res, plotd=false, plotxwithx̂=true, plotx̂min=false, plotŷ=true)

plot4_MTK

As expected, the close-loop response is similar to the one of the last section, but not identical since the stochastic model of the unmeasured disturbances is different.

Acknowledgement

Authored by 1-Bart-1 and baggepinnen, thanks for the contribution.