removed evaloutput for InternalModel

useless public method, internal method `evalŷ` does the job

Author: franckgaga

docs/src/internals/sim_model.md

@@ -4,6 +4,14 @@
 Pages = ["sim_model.md"]
 ```
 
+## Steady-State Calculation
+
+```@docs
+ModelPredictiveControl.steadystate!
+```
+
+## State-Space Functions
+
 ```@docs
 ModelPredictiveControl.f
 ModelPredictiveControl.h

docs/src/internals/state_estim.md

@@ -21,6 +21,12 @@ ModelPredictiveControl.f̂
 ModelPredictiveControl.ĥ
 ```
 
+## Evaluate Estimated Output
+
+```@docs
+ModelPredictiveControl.evalŷ
+```
+
 ## Remove Operating Points
 
 ```@docs

docs/src/manual/linmpc.md

@@ -1,5 +1,9 @@
 # [Manual: Linear Design](@id man_lin)
 
+```@contents
+Pages = ["linmpc.md"]
+```
+
 ## Linear Model
 
 The example considers a continuously stirred-tank reactor (CSTR) with a cold and hot water

docs/src/manual/nonlinmpc.md

@@ -1,5 +1,9 @@
 # [Manual: Nonlinear Design](@id man_nonlin)
 
+```@contents
+Pages = ["nonlinmpc.md"]
+```
+
 ## Nonlinear Model
 
 In this example, the goal is to control the angular position ``θ`` of a pendulum

src/estimator/internal_model.jl

@@ -135,16 +135,16 @@ matrices_internalmodel(::SimModel) = tuple(fill(zeros(0, 0), 5)...)
 @doc raw"""
     f̂(estim::InternalModel, x̂, u, d)
 
-State function ``\mathbf{f̂}`` of the [`InternalModel`].
+State function ``\mathbf{f̂}`` of [`InternalModel`](@ref).
 
-It calls `f(estim.model, x̂, u ,d)` since this estimator does not augment the state vector.
+It calls [`f(estim.model, x̂, u ,d)`](@ref) since this estimator does not augment the states.
 """
 f̂(estim::InternalModel, x̂, u, d) = f(estim.model, x̂, u, d)
 
 @doc raw"""
     ĥ(estim::InternalModel, x̂, d)
 
-Output function ``\mathbf{ĥ}`` of the [`InternalModel`], it calls `h(estim.model, x̂, d)`.
+Output function ``\mathbf{ĥ}`` of [`InternalModel`](@ref), it calls [`h`](@ref) directly.
 """
 ĥ(estim::InternalModel, x̂, d) = h(estim.model, x̂, d)
 
@@ -221,21 +221,6 @@ function initstate_post!(estim::InternalModel)
     return nothing
 end
 
-@doc raw"""
-    evaloutput(estim::InternalModel, ym, d=Float64[]) -> ŷ
-
-Evaluate `InternalModel` outputs `ŷ` from `estim.x̂d` states and measured outputs `ym`.
-
-[`InternalModel`](@ref) estimator needs current measured outputs ``\mathbf{y^m}(k)`` to 
-estimate its outputs ``\mathbf{ŷ}(k)``, since the strategy imposes that 
-``\mathbf{ŷ^m}(k) = \mathbf{y^m}(k)`` is always true.
-"""
-function evaloutput(estim::InternalModel, ym, d=Float64[])
-    ŷ = h(estim.model, estim.x̂d, d - estim.model.dop) + estim.model.yop
-    ŷ[estim.i_ym] = ym
-    return ŷ
-end
-
 "Print InternalModel information without i/o integrators."
 function print_estim_dim(io::IO, estim::InternalModel, n)
     nu, nd = estim.model.nu, estim.model.nd

src/model/linmodel.jl

@@ -193,6 +193,26 @@ is not called). Care must be taken to ensure that the model is controllable and
 """
 LinModel(A, Bu, C, Bd, Dd, Ts, nu, nx, ny, nd)
 
+
+@doc raw"""
+    steadystate!(model::LinModel, u, d)
+
+Set `model.x` to `u` and `d` steady-state if `model` is a [`LinModel`](@ref).
+
+Following [`setop!`](@ref) notation, the method evaluates the equilibrium ``\mathbf{x}``
+from:
+```math
+    \mathbf{x} = \mathbf{(I - A)^{-1}(B_u u_0 + B_d d_0)}
+```
+with constant manipulated inputs ``\mathbf{u_0 = u - u_{op}}`` and measured
+disturbances ``\mathbf{d_0 = d - d_{op}}``. The Moore-Penrose pseudo-inverse computes 
+``\mathbf{(I - A)^{-1}}`` to support integrating `model` (integrator states will be 0).
+"""
+function steadystate!(model::LinModel, u, d)
+    model.x[:] = pinv(I - model.A)*(model.Bu*(u - model.uop) + model.Bd*(d - model.dop))
+    return nothing
+end
+
 """
     f(model::LinModel, x, u, d)
 

src/model/nonlinmodel.jl

@@ -87,6 +87,10 @@ function validate_fcts(f, h)
     end
 end
 
+"Do nothing if `model` is a [`NonLinModel`](@ref)."
+steadystate!(::SimModel, _ , _ ) = nothing
+
+
 "Call ``\\mathbf{f(x, u, d)}`` with `model.f` function for [`NonLinModel`](@ref)."
 f(model::NonLinModel, x, u, d) = model.f(x, u, d)
 

src/precompile_calls.jl

@@ -6,7 +6,6 @@ y = model()
 
 mpc_im = setconstraint!(LinMPC(InternalModel(model)), ymin=[45, -Inf])
 initstate!(mpc_im, model.uop, y)
-mpc_im.estim([50, 30])
 u = mpc_im([55, 30], ym=y)
 sim!(mpc_im, 3)
 

src/sim_model.jl

@@ -98,6 +98,34 @@ function Base.show(io::IO, model::SimModel)
     print(io,   "$(lpad(nd, n)) measured disturbances d")
 end
 
+@doc raw"""
+    initstate!(model::SimModel, u, d=Float64[]) -> x
+
+Init `model.x` with manipulated inputs `u` and measured disturbances `d` steady-state.
+
+It calls [`steadystate!(u, d)`](@ref):
+
+- If `estim.model` is a [`LinModel`](@ref), the method computes the steady-state of current
+  inputs `u` and measured disturbances `d`.
+- Else, `model.x` is left unchanged. Use [`setstate!`](@ref) to manually modify it.
+
+# Examples
+```jldoctest
+julia> model = LinModel(tf(6, [10, 1]), 2.0);
+
+julia> u = [1]; x = initstate!(model, u); y = round.(evaloutput(model), digits=3)
+1-element Vector{Float64}:
+ 6.0
+julia> x ≈ updatestate!(model, u)
+true
+```
+
+"""
+function initstate!(model::SimModel, u, d=Float64[])
+    steadystate!(model, u, d)
+    return model.x
+end
+
 """
     updatestate!(model::SimModel, u, d=Float64[]) -> x
 

src/state_estim.jl

@@ -296,9 +296,9 @@ The method tries to find a good stead-state for the initial esitmate ``\mathbf{x
 removes the operating points with [`remove_op!`](@ref) and call [`init_estimate!`](@ref):
 
 - If `estim.model` is a [`LinModel`](@ref), it finds the steady-state of the augmented model
-  using `u` and `d` arguments, and uses the `ym` argument to enforce that ``\mathbf{ŷ^m} = 
-  \mathbf{y^m}``. For control applications, this solution produces a bumpless manual to 
-  automatic transfer. See [`init_estimate!`](@ref) for details.
+  using `u` and `d` arguments, and uses the `ym` argument to enforce that 
+  ``\mathbf{ŷ^m}(0) = \mathbf{y^m}(0)``. For control applications, this solution produces a
+  bumpless manual to automatic transfer. See [`init_estimate!`](@ref) for details.
 - Else, `estim.x̂` is left unchanged. Use [`setstate!`](@ref) to manually modify it.
 
 If applicable, it also sets the error covariance `estim.P̂` to ``\mathbf{P̂}(0)``.
@@ -414,7 +414,27 @@ include("estimator/kalman.jl")
 include("estimator/luenberger.jl")
 include("estimator/internal_model.jl")
 
-"Get [`InternalModel`](@ref) output `ŷ` from current measured outputs `ym` and dist. `d`."
-evalŷ(estim::InternalModel, ym, d) = evaloutput(estim,ym, d)
-"Other [`StateEstimator`](@ref) ignores `ym` to evaluate `ŷ`."
-evalŷ(estim::StateEstimator, _, d) = evaloutput(estim, d)
+"""
+    evalŷ(estim::StateEstimator, _ , d) -> ŷ
+
+Evaluate [`StateEstimator`](@ref) output `ŷ` from measured disturbance `d` and `estim.x̂`.
+
+Second argument is ignored, except for [`InternalModel`](@ref).
+"""
+evalŷ(estim::StateEstimator, _ , d) = evaloutput(estim, d)
+
+@doc raw"""
+    evalŷ(estim::InternalModel, ym, d) -> ŷ
+
+Get [`InternalModel`](@ref) output `ŷ` from current measured outputs `ym` and dist. `d`.
+
+[`InternalModel`](@ref) estimator needs current measured outputs ``\mathbf{y^m}(k)`` to 
+estimate its outputs ``\mathbf{ŷ}(k)``, since the strategy imposes that 
+``\mathbf{ŷ^m}(k) = \mathbf{y^m}(k)`` is always true.
+"""
+function evalŷ(estim::InternalModel, ym, d)
+    ŷ = h(estim.model, estim.x̂d, d - estim.model.dop) + estim.model.yop
+    ŷ[estim.i_ym] = ym
+    return ŷ
+end
+