From 5bd6e3167d3e7947d367bb17a682f4206b999863 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Tue, 16 Feb 2021 19:09:52 +0100 Subject: [PATCH] Minor documentation improvements and fixes for internal variables --- doc/en/bibliography.rst | 6 +++- doc/en/ref_algorithm_Blue.rst | 13 ++++++++- .../ref_algorithm_DifferentialEvolution.rst | 2 ++ doc/en/snippets/InitializationPoint.rst | 3 ++ doc/en/snippets/QualityCriterion.rst | 6 ++-- .../SimulatedObservationAtOptimum.rst | 4 +-- doc/fr/bibliography.rst | 6 +++- doc/fr/ref_algorithm_Blue.rst | 15 ++++++++-- .../ref_algorithm_DifferentialEvolution.rst | 2 ++ doc/fr/snippets/InitializationPoint.rst | 3 ++ doc/fr/snippets/QualityCriterion.rst | 8 +++--- .../SimulatedObservationAtOptimum.rst | 6 ++-- .../DerivativeFreeOptimization.py | 9 +++++- .../daAlgorithms/DifferentialEvolution.py | 28 +++++++++++-------- .../daAlgorithms/EnsembleKalmanFilter.py | 6 ++-- .../daAlgorithms/ParticleSwarmOptimization.py | 15 ++++++---- .../daAlgorithms/QuantileRegression.py | 2 +- src/daComposant/daCore/NumericObjects.py | 2 +- 18 files changed, 97 insertions(+), 39 deletions(-) diff --git a/doc/en/bibliography.rst b/doc/en/bibliography.rst index ca89a7f..0626edc 100644 --- a/doc/en/bibliography.rst +++ b/doc/en/bibliography.rst @@ -47,7 +47,11 @@ Bibliography .. [Chakraborty08] Chakraborty U.K., *Advances in differential evolution*, Studies in computational intelligence, Vol.143, Springer, 2008 -.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994 +.. [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 + +.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), pp.10143–10162, 1994 .. [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 diff --git a/doc/en/ref_algorithm_Blue.rst b/doc/en/ref_algorithm_Blue.rst index d6671bb..67fec5d 100644 --- a/doc/en/ref_algorithm_Blue.rst +++ b/doc/en/ref_algorithm_Blue.rst @@ -31,7 +31,8 @@ Calculation algorithm "*Blue*" .. include:: snippets/Header2Algo01.rst This algorithm realizes a BLUE (Best Linear Unbiased Estimator) type estimation -of the state of a system. More precisely, it is an Aitken estimator. +of the state of a system. It is a linear, unbiased and optimal estimation. +Technically, it is an Aitken estimator. This algorithm is always the fastest of all the assimilation algorithms of ADAO. It is theoretically reserved for observation operator cases which are linear, @@ -43,6 +44,16 @@ In case of non-linearity, even slightly marked, it will be easily preferred the :ref:`section_ref_algorithm_ExtendedBlue` or the :ref:`section_ref_algorithm_3DVAR`. +.. index:: single: Optimal Interpolation + +Additional remark: an algebraic simplification of the BLUE leads to the optimal +interpolation method, named "*Optimal Interpolation*" or "*OI*". It is a very +simple and inexpensive method, especially adapted to very (very) large +problems, but whose disadvantage is to provide a globally sub-optimal and noisy +analysis result, even inconsistent. The way to avoid these disadvantages is to +adapt very precisely the elements of the method to each physical model. For +these reasons, this method is not proposed nor recommended. + .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/en/ref_algorithm_DifferentialEvolution.rst b/doc/en/ref_algorithm_DifferentialEvolution.rst index 64c853c..f7c2cc8 100644 --- a/doc/en/ref_algorithm_DifferentialEvolution.rst +++ b/doc/en/ref_algorithm_DifferentialEvolution.rst @@ -181,5 +181,7 @@ StoreSupplementaryCalculations .. include:: snippets/Header2Algo07.rst - [Chakraborty08]_ +- [Das11]_ +- [Das16]_ - [Price05]_ - [Storn97]_ diff --git a/doc/en/snippets/InitializationPoint.rst b/doc/en/snippets/InitializationPoint.rst index 5a949e7..3c8f356 100644 --- a/doc/en/snippets/InitializationPoint.rst +++ b/doc/en/snippets/InitializationPoint.rst @@ -6,3 +6,6 @@ InitializationPoint not required and is equal to the background :math:`\mathbf{x}^b`. If provided, it replaces the background only for initialization. Its value must allow to build a vector of the same size as the background. + + Example : + ``{"InitializationPoint":[1, 2, 3, 4, 5]}`` diff --git a/doc/en/snippets/QualityCriterion.rst b/doc/en/snippets/QualityCriterion.rst index c91660e..1ff2d33 100644 --- a/doc/en/snippets/QualityCriterion.rst +++ b/doc/en/snippets/QualityCriterion.rst @@ -6,9 +6,9 @@ QualityCriterion criterion named "DA", the augmented weighted least squares. The possible criteria has to be in the following list, where the equivalent names are indicated by the sign "<=>": - ["AugmentedWeightedLeastSquares"<=>"AWLS"<=>"DA", - "WeightedLeastSquares"<=>"WLS", "LeastSquares"<=>"LS"<=>"L2", - "AbsoluteValue"<=>"L1", "MaximumError"<=>"ME"]. + ["AugmentedWeightedLeastSquares" <=> "AWLS" <=> "DA", + "WeightedLeastSquares" <=> "WLS", "LeastSquares" <=> "LS" <=> "L2", + "AbsoluteValue" <=> "L1", "MaximumError" <=> "ME"]. Example: ``{"QualityCriterion":"DA"}`` diff --git a/doc/en/snippets/SimulatedObservationAtOptimum.rst b/doc/en/snippets/SimulatedObservationAtOptimum.rst index a3bc4cc..9015483 100644 --- a/doc/en/snippets/SimulatedObservationAtOptimum.rst +++ b/doc/en/snippets/SimulatedObservationAtOptimum.rst @@ -2,9 +2,9 @@ .. index:: single: Forecast SimulatedObservationAtOptimum - *List of vectors*. Each element is a vector of observation simulated by the + *List of vectors*. Each element is a vector of observation obtained by the observation operator from the analysis or optimal state :math:`\mathbf{x}^a`. - It is the forecast from the analysis or the optimal state, and it is + It is the observed forecast from the analysis or the optimal state, and it is sometimes called "*Forecast*". Example: diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index d2c03ec..76f5dfe 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -47,7 +47,11 @@ Bibliographie .. [Chakraborty08] Chakraborty U.K., *Advances in differential evolution*, Studies in computational intelligence, Vol.143, Springer, 2008 -.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), 10,143–10,162, 1994 +.. [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 + +.. [Evensen94] Evensen G., *Sequential data assimilation with a nonlinear quasi-geostrophic model using Monte Carlo methods to forecast error statistics*, Journal of Geophysical Research, 99(C5), pp.10143–10162, 1994 .. [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 diff --git a/doc/fr/ref_algorithm_Blue.rst b/doc/fr/ref_algorithm_Blue.rst index 70b46cd..d4f2842 100644 --- a/doc/fr/ref_algorithm_Blue.rst +++ b/doc/fr/ref_algorithm_Blue.rst @@ -31,8 +31,8 @@ Algorithme de calcul "*Blue*" .. include:: snippets/Header2Algo01.rst Cet algorithme réalise une estimation de type BLUE (Best Linear Unbiased -Estimator) de l'état d'un système. De manière précise, c'est un estimateur -d'Aitken. +Estimator) de l'état d'un système. C'est une estimation linéaire, sans biais et +optimale. De manière technique, c'est un estimateur d'Aitken. Cet algorithme est toujours le plus rapide de l'ensemble des algorithmes d'assimilation d'ADAO. Il est théoriquement réservé aux cas d'opérateurs @@ -44,6 +44,17 @@ En cas de non-linéarité, même peu marquée, on lui préférera aisément l':ref:`section_ref_algorithm_ExtendedBlue` ou l':ref:`section_ref_algorithm_3DVAR`. +.. index:: single: Optimal Interpolation + +Remarque complémentaire : une simplification algébrique du BLUE conduit à la +méthode d'interpolation optimale, nommée "*Optimal Interpolation*" ou "*OI*". +C'est une méthode très simple et peu coûteuse, spécialement adaptée aux +problèmes de très (très) grande taille, mais dont l'inconvénient est de fournir +un résultat d'analyse globalement sous-optimal et bruité, voire incohérent. Le +moyen d'éviter ces désavantages est d'adapter très précisément les éléments de +la méthode à chaque modèle physique. Pour ces raisons, cette méthode n'est donc +pas proposée. + .. ------------------------------------ .. .. include:: snippets/Header2Algo02.rst diff --git a/doc/fr/ref_algorithm_DifferentialEvolution.rst b/doc/fr/ref_algorithm_DifferentialEvolution.rst index a594f03..c2444c6 100644 --- a/doc/fr/ref_algorithm_DifferentialEvolution.rst +++ b/doc/fr/ref_algorithm_DifferentialEvolution.rst @@ -183,5 +183,7 @@ StoreSupplementaryCalculations .. include:: snippets/Header2Algo07.rst - [Chakraborty08]_ +- [Das11]_ +- [Das16]_ - [Price05]_ - [Storn97]_ diff --git a/doc/fr/snippets/InitializationPoint.rst b/doc/fr/snippets/InitializationPoint.rst index 12236bc..385df56 100644 --- a/doc/fr/snippets/InitializationPoint.rst +++ b/doc/fr/snippets/InitializationPoint.rst @@ -7,3 +7,6 @@ InitializationPoint Dans le cas où il est fourni, il ne remplace l'ébauche que pour l'initialisation. Sa valeur doit permettre de construire un vecteur de taille identique à l'ébauche. + + Exemple : + ``{"InitializationPoint":[1, 2, 3, 4, 5]}`` diff --git a/doc/fr/snippets/QualityCriterion.rst b/doc/fr/snippets/QualityCriterion.rst index 4ca7362..d10b181 100644 --- a/doc/fr/snippets/QualityCriterion.rst +++ b/doc/fr/snippets/QualityCriterion.rst @@ -5,10 +5,10 @@ QualityCriterion pour trouver l'estimation optimale de l'état. Le défaut est le critère usuel de l'assimilation de données nommé "DA", qui est le critère de moindres carrés pondérés augmentés. Les critères possibles sont dans la liste - suivante, dans laquelle les noms équivalents sont indiqués par un signe "<=>" - : ["AugmentedWeightedLeastSquares"<=>"AWLS"<=>"DA", - "WeightedLeastSquares"<=>"WLS", "LeastSquares"<=>"LS"<=>"L2", - "AbsoluteValue"<=>"L1", "MaximumError"<=>"ME"]. + suivante, dans laquelle les noms équivalents sont indiqués par un signe "<=>" : + ["AugmentedWeightedLeastSquares" <=> "AWLS" <=> "DA", + "WeightedLeastSquares" <=> "WLS", "LeastSquares" <=> "LS" <=> "L2", + "AbsoluteValue" <=> "L1", "MaximumError" <=> "ME"]. Exemple : ``{"QualityCriterion":"DA"}`` diff --git a/doc/fr/snippets/SimulatedObservationAtOptimum.rst b/doc/fr/snippets/SimulatedObservationAtOptimum.rst index 4c484da..d7bc73b 100644 --- a/doc/fr/snippets/SimulatedObservationAtOptimum.rst +++ b/doc/fr/snippets/SimulatedObservationAtOptimum.rst @@ -2,10 +2,10 @@ .. index:: single: Forecast SimulatedObservationAtOptimum - *Liste de vecteurs*. Chaque élément est un vecteur d'observation simulé par + *Liste de vecteurs*. Chaque élément est un vecteur d'observation obtenu par l'opérateur d'observation à partir de l'analyse ou de l'état optimal - :math:`\mathbf{x}^a`. C'est la prévision à partir de l'analyse ou de l'état - optimal, et elle est parfois appellée "*Forecast*". + :math:`\mathbf{x}^a`. C'est l'observation de la prévision à partir de + l'analyse ou de l'état optimal, et elle est parfois appellée "*Forecast*". Exemple : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]`` diff --git a/src/daComposant/daAlgorithms/DerivativeFreeOptimization.py b/src/daComposant/daAlgorithms/DerivativeFreeOptimization.py index 0cbba96..78e2a30 100644 --- a/src/daComposant/daAlgorithms/DerivativeFreeOptimization.py +++ b/src/daComposant/daAlgorithms/DerivativeFreeOptimization.py @@ -33,7 +33,14 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = "BOBYQA", typecast = str, message = "Minimiseur utilisé", - listval = ["BOBYQA", "COBYLA", "NEWUOA", "POWELL", "SIMPLEX", "SUBPLEX"], + listval = [ + "BOBYQA", + "COBYLA", + "NEWUOA", + "POWELL", + "SIMPLEX", + "SUBPLEX", + ], ) self.defineRequiredParameter( name = "MaximumNumberOfSteps", diff --git a/src/daComposant/daAlgorithms/DifferentialEvolution.py b/src/daComposant/daAlgorithms/DifferentialEvolution.py index 06579a9..8e7710f 100644 --- a/src/daComposant/daAlgorithms/DifferentialEvolution.py +++ b/src/daComposant/daAlgorithms/DifferentialEvolution.py @@ -36,16 +36,18 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): listval = [ "BEST1BIN", "BEST1EXP", - "RAND1EXP", - "RANDTOBEST1EXP", - # "CURRENTTOBEST1EXP", + "BEST2BIN", "BEST2EXP", + "RAND1BIN", + "RAND1EXP", + "RAND2BIN", "RAND2EXP", "RANDTOBEST1BIN", - # "CURRENTTOBEST1BIN", - "BEST2BIN", - "RAND2BIN", - "RAND1BIN", + "RANDTOBEST1EXP", + ], + listadv = [ + "CURRENTTOBEST1EXP", + "CURRENTTOBEST1BIN", ], ) self.defineRequiredParameter( @@ -90,11 +92,13 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = "AugmentedWeightedLeastSquares", typecast = str, message = "Critère de qualité utilisé", - listval = ["AugmentedWeightedLeastSquares","AWLS","DA", - "WeightedLeastSquares","WLS", - "LeastSquares","LS","L2", - "AbsoluteValue","L1", - "MaximumError","ME"], + listval = [ + "AugmentedWeightedLeastSquares","AWLS","DA", + "WeightedLeastSquares","WLS", + "LeastSquares","LS","L2", + "AbsoluteValue","L1", + "MaximumError","ME", + ], ) self.defineRequiredParameter( name = "StoreInternalVariables", diff --git a/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py b/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py index a1d3598..b475c71 100644 --- a/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py +++ b/src/daComposant/daAlgorithms/EnsembleKalmanFilter.py @@ -80,8 +80,8 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): "MultiplicativeOnBackgroundCovariance", "MultiplicativeOnAnalysisAnomalies", "MultiplicativeOnBackgroundAnomalies", - "AdditiveOnBackgroundCovariance", "AdditiveOnAnalysisCovariance", + "AdditiveOnBackgroundCovariance", "HybridOnBackgroundCovariance", ], ) @@ -98,9 +98,11 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): typecast = str, message = "Méthode d'inflation d'ensemble", listval = [ + "SchurLocalization", + ], + listadv = [ "CovarianceLocalization", "DomainLocalization", - "SchurLocalization", "GaspariCohnLocalization", ], ) diff --git a/src/daComposant/daAlgorithms/ParticleSwarmOptimization.py b/src/daComposant/daAlgorithms/ParticleSwarmOptimization.py index 8df1072..9078e95 100644 --- a/src/daComposant/daAlgorithms/ParticleSwarmOptimization.py +++ b/src/daComposant/daAlgorithms/ParticleSwarmOptimization.py @@ -74,11 +74,16 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = "AugmentedWeightedLeastSquares", typecast = str, message = "Critère de qualité utilisé", - listval = ["AugmentedWeightedLeastSquares","AWLS","AugmentedPonderatedLeastSquares","APLS","DA", - "WeightedLeastSquares","WLS","PonderatedLeastSquares","PLS", - "LeastSquares","LS","L2", - "AbsoluteValue","L1", - "MaximumError","ME"], + listval = [ + "AugmentedWeightedLeastSquares","AWLS","DA", + "WeightedLeastSquares","WLS", + "LeastSquares","LS","L2", + "AbsoluteValue","L1", + "MaximumError","ME"], + listadv = [ + "AugmentedPonderatedLeastSquares","APLS", + "PonderatedLeastSquares","PLS", + ] ) self.defineRequiredParameter( name = "StoreInternalVariables", diff --git a/src/daComposant/daAlgorithms/QuantileRegression.py b/src/daComposant/daAlgorithms/QuantileRegression.py index 0037e9b..1a23f02 100644 --- a/src/daComposant/daAlgorithms/QuantileRegression.py +++ b/src/daComposant/daAlgorithms/QuantileRegression.py @@ -41,7 +41,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = "MMQR", typecast = str, message = "Minimiseur utilisé", - listval = ["MMQR"], + listval = ["MMQR",], ) self.defineRequiredParameter( name = "MaximumNumberOfSteps", diff --git a/src/daComposant/daCore/NumericObjects.py b/src/daComposant/daCore/NumericObjects.py index 762e047..7571a15 100644 --- a/src/daComposant/daCore/NumericObjects.py +++ b/src/daComposant/daCore/NumericObjects.py @@ -610,7 +610,7 @@ def CovarianceInflation( OutputCovOrEns = InputCovOrEnsMean[:,numpy.newaxis] \ + InflationFactor * (InputCovOrEns - InputCovOrEnsMean[:,numpy.newaxis]) # - elif InflationType in ["AdditiveOnBackgroundCovariance", "AdditiveOnAnalysisCovariance"]: + elif InflationType in ["AdditiveOnAnalysisCovariance", "AdditiveOnBackgroundCovariance"]: if InflationFactor < 0.: raise ValueError("Inflation factor for additive inflation has to be greater or equal than 0.") if InflationFactor < mpr: -- 2.39.2