added getinfo doc

Author: franckgaga

.vscode/settings.json

@@ -28,6 +28,7 @@
         "feedforward",
         "franckgaga",
         "getestimates",
+        "getinfo",
         "Hodouin",
         "initpred",
         "initstate",

Project.toml

@@ -1,7 +1,7 @@
 name = "ModelPredictiveControl"
 uuid = "61f9bdb8-6ae4-484a-811f-bbf86720c31c"
 authors = ["Francis Gagnon"]
-version = "0.4.1"
+version = "0.5.0"
 
 [deps]
 ControlSystemsBase = "aaaaaaaa-a6ca-5380-bf3e-84a91bcd477e"

docs/src/index.md

@@ -60,13 +60,15 @@ Pages = [
 - ✅ optimization based on `JuMP.jl`:
   - ✅ quickly compare multiple optimizers
   - ✅ nonlinear solvers relying on automatic differentiation (exact derivative)
-- ⬜ additional information about the optimum to ease troubleshooting:
-  - ⬜ optimal input increments over control horizon
-  - ⬜ slack variable optimum
-  - ⬜ objective function optimum
-  - ⬜ output predictions at optimum
-  - ⬜ current stochastic output predictions
-  - ⬜ optimal economic costs
+- ✅ additional information about the optimum to ease troubleshooting:
+  - ✅ optimal input increments over control horizon
+  - ✅ slack variable optimum
+  - ✅ objective function optimum
+  - ✅ output predictions at optimum
+  - ✅ current stochastic output predictions
+  - ✅ current deterministic output predictions
+  - ✅ optimal economic costs
+  - ✅ optimizer solution summary
 
 ### State Estimation Features
 

docs/src/public/predictive_control.md

@@ -45,3 +45,9 @@ setconstraint!
 ```@docs
 moveinput!
 ```
+
+## Get Additional Information
+
+```@docs
+getinfo
+```

src/controller/nonlinmpc.jl

@@ -188,6 +188,11 @@ function NonLinMPC(
     return NonLinMPC{S, JEFunc}(estim, Hp, Hc, Mwt, Nwt, Lwt, Cwt, Ewt, JE, ru, optim)
 end
 
+"""
+    getinfo(mpc::NonLinMPC)
+
+Invoke [`getinfo(::PredictiveController)`](@ref) and add `:JE` the economic optimum ``J_E``.
+"""
 function getinfo(mpc::NonLinMPC)
     info, sol_summary = invoke(getinfo, Tuple{PredictiveController}, mpc)
     U, Ŷ, D̂ = info[:U], info[:Ŷ], info[:D̂]

src/predictive_control.jl

@@ -263,36 +263,39 @@ function moveinput!(
     return u
 end
 
-#=
-
-
-"Include the additional information about the optimum to ease troubleshooting."
-mutable struct OptimInfo
-    ΔŨ::Vector{Float64}
-    ϵ ::Float64
-    J ::Float64
-    u ::Vector{Float64}
-    U ::Vector{Float64}
-    ŷ ::Vector{Float64}
-    Ŷ ::Vector{Float64}
-    ŷs::Vector{Float64}
-    Ŷs::Vector{Float64}
-end
-=#
-
-#=
-function write_info!(mpc::LinMPC, ΔŨ, J, ŷs, Ŷs)
-    mpc.info.ΔŨ = ΔŨ
-    mpc.info.ϵ = isinf(mpc.C) ? NaN : ΔŨ[end]
-    mpc.info.J = J
-    mpc.info.U = mpc.S̃_Hp*ΔŨ + mpc.T_Hp*(mpc.estim.lastu0 + mpc.estim.model.uop)
-    mpc.info.u = mpc.info.U[1:mpc.estim.model.nu]
-    mpc.info.ŷ = mpc.ŷ
-    mpc.info.Ŷ = mpc.Ẽ*ΔŨ + mpc.F
-    mpc.info.ŷs, mpc.info.Ŷs = ŷs, Ŷs
-end
-=#
+@doc raw"""
+    getinfo(mpc::PredictiveController)
+
+Get additional information about `mpc` controller optimum.
+
+Return the dictionary `info` with the additional information, and `sol_summary`, the
+optimizer solution summary that can be printed. The dictionary `info` has the following 
+fields:
+
+- `:ΔU` : optimal manipulated input increments over `Hc` ``(\mathbf{ΔU})``
+- `:ϵ`  : optimal slack variable ``(ϵ)``
+- `:J`  : objective value optimum ``(J)``
+- `:U`  : optimal manipulated inputs over `Hp` ``(\mathbf{U})``
+- `:u`  : current optimal manipulated input ``(\mathbf{u})``
+- `:d`  : current measured disturbance ``(\mathbf{d})``
+- `:D̂`  : predicted measured disturbances over `Hp` ``(\mathbf{D̂})``
+- `:ŷ`  : current estimated output ``(\mathbf{ŷ})``
+- `:Ŷ`  : predicted outputs over `Hp` ``(\mathbf{Ŷ = Ŷ_d + Ŷ_s})``
+- `:Ŷd` : predicted deterministic output over `Hp` ``(\mathbf{Ŷ_d})``
+- `:Ŷs` : predicted stochastic output over `Hp` ``(\mathbf{Ŷ_s})``
+- `:R̂y` : predicted output setpoint over `Hp` ``(\mathbf{R̂_y})``
+- `:R̂u` : predicted manipulated input setpoint over `Hp` ``(\mathbf{R̂_u})``
+
+# Examples
+```jldoctest
+julia> mpc = LinMPC(LinModel(tf(5, [2, 1]), 3), Nwt=[0], Hp=1000, Hc=1);
+
+julia> u = moveinput!(mpc, [5]);
 
+julia> info, sol_summary = getinfo(mpc); round.(info[:Ŷ][end], digits=2)
+5.0
+```
+"""
 function getinfo(mpc::PredictiveController)
     sol_summary = solution_summary(mpc.optim) 
     info = Dict{Symbol, InfoDictType}()

test/test_predictive_control.jl

@@ -56,13 +56,16 @@ end
     @test all((-mpc.con.A_Ŷmin[:, end], -mpc.con.A_Ŷmax[:, end]) .≈ ([1.0,1.1], [1.2,1.3]))
 end
 
-@testset "LinMPC moves" begin
+@testset "LinMPC moves and getinfo" begin
     mpc = LinMPC(LinModel(tf(5, [2, 1]), 3), Nwt=[0], Hp=1000, Hc=1)
     r = [5]
     u = moveinput!(mpc, r)
-    @test u ≈ [1] atol=1e-3
+    @test u ≈ [1] atol=1e-2
     u = mpc(r)
-    @test u ≈ [1] atol=1e-3
+    @test u ≈ [1] atol=1e-2
+    info, _ = getinfo(mpc)
+    @test info[:u] ≈ u
+    @test info[:Ŷ][end] ≈ 5 atol=1e-2
 end
 
 @testset "LinMPC other methods" begin
@@ -126,24 +129,30 @@ end
     @test all((nmpc.con.c_Ŷmin, nmpc.con.c_Ŷmax) .≈ ([1.0,1.1], [1.2,1.3]))
 end
 
-@testset "NonLinMPC moves" begin
+@testset "NonLinMPC moves and getinfo" begin
     linmodel = LinModel(tf(5, [2, 1]), 3)
     nmpc_lin = NonLinMPC(linmodel, Nwt=[0], Hp=1000, Hc=1)
     r = [5]
     u = moveinput!(nmpc_lin, r)
     @test u ≈ [1] atol=1e-3
     u = nmpc_lin(r)
     @test u ≈ [1] atol=1e-3
+    info, _ = getinfo(nmpc_lin)
+    @test info[:u] ≈ u
+    @test info[:Ŷ][end] ≈ 5 atol=1e-2
 
     f(x,u,_) = linmodel.A*x + linmodel.Bu*u
     h(x,_)   = linmodel.C*x 
     nonlinmodel = NonLinModel(f, h, 3, 1, 1, 1)
     nmpc_nonlin = NonLinMPC(nonlinmodel, Nwt=[0], Hp=1000, Hc=1)
     r = [5]
     u = moveinput!(nmpc_nonlin, r)
-    @test u ≈ [1] atol=1e-3
+    @test u ≈ [1] atol=1e-2
     u = nmpc_nonlin(r)
-    @test u ≈ [1] atol=1e-3
+    @test u ≈ [1] atol=1e-2
+    info, _ = getinfo(nmpc_nonlin)
+    @test info[:u] ≈ u
+    @test info[:Ŷ][end] ≈ 5 atol=1e-2
 end
 
 @testset "NonLinMPC other methods" begin