added : plotxwithx̂ option and output step dist in manual

Author: franckgaga

README.md

@@ -9,7 +9,7 @@ A [model predictive control](https://en.wikipedia.org/wiki/Model_predictive_cont
 for Julia.
 
 The package depends on [`ControlSystemsBase.jl`](https://github.com/JuliaControl/ControlSystems.jl)
-for the linear systems and [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) for the solvers.
+for the linear systems and [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) for the solving.
 
 ## Installation
 

docs/make.jl

@@ -14,7 +14,6 @@ DocMeta.setdocmeta!(
 )
 makedocs(
     sitename    = "ModelPredictiveControl.jl",
-    modules     = [ModelPredictiveControl],
     doctest     = true,
     format      = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
@@ -24,6 +23,7 @@ makedocs(
         "Home" => "index.md",
         "Manual" => [
             "Examples" => [
+                "Installation" => "manual/installation.md",
                 "Linear Design" => "manual/linmpc.md",
                 "Nonlinear Design" => "manual/nonlinmpc.md",
             ],

docs/src/index.md

@@ -4,73 +4,53 @@ A [model predictive control](https://en.wikipedia.org/wiki/Model_predictive_cont
 for Julia.
 
 The package depends on [`ControlSystemsBase.jl`](https://github.com/JuliaControl/ControlSystems.jl)
-for the linear systems and [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) for the solvers.
+for the linear systems and [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) for the solving.
 
-## Contents
+The objective is to provide a simple and clear framework to quickly design model predictive
+controllers (MPCs) in Julia, while keeping the flexibility for advanced optimization. Modern
+MPCs based on closed-loop state estimators are the main focus of the package, but classical
+approaches that rely on internal models are also possible. The `JuMP.jl` interface allows
+to easily test different solvers if the performance of the default settings is not
+satisfactory.
+
+The documentation is divided in two parts:
+
+- **[Manual](@ref man_lin)** This section includes step-by-step guides to design
+  predictive controllers or multiple case studies.
+- **[Functions](@ref func_sim_model)** This part contains the documentation of
+  methods and types that are exported by the package. The "Internals" section provides
+  implementation details of functions that are not exported.
+
+## Manual
 
 ```@contents
+Depth = 2
 Pages = [
-    "index.md",
+    "manual/installation.md",
     "manual/linmpc.md",
     "manual/nonlinmpc.md",
+]
+```
+
+## Functions: Public
+
+```@contents
+Depth = 2
+Pages = [
     "public/sim_model.md",
     "public/state_estim.md",
     "public/predictive_control.md",
     "public/generic_func.md",
+]
+```
+
+## Functions: Internals
+
+```@contents
+Depth = 1
+Pages = [
     "internals/sim_model.md",
     "internals/state_estim.md",
     "internals/predictive_control.md",
-    "func_index.md"
 ]
 ```
-
-## Features
-
-### Legend
-
-✅ implemented feature  
-⬜ planned feature
-
-### Model Predictive Control Features
-
-- ✅ linear and nonlinear plant models exploiting multiple dispatch
-- ✅ supported objective function terms:
-  - ✅ output setpoint tracking
-  - ✅ move suppression
-  - ✅ input setpoint tracking
-  - ✅ economic costs (economic model predictive control)
-  - ⬜ terminal cost to ensure nominal stability
-- ✅ soft and hard constraints on:
-  - ✅ output predictions
-  - ✅ manipulated inputs
-  - ✅ manipulated inputs increments
-- ⬜ custom manipulated input constraints that are a function of the predictions
-- ✅ supported feedback strategy:
-  - ✅ state estimator (see State Estimation features)
-  - ✅ internal model structure with a custom stochastic model
-- ✅ offset-free tracking with a single or multiple integrators on measured outputs
-- ✅ support for unmeasured model outputs
-- ✅ feedforward action with measured disturbances that supports direct transmission
-- ✅ custom predictions for:
-  - ✅ output setpoints
-  - ✅ measured disturbances
-- ✅ easy integration with `Plots.jl`
-- ✅ 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
-
-### State Estimation Features
-
-- ⬜ supported state estimators/observers:
-  - ✅ steady-state Kalman filter
-  - ✅ Kalman filter
-  - ✅ Luenberger observer
-  - ✅ internal model structure
-  - ⬜ extended Kalman filter
-  - ✅ unscented Kalman filter
-  - ⬜ moving horizon estimator
-- ✅ observers in predictor form to ease  control applications
-- ⬜ moving horizon estimator that supports:
-  - ⬜ inequality state constraints
-  - ⬜ zero process noise equality constraint to reduce the problem size

docs/src/manual/installation.md

@@ -0,0 +1,16 @@
+# Manual: Installation
+
+To install the `ModelPredictiveControl` package, run this command in the Julia REPL:
+
+```julia
+using Pkg; Pkg.add("ModelPredictiveControl")
+```
+
+It will also automatically install all the dependencies, including [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl)
+and [`ControlSystemsBase.jl`](https://github.com/JuliaControl/ControlSystems.jl). Note that
+that the construction of linear models typically requires `ss` or `tf` functions, it is thus
+recommended to load the package with:
+
+```julia
+using ModelPredictiveControl, ControlSystemsBase
+```

docs/src/manual/linmpc.md

@@ -113,8 +113,8 @@ nothing # hide
 The [`LinMPC`](@ref) objects are also callable as an alternative syntax for
 [`moveinput!`](@ref). Calling [`updatestate!`](@ref) on the `mpc` object updates its
 internal state for the *NEXT* control period (this is by design, see
-[State Estimators](@ref) for justifications). That is why the call is done at the end of the
-`for` loop. The same logic applies for `model`.
+[Functions: State Estimators](@ref) for justifications). That is why the call is done at the
+end of the `for` loop. The same logic applies for `model`.
 
 Lastly, we plot the closed-loop test with the `Plots` package:
 

docs/src/manual/nonlinmpc.md

@@ -50,7 +50,7 @@ is good practice to first simulate `model` using [`sim!`](@ref) as a quick sanit
 
 ```@example 1
 using Plots
-u = [0.5] # τ = 0.5 N m
+u = [0.5]
 plot(sim!(model, 60, u), plotu=false)
 ```
 
@@ -59,7 +59,7 @@ plot(sim!(model, 60, u), plotu=false)
 An [`UnscentedKalmanFilter`](@ref) estimates the plant state :
 
 ```@example 1
-estim = UnscentedKalmanFilter(model, σQ=[0.5, 2.5], σQ_int=[0.5])
+estim = UnscentedKalmanFilter(model, σQ=[0.5, 2.5], σQ_int=[5.0], σR=[0.5])
 ```
 
 The standard deviation of the angular velocity ``ω`` is higher here (`σQ` second value)
@@ -70,24 +70,33 @@ since ``\dot{ω}(t)`` equation includes an uncertain parameter: the friction coe
 par_plant = (par[1], par[2], par[3] + 0.25, par[4])
 f_plant(x, u, _) = x + Ts*pendulum(par_plant, x, u)
 plant = NonLinModel(f_plant, h, Ts, nu, nx, ny)
-res = sim!(estim, 30, [0.5], plant=plant, y_noise=[0.5]) # τ = 0.5 N m
-plot(res, plotu=false, plotx=true, plotx̂=true)
+res = sim!(estim, 60, [0.5], plant=plant, y_noise=[0.5])
+plot(res, plotu=false, plotxwithx̂=true)
 ```
 
-The Kalman filter performance seems sufficient for control. As the motor torque is limited
-to -1.5 to 1.5 N m, we incorporate the input constraints in a [`NonLinMPC`](@ref):
+The estimate ``x̂_3`` is the integrator state that compensates for static errors (`nint_ym`
+parameter of [`UnscentedKalmanFilter`](@ref)). The Kalman filter performance seems
+sufficient for control. As the motor torque is limited to -1.5 to 1.5 N m, we incorporate
+the input constraints in a [`NonLinMPC`](@ref):
 
 ```@example 1
-mpc = NonLinMPC(estim, Hp=20, Hc=2, Mwt=[0.1], Nwt=[1.0], Cwt=Inf)
+mpc = NonLinMPC(estim, Hp=20, Hc=4, Mwt=[0.1], Nwt=[1.0], Cwt=Inf)
 mpc = setconstraint!(mpc, umin=[-1.5], umax=[+1.5])
 ```
 
 We test `mpc` performance on `plant` by imposing an angular setpoint of 180° (inverted
 position):
 
 ```@example 1
-res = sim!(mpc, 30, [180.0], x̂0=zeros(mpc.estim.nx̂), plant=plant, x0=zeros(plant.nx))
-plot(res, plotŷ=true)
+res = sim!(mpc, 65, [180.0], plant=plant, x0=zeros(plant.nx), x̂0=zeros(mpc.estim.nx̂))
+plot(res)
 ```
 
-The controller seems robust enough to variations on ``K`` coefficient.
+The controller seems robust enough to variations on ``K`` coefficient. Moreover, starting
+from this inverted position, the closed-loop response to a step disturbances of 10° on ``θ``
+is also satisfactory:
+
+```@example 1
+res = sim!(mpc, 65, [180.0], plant=plant, x0=[π, 0], x̂0=[π, 0, 0], y_step=[10])
+plot(res)
+```

docs/src/public/sim_model.md

@@ -1,4 +1,4 @@
-# Functions: Plant Models
+# [Functions: Plant Models](@id func_sim_model)
 
 ```@contents
 Pages = ["sim_model.md"]

example/juMPC.jl

@@ -169,14 +169,9 @@ ps = plot(res, plotx=true)
 display(ps)
 
 res2 = sim!(uscKalmanFilter1, mpc.Hp+10)
-ps2 = plot(res2)
+ps2 = plot(res2, plotxwithx̂=true)
 display(ps2)
 
-res2 = sim!(uscKalmanFilter1, mpc.Hp+10, plant=deepcopy(uscKalmanFilter1.model))
-ps2 = plot(res2, plotx=true, plotx̂=true)
-display(ps2)
-
-
 
 test_mpc(linModel4, nmpc)
 @time u_data, y_data, r_data, d_data = test_mpc(linModel4, nmpc)