doc: added some details on the initial state estimate in the estimator docstrings

Author: franckgaga

src/estimator/kalman.jl

@@ -94,7 +94,9 @@ model, which is specified by the numbers of integrator `nint_u` and `nint_ym` (s
 Help). Likewise, the covariance matrices are augmented with ``\mathbf{Q̂ = \text{diag}(Q, 
 Q_{int_u}, Q_{int_{ym}})}`` and ``\mathbf{R̂ = R}``. The matrices ``\mathbf{Ĉ^m, D̂_d^m}`` are
 the rows of ``\mathbf{Ĉ, D̂_d}`` that correspond to measured outputs ``\mathbf{y^m}`` (and 
-unmeasured ones, for ``\mathbf{Ĉ^u, D̂_d^u}``).
+unmeasured ones, for ``\mathbf{Ĉ^u, D̂_d^u}``). The Kalman filter will estimate the current
+state with the newest measurements ``\mathbf{x̂}_k(k)`` if `direct == true`, else it will
+predict the the state of the next time step ``\mathbf{x̂}_k(k+1)``.
 
 # Arguments
 !!! info
@@ -331,10 +333,12 @@ end
 
 Construct a time-varying Kalman Filter with the [`LinModel`](@ref) `model`.
 
-The process model is identical to [`SteadyKalmanFilter`](@ref). The matrix ``\mathbf{P̂}_k``
-is the estimation error covariance of `model` states augmented with the stochastic ones
-(specified by `nint_u` and `nint_ym`). Three keyword arguments modify its initial value with
-``\mathbf{P̂}_{-1}(0) = \mathrm{diag}\{ \mathbf{P}(0), \mathbf{P_{int_{u}}}(0), \mathbf{P_{int_{ym}}}(0) \}``.
+The process model is identical to [`SteadyKalmanFilter`](@ref). The matrix ``\mathbf{P̂}`` is
+the estimation error covariance of `model` states augmented with the stochastic ones
+(specified by `nint_u` and `nint_ym`). Three keyword arguments specify its initial value with
+``\mathbf{P̂}_{-1}(0) = \mathrm{diag}\{ \mathbf{P}(0), \mathbf{P_{int_{u}}}(0), 
+\mathbf{P_{int_{ym}}}(0) \}``. The initial state estimate ``\mathbf{x̂}_{-1}(0)`` can be
+manually specified with [`setstate!`](@ref), or automatically with [`initstate!`](@ref).
 
 # Arguments
 !!! info
@@ -572,7 +576,11 @@ See [`SteadyKalmanFilter`](@ref) for details on ``\mathbf{v}(k), \mathbf{w}(k)``
 state-space functions augmented with the stochastic model of the unmeasured disturbances,
 which is specified by the numbers of integrator `nint_u` and `nint_ym` (see Extended Help).
 The ``\mathbf{ĥ^m}`` function represents the measured outputs of ``\mathbf{ĥ}`` function
-(and unmeasured ones, for ``\mathbf{ĥ^u}``).
+(and unmeasured ones, for ``\mathbf{ĥ^u}``). The matrix ``\mathbf{P̂}`` is the estimation
+error covariance of `model` state augmented with the stochastic ones. Three keyword
+arguments specify its initial value with ``\mathbf{P̂}_{-1}(0) = 
+\mathrm{diag}\{ \mathbf{P}(0), \mathbf{P_{int_{u}}}(0), \mathbf{P_{int_{ym}}}(0) \}``. The 
+initial state estimate ``\mathbf{x̂}_{-1}(0)`` can be manually specified with [`setstate!`](@ref).
 
 # Arguments
 !!! info

src/estimator/mhe/construct.jl

@@ -300,27 +300,32 @@ MovingHorizonEstimator estimator with a sample time Ts = 10.0 s, Ipopt optimizer
     with ``p=1`` is particularly useful for the MHE since it moves its expensive
     computations after the MPC optimization. That is, [`preparestate!`](@ref) will solve the
     optimization by default, but it can be postponed to [`updatestate!`](@ref) with
-    `direct=false`. Note that contrarily to all the other estimators in the module, the MHE
-    in its current form with ``p=0`` interprets the initial state estimate and covariance as 
-    ``\mathbf{x̂}_{-1}(-1)`` and ``\mathbf{P̂}_{-1}(-1)``, that is, an *a posteriori*
-    estimate[^2] from the last time step. 
-
-    [^2]: M. Hovd (2012), "A Note On The Smoothing Formulation Of Moving Horizon Estimation",
-          *Facta Universitatis*, Vol. 11 №2.
+    `direct=false`.
 
     The Extended Help of [`SteadyKalmanFilter`](@ref) details the augmentation with `nint_ym` 
     and `nint_u` arguments. The default augmentation scheme is identical, that is `nint_u=0`
     and `nint_ym` computed by [`default_nint`](@ref). Note that the constructor does not
     validate the observability of the resulting augmented [`NonLinModel`](@ref). In such
     cases, it is the user's responsibility to ensure that it is still observable.
-    
-    The slack variable ``ϵ`` relaxes the constraints if enabled, see [`setconstraint!`](@ref). 
-    It is disabled by default for the MHE (from `Cwt=Inf`) but it should be activated for
-    problems with two or more types of bounds, to ensure feasibility (e.g. on the estimated
-    state ``\mathbf{x̂}`` and sensor noise ``\mathbf{v̂}``).
-    
-    The optimization and the estimation of the covariance at arrival 
-    ``\mathbf{P̂}_{k-N_k}(k-N_k+p)`` depend on `model`:
+
+    The estimation covariance at arrival ``\mathbf{P̂}_{k-N_k}(k-N_k+p)`` gives an uncertainty
+    on the state estimate at the beginning of the window ``k-N_k+p``, that is, in the past.
+    It is not the same as the current estimate covariance ``\mathbf{P̂}_k(k)``, a value not
+    computed by the MHE (contrarily to e.g. the [`KalmanFilter`](@ref)). Three keyword
+    arguments specify its initial value with ``\mathbf{P̂_i} =  \mathrm{diag}\{ \mathbf{P}(0),
+    \mathbf{P_{int_{u}}}(0), \mathbf{P_{int_{ym}}}(0) \}``. The initial state estimate
+    ``\mathbf{x̂_i}`` can be manually specified with [`setstate!`](@ref), or automatically 
+    with [`initstate!`](@ref) for [`LinModel`](@ref). Note the MHE with ``p=0`` is slightly
+    inconsistent with all the other estimators here. It interprets the initial values as
+    ``\mathbf{x̂}_{-1}(-1) = \mathbf{x̂_i}`` and  ``\mathbf{P̂}_{-1}(-1) = \mathbf{P̂_i}``, that 
+    is, an *a posteriori* estimate[^2] from the last time step. The MHE with ``p=1`` is
+    consistent, interpreting them as  ``\mathbf{x̂}_{-1}(0) = \mathbf{x̂_i}`` and
+    ``\mathbf{P̂}_{-1}(0) = \mathbf{P̂_i}``.
+
+    [^2]: M. Hovd (2012), "A Note On The Smoothing Formulation Of Moving Horizon Estimation",
+          *Facta Universitatis*, Vol. 11 №2.
+
+    The optimization and the update of the arrival covariance depend on `model`:
 
     - If `model` is a [`LinModel`](@ref), the optimization is treated as a quadratic program
       with a time-varying Hessian, which is generally cheaper than nonlinear programming. By
@@ -330,10 +335,14 @@ MovingHorizonEstimator estimator with a sample time Ts = 10.0 s, Ipopt optimizer
       functions must be compatible with this feature. See [Automatic differentiation](https://jump.dev/JuMP.jl/stable/manual/nlp/#Automatic-differentiation)
       for common mistakes when writing these functions. An [`UnscentedKalmanFilter`](@ref)
       estimates the arrival covariance by default.
-
-    Note that if `Cwt≠Inf`, the attribute `nlp_scaling_max_gradient` of `Ipopt` is set to 
-    `10/Cwt` (if not already set), to scale the small values of ``ϵ``. Use the second
-    constructor to specify the covariance estimation method.
+    
+    The slack variable ``ϵ`` relaxes the constraints if enabled, see [`setconstraint!`](@ref). 
+    It is disabled by default for the MHE (from `Cwt=Inf`) but it should be activated for
+    problems with two or more types of bounds, to ensure feasibility (e.g. on the estimated
+    state ``\mathbf{x̂}`` and sensor noise ``\mathbf{v̂}``). Note that if `Cwt≠Inf`, the
+    attribute `nlp_scaling_max_gradient` of `Ipopt` is set to  `10/Cwt` (if not already set), 
+    to scale the small values of ``ϵ``. Use the second constructor to specify the covariance
+    estimation method.
 """
 function MovingHorizonEstimator(
     model::SM;