From 7bf81b3115519e48cc3e4b455608c9e22936ff00 Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 14:16:43 -0500 Subject: [PATCH 1/9] doc: `MTK` section in manual now support DAEs --- docs/src/manual/mtk.md | 230 +++++++++++++++++++++++++++++++++-------- 1 file changed, 186 insertions(+), 44 deletions(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index 4508a65b6..88535fef9 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -4,56 +4,49 @@ Pages = ["mtk.md"] ``` -## Pendulum Model +## Introduction -This example integrates the simple pendulum model of the [penultimate section](@ref man_nonlin) -in [`ModelingToolkit`](https://docs.sciml.ai/ModelingToolkit/stable/) (MTK) framework and -extracts appropriate `f!` and `h!` functions to construct a [`NonLinModel`](@ref). An -[`NonLinMPC`](@ref) is designed from this model and simulated to reproduce the results of -the last section. +This example integrates the simple pendulum and pH neutralization models of the +[penultimate section](@ref man_nonlin) and [ultimate section](@ref man_dae), respectively, +in the [`ModelingToolkit`](https://docs.sciml.ai/ModelingToolkit/stable/) (MTK) framework. +It then extracts functions with appropriate signature to construct [`SimModel`](@ref) +objects. This object is then used to design controllers similar to the previous sections. !!! danger "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. - -We first construct and instantiate the pendulum model: + will work for all corner cases. For instance, measured disturbances are not supported in + the current implementation (to be added). ```@codeblocks line_counter = :continue ``` +## MTK Model Conversion + +We first define two methods that convert MTK model to either a [`NonLinModel`](@ref) or a +[`NonLinModelDAE`](@ref), depending on the presence of algebraic equations. The methods rely +on [input-output systems](https://docs.sciml.ai/ModelingToolkit/stable/basics/InputOutput/). +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: + ```@example 1 using ModelPredictiveControl, ModelingToolkit using ModelingToolkit: D_nounits as D, t_nounits as t -@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) -``` -We than convert the MTK model to an [input-output system](https://docs.sciml.ai/ModelingToolkit/stable/basics/InputOutput/): - -```@example 1 -function generate_f_h(model, inputs, outputs) +function generate_f_h_mtk(model, inputs, outputs) (_, f_ip), x_sym, p_sym, io_sys = ModelingToolkit.generate_control_function( model, inputs, split=false, simplify=true ) - if any(ModelingToolkit.is_alg_equation, equations(io_sys)) - error("Systems with algebraic equations are not supported") - end - nu, nx, ny = length(inputs), length(x_sym), length(outputs) - function f!(ẋ, x, u, _ , p) + i_alg = ModelingToolkit.is_alg_equation.(equations(io_sys)) + function f_mtk!(ẋ, x, u, _ , p) try f_ip(ẋ, x, u, p, nothing) 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.") + "function, see the constructor docstring for a workaround.") else rethrow() end @@ -63,8 +56,8 @@ function generate_f_h(model, inputs, outputs) (_, h_ip) = ModelingToolkit.build_explicit_observed_function( io_sys, outputs; inputs, return_inplace = true ) - u_nothing = fill(nothing, nu) - function h!(y, x, _ , p) + u_nothing = fill(nothing, length(inputs)) + function h_mtk!(y, x, _ , 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 @@ -81,8 +74,11 @@ function generate_f_h(model, inputs, outputs) return nothing end ic = initial_conditions(io_sys) - p_map = try - Dict(sym => ic[sym] for sym in p_sym) + 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)") @@ -91,43 +87,115 @@ function generate_f_h(model, inputs, outputs) end end p = ModelingToolkit.varmap_to_vars(p_map, p_sym) - return f!, h!, p, x_sym, p_sym, nu, nx, ny + x = ModelingToolkit.varmap_to_vars(x_map, x_sym) + return f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg +end +``` + +The `generate_model` method then constructs an adequate [`SimModel`](@ref) object that +internally separate the differential states and algebraic variables, if any, to comply with +this package's interface: + +```@example 1 +function generate_model( + f_mtk!::F, h_mtk!::H, Ts, i_alg, inputs, outputs, p; + xs_mtk=zeros(length(i_alg)), unit="s", transcription=OrthogonalCollocation() +) where {F<:Function, H<:Function} + nu, ny = length(inputs), length(outputs) + 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; p, unit, xs_0, as_0, transcription + ) + else + f!, h! = f_mtk!, h_mtk! + model = NonLinModel(f!, h!, Ts, nu, nx, ny; p, unit) + end + return model # deliberately type unstable function end +``` + +## Pendulum Model + +We first construct and instantiate the pendulum model as a MTK `System` object: + +```@example 1 +@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) +``` + +We can now convert the MTK model: + +```@example 1 inputs, outputs = [τ], [y] -f!, h!, p, x_sym, p_sym, nu, nx, ny = generate_f_h(mtk_model, inputs, outputs) -x_sym +f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(mtk_model, inputs, outputs) +[x_sym x] ``` Since MTK is an acausal modeling framework, we do not have the control on 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 [last section](@ref man_nonlin) in the reverse order. As the same -also applies for the parameters, the `p_sym` object informs on how the `p` vector is sorted: +that is, the states of the [pendulum section](@ref man_nonlin) in the reverse order. As the +same also applies for the parameters, the `p_sym` object informs on how the `p` vector is +sorted: ```@example 1 [p_sym p] ``` -We can now construct a [`NonLinModel`](@ref) with this specific state realization: +We can now construct a [`SimModel`](@ref) with this specific state realization: ```@example 1 -vu, vx, vy = ["\$τ\$ (Nm)"], ["\$ω\$ (rad/s)", "\$θ\$ (rad)"], ["\$θ\$ (°)"] Ts = 0.1 -model = setname!(NonLinModel(f!, h!, Ts, nu, nx, ny; p); u=vu, x=vx, y=vy) +model = 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) ``` -We also instantiate a plant model with a 25 % larger friction coefficient ``K``: +As expected, the returned model is a [`NonLinModel`](@ref) object, since the pendulum model +has no algebraic equations. We also instantiate a plant model with a 25 % larger friction +coefficient ``K``: ```@example 1 i_K = findfirst(==("K"), string.(p_sym)) p2 = copy(p) p2[i_K] = 1.25*p[i_K] -plant = setname!(NonLinModel(f!, h!, Ts, nu, nx, ny; p=p2), u=vu, x=vx, y=vy) +plant = generate_model(f_mtk!, h_mtk!, Ts, i_alg, inputs, outputs, p2) +plant = setname!(plant; u=vu, x=vx, y=vy) ``` -## Controller Design +## Pendulum Controller Design -We can than reproduce the Kalman filter and the controller design of the [last section](@ref man_nonlin) +We can than reproduce the Kalman filter and the controller design of the [penultimate section](@ref man_nonlin) by reversing the order of `σQ` vector, because of the different state realization: ```@example 1 @@ -169,6 +237,80 @@ display(p) # hide ![plot2_MTK](plot2_MTK.svg) +## Neutralization Reactor Model + +!!! todo "Under Construction" + This section is not finished, only the model conversion is written for now. + +The MTK model of the neutralization reactor from the [last section](@ref man_dae) is +constructed as follows: + +```@example 1 +@parameters c_Ain=0.1 c_Bin=0.1 Kw=1e-14 Ka=1.75e-5 V=1000 q_Ain=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) +``` + +The substitution ``a_H = 10^(-pH)`` is explicitly applied in the algebraic equation to +improve the numerical conditioning of the system. The converted model is: + +```@example 1 +inputs, outputs = [q_Bin], [pH] +f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(mtk_model, inputs, outputs) +[x_sym x] +``` + +The content of `x_sym` shows it settled for the combined state and algebraic vector +``[\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](@ref man_dae). The order of the +parameters is: + +```@example 1 +[p_sym p] +``` + +We can now construct a [`SimModel`](@ref) with this realization: + +```@example 1 +Ts, unit = 0.5, "h" +xs_mtk = x +transcription = TrapezoidalCollocation() +model = generate_model( + f_mtk!, h_mtk!, Ts, i_alg, inputs, outputs, p; xs_mtk, unit, transcription +) +vu = [raw"$q_{Bin}$ (L/min)"] +vx, vy = [raw"$c_B$ (mol/L)", raw"$c_A$ (mol/L)"], [raw"$\mathrm{pH}$"] +model = setname!(model, u=vu, y=vy, x=vx) +``` + +The returned value is a [`NonLinModelDAE`](@ref) object, as expected. The transient +response is identical to the first 10 hours of the open-loop simulations of the +[last section](@ref man_dae): + +```@example 1 +using Plots +u, x_0 = [10.0], [0.0495, 0.0505] +N = 21 +using Logging # hide +res = with_logger(ConsoleLogger(stderr, Error)) do # hide +res = sim!(model, N, u; x_0) +end # hide +p = plot(res) +savefig(p, "plot3_MTK.svg") # hide +display(p) # hide +``` + +![plot3_MTK](plot3_MTK.svg) + ## Acknowledgement Authored by `1-Bart-1` and `baggepinnen`, thanks for the contribution. From fbd784419a19bdb5c6f5e676c2d30c87e50ffde3 Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 14:17:57 -0500 Subject: [PATCH 2/9] doc: minor correction --- docs/src/manual/nonlinmpc2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/manual/nonlinmpc2.md b/docs/src/manual/nonlinmpc2.md index b553d567f..8668269c2 100644 --- a/docs/src/manual/nonlinmpc2.md +++ b/docs/src/manual/nonlinmpc2.md @@ -459,7 +459,7 @@ display(p) # hide ![plot4_DAEpH](plot4_DAEpH.svg) -Finally, we benchmark the total runtime for this scenario, including estimation, control, +Finally, we benchmark the total runtime for this scenario, including estimation, control, and plant simulation: ```@example 1 From b1b8ecc2be904194ef24c97040c05187d41da5e8 Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 14:39:59 -0500 Subject: [PATCH 3/9] doc: minor corrections --- docs/src/manual/mtk.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index 88535fef9..b3a79e9dc 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -93,7 +93,7 @@ end ``` The `generate_model` method then constructs an adequate [`SimModel`](@ref) object that -internally separate the differential states and algebraic variables, if any, to comply with +internally separates the differential states and algebraic variables, if any, to comply with this package's interface: ```@example 1 @@ -161,11 +161,11 @@ f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(mtk_model, inputs, [x_sym x] ``` -Since MTK is an acausal modeling framework, we do not have the control on the state +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](@ref man_nonlin) in the reverse order. As the -same also applies for the parameters, the `p_sym` object informs on how the `p` vector is +same also applies to the parameters, the `p_sym` object informs on how the `p` vector is sorted: ```@example 1 @@ -195,7 +195,7 @@ plant = setname!(plant; u=vu, x=vx, y=vy) ## Pendulum Controller Design -We can than reproduce the Kalman filter and the controller design of the [penultimate section](@ref man_nonlin) +We can then reproduce the Kalman filter and the controller design of the [penultimate section](@ref man_nonlin) by reversing the order of `σQ` vector, because of the different state realization: ```@example 1 @@ -269,7 +269,7 @@ f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg = generate_f_h_mtk(mtk_model, inputs, [x_sym x] ``` -The content of `x_sym` shows it settled for the combined state and algebraic vector +The content of `x_sym` shows that it chose for the combined state and algebraic vector ``[\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](@ref man_dae). The order of the parameters is: From e69efc935d51cdaccf34d9236f362f79317d91dd Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 14:46:51 -0500 Subject: [PATCH 4/9] doc: debug MTK example --- docs/src/manual/mtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index b3a79e9dc..e39d54413 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -212,7 +212,7 @@ The 180° setpoint response is identical: ```@example 1 using Plots N = 35 -using JuMP; unset_time_limit_sec(nmpc.optim) # hide +import JuMP; JuMP.unset_time_limit_sec(nmpc.optim) # hide using Logging # hide res_ry = with_logger(ConsoleLogger(stderr, Error)) do # hide res_ry = sim!(nmpc, N, [180.0], plant=plant, x_0=[0, 0], x̂_0=[0, 0, 0]) From 4baa23f9e7abd58631ffdca11dadcbcc9620ee2d Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 15:16:28 -0500 Subject: [PATCH 5/9] doc: hide useless stuff --- docs/src/manual/mtk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index e39d54413..c6f33cb0e 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -90,6 +90,7 @@ function generate_f_h_mtk(model, inputs, outputs) x = ModelingToolkit.varmap_to_vars(x_map, x_sym) return f_mtk!, h_mtk!, p_sym, p, x_sym, x, i_alg end +nothing # hide ``` The `generate_model` method then constructs an adequate [`SimModel`](@ref) object that @@ -136,6 +137,7 @@ function generate_model( end return model # deliberately type unstable function end +nothing # hide ``` ## Pendulum Model From d4b66468cc4f8a7d5a37d637d6342962f61f1d7a Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 15:17:57 -0500 Subject: [PATCH 6/9] doc: minor correction --- docs/src/manual/mtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index c6f33cb0e..bb7156162 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -262,7 +262,7 @@ eqs = [ @named mtk_model = System(eqs, t) ``` -The substitution ``a_H = 10^(-pH)`` is explicitly applied in the algebraic equation to +The substitution ``a_H = 10^{-pH}`` is explicitly applied in the algebraic equation to improve the numerical conditioning of the system. The converted model is: ```@example 1 From 07caa849452d84572850bdf9417eae74ab6fee67 Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 15:18:26 -0500 Subject: [PATCH 7/9] doc: minor correction --- docs/src/manual/mtk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index bb7156162..a2d334e98 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -262,8 +262,8 @@ eqs = [ @named mtk_model = System(eqs, t) ``` -The substitution ``a_H = 10^{-pH}`` is explicitly applied in the algebraic equation to -improve the numerical conditioning of the system. The converted model is: +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: ```@example 1 inputs, outputs = [q_Bin], [pH] From 05986af2c6a2254ddfa5e1e6ec3b67b98391b9e7 Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 15:51:46 -0500 Subject: [PATCH 8/9] doc: minor improvement --- docs/src/manual/mtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index a2d334e98..9f89f1779 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -56,7 +56,7 @@ function generate_f_h_mtk(model, inputs, outputs) (_, h_ip) = ModelingToolkit.build_explicit_observed_function( io_sys, outputs; inputs, return_inplace = true ) - u_nothing = fill(nothing, length(inputs)) + const u_nothing = fill(nothing, length(inputs)) function h_mtk!(y, x, _ , p) try # MTK.jl supports a `u` argument in `h_ip` function but not this package. We From 8a613d375a461e432f0c59d4e2511f3ca64a468e Mon Sep 17 00:00:00 2001 From: franckgaga Date: Thu, 12 Nov 2026 15:58:33 -0500 Subject: [PATCH 9/9] Revert "doc: minor improvement" This reverts commit 05986af2c6a2254ddfa5e1e6ec3b67b98391b9e7. --- docs/src/manual/mtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/manual/mtk.md b/docs/src/manual/mtk.md index 9f89f1779..a2d334e98 100644 --- a/docs/src/manual/mtk.md +++ b/docs/src/manual/mtk.md @@ -56,7 +56,7 @@ function generate_f_h_mtk(model, inputs, outputs) (_, h_ip) = ModelingToolkit.build_explicit_observed_function( io_sys, outputs; inputs, return_inplace = true ) - const u_nothing = fill(nothing, length(inputs)) + u_nothing = fill(nothing, length(inputs)) function h_mtk!(y, x, _ , p) try # MTK.jl supports a `u` argument in `h_ip` function but not this package. We