doc: add information about move blocking in public section

Author: franckgaga

docs/src/internals/predictive_control.md

@@ -12,6 +12,7 @@ The prediction methodology of this module is mainly based on Maciejowski textboo
 ## Controller Construction
 
 ```@docs
+ModelPredictiveControl.move_blocking
 ModelPredictiveControl.init_ZtoΔU   
 ModelPredictiveControl.init_ZtoU
 ModelPredictiveControl.init_predmat

src/controller/construct.jl

@@ -457,26 +457,40 @@ end
 estimate_delays(::SimModel) = 0
 
 
-"""
+@doc raw"""
     move_blocking(Hp::Int, Hc::AbstractVector{Int}) -> nb
 
-Get move blocking vector `nb` and actual control horizon from `Hp` and `Hc` arguments.
-
-The argument `Hc` is in fact the move blocking vector `nb` provided by the user. The `nb`
-vector is modified in these two cases:
+Get the move blocking vector `nb` from the `Hc` argument, and modify it to match `Hp`.
 
+The argument `Hc` is interpreted as the move blocking vector `nb`. It specifies the length
+of each step (or "block") in the ``\mathbf{ΔU}`` vector, to customize the pattern (strictly
+positive integers):
+```math
+    \mathbf{n_b} = \begin{bmatrix} n_1 & n_2 & \cdots & n_{H_c} \end{bmatrix}'
+```
+The vector with all the manipulated input increments is then defined as:
+```math
+\mathbf{ΔU} = \begin{bmatrix}
+    \mathbf{Δu}(k + 0)                                  \\[0.1em]
+    \mathbf{Δu}(k + ∑_{i=1}^1 n_i)                      \\[0.1em]
+    \mathbf{Δu}(k + ∑_{i=1}^2 n_i)                      \\[0.1em]
+    \vdots                                              \\[0.1em]
+    \mathbf{Δu}(k + ∑_{i=1}^{H_c-1} n_i)   
+\end{bmatrix}
+```
+The provided `nb` vector is modified in these two cases:
 - If `sum(nb) < Hp`, a new element is pushed to `nb` with the value `Hp - sum(nb)`.
 - If `sum(nb) > Hp`, the intervals are truncated until the sum is `Hp`. For example, if
   `Hp = 10` and `nb = [1, 2, 3, 6, 7]`, then `nb` is truncated to `[1, 2, 3, 4]`.
 """ 
 function move_blocking(Hp_arg::Int, Hc_arg::AbstractVector{Int})
     Hp = Hp_arg
     nb = Hc_arg
+    all(>(0), nb) || throw(ArgumentError("Move blocking vector must be strictly positive integers."))
     if sum(nb) < Hp
         newblock = [Hp - sum(nb)]
         nb = [nb; newblock]
     elseif sum(nb) > Hp
-        #For example, if Hp = 10 and nb = [1, 2, 3, 6, 7], than nb is truncated to [1, 2, 3, 4]
         nb = nb[begin:findfirst(≥(Hp), cumsum(nb))]
         if sum(nb) > Hp
             # if the last block is too large, it is truncated to fit Hp:
@@ -489,7 +503,7 @@ end
 """
     move_blocking(Hp::Int, Hc::Int) -> nb
 
-Construct a move blocking vector `nb` that match the provided `Hp` and `Hc` horizons.
+Construct a move blocking vector `nb` that match the provided `Hp` and `Hc` integers.
 
 The vector is filled with `1`s, except for the last element which is `Hp - Hc + 1`.
 """

src/controller/linmpc.jl

@@ -146,8 +146,9 @@ arguments. This controller allocates memory at each time step for the optimizati
 
 # Arguments
 - `model::LinModel` : model used for controller predictions and state estimations.
-- `Hp=10+nk` : prediction horizon ``H_p``, `nk` is the number of delays in `model`.
-- `Hc=2` : control horizon ``H_c``.
+- `Hp::Int=10+nk` : prediction horizon ``H_p``, `nk` is the number of delays in `model`.
+- `Hc::Union{Int, Vector{Int}}=2` : control horizon ``H_c``, custom move blocking is 
+   specified with a vector of integers (see [`move_blocking`](@ref) for details).
 - `Mwt=fill(1.0,model.ny)` : main diagonal of ``\mathbf{M}`` weight matrix (vector).
 - `Nwt=fill(0.1,model.nu)` : main diagonal of ``\mathbf{N}`` weight matrix (vector).
 - `Lwt=fill(0.0,model.nu)` : main diagonal of ``\mathbf{L}`` weight matrix (vector).

src/controller/nonlinmpc.jl

@@ -189,8 +189,10 @@ This controller allocates memory at each time step for the optimization.
 
 # Arguments
 - `model::SimModel` : model used for controller predictions and state estimations.
-- `Hp=nothing`: prediction horizon ``H_p``, must be specified for [`NonLinModel`](@ref).
-- `Hc=2` : control horizon ``H_c``.
+- `Hp::Int=10+nk` : prediction horizon ``H_p``, `nk` is the number of delays if `model` is a
+   [`LinModel`](@ref) (must be specified otherwise).
+- `Hc::Union{Int, Vector{Int}}=2` : control horizon ``H_c``, custom move blocking is 
+   specified with a vector of integers (see [`move_blocking`](@ref) for details).
 - `Mwt=fill(1.0,model.ny)` : main diagonal of ``\mathbf{M}`` weight matrix (vector).
 - `Nwt=fill(0.1,model.nu)` : main diagonal of ``\mathbf{N}`` weight matrix (vector).
 - `Lwt=fill(0.0,model.nu)` : main diagonal of ``\mathbf{L}`` weight matrix (vector).

src/controller/transcription.jl

@@ -66,29 +66,8 @@ end
 
 Init decision variables to input increments over ``H_c`` conversion matrix `PΔu`.
 
-Introducing the move blocking vector that specifies the length of each step in the 
-``\mathbf{ΔU}`` vector, to customize the pattern (strictly positive integers):
-
-```math
-\mathbf{n_b} = \begin{bmatrix} n_1 & n_2 & \cdots & n_{H_c} \end{bmatrix}'
-```
-
-The vector with all the manipulated input increments over the control horizon is defined
-as:
-
-```math
-\mathbf{ΔU} = \begin{bmatrix}
-    \mathbf{Δu}(k + 0)                                  \\[0.1em]
-    \mathbf{Δu}(k + ∑_{i=1}^1 n_i)                      \\[0.1em]
-    \mathbf{Δu}(k + ∑_{i=1}^2 n_i)                      \\[0.1em]
-    \vdots                                              \\[0.1em]
-    \mathbf{Δu}(k + ∑_{i=1}^{H_c-1} n_i)   
-\end{bmatrix}
-```
-
-This vector is extracted from from the decision variables ``\mathbf{Z}`` using the following
-formula:
-
+The conversion from the decision variables ``\mathbf{Z}`` to ``\mathbf{ΔU}``, the input
+increments over ``H_c``, is computed by:
 ```math
 \mathbf{ΔU} = \mathbf{P_{Δu}} \mathbf{Z}
 ```
@@ -134,7 +113,7 @@ The ``\mathbf{P_u}`` and ``\mathbf{T_u}`` matrices are defined in the Extended H
 
 # Extended Help
 !!! details "Extended Help"
-    With ``n_j``, the ``j``th element of the ``\mathbf{n_b}`` vector definedc in [`init_ZtoΔU`](@ref)
+    With ``n_j``, the ``j``th element of the ``\mathbf{n_b}`` vector defined in [`move_blocking`](@ref)
     documentation, we introduce the ``\mathbf{Q}(j)`` matrix of size `(nu*nj, nu)`:
     ```math
     \mathbf{Q}(j) =         \begin{bmatrix}