..
- Copyright (C) 2008-2018 EDF R&D
+ Copyright (C) 2008-2023 EDF R&D
This file is part of SALOME ADAO module.
Algorithme de calcul "*UnscentedKalmanFilter*"
----------------------------------------------
-Description
-+++++++++++
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo01.rst
Cet algorithme réalise une estimation de l'état d'un système dynamique par un
filtre de Kalman "unscented", permettant d'éviter de devoir calculer les
opérateurs tangent ou adjoint pour les opérateurs d'observation ou d'évolution,
comme dans les filtres de Kalman simple ou étendu.
-Commandes requises et optionnelles
-++++++++++++++++++++++++++++++++++
-
-.. index:: single: AlgorithmParameters
-.. index:: single: Background
-.. index:: single: BackgroundError
-.. index:: single: Observation
-.. index:: single: ObservationError
-.. index:: single: ObservationOperator
-.. index:: single: Bounds
-.. index:: single: ConstrainedBy
-.. index:: single: EstimationOf
-.. index:: single: Alpha
-.. index:: single: Beta
-.. index:: single: Kappa
-.. index:: single: Reconditioner
-.. index:: single: StoreSupplementaryCalculations
-
-Les commandes requises générales, disponibles dans l'interface en édition, sont
-les suivantes:
-
- Background
- *Commande obligatoire*. Elle définit le vecteur d'ébauche ou
- d'initialisation, noté précédemment :math:`\mathbf{x}^b`. Sa valeur est
- définie comme un objet de type "*Vector*" ou de type "*VectorSerie*".
-
- BackgroundError
- *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
- d'ébauche, notée précédemment :math:`\mathbf{B}`. Sa valeur est définie
- comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
- type "*DiagonalSparseMatrix*".
-
- Observation
- *Commande obligatoire*. Elle définit le vecteur d'observation utilisé en
- assimilation de données ou en optimisation, et noté précédemment
- :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type "*Vector*"
- ou de type "*VectorSerie*".
-
- ObservationError
- *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
- d'ébauche, notée précédemment :math:`\mathbf{R}`. Sa valeur est définie
- comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
- type "*DiagonalSparseMatrix*".
-
- ObservationOperator
- *Commande obligatoire*. Elle indique l'opérateur d'observation, noté
- précédemment :math:`H`, qui transforme les paramètres d'entrée
- :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
- observations :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de
- type "*Function*" ou de type "*Matrix*". Dans le cas du type "*Function*",
- différentes formes fonctionnelles peuvent être utilisées, comme décrit dans
- la section :ref:`section_ref_operator_requirements`. Si un contrôle
- :math:`U` est inclus dans le modèle d'observation, l'opérateur doit être
- appliqué à une paire :math:`(X,U)`.
-
-Les commandes optionnelles générales, disponibles dans l'interface en édition,
-sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les
-paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les
-options particulières, décrites ci-après, de l'algorithme. On se reportera à la
-:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
-commande.
-
-Les options de l'algorithme sont les suivantes:
-
- Bounds
- Cette clé permet de définir des bornes supérieure et inférieure pour chaque
- variable d'état optimisée. Les bornes doivent être données par une liste de
- liste de paires de bornes inférieure/supérieure pour chaque variable, avec
- une valeur extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas
- une valeur autorisée lorsqu'il n'y a pas de borne).
-
- Exemple : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,1.e99],[-1.e99,1.e99]]}``
-
- ConstrainedBy
- Cette clé permet d'indiquer la méthode de prise en compte des contraintes de
- bornes. La seule disponible est "EstimateProjection", qui projette
- l'estimation de l'état courant sur les contraintes de bornes.
-
- Exemple : ``{"ConstrainedBy":"EstimateProjection"}``
-
- EstimationOf
- Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
- soit une estimation de l'état, avec la valeur "State", ou une estimation de
- paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
-
- Exemple : ``{"EstimationOf":"Parameters"}``
-
- Alpha, Beta, Kappa, Reconditioner
- Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert
- une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour
- une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière,
- dont la bonne valeur par défaut est obtenue en la mettant à 0.
- "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut
- étant 1.
-
- Exemple : ``{"Alpha":1,"Beta":2,"Kappa":0,"Reconditioner":1}``
-
- 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 : ["APosterioriCorrelations",
- "APosterioriCovariance", "APosterioriStandardDeviations",
- "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb",
- "CostFunctionJo", "CurrentState", "Innovation"].
-
- Exemple : ``{"StoreSupplementaryCalculations":["BMA", "Innovation"]}``
-
-Informations et variables disponibles à la fin de l'algorithme
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Il s'applique aux cas d'opérateurs d'observation et d'évolution incrémentale
+(processus) non-linéaires et présente d'excellentes qualités de robustesse et
+de performances. Il peut être rapproché de
+l':ref:`section_ref_algorithm_EnsembleKalmanFilter`, dont les qualités sont
+similaires pour les systèmes non-linéaires.
-En sortie, après exécution de l'algorithme, on dispose d'informations et de
-variables issues du calcul. La description des
-:ref:`section_ref_output_variables` indique la manière de les obtenir par la
-méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables
-d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter
-l'écriture des procédures de post-processing, sont décrites dans
-l':ref:`subsection_r_o_v_Inventaire`.
+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.
-Les sorties non conditionnelles de l'algorithme sont les suivantes:
+Dans le cas d'opérateurs linéaires ou "faiblement" non-linéaire, on peut
+aisément utiliser l':ref:`section_ref_algorithm_ExtendedKalmanFilter` ou même
+l':ref:`section_ref_algorithm_KalmanFilter`, qui sont souvent largement moins
+coûteux en évaluation sur de petits systèmes. On peut vérifier la linéarité des
+opérateurs à l'aide de l':ref:`section_ref_algorithm_LinearityTest`.
- Analysis
- *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*`
- en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de
- données.
+.. index::
+ pair: Variant ; UKF
+ pair: Variant ; 2UKF
- Exemple : ``Xa = ADD.get("Analysis")[-1]``
+On fait une différence entre le filtre de Kalman "unscented" tenant compte de
+bornes sur les états (la variante nommée "2UKF", qui est recommandée et qui est
+utilisée par défaut), et le filtre de Kalman "unscented" canonique conduit sans
+aucune contrainte (la variante nommée "UKF", qui n'est pas recommandée).
-Les sorties conditionnelles de l'algorithme sont les suivantes:
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo02.rst
- APosterioriCorrelations
- *Liste de matrices*. Chaque élément est une matrice de corrélation des
- erreurs *a posteriori* de l'état optimal.
+.. include:: snippets/Background.rst
- Exemple : ``C = ADD.get("APosterioriCorrelations")[-1]``
+.. include:: snippets/BackgroundError.rst
- APosterioriCovariance
- *Liste de matrices*. Chaque élément est une matrice :math:`\mathbf{A}*` de
- covariances des erreurs *a posteriori* de l'état optimal.
+.. include:: snippets/EvolutionError.rst
- Exemple : ``A = ADD.get("APosterioriCovariance")[-1]``
+.. include:: snippets/EvolutionModel.rst
- APosterioriStandardDeviations
- *Liste de matrices*. Chaque élément est une matrice d'écart-types des
- erreurs *a posteriori* de l'état optimal.
+.. include:: snippets/Observation.rst
- Exemple : ``E = ADD.get("APosterioriStandardDeviations")[-1]``
+.. include:: snippets/ObservationError.rst
- APosterioriVariances
- *Liste de matrices*. Chaque élément est une matrice de variances des erreurs
- *a posteriori* de l'état optimal.
+.. include:: snippets/ObservationOperator.rst
- Exemple : ``V = ADD.get("APosterioriVariances")[-1]``
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo03AdOp.rst
- BMA
- *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre
- l'ébauche et l'état optimal.
+.. include:: snippets/BoundsWithNone.rst
- Exemple : ``bma = ADD.get("BMA")[-1]``
+.. include:: snippets/ConstrainedBy.rst
- CostFunctionJ
- *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
- :math:`J`.
+.. include:: snippets/EstimationOf_State.rst
- Exemple : ``J = ADD.get("CostFunctionJ")[:]``
+.. include:: snippets/AlphaBeta.rst
- CostFunctionJb
- *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
- :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche.
+StoreSupplementaryCalculations
+ .. index:: single: StoreSupplementaryCalculations
- Exemple : ``Jb = ADD.get("CostFunctionJb")[:]``
+ *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. Leur
+ disponibilité implique, potentiellement, des calculs ou du stockage coûteux.
+ La valeur par défaut est donc une liste vide, aucune de ces variables n'étant
+ calculée et stockée par défaut (sauf les variables inconditionnelles). Les
+ noms possibles pour les variables supplémentaires sont dans la liste suivante
+ (la description détaillée de chaque variable nommée est donnée dans la suite
+ de cette documentation par algorithme spécifique, dans la sous-partie
+ "*Informations et variables disponibles à la fin de l'algorithme*") : [
+ "Analysis",
+ "APosterioriCorrelations",
+ "APosterioriCovariance",
+ "APosterioriStandardDeviations",
+ "APosterioriVariances",
+ "BMA",
+ "CostFunctionJ",
+ "CostFunctionJAtCurrentOptimum",
+ "CostFunctionJb",
+ "CostFunctionJbAtCurrentOptimum",
+ "CostFunctionJo",
+ "CostFunctionJoAtCurrentOptimum",
+ "CurrentOptimum",
+ "CurrentState",
+ "ForecastCovariance",
+ "ForecastState",
+ "IndexOfOptimum",
+ "InnovationAtCurrentAnalysis",
+ "InnovationAtCurrentState",
+ "SimulatedObservationAtCurrentAnalysis",
+ "SimulatedObservationAtCurrentOptimum",
+ "SimulatedObservationAtCurrentState",
+ ].
- CostFunctionJo
- *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart
- :math:`J^o`, c'est-à-dire de la partie écart à l'observation.
+ Exemple :
+ ``{"StoreSupplementaryCalculations":["CurrentState", "Residu"]}``
- Exemple : ``Jo = ADD.get("CostFunctionJo")[:]``
+.. include:: snippets/Variant_UKF.rst
- CurrentState
- *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé
- au cours du déroulement de l'algorithme d'optimisation.
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo04.rst
- Exemple : ``Xs = ADD.get("CurrentState")[:]``
+.. include:: snippets/Analysis.rst
- Innovation
- *Liste de vecteurs*. Chaque élément est un vecteur d'innovation, qui est
- en statique l'écart de l'optimum à l'ébauche, et en dynamique l'incrément
- d'évolution.
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo05.rst
- Exemple : ``d = ADD.get("Innovation")[-1]``
+.. include:: snippets/Analysis.rst
-Voir aussi
-++++++++++
+.. include:: snippets/APosterioriCorrelations.rst
-Références vers d'autres sections :
- - :ref:`section_ref_algorithm_KalmanFilter`
- - :ref:`section_ref_algorithm_ExtendedKalmanFilter`
+.. include:: snippets/APosterioriCovariance.rst
-Références bibliographiques :
- - [WikipediaUKF]_
+.. include:: snippets/APosterioriStandardDeviations.rst
+
+.. include:: snippets/APosterioriVariances.rst
+
+.. include:: snippets/BMA.rst
+
+.. 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/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_UnscentedKalmanFilter_examples:
+
+.. include:: snippets/Header2Algo06.rst
+
+- :ref:`section_ref_algorithm_KalmanFilter`
+- :ref:`section_ref_algorithm_ExtendedKalmanFilter`
+- :ref:`section_ref_algorithm_EnsembleKalmanFilter`
+
+.. ------------------------------------ ..
+.. include:: snippets/Header2Algo07.rst
+
+- [WikipediaUKF]_
