doc add MPC vectors nomenclature in introduction

Author: franckgaga

docs/src/public/predictive_control.md

@@ -12,9 +12,47 @@ assumes by default that the current model mismatch estimation is constant in the
 (same approach than dynamic matrix control, DMC).
 
 !!! info
-    The nomenclature uses hats for the predictions (or estimations, for the state
-    estimators) e.g. ``\mathbf{Ŷ}`` encompasses the future model outputs ``\mathbf{y}`` over
-    the prediction horizon ``H_p``.
+    The nomenclature use capital letters for time series (and matrices) and hats for the
+    predictions (and estimations, for state estimators).
+
+To be precise, at the ``k``th control period, the vectors that encompass the future measured
+disturbances ``\mathbf{d̂}``, model outputs ``\mathbf{ŷ}`` and setpoints ``\mathbf{r̂_y}``
+over the prediction horizon ``H_p`` are defined as:
+
+```math
+    \mathbf{D̂} = \begin{bmatrix}
+        \mathbf{d̂}(k+1)   \\ \mathbf{d̂}(k+2)   \\ \vdots  \\ \mathbf{d̂}(k+H_p)
+    \end{bmatrix} \: , \quad
+    \mathbf{Ŷ} = \begin{bmatrix}
+        \mathbf{ŷ}(k+1)   \\ \mathbf{ŷ}(k+2)   \\ \vdots  \\ \mathbf{ŷ}(k+H_p)
+    \end{bmatrix} \: \text{and} \quad
+    \mathbf{R̂_y} = \begin{bmatrix}
+        \mathbf{r̂_y}(k+1) \\ \mathbf{r̂_y}(k+2) \\ \vdots  \\ \mathbf{r̂_y}(k+H_p)
+    \end{bmatrix}
+```
+
+The vectors for the manipulated input ``\mathbf{u}`` are shifted by one time step:
+
+```math
+    \mathbf{U} = \begin{bmatrix}
+        \mathbf{u}(k+0) \\ \mathbf{u}(k+1) \\ \vdots  \\ \mathbf{u}(k+H_p-1)
+    \end{bmatrix} \: \text{and} \quad
+    \mathbf{R̂_u} = \begin{bmatrix}
+        \mathbf{r_u}    \\ \mathbf{r_u}    \\ \vdots  \\ \mathbf{r_u}
+    \end{bmatrix}
+```
+
+assuming constant input setpoints at ``\mathbf{r_u}``. Defining the manipulated input
+increment as ``\mathbf{Δu}(k+j) = \mathbf{u}(k+j) - \mathbf{u}(k+j-1)``, the control horizon
+``H_c`` enforces that ``\mathbf{Δu}(k+j) = \mathbf{0}`` for ``j ≥ H_c``. For this reason,
+the vector that collects them is truncated up to ``k+H_c-1``:
+
+```math
+    \mathbf{ΔU} =
+    \begin{bmatrix}
+        \mathbf{Δu}(k+0) \\ \mathbf{Δu}(k+1) \\ \vdots  \\ \mathbf{Δu}(k+H_c-1)
+    \end{bmatrix}
+```
 
 ## PredictiveController
 

docs/src/public/state_estim.md

@@ -18,9 +18,10 @@ error with closed-loop control (offset-free tracking).
 
 The estimators are all implemented in the predictor form (a.k.a. observer form), that is,
 they all estimates at each discrete time ``k`` the states of the next period
-``\mathbf{x̂}_k(k+1)`` (also written ``\mathbf{x̂}_{k+1|k}`` [elsewhere](https://en.wikipedia.org/wiki/Kalman_filter)).
-In contrast, the filter form that estimates ``\mathbf{x̂}_k(k)`` is
-sometimes slightly more accurate.
+``\mathbf{x̂}_k(k+1)``[^1]. In contrast, the filter form that estimates ``\mathbf{x̂}_k(k)``
+is sometimes slightly more accurate.
+
+[^1]: also denoted ``\mathbf{x̂}_{k+1|k}`` [elsewhere](https://en.wikipedia.org/wiki/Kalman_filter).
 
 The predictor form comes in handy for control applications since the estimations come after
 the controller computations, without introducing any additional delays. Moreover, the

src/estimator/kalman.jl

@@ -64,7 +64,8 @@ end
 
 Construct a steady-state Kalman Filter with the [`LinModel`](@ref) `model`.
 
-The steady-state (or asymptotic) Kalman filter is based on the process model :
+The steady-state (or [asymptotic](https://en.wikipedia.org/wiki/Kalman_filter#Asymptotic_form))
+Kalman filter is based on the process model :
 ```math
 \begin{aligned}
     \mathbf{x}(k+1) &= 

src/predictive_control.jl

@@ -227,28 +227,17 @@ Compute the optimal manipulated input value `u` for the current control period.
 
 Solve the optimization problem of `mpc` [`PredictiveController`](@ref) and return the 
 results ``\mathbf{u}(k)``. Following the receding horizon principle, the algorithm discards 
-the optimal future manipulated inputs ``\mathbf{u}(k+1), \mathbf{u}(k+2), ``... The 
+the optimal future manipulated inputs ``\mathbf{u}(k+1), \mathbf{u}(k+2), ...`` The 
 arguments `ry` and `d` are current output setpoints ``\mathbf{r_y}(k)`` and measured 
-disturbances ``\mathbf{d}(k)``. The predicted output setpoint `R̂y` and measured disturbances 
-`D̂` are defined as:
-```math
-    \mathbf{R̂_y} = \begin{bmatrix}
-        \mathbf{r̂_y}(k+1)   \\
-        \mathbf{r̂_y}(k+2)   \\
-        \vdots              \\
-        \mathbf{r̂_y}(k+H_p)
-    \end{bmatrix}                   \qquad \text{and} \qquad
-    \mathbf{D̂}   = \begin{bmatrix}
-        \mathbf{d̂}(k+1)     \\
-        \mathbf{d̂}(k+2)     \\
-        \vdots              \\
-        \mathbf{d̂}(k+H_p)
-    \end{bmatrix}
-```
-They are assumed constant in the future by default, that is 
-``\mathbf{r̂_y}(k+j) = \mathbf{r_y}(k)`` and ``\mathbf{d̂}(k+j) = \mathbf{d}(k)`` for ``j=1``
-to ``H_p``. Current measured outputs `ym` (keyword argument) are only required if 
-`mpc.estim` is a [`InternalModel`](@ref).
+disturbances ``\mathbf{d}(k)``.
+
+The keyword arguments `R̂y` and `D̂` are the predicted output setpoints ``\mathbf{R̂_y}`` and
+measured disturbances ``\mathbf{D̂}``. They are assumed constant in the future by default, 
+that is ``\mathbf{r̂_y}(k+j) = \mathbf{r_y}(k)`` and ``\mathbf{d̂}(k+j) = \mathbf{d}(k)`` for
+``j=1`` to ``H_p``. Current measured output `ym` is only required if `mpc.estim` is a 
+[`InternalModel`](@ref).
+
+Calling a [`PredictiveController`](@ref) object calls this method.
 
 See also [`LinMPC`](@ref), [`NonLinMPC`](@ref).