wip: doc of transcription methods

Author: franckgaga

docs/src/public/transcription.md

@@ -6,6 +6,9 @@ Pages = ["transcription.md"]
 
 This page contains the documentation of the direct transcription methods used to
 construct [`MovingHorizonEstimator`](@ref), [`LinMPC`](@ref) and [`NonLinMPC`](@ref) types.
+They represent ways to discretize the continuous-time optimal control or estimation problem
+into a finite-dimensional quadratic (QP) or nonlinear program (NLP), which can then be
+solved using an appropriate optimizer.
 
 ## TranscriptionMethod
 

src/estimator/mhe/execute.jl

@@ -379,8 +379,8 @@ function initpred!(estim::MovingHorizonEstimator, model::LinModel)
     # --- update H̃, q̃ and p vectors for quadratic optimization ---
     ẼZ̃ = @views [estim.ẽx̄[:, 1:nZ̃]; estim.Ẽ[1:nYm, 1:nZ̃]]
     FZ̃ = @views [estim.fx̄; estim.F[1:nYm]]
-    invQ̂_Nk = trunc_cov(estim.cov.invQ̂_He, estim.nx̂, Nk, estim.He)
-    invR̂_Nk = trunc_cov(estim.cov.invR̂_He, estim.nym, Nk, estim.He)
+    invQ̂_Nk = trunc_cov(invQ̂_He, estim.nx̂,  Nk, estim.He)
+    invR̂_Nk = trunc_cov(invR̂_He, estim.nym, Nk, estim.He)
     M_Nk = [invP̄ zeros(nx̂, nYm); zeros(nYm, nx̂) invR̂_Nk]
     Ñ_Nk = [fill(C, nε, nε) zeros(nε, nx̂+nŴ); zeros(nx̂, nε+nx̂+nŴ); zeros(nŴ, nε+nx̂) invQ̂_Nk]
     M_Nk_ẼZ̃ = M_Nk*ẼZ̃
@@ -709,7 +709,7 @@ function obj_nonlinprog!(
     nε, Nk = estim.nε, estim.Nk[] 
     nYm, nŴ, nx̂, invP̄ = Nk*estim.nym, Nk*estim.nx̂, estim.nx̂, estim.cov.invP̄
     nx̃ = nε + nx̂
-    invQ̂_Nk = trunc_cov(estim.cov.invQ̂_He, estim.nx̂, Nk, estim.He)
+    invQ̂_Nk = trunc_cov(estim.cov.invQ̂_He, estim.nx̂,  Nk, estim.He)
     invR̂_Nk = trunc_cov(estim.cov.invR̂_He, estim.nym, Nk, estim.He)
     x̂0arr, Ŵ, V̂ = @views Z̃[nx̃-nx̂+1:nx̃], Z̃[nx̃+1:nx̃+nŴ], V̂[1:nYm]
     x̄ .= estim.x̂0arr_old .- x̂0arr

src/transcription.jl

@@ -4,7 +4,7 @@ const COLLOCATION_NODE_TYPE = Float64
 Abstract supertype of all transcription methods for the optimal control/estimation problems.
 
 The module currently supports [`SingleShooting`](@ref), [`MultipleShooting`](@ref),
-[`TrapezoidalCollocation`](@ref) and [`OrthogonalCollocation`](@ref) transcription methods.
+[`TrapezoidalCollocation`](@ref) and [`OrthogonalCollocation`](@ref) transcriptions.
 """
 abstract type TranscriptionMethod end
 abstract type ShootingMethod    <: TranscriptionMethod end
@@ -15,19 +15,33 @@ abstract type CollocationMethod <: TranscriptionMethod end
 
 Construct a direct single shooting [`TranscriptionMethod`](@ref).
 
-The decision variable in the optimization problem is (excluding the slack ``ϵ`` and without
-any custom move blocking):
+For [`MovingHorizonEstimator`](@ref) objects, the decision variable in the optimization
+problem is (excluding the slack ``ϵ``):
+```math
+\mathbf{Z} =                        
+    =                               \begin{bmatrix} 
+    \mathbf{x̂}_k(k-N_k+p)           \\
+    \mathbf{Ŵ}                      \end{bmatrix}
+    =                               \begin{bmatrix}
+    \mathbf{x̂}_k(k-N_k+p)           \\
+    \mathbf{ŵ}(k-N_k+p+0)           \\
+    \mathbf{ŵ}(k-N_k+p+1)           \\
+    \vdots                          \\
+    \mathbf{ŵ}(k+p-1)               \end{bmatrix}
+```
+and, for [`PredictiveController`](@ref) types (without any custom move blocking):
 ```math
 \mathbf{Z} = \mathbf{ΔU} =          \begin{bmatrix} 
     \mathbf{Δu}(k+0)                \\ 
     \mathbf{Δu}(k+1)                \\ 
     \vdots                          \\ 
     \mathbf{Δu}(k+H_c-1)            \end{bmatrix}
 ```
+
 This method computes the predictions by calling the augmented discrete-time model
-recursively over the prediction horizon ``H_p`` in the objective function, or by updating
-the linear coefficients of the quadratic optimization for [`LinModel`](@ref). It is 
-generally  more efficient for small control horizon ``H_c``, stable and mildly nonlinear
+recursively over the horizon in the objective function, or by updating the linear
+coefficients of the quadratic optimization for [`LinModel`](@ref). It is 
+generally  more efficient for small ``H_c`` or ``H_e`` values, stable and mildly nonlinear
 plant model/constraints.
 """
 struct SingleShooting <: ShootingMethod end
@@ -103,8 +117,8 @@ transcription method.
     Note that the stochastic model of the unmeasured disturbances is strictly discrete-time,
     as described in [`ModelPredictiveControl.init_estimstoch`](@ref). Collocation methods
     require continuous-time dynamics. Because of this, the stochastic states are transcribed
-    separately using a [`MultipleShooting`](@ref) method. See [`con_nonlinprogeq!`](@ref)
-    for more details.
+    separately using a [`MultipleShooting`](@ref) method and by exploiting its linear
+    structure. See [`con_nonlinprogeq!`](@ref) for more details.
 """
 struct TrapezoidalCollocation <: CollocationMethod
     h::Int