From 574ecc3975a4b1231b6c93d78e98e65f16621a1b Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Wed, 24 Feb 2021 20:19:34 +0100 Subject: [PATCH] Minor documentation improvements --- doc/en/bibliography.rst | 13 ++++++++++--- doc/en/index.rst | 4 ++-- doc/en/ref_algorithm_3DVAR.rst | 15 +++++++++++++++ doc/en/ref_algorithm_EnsembleKalmanFilter.rst | 14 +++++++++++--- doc/en/snippets/Variant_3DVAR.rst | 8 ++++---- doc/fr/bibliography.rst | 12 +++++++++--- doc/fr/index.rst | 4 ++-- doc/fr/ref_algorithm_3DVAR.rst | 15 +++++++++++++++ doc/fr/ref_algorithm_EnsembleKalmanFilter.rst | 14 +++++++++++--- doc/fr/snippets/Variant_3DVAR.rst | 8 ++++---- 10 files changed, 83 insertions(+), 24 deletions(-) diff --git a/doc/en/bibliography.rst b/doc/en/bibliography.rst index f57c677..9f56615 100644 --- a/doc/en/bibliography.rst +++ b/doc/en/bibliography.rst @@ -31,12 +31,12 @@ Bibliography .. [Asch16] Asch M., Bocquet M., Nodet M., *Data Assimilation - Methods, Algorithms and Applications*, SIAM, 2016 -.. [GilBellosta15] Gil Bellosta C. J., *rPython: Package Allowing R to Call Python*, CRAN, 2015, https://cran.r-project.org/web/packages/rPython/ and http://rpython.r-forge.r-project.org/ - -.. [Bouttier99] Bouttier B., Courtier P., *Data assimilation concepts and methods*, Meteorological Training Course Lecture Series, ECMWF, 1999 +.. [Bishop01] Bishop C. H., Etherton B. J., Majumdar S. J., *Adaptive sampling with the ensemble transform Kalman filter. Part I: theoretical aspects*, Monthly Weather Review, 129, pp.420–436, 2001 .. [Bocquet04] Bocquet M., *Introduction aux principes et méthodes de l'assimilation de données en géophysique*, Lecture Notes, 2014 +.. [Bouttier99] Bouttier B., Courtier P., *Data assimilation concepts and methods*, Meteorological Training Course Lecture Series, ECMWF, 1999 + .. [Buchinsky98] Buchinsky M., *Recent Advances in Quantile Regression Models: A Practical Guidline for Empirical Research*, Journal of Human Resources, 33(1), pp.88-126, 1998 .. [Burgers98] Burgers G., Van Leuween P. J., Evensen G., *Analysis scheme in the Ensemble Kalman Filter*, Monthly Weather Review, 126, 1719–1724, 1998 @@ -51,6 +51,8 @@ Bibliography .. [Courtier94] Courtier P., Thépaut J.-N., Hollingsworth A., *A strategy for operational implementation of 4D-Var, using an incremental approach*, Quarterly Journal of the Royal Meteorological Society, 120, pp.1367–1387, 1994 +.. [Courtier97] Courtier P., *Dual formulation of four-dimensional variational assimilation*, Quarterly Journal of the Royal Meteorological Society, 123, pp.2449-2461, 1997 + .. [Das11] Das S., Suganthan P. N., *Differential Evolution: A Survey of the State-of-the-art*, IEEE Transactions on Evolutionary Computation, 15(1), pp.4-31, 2011 .. [Das16] Das S., Mullick S. S., Suganthan P. N., *Recent Advances in Differential Evolution - An Updated Survey*, Swarm and Evolutionary Computation, 27, pp.1-30, 2016 @@ -59,6 +61,8 @@ Bibliography .. [Evensen03] Evensen G., *The Ensemble Kalman Filter: theoretical formulation and practical implementation*, Seminar on Recent developments in data assimilation for atmosphere and ocean, ECMWF, 8 to 12 September 2003 +.. [GilBellosta15] Gil Bellosta C. J., *rPython: Package Allowing R to Call Python*, CRAN, 2015, https://cran.r-project.org/web/packages/rPython/ and http://rpython.r-forge.r-project.org/ + .. [Glover89] Glover F., *Tabu Search-Part I*, ORSA Journal on Computing, 1(2), pp.190-206, 1989 .. [Glover90] Glover F., *Tabu Search-Part II*, ORSA Journal on Computing, 2(1), pp.4-32, 1990 @@ -140,3 +144,6 @@ Bibliography .. [WikipediaUKF] Wikipedia, *Unscented Kalman Filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter .. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997 + +.. [Zupanski05] Zupanski M., *Maximum likelihood ensemble filter: Theoretical aspects*, Monthly Weather Review, 133, pp.1710–1726, 2005 + diff --git a/doc/en/index.rst b/doc/en/index.rst index 5ee146d..751e888 100644 --- a/doc/en/index.rst +++ b/doc/en/index.rst @@ -82,9 +82,9 @@ part :ref:`section_license`. tui reference license + bibliography + notations glossary genindex - notations - bibliography * :ref:`search` diff --git a/doc/en/ref_algorithm_3DVAR.rst b/doc/en/ref_algorithm_3DVAR.rst index de5b597..ff875c2 100644 --- a/doc/en/ref_algorithm_3DVAR.rst +++ b/doc/en/ref_algorithm_3DVAR.rst @@ -39,6 +39,21 @@ classical :math:`J` function in static data assimilation: which is usually designed as the "*3D-Var*" function (see for example [Talagrand97]_). The terms "*3D-Var*", "*3D-VAR*" and "*3DVAR*" are equivalent. +There exists various variants of this algorithm. The following stable and robust formulations are proposed here: + +.. index:: + pair: Variant ; 3DVAR + pair: Variant ; 3DVAR-VAN + pair: Variant ; 3DVAR-Incr + pair: Variant ; 3DVAR-PSAS + +- "3DVAR" (3D Variational analysis, see [Lorenc86]_, [LeDimet86]_, [Talagrand97]_), original and very robust algorithm, +- "3DVAR-VAN" (3D Variational Analysis with No inversion of B, see [Lorenc88]_), similar algorithm but avoiding inversion of the covariance matrix B, +- "3DVAR-Incr" (Incremental 3DVAR, see [Courtier94]_), cheaper algorithm but involving an approximation of non-linear operators, +- "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR, see [Courtier97]_, [Cohn98]_), algorithm sometimes more cheap because it operates in another space, but involving an approximation of non-linear operators. + +It is recommended to use the original 3DVAR. + .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/en/ref_algorithm_EnsembleKalmanFilter.rst b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst index d09c850..55e9820 100644 --- a/doc/en/ref_algorithm_EnsembleKalmanFilter.rst +++ b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst @@ -52,12 +52,19 @@ In case of linear of "slightly" non-linear operators, one can easily use the to evaluate on small systems. One can verify the linearity of the operators with the help of the :ref:`section_ref_algorithm_LinearityTest`. -There exists a lot of variants of this algorithm. Stable and robust ones are proposed here: +There exists a lot of variants of this algorithm. The following stable and robust formulations are proposed here: -- "EnKF" (Ensemble Kalman Filter), original stochastic algorithm, allowing consistent treatment of non-linear evolution operator, +.. index:: + pair: Variant ; EnKF + pair: Variant ; ETKF + pair: Variant ; ETKF-N + pair: Variant ; MLEF + pair: Variant ; IEnKF + +- "EnKF" (Ensemble Kalman Filter, see [Evensen94]_), original stochastic algorithm, allowing consistent treatment of non-linear evolution operator, - "ETKF" (Ensemble-Transform Kalman Filter), deterministic EnKF algorithm, allowing treatment of non-linear evolution operator with a lot less members (one recommends to use a number of members on the order of 10 or even sometimes less), - "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), ETKF algorithm of "finite size N", yhat doesn't need inflation that is often required with the other algorithms, -- "MLEF" (Maximum Likelihood Kalman Filter), deterministic EnKF scheme, allowing in addition the consistent treament of non-linear observation operator, +- "MLEF" (Maximum Likelihood Kalman Filter, see [Zupanski05]_), deterministic EnKF scheme, allowing in addition the consistent treament of non-linear observation operator, - "IEnKF" (Iterative_EnKF), deterministic EnKF scheme, improving treament of operators non-linearities. Without being a universal recommandation, one recommend to use EnKF as a reference algorithm, and the other algorithms (in this order) as means to obtain less costly data assimilation with hopefully the same quality. @@ -191,4 +198,5 @@ StoreSupplementaryCalculations - [Evensen94]_ - [Burgers98]_ - [Evensen03]_ +- [Zupanski05]_ - [WikipediaEnKF]_ diff --git a/doc/en/snippets/Variant_3DVAR.rst b/doc/en/snippets/Variant_3DVAR.rst index f23494e..55ae94d 100644 --- a/doc/en/snippets/Variant_3DVAR.rst +++ b/doc/en/snippets/Variant_3DVAR.rst @@ -9,10 +9,10 @@ Variant *Predifined name*. This key allows to choose one of the possible variants for the main algorithm. The default variant is the original "3DVAR", and the possible ones are - "3DVAR" (3D Variational analysis, see [Lorenc86]_, [LeDimet86]_, [Talagrand97]_), - "3DVAR-VAN" (3D Variational Analysis with No inversion of B, see [Lorenc88]_), - "3DVAR-Incr" (Incremental 3DVAR, see [Courtier94]_), - "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR, see [Cohn98]_), + "3DVAR" (3D Variational analysis), + "3DVAR-VAN" (3D Variational Analysis with No inversion of B), + "3DVAR-Incr" (Incremental 3DVAR), + "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR), It is highly recommended to keep the default value. Exemple : diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index a73cae8..315e6b4 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -31,12 +31,12 @@ Bibliographie .. [Asch16] Asch M., Bocquet M., Nodet M., *Data Assimilation - Methods, Algorithms and Applications*, SIAM, 2016 -.. [GilBellosta15] Gil Bellosta C. J., *rPython: Package Allowing R to Call Python*, CRAN, 2015, https://cran.r-project.org/web/packages/rPython/ and http://rpython.r-forge.r-project.org/ - -.. [Bouttier99] Bouttier B., Courtier P., *Data assimilation concepts and methods*, Meteorological Training Course Lecture Series, ECMWF, 1999 +.. [Bishop01] Bishop C. H., Etherton B. J., Majumdar S. J., *Adaptive sampling with the ensemble transform Kalman filter. Part I: theoretical aspects*, Monthly Weather Review, 129, pp.420–436, 2001 .. [Bocquet04] Bocquet M., *Introduction aux principes et méthodes de l'assimilation de données en géophysique*, Lecture Notes, 2014 +.. [Bouttier99] Bouttier B., Courtier P., *Data assimilation concepts and methods*, Meteorological Training Course Lecture Series, ECMWF, 1999 + .. [Buchinsky98] Buchinsky M., *Recent Advances in Quantile Regression Models: A Practical Guidline for Empirical Research*, Journal of Human Resources, 33(1), pp.88-126, 1998 .. [Burgers98] Burgers G., Van Leuween P. J., Evensen G., *Analysis scheme in the Ensemble Kalman Filter*, Monthly Weather Review, 126, 1719–1724, 1998 @@ -51,6 +51,8 @@ Bibliographie .. [Courtier94] Courtier P., Thépaut J.-N., Hollingsworth A., *A strategy for operational implementation of 4D-Var, using an incremental approach*, Quarterly Journal of the Royal Meteorological Society, 120, pp.1367–1387, 1994 +.. [Courtier97] Courtier P., *Dual formulation of four-dimensional variational assimilation*, Quarterly Journal of the Royal Meteorological Society, 123, pp.2449-2461, 1997 + .. [Das11] Das S., Suganthan P. N., *Differential Evolution: A Survey of the State-of-the-art*, IEEE Transactions on Evolutionary Computation, 15(1), pp.4-31, 2011 .. [Das16] Das S., Mullick S. S., Suganthan P. N., *Recent Advances in Differential Evolution - An Updated Survey*, Swarm and Evolutionary Computation, 27, pp.1-30, 2016 @@ -59,6 +61,8 @@ Bibliographie .. [Evensen03] Evensen G., *The Ensemble Kalman Filter: theoretical formulation and practical implementation*, Seminar on Recent developments in data assimilation for atmosphere and ocean, ECMWF, 8 to 12 September 2003 +.. [GilBellosta15] Gil Bellosta C. J., *rPython: Package Allowing R to Call Python*, CRAN, 2015, https://cran.r-project.org/web/packages/rPython/ and http://rpython.r-forge.r-project.org/ + .. [Glover89] Glover F., *Tabu Search-Part I*, ORSA Journal on Computing, 1(2), pp.190-206, 1989 .. [Glover90] Glover F., *Tabu Search-Part II*, ORSA Journal on Computing, 2(1), pp.4-32, 1990 @@ -141,6 +145,8 @@ Bibliographie .. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997 +.. [Zupanski05] Zupanski M., *Maximum likelihood ensemble filter: Theoretical aspects*, Monthly Weather Review, 133, pp.1710–1726, 2005 + *Nota Bene* : un lien vers la version française de chaque page Wikipédia se trouve dans le sous-menu "*Languages*". Les deux versions sont complémentaires car, même si souvent le contenu en anglais est plus fourni, les informations diff --git a/doc/fr/index.rst b/doc/fr/index.rst index dcf362d..276d241 100644 --- a/doc/fr/index.rst +++ b/doc/fr/index.rst @@ -86,9 +86,9 @@ pas de lire la partie :ref:`section_license`. tui reference license + bibliography + notations glossary genindex - notations - bibliography * :ref:`search` diff --git a/doc/fr/ref_algorithm_3DVAR.rst b/doc/fr/ref_algorithm_3DVAR.rst index 2bb864e..6fadb6f 100644 --- a/doc/fr/ref_algorithm_3DVAR.rst +++ b/doc/fr/ref_algorithm_3DVAR.rst @@ -41,6 +41,21 @@ 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. +Il existe diverses variantes de cet algorithme. On propose ici des formulations stables et robustes suivantes : + +.. index:: + pair: Variant ; 3DVAR + pair: Variant ; 3DVAR-VAN + pair: Variant ; 3DVAR-Incr + pair: Variant ; 3DVAR-PSAS + +- "3DVAR" (3D Variational analysis, voir [Lorenc86]_, [LeDimet86]_, [Talagrand97]_), algorithme d'origine et très robuste, +- "3DVAR-VAN" (3D Variational Analysis with No inversion of B, voir [Lorenc88]_), algorithme similaire mais permettant d'éviter l'inversion de la matrice de covariance B, +- "3DVAR-Incr" (Incremental 3DVAR, voir [Courtier94]_), algorithme plus économique mais impliquant une approximation des opérateurs non-linéaires, +- "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR, voir [Courtier97]_, [Cohn98]_), algorithme parfois plus économique car opérant dans un autre espace, mais impliquant une approximation des opérateurs non-linéaires. + +On recommande d'utiliser le 3DVAR d'origine. + .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst index ab48488..1c30849 100644 --- a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst +++ b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst @@ -53,12 +53,19 @@ 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`. -Il existe de nombreuses variantes de cet algorithme. On propose ici des formes stables et robustes suivantes : +Il existe de nombreuses variantes de cet algorithme. On propose ici des formulations stables et robustes suivantes : -- "EnKF" (Ensemble Kalman Filter), algorithme stochastique original, permettant de traiter de manière consistante un opérateur d'évolution non-linéaire, +.. index:: + pair: Variant ; EnKF + pair: Variant ; ETKF + pair: Variant ; ETKF-N + pair: Variant ; MLEF + pair: Variant ; IEnKF + +- "EnKF" (Ensemble Kalman Filter, voir [Evensen94]_), algorithme stochastique original, 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 (on recommande d'utiliser un nombre de membres de l'ordre de 10 ou même parfois moins), - "ETKF-N" (Ensemble-Transform Kalman Filter of finite size N), algorithme d'ETKF dit de "taille finie N", évitant de recourir à une inflation souvent nécessaire avec les autres algorithms -- "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), +- "MLEF" (Maximum Likelihood Kalman Filter, voir [Zupanski05]_), 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), schéma déterministe d'EnKF, améliorant le traitement des non-linéarités des opérateurs. Sans pouvoir prétendre à l'universalité, on recommande d'utiliser l'EnKF comme référence, et les autres algorithmes (dans l'ordre) comme des moyens pour obtenir une assimilation de données plus économique et de qualité éventuellement similaire. @@ -193,4 +200,5 @@ StoreSupplementaryCalculations - [Evensen94]_ - [Burgers98]_ - [Evensen03]_ +- [Zupanski05]_ - [WikipediaEnKF]_ diff --git a/doc/fr/snippets/Variant_3DVAR.rst b/doc/fr/snippets/Variant_3DVAR.rst index d3a58e3..88bee1f 100644 --- a/doc/fr/snippets/Variant_3DVAR.rst +++ b/doc/fr/snippets/Variant_3DVAR.rst @@ -9,10 +9,10 @@ Variant *Nom prédéfini*. Cette clé permet de choisir l'une des variantes possibles pour l'algorithme principal. La variante par défaut est le "3DVAR" d'origine, et les choix possibles sont - "3DVAR" (3D Variational analysis, voir [Lorenc86]_, [LeDimet86]_, [Talagrand97]_), - "3DVAR-VAN" (3D Variational Analysis with No inversion of B, voir [Lorenc88]_), - "3DVAR-Incr" (Incremental 3DVAR, voir [Courtier94]_), - "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR, voir [Cohn98]_), + "3DVAR" (3D Variational analysis), + "3DVAR-VAN" (3D Variational Analysis with No inversion of B), + "3DVAR-Incr" (Incremental 3DVAR), + "3DVAR-PSAS" (Physical-space Statistical Analysis Scheme for 3DVAR), Il est fortement conseillé de conserver la valeur par défaut. Exemple : -- 2.39.2