Documentation improvements and post analysis

[modules/adao.git] / doc / fr / ref_algorithm_ExtendedKalmanFilter.rst

diff --git a/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst
index 8696d30e733bdde8aaf56d9da597b67ed9b095dd..9fc7dbe2a448fd07b7c0a74fe8c963f2c543225a 100644 (file)
--- a/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst
+++ b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst
@@ -1,5 +1,5 @@
 ..
-   Copyright (C) 2008-2019 EDF R&D
+   Copyright (C) 2008-2021 EDF R&D
 
    This file is part of SALOME ADAO module.
 
@@ -34,6 +34,23 @@ Cet algorithme réalise une estimation de l'état d'un système dynamique par un
 filtre de Kalman étendu, utilisant un calcul non linéaire de l'état et de
 l'évolution incrémentale (processus).
 
+Conceptuellement, on peut représenter le schéma temporel d'action des
+opérateurs d'évolution et d'observation dans cet algorithme de la manière
+suivante, avec **x** l'état et **P** la covariance d'erreur d'état :
+
+  .. _schema_temporel_KF:
+  .. image:: images/schema_temporel_KF.png
+    :align: center
+    :width: 100%
+  .. centered::
+    **Schéma temporel des étapes en assimilation par filtre de Kalman étendu**
+
+On remarque qu'il n'y a pas d'analyse effectuée au pas de temps initial
+(numéroté 0 dans l'indexage temporel) car il n'y a pas de prévision à cet
+instant (l'ébauche est stockée comme pseudo-analyse au pas initial). Si les
+observations sont fournies en série par l'utilisateur, la première n'est donc
+pas utilisée.
+
 Dans le cas d'opérateurs réellement non-linéaires, on peut aisément utiliser
 l':ref:`section_ref_algorithm_EnsembleKalmanFilter` ou
 l':ref:`section_ref_algorithm_UnscentedKalmanFilter`, qui sont souvent
@@ -41,6 +58,15 @@ largement plus adaptés aux comportements non-linéaires mais plus coûteux. On
 peut vérifier la linéarité des opérateurs à l'aide de
 l':ref:`section_ref_algorithm_LinearityTest`.
 
+.. index::
+    pair: Variant ; EKF
+    pair: Variant ; CEKF
+
+On fait une différence entre le filtre de Kalman étendu tenant compte de
+bornes sur les états (la variante nommée "CEKF", qui est recommandée et qui est
+utilisée par défaut), et le filtre de Kalman étendu conduit sans
+aucune contrainte (la variante nommée "EKF", qui n'est pas recommandée).
+
 .. ------------------------------------ ..
 .. include:: snippets/Header2Algo02.rst
 
@@ -61,7 +87,7 @@ l':ref:`section_ref_algorithm_LinearityTest`.
 .. ------------------------------------ ..
 .. include:: snippets/Header2Algo03AdOp.rst
 
-.. include:: snippets/BoundsWithExtremes.rst
+.. include:: snippets/BoundsWithNone.rst
 
 .. include:: snippets/ConstrainedBy.rst
 
@@ -70,25 +96,42 @@ l':ref:`section_ref_algorithm_LinearityTest`.
 StoreSupplementaryCalculations
   .. index:: single: StoreSupplementaryCalculations
 
-  Cette liste indique les noms des variables supplémentaires qui peuvent être
-  disponibles à la fin de l'algorithme. Cela implique potentiellement des
-  calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
-  aucune de ces variables n'étant calculée et stockée par défaut. Les noms
-  possibles sont dans la liste suivante : [
+  *Liste de noms*. Cette liste indique les noms des variables supplémentaires
+  qui peuvent être disponibles au cours du déroulement ou à la fin de
+  l'algorithme, si elles sont initialement demandées par l'utilisateur. Cela
+  implique potentiellement des calculs ou du stockage coûteux. La valeur par
+  défaut est une liste vide, aucune de ces variables n'étant calculée et
+  stockée par défaut sauf les variables inconditionnelles. Les noms possibles
+  sont dans la liste suivante : [
+  "Analysis",
   "APosterioriCorrelations",
   "APosterioriCovariance",
   "APosterioriStandardDeviations",
   "APosterioriVariances",
   "BMA",
   "CostFunctionJ",
+  "CostFunctionJAtCurrentOptimum",
   "CostFunctionJb",
+  "CostFunctionJbAtCurrentOptimum",
   "CostFunctionJo",
+  "CostFunctionJoAtCurrentOptimum",
+  "CurrentIterationNumber",
+  "CurrentOptimum",
   "CurrentState",
-  "Innovation",
+  "ForecastCovariance",
+  "ForecastState",
+  "IndexOfOptimum",
+  "InnovationAtCurrentAnalysis",
+  "InnovationAtCurrentState",
+  "SimulatedObservationAtCurrentAnalysis",
+  "SimulatedObservationAtCurrentOptimum",
+  "SimulatedObservationAtCurrentState",
   ].
 
   Exemple :
-  ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
+  ``{"StoreSupplementaryCalculations":["BMA", "CurrentState"]}``
+
+.. include:: snippets/Variant_EKF.rst
 
 .. ------------------------------------ ..
 .. include:: snippets/Header2Algo04.rst
@@ -98,6 +141,8 @@ StoreSupplementaryCalculations
 .. ------------------------------------ ..
 .. include:: snippets/Header2Algo05.rst
 
+.. include:: snippets/Analysis.rst
+
 .. include:: snippets/APosterioriCorrelations.rst
 
 .. include:: snippets/APosterioriCovariance.rst
@@ -110,13 +155,37 @@ 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/CurrentIterationNumber.rst
+
+.. include:: snippets/CurrentOptimum.rst
+
 .. include:: snippets/CurrentState.rst
 
-.. include:: snippets/Innovation.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
 
 .. ------------------------------------ ..
 .. include:: snippets/Header2Algo06.rst
@@ -124,3 +193,8 @@ StoreSupplementaryCalculations
 - :ref:`section_ref_algorithm_KalmanFilter`
 - :ref:`section_ref_algorithm_EnsembleKalmanFilter`
 - :ref:`section_ref_algorithm_UnscentedKalmanFilter`
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
+
+- [WikipediaEKF]_