Skip to content

Commit e5cc5aa

Browse files
franckgagafranckgaga
committed
Extended helps in details admonition (collapsed)
1 parent 704846d commit e5cc5aa

File tree

8 files changed

+269
-254
lines changed

8 files changed

+269
-254
lines changed

‎src/controller/construct.jl‎

Lines changed: 76 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
@doc raw"""
22
setconstraint!(mpc::PredictiveController; <keyword arguments>) -> mpc
33
4-
Set the constraint parameters of `mpc` predictive controller.
4+
Set the constraint parameters of the [`PredictiveController`](@ref) `mpc`.
55
66
The predictive controllers support both soft and hard constraints, defined by:
77
```math
@@ -13,16 +13,11 @@ The predictive controllers support both soft and hard constraints, defined by:
1313
\end{alignat*}
1414
```
1515
and also ``ϵ ≥ 0``. The last line is the terminal constraints applied on the states at the
16-
end of the horizon (see Extended Help). All the constraint parameters are vector. Use `±Inf`
17-
values when there is no bound. The constraint softness parameters ``\mathbf{c}``, also
18-
called equal concern for relaxation, are non-negative values that specify the softness of
19-
the associated bound. Use `0.0` values for hard constraints. The output and terminal
16+
end of the horizon (see Extended Help). See [`MovingHorizonEstimator`](@ref) constraints
17+
for details on bounds and softness parameters ``\mathbf{c}``. The output and terminal
2018
constraints are all soft by default. See Extended Help for time-varying constraints.
2119
2220
# Arguments
23-
!!! info
24-
Same as above for the keyword arguments and default constraints.
25-
2621
- `mpc::PredictiveController` : predictive controller to set constraints.
2722
- `umin = fill(-Inf,nu)` : manipulated input lower bounds ``\mathbf{u_{min}}``.
2823
- `umax = fill(+Inf,nu)` : manipulated input upper bounds ``\mathbf{u_{max}}``.
@@ -61,34 +56,35 @@ LinMPC controller with a sample time Ts = 4.0 s, OSQP optimizer, SteadyKalmanFil
6156
```
6257
6358
# Extended Help
64-
Terminal constraints provide closed-loop stability guarantees on the nominal plant model.
65-
They can render an unfeasible problem however. In practice, a sufficiently large prediction
66-
horizon ``H_p`` without terminal constraints is typically enough for stability. Note that
67-
terminal constraints are applied on the augmented state vector ``\mathbf{x̂}`` (see
68-
[`SteadyKalmanFilter`](@ref) for details on augmentation).
69-
70-
For variable constraints, the bounds can be modified after calling [`moveinput!`](@ref),
71-
that is, at runtime, but not the softness parameters ``\mathbf{c}``. It is not possible to
72-
modify `±Inf` bounds at runtime.
73-
74-
!!! tip
75-
To keep a variable unconstrained while maintaining the ability to add a constraint later
76-
at runtime, set the bound to an absolute value sufficiently large when you create the
77-
controller (but different than `±Inf`).
78-
79-
It is also possible to specify time-varying constraints over ``H_p`` and ``H_c`` horizons.
80-
In such a case, they are defined by:
81-
```math
82-
\begin{alignat*}{3}
83-
\mathbf{U_{min} - C_{u_{min}}} ϵ ≤&&\ \mathbf{U} &≤ \mathbf{U_{max} + C_{u_{max}}} ϵ \\
84-
\mathbf{ΔU_{min} - C_{Δu_{min}}} ϵ ≤&&\ \mathbf{ΔU} &≤ \mathbf{ΔU_{max} + C_{Δu_{max}}} ϵ \\
85-
\mathbf{Y_{min} - C_{y_{min}}} ϵ ≤&&\ \mathbf{Ŷ} &≤ \mathbf{Y_{max} + C_{y_{max}}} ϵ
86-
\end{alignat*}
87-
```
88-
For this, use the same keyword arguments as above but with a capital letter:
89-
- `Umin` / `Umax` / `C_umin` / `C_umax` : ``\mathbf{U}`` constraints `(nu*Hp,)`.
90-
- `ΔUmin` / `ΔUmax` / `C_Δumin` / `C_Δumax` : ``\mathbf{ΔU}`` constraints `(nu*Hc,)`.
91-
- `Ymin` / `Ymax` / `C_ymin` / `C_ymax` : ``\mathbf{Ŷ}`` constraints `(ny*Hp,)`.
59+
!!! details "Extended Help"
60+
Terminal constraints provide closed-loop stability guarantees on the nominal plant model.
61+
They can render an unfeasible problem however. In practice, a sufficiently large
62+
prediction horizon ``H_p`` without terminal constraints is typically enough for
63+
stability. Note that terminal constraints are applied on the augmented state vector
64+
``\mathbf{x̂}`` (see [`SteadyKalmanFilter`](@ref) for details on augmentation).
65+
66+
For variable constraints, the bounds can be modified after calling [`moveinput!`](@ref),
67+
that is, at runtime, but not the softness parameters ``\mathbf{c}``. It is not possible
68+
to modify `±Inf` bounds at runtime.
69+
70+
!!! tip
71+
To keep a variable unconstrained while maintaining the ability to add a constraint
72+
later at runtime, set the bound to an absolute value sufficiently large when you
73+
create the controller (but different than `±Inf`).
74+
75+
It is also possible to specify time-varying constraints over ``H_p`` and ``H_c``
76+
horizons. In such a case, they are defined by:
77+
```math
78+
\begin{alignat*}{3}
79+
\mathbf{U_{min} - C_{u_{min}}} ϵ ≤&&\ \mathbf{U} &≤ \mathbf{U_{max} + C_{u_{max}}} ϵ \\
80+
\mathbf{ΔU_{min} - C_{Δu_{min}}} ϵ ≤&&\ \mathbf{ΔU} &≤ \mathbf{ΔU_{max} + C_{Δu_{max}}} ϵ \\
81+
\mathbf{Y_{min} - C_{y_{min}}} ϵ ≤&&\ \mathbf{Ŷ} &≤ \mathbf{Y_{max} + C_{y_{max}}} ϵ
82+
\end{alignat*}
83+
```
84+
For this, use the same keyword arguments as above but with a capital letter:
85+
- `Umin` / `Umax` / `C_umin` / `C_umax` : ``\mathbf{U}`` constraints `(nu*Hp,)`.
86+
- `ΔUmin` / `ΔUmax` / `C_Δumin` / `C_Δumax` : ``\mathbf{ΔU}`` constraints `(nu*Hc,)`.
87+
- `Ymin` / `Ymax` / `C_ymin` / `C_ymax` : ``\mathbf{Ŷ}`` constraints `(ny*Hp,)`.
9288
"""
9389
function setconstraint!(
9490
mpc::PredictiveController;
@@ -377,49 +373,50 @@ Operating points on ``\mathbf{u}``, ``\mathbf{d}`` and ``\mathbf{y}`` are omitte
377373
equations.
378374
379375
# Extended Help
380-
Using the augmented matrices ``\mathbf{Â, B̂_u, Ĉ, B̂_d, D̂_d}`` in `estim` and the function
381-
``\mathbf{W}(j) = \mathbf{Ĉ} ( ∑_{i=0}^j \mathbf{Â}^i ) \mathbf{B̂_u}``, the prediction
382-
matrices are computed by :
383-
```math
384-
\begin{aligned}
385-
\mathbf{E} &= \begin{bmatrix}
386-
\mathbf{W}(0) & \mathbf{0} & \cdots & \mathbf{0} \\
387-
\mathbf{W}(1) & \mathbf{W}(0) & \cdots & \mathbf{0} \\
388-
\vdots & \vdots & \ddots & \vdots \\
389-
\mathbf{W}(H_p-1) & \mathbf{W}(H_p-2) & \cdots & \mathbf{W}(H_p-H_c+1) \end{bmatrix} \\
390-
\mathbf{G} &= \begin{bmatrix}
391-
\mathbf{Ĉ}\mathbf{Â}^{0} \mathbf{B̂_d} \\
392-
\mathbf{Ĉ}\mathbf{Â}^{1} \mathbf{B̂_d} \\
393-
\vdots \\
394-
\mathbf{Ĉ}\mathbf{Â}^{H_p-1} \mathbf{B̂_d} \end{bmatrix} \\
395-
\mathbf{J} &= \begin{bmatrix}
396-
\mathbf{D̂_d} & \mathbf{0} & \cdots & \mathbf{0} \\
397-
\mathbf{Ĉ}\mathbf{Â}^{0} \mathbf{B̂_d} & \mathbf{D̂_d} & \cdots & \mathbf{0} \\
398-
\vdots & \vdots & \ddots & \vdots \\
399-
\mathbf{Ĉ}\mathbf{Â}^{H_p-2} \mathbf{B̂_d} & \mathbf{Ĉ}\mathbf{Â}^{H_p-3} \mathbf{B̂_d} & \cdots & \mathbf{D̂_d} \end{bmatrix} \\
400-
\mathbf{K} &= \begin{bmatrix}
401-
\mathbf{Ĉ}\mathbf{Â}^{1} \\
402-
\mathbf{Ĉ}\mathbf{Â}^{2} \\
403-
\vdots \\
404-
\mathbf{Ĉ}\mathbf{Â}^{H_p} \end{bmatrix} \\
405-
\mathbf{V} &= \begin{bmatrix}
406-
\mathbf{W}(0) \\
407-
\mathbf{W}(1) \\
408-
\vdots \\
409-
\mathbf{W}(H_p-1) \end{bmatrix}
410-
\end{aligned}
411-
```
412-
For the terminal constraints, the matrices are computed with the function
413-
``\mathbf{w_x̂}(j) = ( ∑_{i=0}^j \mathbf{Â}^i ) \mathbf{B̂_u}`` and:
414-
```math
415-
\begin{aligned}
416-
\mathbf{e_x̂} &= \begin{bmatrix} \mathbf{w_x̂}(H_p-1) & \mathbf{w_x̂}(H_p-2) & \cdots & \mathbf{w_x̂}(H_p-H_c+1) \end{bmatrix} \\
417-
\mathbf{g_x̂} &= \mathbf{Â}^{H_p-1} \mathbf{B̂_d} \\
418-
\mathbf{j_x̂} &= \begin{bmatrix} \mathbf{Â}^{H_p-2} \mathbf{B̂_d} & \mathbf{Â}^{H_p-3} \mathbf{B̂_d} & \cdots & \mathbf{0} \end{bmatrix} \\
419-
\mathbf{k_x̂} &= \mathbf{Â}^{H_p} \\
420-
\mathbf{v_x̂} &= \mathbf{w_x̂}(H_p-1)
421-
\end{aligned}
422-
```
376+
!!! details "Extended Help"
377+
Using the augmented matrices ``\mathbf{Â, B̂_u, Ĉ, B̂_d, D̂_d}`` in `estim` and the
378+
function ``\mathbf{W}(j) = \mathbf{Ĉ} ( ∑_{i=0}^j \mathbf{Â}^i ) \mathbf{B̂_u}``, the
379+
prediction matrices are computed by :
380+
```math
381+
\begin{aligned}
382+
\mathbf{E} &= \begin{bmatrix}
383+
\mathbf{W}(0) & \mathbf{0} & \cdots & \mathbf{0} \\
384+
\mathbf{W}(1) & \mathbf{W}(0) & \cdots & \mathbf{0} \\
385+
\vdots & \vdots & \ddots & \vdots \\
386+
\mathbf{W}(H_p-1) & \mathbf{W}(H_p-2) & \cdots & \mathbf{W}(H_p-H_c+1) \end{bmatrix} \\
387+
\mathbf{G} &= \begin{bmatrix}
388+
\mathbf{Ĉ}\mathbf{Â}^{0} \mathbf{B̂_d} \\
389+
\mathbf{Ĉ}\mathbf{Â}^{1} \mathbf{B̂_d} \\
390+
\vdots \\
391+
\mathbf{Ĉ}\mathbf{Â}^{H_p-1} \mathbf{B̂_d} \end{bmatrix} \\
392+
\mathbf{J} &= \begin{bmatrix}
393+
\mathbf{D̂_d} & \mathbf{0} & \cdots & \mathbf{0} \\
394+
\mathbf{Ĉ}\mathbf{Â}^{0} \mathbf{B̂_d} & \mathbf{D̂_d} & \cdots & \mathbf{0} \\
395+
\vdots & \vdots & \ddots & \vdots \\
396+
\mathbf{Ĉ}\mathbf{Â}^{H_p-2} \mathbf{B̂_d} & \mathbf{Ĉ}\mathbf{Â}^{H_p-3} \mathbf{B̂_d} & \cdots & \mathbf{D̂_d} \end{bmatrix} \\
397+
\mathbf{K} &= \begin{bmatrix}
398+
\mathbf{Ĉ}\mathbf{Â}^{1} \\
399+
\mathbf{Ĉ}\mathbf{Â}^{2} \\
400+
\vdots \\
401+
\mathbf{Ĉ}\mathbf{Â}^{H_p} \end{bmatrix} \\
402+
\mathbf{V} &= \begin{bmatrix}
403+
\mathbf{W}(0) \\
404+
\mathbf{W}(1) \\
405+
\vdots \\
406+
\mathbf{W}(H_p-1) \end{bmatrix}
407+
\end{aligned}
408+
```
409+
For the terminal constraints, the matrices are computed with the function
410+
``\mathbf{w_x̂}(j) = ( ∑_{i=0}^j \mathbf{Â}^i ) \mathbf{B̂_u}`` and:
411+
```math
412+
\begin{aligned}
413+
\mathbf{e_x̂} &= \begin{bmatrix} \mathbf{w_x̂}(H_p-1) & \mathbf{w_x̂}(H_p-2) & \cdots & \mathbf{w_x̂}(H_p-H_c+1) \end{bmatrix} \\
414+
\mathbf{g_x̂} &= \mathbf{Â}^{H_p-1} \mathbf{B̂_d} \\
415+
\mathbf{j_x̂} &= \begin{bmatrix} \mathbf{Â}^{H_p-2} \mathbf{B̂_d} & \mathbf{Â}^{H_p-3} \mathbf{B̂_d} & \cdots & \mathbf{0} \end{bmatrix} \\
416+
\mathbf{k_x̂} &= \mathbf{Â}^{H_p} \\
417+
\mathbf{v_x̂} &= \mathbf{w_x̂}(H_p-1)
418+
\end{aligned}
419+
```
423420
"""
424421
function init_predmat(estim::StateEstimator{NT}, model::LinModel, Hp, Hc) where {NT<:Real}
425422
Â, B̂u, Ĉ, B̂d, D̂d = estim.Â, estim.B̂u, estim.Ĉ, estim.B̂d, estim.D̂d

‎src/controller/linmpc.jl‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -142,26 +142,27 @@ LinMPC controller with a sample time Ts = 4.0 s, OSQP optimizer, SteadyKalmanFil
142142
```
143143
144144
# Extended Help
145-
Manipulated inputs setpoints ``\mathbf{r_u}`` are not common but they can be interesting
146-
for over-actuated systems, when `nu > ny` (e.g. prioritize solutions with lower economical
147-
costs). The default `Lwt` value implies that this feature is disabled by default.
148-
149-
The objective function follows this nomenclature:
150-
151-
| VARIABLE | DESCRIPTION | SIZE |
152-
| :------------------- | :------------------------------------------------------- | :--------------- |
153-
| ``H_p`` | prediction horizon (integer) | `()` |
154-
| ``H_c`` | control horizon (integer) | `()` |
155-
| ``\mathbf{ΔU}`` | manipulated input increments over ``H_c`` | `(nu*Hc,)` |
156-
| ``\mathbf{Ŷ}`` | predicted outputs over ``H_p`` | `(ny*Hp,)` |
157-
| ``\mathbf{U}`` | manipulated inputs over ``H_p`` | `(nu*Hp,)` |
158-
| ``\mathbf{R̂_y}`` | predicted output setpoints over ``H_p`` | `(ny*Hp,)` |
159-
| ``\mathbf{R̂_u}`` | predicted manipulated input setpoints over ``H_p`` | `(nu*Hp,)` |
160-
| ``\mathbf{M_{H_p}}`` | output setpoint tracking weights over ``H_p`` | `(ny*Hp, ny*Hp)` |
161-
| ``\mathbf{N_{H_c}}`` | manipulated input increment weights over ``H_c`` | `(nu*Hc, nu*Hc)` |
162-
| ``\mathbf{L_{H_p}}`` | manipulated input setpoint tracking weights over ``H_p`` | `(nu*Hp, nu*Hp)` |
163-
| ``C`` | slack variable weight | `()` |
164-
| ``ϵ`` | slack variable for constraint softening | `()` |
145+
!!! details "Extended Help"
146+
Manipulated inputs setpoints ``\mathbf{r_u}`` are not common but they can be interesting
147+
for over-actuated systems, when `nu > ny` (e.g. prioritize solutions with lower
148+
economical costs). The default `Lwt` value implies that this feature is disabled by default.
149+
150+
The objective function follows this nomenclature:
151+
152+
| VARIABLE | DESCRIPTION | SIZE |
153+
| :------------------- | :------------------------------------------------------- | :--------------- |
154+
| ``H_p`` | prediction horizon (integer) | `()` |
155+
| ``H_c`` | control horizon (integer) | `()` |
156+
| ``\mathbf{ΔU}`` | manipulated input increments over ``H_c`` | `(nu*Hc,)` |
157+
| ``\mathbf{Ŷ}`` | predicted outputs over ``H_p`` | `(ny*Hp,)` |
158+
| ``\mathbf{U}`` | manipulated inputs over ``H_p`` | `(nu*Hp,)` |
159+
| ``\mathbf{R̂_y}`` | predicted output setpoints over ``H_p`` | `(ny*Hp,)` |
160+
| ``\mathbf{R̂_u}`` | predicted manipulated input setpoints over ``H_p`` | `(nu*Hp,)` |
161+
| ``\mathbf{M_{H_p}}`` | output setpoint tracking weights over ``H_p`` | `(ny*Hp, ny*Hp)` |
162+
| ``\mathbf{N_{H_c}}`` | manipulated input increment weights over ``H_c`` | `(nu*Hc, nu*Hc)` |
163+
| ``\mathbf{L_{H_p}}`` | manipulated input setpoint tracking weights over ``H_p`` | `(nu*Hp, nu*Hp)` |
164+
| ``C`` | slack variable weight | `()` |
165+
| ``ϵ`` | slack variable for constraint softening | `()` |
165166
"""
166167
function LinMPC(
167168
model::LinModel;

‎src/controller/nonlinmpc.jl‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -156,15 +156,16 @@ NonLinMPC controller with a sample time Ts = 10.0 s, Ipopt optimizer, UnscentedK
156156
```
157157
158158
# Extended Help
159-
`NonLinMPC` controllers based on [`LinModel`](@ref) compute the predictions with matrix
160-
algebra instead of a `for` loop. This feature can accelerate the optimization, especially
161-
for the constraint handling, and is not available in any other package, to my knowledge.
159+
!!! details "Extended Help"
160+
`NonLinMPC` controllers based on [`LinModel`](@ref) compute the predictions with matrix
161+
algebra instead of a `for` loop. This feature can accelerate the optimization, especially
162+
for the constraint handling, and is not available in any other package, to my knowledge.
162163
163-
The optimizations rely on [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) automatic
164-
differentiation (AD) to compute the objective and constraint derivatives. Optimizers
165-
generally benefit from exact derivatives like AD. However, the [`NonLinModel`](@ref) `f`
166-
and `h` functions must be compatible with this feature. See [Automatic differentiation](https://jump.dev/JuMP.jl/stable/manual/nlp/#Automatic-differentiation)
167-
for common mistakes when writing these functions.
164+
The optimizations rely on [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) automatic
165+
differentiation (AD) to compute the objective and constraint derivatives. Optimizers
166+
generally benefit from exact derivatives like AD. However, the [`NonLinModel`](@ref) `f`
167+
and `h` functions must be compatible with this feature. See [Automatic differentiation](https://jump.dev/JuMP.jl/stable/manual/nlp/#Automatic-differentiation)
168+
for common mistakes when writing these functions.
168169
"""
169170
function NonLinMPC(
170171
model::SimModel;

‎src/estimator/internal_model.jl‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,12 +72,13 @@ InternalModel estimator with a sample time Ts = 0.5 s, LinModel and:
7272
```
7373
7474
# Extended Help
75-
`stoch_ym` is a `TransferFunction` or `StateSpace` object that models disturbances on
76-
``\mathbf{y^m}``. Its input is a hypothetical zero mean white noise vector. `stoch_ym`
77-
supposes 1 integrator per measured outputs by default, assuming that the current stochastic
78-
estimate ``\mathbf{ŷ_s^m}(k) = \mathbf{y^m}(k) - \mathbf{ŷ_d^m}(k)`` is constant in the
79-
future. This is the dynamic matrix control (DMC) strategy, which is simple but sometimes too
80-
aggressive. Additional poles and zeros in `stoch_ym` can mitigate this.
75+
!!! details "Extended Help"
76+
`stoch_ym` is a `TransferFunction` or `StateSpace` object that models disturbances on
77+
``\mathbf{y^m}``. Its input is a hypothetical zero mean white noise vector. `stoch_ym`
78+
supposes 1 integrator per measured outputs by default, assuming that the current stochastic
79+
estimate ``\mathbf{ŷ_s^m}(k) = \mathbf{y^m}(k) - \mathbf{ŷ_d^m}(k)`` is constant in the
80+
future. This is the dynamic matrix control (DMC) strategy, which is simple but sometimes
81+
too aggressive. Additional poles and zeros in `stoch_ym` can mitigate this.
8182
"""
8283
function InternalModel(
8384
model::SM;

0 commit comments

Comments
 (0)