doc/en/ref_algorithm_KalmanFilter.rst

   1 ..
   2    Copyright (C) 2008-2024 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. index:: single: KalmanFilter
  25 .. _section_ref_algorithm_KalmanFilter:
  26
  27 Calculation algorithm "*KalmanFilter*"
  28 --------------------------------------
  29
  30 .. ------------------------------------ ..
  31 .. include:: snippets/Header2Algo01.rst
  32
  33 This algorithm realizes an estimation of the state of a dynamic system by a
  34 Kalman Filter. In discrete form, it is an iterative (or recursive) estimator of
  35 the current state using the previous state and the current observations. The
  36 time (or pseudo-time) between two steps is the time between successive
  37 observations. Each iteration step is composed of two successive phases,
  38 classically called "*prediction*" and "*correction*". The prediction step uses
  39 an incremental evolution operator to establish an estimate of the current state
  40 from the state estimated at the previous step. The correction (or *update*)
  41 step uses the current observations to improve the estimate by correcting the
  42 predicted state.
  43
  44 It is theoretically reserved for observation and incremental evolution
  45 operators cases which are linear, even if it sometimes works in "slightly"
  46 non-linear cases. One can verify the linearity of the operators with the help
  47 of a :ref:`section_ref_algorithm_LinearityTest`.
  48
  49 Conceptually, we can represent the temporal pattern of action of the evolution
  50 and observation operators in this algorithm in the following way, with **x**
  51 the state, **P** the state error covariance, *t* the discrete iterative time :
  52
  53   .. _schema_temporel_KF:
  54   .. figure:: images/schema_temporel_KF.png
  55     :align: center
  56     :width: 100%
  57
  58     **Timeline of steps in Kalman filter data assimilation**
  59
  60 In this scheme, the analysis **(x,P)** is obtained by means of the
  61 "*correction*" by observing the "*prediction*" of the previous state. We notice
  62 that there is no analysis performed at the initial time step (numbered 0 in the
  63 time indexing) because there is no forecast at this time (the background is
  64 stored as a pseudo analysis at the initial time step). If the observations are
  65 provided in series by the user, the first one is therefore not used.
  66
  67 This filter can also be used to estimate (jointly or solely) parameters and not
  68 the state, in which case neither the time nor the evolution have any meaning.
  69 The iteration steps are then linked to the insertion of a new observation in
  70 the recursive estimation. One should consult the section
  71 :ref:`section_theory_dynamic` for the implementation concepts.
  72
  73 In case of non-linearity of the operators, even slightly marked, it will be
  74 preferred a :ref:`section_ref_algorithm_ExtendedKalmanFilter`, or a
  75 :ref:`section_ref_algorithm_UnscentedKalmanFilter` and a
  76 :ref:`section_ref_algorithm_UnscentedKalmanFilter` that are more powerful. One
  77 can verify the linearity of the operators with the help of a
  78 :ref:`section_ref_algorithm_LinearityTest`.
  79
  80 .. ------------------------------------ ..
  81 .. include:: snippets/Header2Algo12.rst
  82
  83 .. include:: snippets/FeaturePropLocalOptimization.rst
  84
  85 .. include:: snippets/FeaturePropDerivativeNeeded.rst
  86
  87 .. include:: snippets/FeaturePropParallelDerivativesOnly.rst
  88
  89 .. ------------------------------------ ..
  90 .. include:: snippets/Header2Algo02.rst
  91
  92 .. include:: snippets/Background.rst
  93
  94 .. include:: snippets/BackgroundError.rst
  95
  96 .. include:: snippets/EvolutionError.rst
  97
  98 .. include:: snippets/EvolutionModel.rst
  99
 100 .. include:: snippets/Observation.rst
 101
 102 .. include:: snippets/ObservationError.rst
 103
 104 .. include:: snippets/ObservationOperator.rst
 105
 106 .. ------------------------------------ ..
 107 .. include:: snippets/Header2Algo03AdOp.rst
 108
 109 .. include:: snippets/EstimationOf_State.rst
 110
 111 StoreSupplementaryCalculations
 112   .. index:: single: StoreSupplementaryCalculations
 113
 114   *List of names*. This list indicates the names of the supplementary
 115   variables, that can be available during or at the end of the algorithm, if
 116   they are initially required by the user. Their availability involves,
 117   potentially, costly calculations or memory consumptions. The default is then
 118   a void list, none of these variables being calculated and stored by default
 119   (excepted the unconditional variables). The possible names are in the
 120   following list (the detailed description of each named variable is given in
 121   the following part of this specific algorithmic documentation, in the
 122   sub-section "*Information and variables available at the end of the
 123   algorithm*"): [
 124   "Analysis",
 125   "APosterioriCorrelations",
 126   "APosterioriCovariance",
 127   "APosterioriStandardDeviations",
 128   "APosterioriVariances",
 129   "BMA",
 130   "CostFunctionJ",
 131   "CostFunctionJAtCurrentOptimum",
 132   "CostFunctionJb",
 133   "CostFunctionJbAtCurrentOptimum",
 134   "CostFunctionJo",
 135   "CostFunctionJoAtCurrentOptimum",
 136   "CurrentOptimum",
 137   "CurrentState",
 138   "CurrentStepNumber",
 139   "ForecastCovariance",
 140   "ForecastState",
 141   "IndexOfOptimum",
 142   "InnovationAtCurrentAnalysis",
 143   "InnovationAtCurrentState",
 144   "SimulatedObservationAtCurrentAnalysis",
 145   "SimulatedObservationAtCurrentOptimum",
 146   "SimulatedObservationAtCurrentState",
 147   ].
 148
 149   Example :
 150   ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
 151
 152 .. ------------------------------------ ..
 153 .. include:: snippets/Header2Algo04.rst
 154
 155 .. include:: snippets/Analysis.rst
 156
 157 .. ------------------------------------ ..
 158 .. include:: snippets/Header2Algo05.rst
 159
 160 .. include:: snippets/Analysis.rst
 161
 162 .. include:: snippets/APosterioriCorrelations.rst
 163
 164 .. include:: snippets/APosterioriCovariance.rst
 165
 166 .. include:: snippets/APosterioriStandardDeviations.rst
 167
 168 .. include:: snippets/APosterioriVariances.rst
 169
 170 .. include:: snippets/BMA.rst
 171
 172 .. include:: snippets/CostFunctionJ.rst
 173
 174 .. include:: snippets/CostFunctionJAtCurrentOptimum.rst
 175
 176 .. include:: snippets/CostFunctionJb.rst
 177
 178 .. include:: snippets/CostFunctionJbAtCurrentOptimum.rst
 179
 180 .. include:: snippets/CostFunctionJo.rst
 181
 182 .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst
 183
 184 .. include:: snippets/CurrentOptimum.rst
 185
 186 .. include:: snippets/CurrentState.rst
 187
 188 .. include:: snippets/CurrentStepNumber.rst
 189
 190 .. include:: snippets/ForecastCovariance.rst
 191
 192 .. include:: snippets/ForecastState.rst
 193
 194 .. include:: snippets/IndexOfOptimum.rst
 195
 196 .. include:: snippets/InnovationAtCurrentAnalysis.rst
 197
 198 .. include:: snippets/InnovationAtCurrentState.rst
 199
 200 .. include:: snippets/SimulatedObservationAtCurrentAnalysis.rst
 201
 202 .. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
 203
 204 .. include:: snippets/SimulatedObservationAtCurrentState.rst
 205
 206 .. ------------------------------------ ..
 207 .. _section_ref_algorithm_KalmanFilter_examples:
 208
 209 .. include:: snippets/Header2Algo09.rst
 210
 211 .. --------- ..
 212 .. include:: scripts/simple_KalmanFilter1.rst
 213
 214 .. literalinclude:: scripts/simple_KalmanFilter1.py
 215
 216 .. include:: snippets/Header2Algo10.rst
 217
 218 .. literalinclude:: scripts/simple_KalmanFilter1.res
 219     :language: none
 220
 221 .. include:: snippets/Header2Algo11.rst
 222
 223 .. _simple_KalmanFilter1_state:
 224 .. image:: scripts/simple_KalmanFilter1_state.png
 225   :align: center
 226   :width: 90%
 227
 228 .. _simple_KalmanFilter1_variance:
 229 .. image:: scripts/simple_KalmanFilter1_variance.png
 230   :align: center
 231   :width: 90%
 232
 233 .. --------- ..
 234 .. include:: scripts/simple_KalmanFilter2.rst
 235
 236 .. literalinclude:: scripts/simple_KalmanFilter2.py
 237
 238 .. include:: snippets/Header2Algo10.rst
 239
 240 .. literalinclude:: scripts/simple_KalmanFilter2.res
 241     :language: none
 242
 243 .. include:: snippets/Header2Algo11.rst
 244
 245 .. _simple_KalmanFilter2_state:
 246 .. image:: scripts/simple_KalmanFilter2_state.png
 247   :align: center
 248   :width: 90%
 249
 250 .. _simple_KalmanFilter2_variance:
 251 .. image:: scripts/simple_KalmanFilter2_variance.png
 252   :align: center
 253   :width: 90%
 254
 255 .. ------------------------------------ ..
 256 .. include:: snippets/Header2Algo06.rst
 257
 258 - :ref:`section_ref_algorithm_ExtendedKalmanFilter`
 259 - :ref:`section_ref_algorithm_EnsembleKalmanFilter`
 260 - :ref:`section_ref_algorithm_UnscentedKalmanFilter`
 261
 262 .. ------------------------------------ ..
 263 .. include:: snippets/Header2Algo07.rst
 264
 265 - [Welch06]_
 266 - [WikipediaKF]_