doc: added internal function optim_objective

Author: franckgaga

docs/src/internals/predictive_control.md

@@ -29,3 +29,9 @@ ModelPredictiveControl.init_matconstraint_mpc
 ModelPredictiveControl.initpred!(::PredictiveController, ::LinModel, ::Any, ::Any, ::Any, ::Any, ::Any)
 ModelPredictiveControl.linconstraint!(::PredictiveController, ::LinModel)
 ```
+
+## Solve Optimization Problem
+
+```@docs
+ModelPredictiveControl.optim_objective!
+```

src/controller/execute.jl

@@ -359,10 +359,27 @@ function obj_nonlinprog(
     return JR̂y + JΔŨ + JR̂u + E_JE
 end
 
-"""
-    optim_objective!(mpc::PredictiveController)
+@doc raw"""
+    optim_objective!(mpc::PredictiveController) -> ΔŨ
+
+Optimize the objective function of `mpc` [`PredictiveController`](@ref) and return the solution `ΔŨ`.
 
-Optimize the objective function ``J`` of `mpc` controller and return the solution `ΔŨ`.
+If supported by `mpc.optim`, it warm-starts the solver at:
+```math
+\mathbf{ΔŨ} = 
+\begin{bmatrix}
+    \mathbf{Δu}_{k-1}(k+0)      \\ 
+    \mathbf{Δu}_{k-1}(k+1)      \\ 
+    \vdots                      \\
+    \mathbf{Δu}_{k-1}(k+H_c-2)  \\
+    \mathbf{0}                  \\
+    ϵ_{k-1}
+\end{bmatrix}
+```
+where ``\mathbf{Δu}_{k-1}(k+j)`` is the input increment for time ``k+j`` computed at the 
+last control period ``k-1``. It then calls `JuMP.optimize!(mpc.optim)` and extract the
+solution. A failed optimization prints an `@error` log in the REPL and returns the 
+warm-start value.
 """
 function optim_objective!(mpc::PredictiveController{NT}) where {NT<:Real}
     optim = mpc.optim

src/controller/explicitmpc.jl

@@ -186,6 +186,8 @@ end
 linconstraint!(::ExplicitMPC, ::LinModel) = nothing
 
 @doc raw"""
+    optim_objective!(mpc::ExplicitMPC) -> ΔŨ
+
 Analytically solve the optimization problem for [`ExplicitMPC`](@ref).
 
 The solution is ``\mathbf{ΔŨ = - H̃^{-1} q̃}``, see [`init_quadprog`](@ref).