added: setname! function for variable names in plot labels

doc: use `setname!` on the pendulum

Author: franckgaga

docs/src/manual/nonlinmpc.md

@@ -53,8 +53,9 @@ end
 const par = (9.8, 0.4, 1.2, 0.3)
 f(x, u, _ ) = pendulum(par, x, u)
 h(x, _ )    = [180/π*x[1]]  # [°]
-Ts, nu, nx, ny = 0.1, 1, 2, 1
-model = NonLinModel(f, h, Ts, nu, nx, ny)
+nu, nx, ny, Ts = 1, 2, 1, 0.1
+vu, vx, vy = ["\$τ\$ (N m)"], ["\$θ\$ (rad)", "\$ω\$ (rad/s)"], ["\$θ\$ (°)"]
+model = setname!(NonLinModel(f, h, Ts, nu, nx, ny); u=vu, x=vx, y=vy)
 ```
 
 The output function ``\mathbf{h}`` converts the ``θ`` angle to degrees. Note that special
@@ -72,6 +73,8 @@ plot(res, plotu=false)
 savefig(ans, "plot1_NonLinMPC.svg"); nothing # hide
 ```
 
+The [`setname!`](@ref) function allows customizing the Y-axis labels.
+
 ![plot1_NonLinMPC](plot1_NonLinMPC.svg)
 
 ## Nonlinear Model Predictive Controller
@@ -93,7 +96,7 @@ estimator tuning is tested on a plant with a 25 % larger friction coefficient ``
 ```@example 1
 const par_plant = (par[1], par[2], 1.25*par[3], par[4])
 f_plant(x, u, _ ) = pendulum(par_plant, x, u)
-plant = NonLinModel(f_plant, h, Ts, nu, nx, ny)
+plant = setname!(NonLinModel(f_plant, h, Ts, nu, nx, ny); u=vu, x=vx, y=vy)
 res = sim!(estim, N, [0.5], plant=plant, y_noise=[0.5])
 plot(res, plotu=false, plotxwithx̂=true)
 savefig(ans, "plot2_NonLinMPC.svg"); nothing # hide
@@ -173,8 +176,8 @@ Kalman Filter similar to the previous one (``\mathbf{y^m} = θ`` and ``\mathbf{y
 ```@example 1
 h2(x, _ ) = [180/π*x[1], x[2]]
 nu, nx, ny = 1, 2, 2
-model2 = NonLinModel(f      , h2, Ts, nu, nx, ny)
-plant2 = NonLinModel(f_plant, h2, Ts, nu, nx, ny)
+model2 = setname!(NonLinModel(f      , h2, Ts, nu, nx, ny), u=vu, x=vx, y=[vy; vx[2]])
+plant2 = setname!(NonLinModel(f_plant, h2, Ts, nu, nx, ny), u=vu, x=vx, y=[vy; vx[2]])
 estim2 = UnscentedKalmanFilter(model2; σQ, σR, nint_u, σQint_u, i_ym=[1])
 ```
 

docs/src/public/sim_model.md

@@ -29,18 +29,10 @@ LinModel
 NonLinModel
 ```
 
-## Differential Equation Solvers
-
-### DiffSolver
-
-```@docs
-ModelPredictiveControl.DiffSolver
-```
-
-### RungeKutta
+## Set Variable Names
 
 ```@docs
-RungeKutta
+setname!
 ```
 
 ## Set Operating Points
@@ -55,3 +47,17 @@ setop!
 linearize
 linearize!
 ```
+
+## Differential Equation Solvers
+
+### DiffSolver
+
+```@docs
+ModelPredictiveControl.DiffSolver
+```
+
+### RungeKutta
+
+```@docs
+RungeKutta
+```

src/ModelPredictiveControl.jl

@@ -23,7 +23,8 @@ import OSQP, Ipopt
 
 export SimModel, LinModel, NonLinModel
 export DiffSolver, RungeKutta
-export setop!, setstate!, setmodel!, updatestate!, evaloutput, linearize, linearize!
+export setop!, setname!
+export setstate!, setmodel!, updatestate!, evaloutput, linearize, linearize!
 export StateEstimator, InternalModel, Luenberger
 export SteadyKalmanFilter, KalmanFilter, UnscentedKalmanFilter, ExtendedKalmanFilter
 export MovingHorizonEstimator

src/model/linearization.jl

@@ -80,13 +80,17 @@ function linearize(model::SimModel{NT}; kwargs...) where NT<:Real
     Bd = Matrix{NT}(undef, nx, nd)
     Dd = Matrix{NT}(undef, ny, nd)
     linmodel = LinModel{NT}(A, Bu, C, Bd, Dd, model.Ts)
+    linmodel.uname .= model.uname
+    linmodel.xname .= model.xname
+    linmodel.yname .= model.yname
+    linmodel.dname .= model.dname
     return linearize!(linmodel, model; kwargs...)
 end
 
 """
     linearize!(linmodel::LinModel, model::SimModel; <keyword arguments>) -> linmodel
 
-Linearize `model` and store the result in `linmodel`.
+Linearize `model` and store the result in `linmodel` (in-place).
 
 The keyword arguments are identical to [`linearize`](@ref).
 

src/model/linmodel.jl

@@ -15,6 +15,10 @@ struct LinModel{NT<:Real} <: SimModel{NT}
     dop::Vector{NT}
     xop::Vector{NT}
     fop::Vector{NT}
+    uname::Vector{String}
+    yname::Vector{String}
+    dname::Vector{String}
+    xname::Vector{String}
     function LinModel{NT}(A, Bu, C, Bd, Dd, Ts) where {NT<:Real}
         A, Bu = to_mat(A, 1, 1), to_mat(Bu, 1, 1)
         nu, nx = size(Bu, 2), size(A, 2)
@@ -35,8 +39,19 @@ struct LinModel{NT<:Real} <: SimModel{NT}
         dop = zeros(NT, nd)
         xop = zeros(NT, nx)
         fop = zeros(NT, nx)
+        uname = ["\$u_{$i}\$" for i in 1:nu]
+        yname = ["\$y_{$i}\$" for i in 1:ny]
+        dname = ["\$d_{$i}\$" for i in 1:nd]
+        xname = ["\$x_{$i}\$" for i in 1:nx]
         x0  = zeros(NT, nx)
-        return new(A, Bu, C, Bd, Dd, x0, Ts, nu, nx, ny, nd, uop, yop, dop, xop, fop)
+        return new{NT}(
+            A, Bu, C, Bd, Dd, 
+            x0, 
+            Ts, 
+            nu, nx, ny, nd, 
+            uop, yop, dop, xop, fop,
+            uname, yname, dname, xname
+        )
     end
 end
 

src/model/nonlinmodel.jl

@@ -13,6 +13,10 @@ struct NonLinModel{NT<:Real, F<:Function, H<:Function, DS<:DiffSolver} <: SimMod
     dop::Vector{NT}
     xop::Vector{NT}
     fop::Vector{NT}
+    uname::Vector{String}
+    yname::Vector{String}
+    dname::Vector{String}
+    xname::Vector{String}
     function NonLinModel{NT, F, H, DS}(
         f!::F, h!::H, solver::DS, Ts, nu, nx, ny, nd
     ) where {NT<:Real, F<:Function, H<:Function, DS<:DiffSolver}
@@ -22,9 +26,18 @@ struct NonLinModel{NT<:Real, F<:Function, H<:Function, DS<:DiffSolver} <: SimMod
         dop = zeros(NT, nd)
         xop = zeros(NT, nx)
         fop = zeros(NT, nx)
+        uname = ["\$u_{$i}\$" for i in 1:nu]
+        yname = ["\$y_{$i}\$" for i in 1:ny]
+        dname = ["\$d_{$i}\$" for i in 1:nd]
+        xname = ["\$x_{$i}\$" for i in 1:nx]
         x0  = zeros(NT, nx)
         return new{NT, F, H, DS}(
-            x0, f!, h!, solver, Ts, nu, nx, ny, nd, uop, yop, dop, xop, fop
+            x0, 
+            f!, h!, 
+            solver, Ts, 
+            nu, nx, ny, nd, 
+            uop, yop, dop, xop, fop,
+            uname, yname, dname, xname
         )
     end
 end