..
- Copyright (C) 2008-2019 EDF R&D
+ Copyright (C) 2008-2023 EDF R&D
This file is part of SALOME ADAO module.
.. include:: snippets/Header2Algo01.rst
This algorithm realizes an estimation of the state of a dynamic system by a
-Kalman Filter.
-
-It is theoretically reserved for observation and incremental evolution operators
-cases which are linear, even if it sometimes works in "slightly" non-linear
-cases. One can verify the linearity of the operators with the help of
-the :ref:`section_ref_algorithm_LinearityTest`.
-
-In case of non-linearity, even slightly marked, it will be preferred the
-:ref:`section_ref_algorithm_ExtendedKalmanFilter`, or the
-:ref:`section_ref_algorithm_UnscentedKalmanFilter` and the
-:ref:`section_ref_algorithm_UnscentedKalmanFilter` that are more powerful.
+Kalman Filter. In discrete form, it is an iterative (or recursive) estimator of
+the current state using the previous state and the current observations. The
+time (or pseudo-time) between two steps is the time between successive
+observations. Each iteration step is composed of two successive phases,
+classically called "*prediction*" and "*correction*". The prediction step uses
+an incremental evolution operator to establish an estimate of the current state
+from the state estimated at the previous step. The correction (or *update*)
+step uses the current observations to improve the estimate by correcting the
+predicted state.
+
+It is theoretically reserved for observation and incremental evolution
+operators cases which are linear, even if it sometimes works in "slightly"
+non-linear cases. One can verify the linearity of the operators with the help
+of a :ref:`section_ref_algorithm_LinearityTest`.
+
+Conceptually, we can represent the temporal pattern of action of the evolution
+and observation operators in this algorithm in the following way, with **x**
+the state, **P** the state error covariance, *t* the discrete iterative time :
+
+ .. _schema_temporel_KF:
+ .. figure:: images/schema_temporel_KF.png
+ :align: center
+ :width: 100%
+
+ **Timeline of steps in Kalman filter data assimilation**
+
+In this scheme, the analysis **(x,P)** is obtained by means of the
+"*correction*" by observing the "*prediction*" of the previous state. We notice
+that there is no analysis performed at the initial time step (numbered 0 in the
+time indexing) because there is no forecast at this time (the background is
+stored as a pseudo analysis at the initial time step). If the observations are
+provided in series by the user, the first one is therefore not used.
+
+This filter can also be used to estimate (jointly or solely) parameters and not
+the state, in which case neither the time nor the evolution have any meaning.
+The iteration steps are then linked to the insertion of a new observation in
+the recursive estimation. One should consult the section
+:ref:`section_theory_dynamic` for the implementation concepts.
+
+In case of non-linearity of the operators, even slightly marked, it will be
+preferred a :ref:`section_ref_algorithm_ExtendedKalmanFilter`, or a
+:ref:`section_ref_algorithm_UnscentedKalmanFilter` and a
+:ref:`section_ref_algorithm_UnscentedKalmanFilter` that are more powerful. One
+can verify the linearity of the operators with the help of a
+:ref:`section_ref_algorithm_LinearityTest`.
.. ------------------------------------ ..
.. include:: snippets/Header2Algo02.rst
.. ------------------------------------ ..
.. include:: snippets/Header2Algo03AdOp.rst
-.. include:: snippets/EstimationOf.rst
+.. include:: snippets/EstimationOf_State.rst
StoreSupplementaryCalculations
.. index:: single: StoreSupplementaryCalculations
- This list indicates the names of the supplementary variables that can be
- available at the end of the algorithm, if they are initially required by the
- user. It involves potentially costly calculations or memory consumptions. The
- default is a void list, none of these variables being calculated and stored
- by default excepted the unconditionnal variables. The possible names are in
- the following list: [
+ *List of names*. This list indicates the names of the supplementary
+ variables, that can be available during or at the end of the algorithm, if
+ they are initially required by the user. Their availability involves,
+ potentially, costly calculations or memory consumptions. The default is then
+ a void list, none of these variables being calculated and stored by default
+ (excepted the unconditional variables). The possible names are in the
+ following list (the detailed description of each named variable is given in
+ the following part of this specific algorithmic documentation, in the
+ sub-section "*Information and variables available at the end of the
+ algorithm*"): [
"Analysis",
"APosterioriCorrelations",
"APosterioriCovariance",
"CostFunctionJoAtCurrentOptimum",
"CurrentOptimum",
"CurrentState",
+ "CurrentStepNumber",
+ "ForecastCovariance",
+ "ForecastState",
"IndexOfOptimum",
"InnovationAtCurrentAnalysis",
"InnovationAtCurrentState",
- "PredictedState",
"SimulatedObservationAtCurrentAnalysis",
"SimulatedObservationAtCurrentOptimum",
"SimulatedObservationAtCurrentState",
].
Example :
- ``{"StoreSupplementaryCalculations":["BMA", "CurrentState"]}``
+ ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
.. ------------------------------------ ..
.. include:: snippets/Header2Algo04.rst
.. include:: snippets/CurrentState.rst
+.. include:: snippets/CurrentStepNumber.rst
+
+.. include:: snippets/ForecastCovariance.rst
+
+.. include:: snippets/ForecastState.rst
+
.. include:: snippets/IndexOfOptimum.rst
.. include:: snippets/InnovationAtCurrentAnalysis.rst
.. include:: snippets/InnovationAtCurrentState.rst
-.. include:: snippets/PredictedState.rst
-
.. include:: snippets/SimulatedObservationAtCurrentAnalysis.rst
.. include:: snippets/SimulatedObservationAtCurrentOptimum.rst
.. include:: snippets/SimulatedObservationAtCurrentState.rst
+.. ------------------------------------ ..
+.. _section_ref_algorithm_KalmanFilter_examples:
+
+.. include:: snippets/Header2Algo09.rst
+
+.. --------- ..
+.. include:: scripts/simple_KalmanFilter1.rst
+
+.. literalinclude:: scripts/simple_KalmanFilter1.py
+
+.. include:: snippets/Header2Algo10.rst
+
+.. literalinclude:: scripts/simple_KalmanFilter1.res
+ :language: none
+
+.. include:: snippets/Header2Algo11.rst
+
+.. _simple_KalmanFilter1_state:
+.. image:: scripts/simple_KalmanFilter1_state.png
+ :align: center
+ :width: 90%
+
+.. _simple_KalmanFilter1_variance:
+.. image:: scripts/simple_KalmanFilter1_variance.png
+ :align: center
+ :width: 90%
+
+.. --------- ..
+.. include:: scripts/simple_KalmanFilter2.rst
+
+.. literalinclude:: scripts/simple_KalmanFilter2.py
+
+.. include:: snippets/Header2Algo10.rst
+
+.. literalinclude:: scripts/simple_KalmanFilter2.res
+ :language: none
+
+.. include:: snippets/Header2Algo11.rst
+
+.. _simple_KalmanFilter2_state:
+.. image:: scripts/simple_KalmanFilter2_state.png
+ :align: center
+ :width: 90%
+
+.. _simple_KalmanFilter2_variance:
+.. image:: scripts/simple_KalmanFilter2_variance.png
+ :align: center
+ :width: 90%
+
.. ------------------------------------ ..
.. include:: snippets/Header2Algo06.rst
- :ref:`section_ref_algorithm_ExtendedKalmanFilter`
- :ref:`section_ref_algorithm_EnsembleKalmanFilter`
- :ref:`section_ref_algorithm_UnscentedKalmanFilter`
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
+
+- [Welch06]_
+- [WikipediaKF]_
