X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=doc%2Fen%2Fref_algorithm_KalmanFilter.rst;h=620d9fa18ca7dbcf906de636ad5b1470235a8b5b;hb=19033474d28437bf58393a4d2df24f3e5d6eb48f;hp=70015566e4e94aa1e95843067cf092945a62cf39;hpb=b7a96f284864038a27611a19508c41648dd546aa;p=modules%2Fadao.git diff --git a/doc/en/ref_algorithm_KalmanFilter.rst b/doc/en/ref_algorithm_KalmanFilter.rst index 7001556..620d9fa 100644 --- a/doc/en/ref_algorithm_KalmanFilter.rst +++ b/doc/en/ref_algorithm_KalmanFilter.rst @@ -1,5 +1,5 @@ .. - Copyright (C) 2008-2019 EDF R&D + Copyright (C) 2008-2023 EDF R&D This file is part of SALOME ADAO module. @@ -31,17 +31,51 @@ Calculation algorithm "*KalmanFilter*" .. 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 @@ -63,29 +97,48 @@ In case of non-linearity, even slightly marked, it will be preferred the .. ------------------------------------ .. .. 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. It involves potentially costly - calculations or memory consumptions. The default is a void list, none of - these variables being calculated and stored by default. 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", "APosterioriStandardDeviations", "APosterioriVariances", "BMA", "CostFunctionJ", + "CostFunctionJAtCurrentOptimum", "CostFunctionJb", + "CostFunctionJbAtCurrentOptimum", "CostFunctionJo", + "CostFunctionJoAtCurrentOptimum", + "CurrentOptimum", "CurrentState", - "Innovation", + "CurrentStepNumber", + "ForecastCovariance", + "ForecastState", + "IndexOfOptimum", + "InnovationAtCurrentAnalysis", + "InnovationAtCurrentState", + "SimulatedObservationAtCurrentAnalysis", + "SimulatedObservationAtCurrentOptimum", + "SimulatedObservationAtCurrentState", ]. - Example : ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}`` + Example : + ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}`` .. ------------------------------------ .. .. include:: snippets/Header2Algo04.rst @@ -95,6 +148,8 @@ StoreSupplementaryCalculations .. ------------------------------------ .. .. include:: snippets/Header2Algo05.rst +.. include:: snippets/Analysis.rst + .. include:: snippets/APosterioriCorrelations.rst .. include:: snippets/APosterioriCovariance.rst @@ -107,13 +162,86 @@ StoreSupplementaryCalculations .. include:: snippets/CostFunctionJ.rst +.. include:: snippets/CostFunctionJAtCurrentOptimum.rst + .. include:: snippets/CostFunctionJb.rst +.. include:: snippets/CostFunctionJbAtCurrentOptimum.rst + .. include:: snippets/CostFunctionJo.rst +.. include:: snippets/CostFunctionJoAtCurrentOptimum.rst + +.. include:: snippets/CurrentOptimum.rst + .. include:: snippets/CurrentState.rst -.. include:: snippets/Innovation.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/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 @@ -121,3 +249,9 @@ StoreSupplementaryCalculations - :ref:`section_ref_algorithm_ExtendedKalmanFilter` - :ref:`section_ref_algorithm_EnsembleKalmanFilter` - :ref:`section_ref_algorithm_UnscentedKalmanFilter` + +.. ------------------------------------ .. +.. include:: snippets/Header2Algo07.rst + +- [Welch06]_ +- [WikipediaKF]_