..
- Copyright (C) 2008-2016 EDF R&D
+ Copyright (C) 2008-2023 EDF R&D
This file is part of SALOME ADAO module.
Algorithme de calcul "*UnscentedKalmanFilter*"
----------------------------------------------
-Description
-+++++++++++
-
-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 projete
- 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
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. ------------------------------------ ..
+.. 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.
+
+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]_
