From 3a3733c727712855775f0a686aae22e723b937bc Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Wed, 17 Feb 2021 21:57:14 +0100 Subject: [PATCH] Minor documentation improvements and parameter fix --- doc/en/ref_algorithm_3DVAR.rst | 5 ++-- doc/en/ref_algorithm_4DVAR.rst | 10 ++++--- doc/en/ref_algorithm_Blue.rst | 1 + doc/en/ref_options_AlgorithmParameters.rst | 2 +- doc/en/scripts/simple_KalmanFilter1.py | 1 + doc/en/theory.rst | 10 +++---- doc/fr/ref_algorithm_3DVAR.rst | 6 ++-- doc/fr/ref_algorithm_4DVAR.rst | 6 ++-- doc/fr/ref_algorithm_Blue.rst | 1 + doc/fr/ref_algorithm_EnsembleKalmanFilter.rst | 7 +++++ doc/fr/ref_options_AlgorithmParameters.rst | 2 +- doc/fr/scripts/simple_KalmanFilter1.py | 1 + doc/fr/theory.rst | 10 +++---- .../daAlgorithms/EnsembleKalmanFilter.py | 28 +++++++++---------- 14 files changed, 54 insertions(+), 36 deletions(-) diff --git a/doc/en/ref_algorithm_3DVAR.rst b/doc/en/ref_algorithm_3DVAR.rst index ba85aca..cca9e82 100644 --- a/doc/en/ref_algorithm_3DVAR.rst +++ b/doc/en/ref_algorithm_3DVAR.rst @@ -22,6 +22,7 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D .. index:: single: 3DVAR +.. index:: single: 3D-Var .. _section_ref_algorithm_3DVAR: Calculation algorithm "*3DVAR*" @@ -35,8 +36,8 @@ classical :math:`J` function in static data assimilation: .. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-H(\mathbf{x}))^T.\mathbf{R}^{-1}.(\mathbf{y}^o-H(\mathbf{x})) -which is usually designed as the "*3D-VAR*" function (see for example -[Talagrand97]_). +which is usually designed as the "*3D-Var*" function (see for example +[Talagrand97]_). The terms "*3D-Var*", "*3D-VAR*" and "*3DVAR*" are equivalent. .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/en/ref_algorithm_4DVAR.rst b/doc/en/ref_algorithm_4DVAR.rst index f5a0f68..f873df5 100644 --- a/doc/en/ref_algorithm_4DVAR.rst +++ b/doc/en/ref_algorithm_4DVAR.rst @@ -22,6 +22,7 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D .. index:: single: 4DVAR +.. index:: single: 4D-Var .. _section_ref_algorithm_4DVAR: Calculation algorithm "*4DVAR*" @@ -39,10 +40,11 @@ assimilation: .. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\sum_{t\in T}(\mathbf{y^o}(t)-H(\mathbf{x},t))^T.\mathbf{R}^{-1}.(\mathbf{y^o}(t)-H(\mathbf{x},t)) -which is usually designed as the "*4D-VAR*" function (see for example -[Talagrand97]_). It is well suited in cases of non-linear observation and -evolution operators, its application domain is similar to the one of Kalman -filters, specially the :ref:`section_ref_algorithm_ExtendedKalmanFilter` or the +which is usually designed as the "*4D-Var*" functional (see for example +[Talagrand97]_). The terms "*4D-Var*", "*4D-VAR*" and "*4DVAR*" are equivalent. +It is well suited in cases of non-linear observation and evolution operators, +its application domain is similar to the one of Kalman filters, specially the +:ref:`section_ref_algorithm_ExtendedKalmanFilter` or the :ref:`section_ref_algorithm_UnscentedKalmanFilter`. .. ------------------------------------ .. diff --git a/doc/en/ref_algorithm_Blue.rst b/doc/en/ref_algorithm_Blue.rst index 67fec5d..6d06688 100644 --- a/doc/en/ref_algorithm_Blue.rst +++ b/doc/en/ref_algorithm_Blue.rst @@ -45,6 +45,7 @@ In case of non-linearity, even slightly marked, it will be easily preferred the :ref:`section_ref_algorithm_3DVAR`. .. index:: single: Optimal Interpolation +.. index:: single: OI Additional remark: an algebraic simplification of the BLUE leads to the optimal interpolation method, named "*Optimal Interpolation*" or "*OI*". It is a very diff --git a/doc/en/ref_options_AlgorithmParameters.rst b/doc/en/ref_options_AlgorithmParameters.rst index f308ff6..b8bac88 100644 --- a/doc/en/ref_options_AlgorithmParameters.rst +++ b/doc/en/ref_options_AlgorithmParameters.rst @@ -54,7 +54,7 @@ description). If an option or a parameter is specified by the user for an algorithm that does not support it, the option is simply ignored (left unused) and don't stop the treatment. The meaning of the acronyms or particular names can be found in the -:ref:`genindex` or the :ref:`section_glossary`. +index or the :ref:`section_glossary`. First method : using explicit pre-filled keywords +++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/en/scripts/simple_KalmanFilter1.py b/doc/en/scripts/simple_KalmanFilter1.py index 1a2cb5a..b4fac0f 100644 --- a/doc/en/scripts/simple_KalmanFilter1.py +++ b/doc/en/scripts/simple_KalmanFilter1.py @@ -38,6 +38,7 @@ case.setObserver( Template='ValuePrinter', Variable='Analysis', ) +# case.execute() Xa = case.get("Analysis") Pa = case.get("APosterioriCovariance") diff --git a/doc/en/theory.rst b/doc/en/theory.rst index 73f08dd..66dcf35 100644 --- a/doc/en/theory.rst +++ b/doc/en/theory.rst @@ -212,7 +212,7 @@ minimize the following function :math:`J`: .. math:: J(\mathbf{x})=\frac{1}{2}(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\frac{1}{2}(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) -:math:`J` is classically designed as the "*3D-VAR*" functional in data +:math:`J` is classically designed as the "*3D-Var*" functional in data assimlation (see for example [Talagrand97]_) or as the generalized Tikhonov regularization functional in optimization (see for example [WikipediaTI]_). Since :math:`\mathbf{B}` and :math:`\mathbf{R}` covariance matrices are @@ -248,8 +248,8 @@ distributions (very little restrictive in practice) and of :math:`\mathcal{H}` linearity, that the two *variational* and *filtering* approaches give the same solution. -It is indicated here that these methods of "*3D-VAR*" and "*BLUE*" may be -extended to dynamic problems, called respectively "*4D-VAR*" and "*Kalman +It is indicated here that these methods of "*3D-Var*" and "*BLUE*" may be +extended to dynamic problems, called respectively "*4D-Var*" and "*Kalman filter*". They have to take into account the evolution operator to establish an analysis at the right time steps of the gap between observations and simulations, and to have, at every moment, the propagation of the background @@ -325,7 +325,7 @@ requires to minimize the goal function :math:`J`: .. math:: J(\mathbf{x})=\frac{1}{2}(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\frac{1}{2}(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) -which is named the "*3D-VAR*" objective function. It can be seen as a *least +which is named the "*3D-Var*" objective function. It can be seen as a *least squares minimization* extented form, obtained by adding a regularizing term using :math:`\mathbf{x}-\mathbf{x}^b`, and by weighting the differences using :math:`\mathbf{B}` and :math:`\mathbf{R}` the two covariance matrices. The @@ -367,7 +367,7 @@ The most classical instances of error measurements are recalled or specified below, indicating their identifiers in ADAO for the possible selection of a quality criterion: -- the objective function for the augmented weighted least squares error measurement (which is the basic default functional in all data assimilation algorithms, often named "*3DVAR*" objective function, and which is known for the quality criteria in ADAO as "*AugmentedWeightedLeastSquares*", "*AWLS*" or "*DA*") is: +- the objective function for the augmented weighted least squares error measurement (which is the basic default functional in all data assimilation algorithms, often named "*3D-Var*" objective function, and which is known for the quality criteria in ADAO as "*AugmentedWeightedLeastSquares*", "*AWLS*" or "*DA*") is: .. index:: single: AugmentedWeightedLeastSquares (QualityCriterion) .. index:: single: AWLS (QualityCriterion) diff --git a/doc/fr/ref_algorithm_3DVAR.rst b/doc/fr/ref_algorithm_3DVAR.rst index 4bb750e..641a25d 100644 --- a/doc/fr/ref_algorithm_3DVAR.rst +++ b/doc/fr/ref_algorithm_3DVAR.rst @@ -22,6 +22,7 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D .. index:: single: 3DVAR +.. index:: single: 3D-Var .. _section_ref_algorithm_3DVAR: Algorithme de calcul "*3DVAR*" @@ -36,8 +37,9 @@ statique: .. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-H(\mathbf{x}))^T.\mathbf{R}^{-1}.(\mathbf{y}^o-H(\mathbf{x})) -qui est usuellement désignée comme la fonctionnelle "*3D-VAR*" (voir par exemple -[Talagrand97]_). +qui est usuellement désignée comme la fonctionnelle "*3D-Var*" (voir par +exemple [Talagrand97]_). Les dénominations "*3D-Var*", "*3D-VAR*" et "*3DVAR*" +sont équivalentes. .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/fr/ref_algorithm_4DVAR.rst b/doc/fr/ref_algorithm_4DVAR.rst index 052e532..e8a3841 100644 --- a/doc/fr/ref_algorithm_4DVAR.rst +++ b/doc/fr/ref_algorithm_4DVAR.rst @@ -22,6 +22,7 @@ Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D .. index:: single: 4DVAR +.. index:: single: 4D-Var .. _section_ref_algorithm_4DVAR: Algorithme de calcul "*4DVAR*" @@ -39,8 +40,9 @@ classique en assimilation de données : .. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\sum_{t\in T}(\mathbf{y^o}(t)-H(\mathbf{x},t))^T.\mathbf{R}^{-1}.(\mathbf{y^o}(t)-H(\mathbf{x},t)) -qui est usuellement désignée comme la fonctionnelle "*4D-VAR*" (voir par exemple -[Talagrand97]_). Il est bien adapté aux cas d'opérateurs d'observation et +qui est usuellement désignée comme la fonctionnelle "*4D-Var*" (voir par +exemple [Talagrand97]_). Les dénominations "*4D-Var*", "*4D-VAR*" et "*4DVAR*" +sont équivalentes. Il est bien adapté aux cas d'opérateurs d'observation et d'évolution non-linéaires, son domaine d'application est comparable aux algorithmes de filtrage de Kalman et en particulier l':ref:`section_ref_algorithm_ExtendedKalmanFilter` ou diff --git a/doc/fr/ref_algorithm_Blue.rst b/doc/fr/ref_algorithm_Blue.rst index d4f2842..b9fd910 100644 --- a/doc/fr/ref_algorithm_Blue.rst +++ b/doc/fr/ref_algorithm_Blue.rst @@ -45,6 +45,7 @@ l':ref:`section_ref_algorithm_ExtendedBlue` ou l':ref:`section_ref_algorithm_3DVAR`. .. index:: single: Optimal Interpolation +.. index:: single: OI Remarque complémentaire : une simplification algébrique du BLUE conduit à la méthode d'interpolation optimale, nommée "*Optimal Interpolation*" ou "*OI*". diff --git a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst index d140719..ba788a5 100644 --- a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst +++ b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst @@ -53,6 +53,13 @@ l':ref:`section_ref_algorithm_KalmanFilter`, qui sont souvent largement moins coûteux en évaluations sur de petits systèmes. On peut vérifier la linéarité des opérateurs à l'aide de l':ref:`section_ref_algorithm_LinearityTest`. +Les variantes de cette algorithme sont nombreuses, et on propose ici les versions stables et robustes suivantes : +- "EnKF" (Ensemble Kalman Filter), algorithme stochastique, permettant de traiter de manière consistante un opérateur d'évolution non-linéaire, +- "ETKF" (Ensemble-Transform Kalman Filter), algorithme déterministe d'EnKF, permettant de traiter un opérateur d'évolution non-linéaire avec beaucoup moins de membres, +- "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), algorithme d'ETKF dit de "taille finie N", évitant de recourir l'inflation +- "MLEF" (Maximum Likelihood Kalman Filter), schéma déterministe d'EnKF permettant en plus de traiter de manière consistante un opérateur d'observation non-linéaire), +- "IEnKF" (Iterative_EnKF), + .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/fr/ref_options_AlgorithmParameters.rst b/doc/fr/ref_options_AlgorithmParameters.rst index 28918a7..cd10253 100644 --- a/doc/fr/ref_options_AlgorithmParameters.rst +++ b/doc/fr/ref_options_AlgorithmParameters.rst @@ -56,7 +56,7 @@ partie :ref:`section_tui` pour une description détaillée). Si une option ou un paramètre est spécifié par l'utilisateur pour un algorithme qui ne la supporte pas, cette option est simplement ignorée (laissée inutilisée) et ne bloque pas le traitement. La signification des acronymes ou -des noms particuliers peut être trouvée dans l':ref:`genindex` ou dans le +des noms particuliers peut être trouvée dans l'index ou dans le :ref:`section_glossary`. Première méthode : utiliser les mots-clés explicites pré-remplis diff --git a/doc/fr/scripts/simple_KalmanFilter1.py b/doc/fr/scripts/simple_KalmanFilter1.py index adf3107..afa3924 100644 --- a/doc/fr/scripts/simple_KalmanFilter1.py +++ b/doc/fr/scripts/simple_KalmanFilter1.py @@ -38,6 +38,7 @@ case.setObserver( Template='ValuePrinter', Variable='Analysis', ) +# case.execute() Xa = case.get("Analysis") Pa = case.get("APosterioriCovariance") diff --git a/doc/fr/theory.rst b/doc/fr/theory.rst index 77da7fa..1e87e59 100644 --- a/doc/fr/theory.rst +++ b/doc/fr/theory.rst @@ -223,7 +223,7 @@ classiquement à minimiser la fonction :math:`J` suivante : .. math:: J(\mathbf{x})=\frac{1}{2}(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\frac{1}{2}(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) -:math:`J` est classiquement désignée comme la fonctionnelle "*3D-VAR*" en +:math:`J` est classiquement désignée comme la fonctionnelle "*3D-Var*" en assimilation de données (voir par exemple [Talagrand97]_) ou comme la fonctionnelle de régularisation de Tikhonov généralisée en optimisation (voir par exemple [WikipediaTI]_). Comme les matrices de covariance :math:`\mathbf{B}` @@ -260,8 +260,8 @@ distributions gaussiennes d'erreurs (très peu restrictive en pratique) et de linéarité de :math:`\mathcal{H}`, que les deux approches *variationnelle* et *de filtrage* donnent la même solution. -On indique que ces méthodes de "*3D-VAR*" et de "*BLUE*" peuvent être étendues -à des problèmes dynamiques, sous les noms respectifs de "*4D-VAR*" et de +On indique que ces méthodes de "*3D-Var*" et de "*BLUE*" peuvent être étendues +à des problèmes dynamiques, sous les noms respectifs de "*4D-Var*" et de "*filtre de Kalman*". Elles doivent alors prendre en compte l'opérateur d'évolution pour établir aux bons pas de temps une analyse de l'écart entre les observations et les simulations et pour avoir, à chaque instant, la propagation @@ -345,7 +345,7 @@ variationnelle de données nécessite de minimiser la fonction objectif :math:`J .. math:: J(\mathbf{x})=\frac{1}{2}(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\frac{1}{2}(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) -qui est dénommée la fonctionnelle du "*3D-VAR*". Elle peut être vue comme la +qui est dénommée la fonctionnelle du "*3D-Var*". Elle peut être vue comme la forme étendue d'une *minimisation moindres carrés*, obtenue en ajoutant un terme de régularisation utilisant :math:`\mathbf{x}-\mathbf{x}^b`, et en pondérant les différences par les deux matrices de covariances :math:`\mathbf{B}` et @@ -393,7 +393,7 @@ réduire**. Par exemple, on peut citer une *erreur en valeur absolue*, une classiques de mesures d'erreurs, en indiquant leur identifiant dans ADAO pour la sélection éventuelle d'un critère de qualité : -- la fonction objectif pour la mesure d'erreur par moindres carrés pondérés et augmentés (qui est la fonctionnelle de base par défaut de tous les algorithmes en assimilation de données, souvent nommée la fonctionnelle du "*3D-VAR*", et qui est connue pour les critères de qualité dans ADAO sous les noms de "*AugmentedWeightedLeastSquares*", "*AWLS*" ou "*DA*") est : +- la fonction objectif pour la mesure d'erreur par moindres carrés pondérés et augmentés (qui est la fonctionnelle de base par défaut de tous les algorithmes en assimilation de données, souvent nommée la fonctionnelle du "*3D-Var*", et qui est connue pour les critères de qualité dans ADAO sous les noms de "*AugmentedWeightedLeastSquares*", "*AWLS*" ou "*DA*") est : .. index:: single: AugmentedWeightedLeastSquares (QualityCriterion) .. index:: single: AWLS (QualityCriterion) diff --git a/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py b/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py index b475c71..2b8f69d 100644 --- a/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py +++ b/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py @@ -29,8 +29,8 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): def __init__(self): BasicObjects.Algorithm.__init__(self, "ENSEMBLEKALMANFILTER") self.defineRequiredParameter( - name = "Minimizer", - default = "StochasticEnKF", + name = "Variant", + default = "EnKF", typecast = str, message = "Minimiseur utilisé", listval = [ @@ -175,50 +175,50 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): # #-------------------------- # Default EnKF = EnKF-16 = StochasticEnKF - if self._parameters["Minimizer"] in ["EnKF-05"]: + if self._parameters["Variant"] in ["EnKF-05"]: NumericObjects.senkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="KalmanFilterFormula05") # - elif self._parameters["Minimizer"] in ["EnKF-16", "StochasticEnKF", "EnKF"]: + elif self._parameters["Variant"] in ["EnKF-16", "StochasticEnKF", "EnKF"]: NumericObjects.senkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="KalmanFilterFormula16") # #-------------------------- # Default ETKF = ETKF-KFF - elif self._parameters["Minimizer"] in ["ETKF-KFF", "ETKF"]: + elif self._parameters["Variant"] in ["ETKF-KFF", "ETKF"]: NumericObjects.etkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="KalmanFilterFormula") # - elif self._parameters["Minimizer"] == "ETKF-VAR": + elif self._parameters["Variant"] == "ETKF-VAR": NumericObjects.etkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="Variational") # #-------------------------- # Default ETKF-N = ETKF-N-16 - elif self._parameters["Minimizer"] == "ETKF-N-11": + elif self._parameters["Variant"] == "ETKF-N-11": NumericObjects.etkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="FiniteSize11") # - elif self._parameters["Minimizer"] == "ETKF-N-15": + elif self._parameters["Variant"] == "ETKF-N-15": NumericObjects.etkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="FiniteSize15") # - elif self._parameters["Minimizer"] in ["ETKF-N-16", "ETKF-N"]: + elif self._parameters["Variant"] in ["ETKF-N-16", "ETKF-N"]: NumericObjects.etkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, VariantM="FiniteSize16") # #-------------------------- # Default MLEF = MLEF-T - elif self._parameters["Minimizer"] in ["MLEF-T", "MLEF"]: + elif self._parameters["Variant"] in ["MLEF-T", "MLEF"]: NumericObjects.mlef(self, Xb, Y, U, HO, EM, CM, R, B, Q, BnotT=False) # - elif self._parameters["Minimizer"] == "MLEF-B": + elif self._parameters["Variant"] == "MLEF-B": NumericObjects.mlef(self, Xb, Y, U, HO, EM, CM, R, B, Q, BnotT=True) # #-------------------------- # Default IEnKF = IEnKF-T - elif self._parameters["Minimizer"] in ["IEnKF-T", "IEnKF"]: + elif self._parameters["Variant"] in ["IEnKF-T", "IEnKF"]: NumericObjects.ienkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, BnotT=False) # - elif self._parameters["Minimizer"] in ["IEnKF-B", "IEKF"]: + elif self._parameters["Variant"] in ["IEnKF-B", "IEKF"]: NumericObjects.ienkf(self, Xb, Y, U, HO, EM, CM, R, B, Q, BnotT=True) # #-------------------------- else: - raise ValueError("Error in Minimizer name: %s"%self._parameters["Minimizer"]) + raise ValueError("Error in Variant name: %s"%self._parameters["Minimizer"]) # self._post_run(HO) return 0 -- 2.39.2