From 88c4c8bf099cd9180a0666139ed09cdec68887b8 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Sun, 21 Jan 2018 06:45:25 +0100 Subject: [PATCH] Adding EnKF documentation --- doc/en/bibliography.rst | 12 +- doc/en/ref_algorithm_EnsembleKalmanFilter.rst | 153 +++++++++++++++++ doc/en/reference.rst | 1 + doc/fr/bibliography.rst | 22 ++- doc/fr/ref_algorithm_EnsembleKalmanFilter.rst | 154 ++++++++++++++++++ doc/fr/reference.rst | 1 + 6 files changed, 334 insertions(+), 9 deletions(-) create mode 100644 doc/en/ref_algorithm_EnsembleKalmanFilter.rst create mode 100644 doc/fr/ref_algorithm_EnsembleKalmanFilter.rst diff --git a/doc/en/bibliography.rst b/doc/en/bibliography.rst index c588f75..7dd846a 100644 --- a/doc/en/bibliography.rst +++ b/doc/en/bibliography.rst @@ -37,10 +37,16 @@ Bibliography .. [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 + .. [Byrd95] Byrd R. H., Lu P., Nocedal J., *A Limited Memory Algorithm for Bound Constrained Optimization*, SIAM Journal on Scientific and Statistical Computing, 16(5), pp.1190-1208, 1995 .. [Cade03] Cade B. S., Noon B. R., *A Gentle Introduction to Quantile Regression for Ecologists*, Frontiers in Ecology and the Environment, 1(8), pp.412-420, 2003 +.. [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 + +.. [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 + .. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997 .. [Johnson08] Johnson S. G., *The NLopt nonlinear-optimization package*, http://ab-initio.mit.edu/nlopt @@ -83,16 +89,18 @@ Bibliography .. [WikipediaDA] Wikipedia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation +.. [WikipediaEnKF] Wikipedia, *Ensemble Kalman Filter*, http://en.wikipedia.org/wiki/Ensemble_Kalman_filter + .. [WikipediaMO] Wikipedia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_optimization .. [WikipediaND] Wikipedia, *Nondimensionalization*, https://en.wikipedia.org/wiki/Nondimensionalization -.. [WikipediaPSO] Wikipedia, *Particle swarm optimization*, https://en.wikipedia.org/wiki/Particle_swarm_optimization +.. [WikipediaPSO] Wikipedia, *Particle Swarm Optimization*, https://en.wikipedia.org/wiki/Particle_swarm_optimization .. [WikipediaQR] Wikipedia, *Quantile regression*, https://en.wikipedia.org/wiki/Quantile_regression .. [WikipediaTI] Wikipedia, *Tikhonov regularization*, https://en.wikipedia.org/wiki/Tikhonov_regularization -.. [WikipediaUKF] Wikipedia, *Unscented Kalman filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter +.. [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 diff --git a/doc/en/ref_algorithm_EnsembleKalmanFilter.rst b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst new file mode 100644 index 0000000..61b6591 --- /dev/null +++ b/doc/en/ref_algorithm_EnsembleKalmanFilter.rst @@ -0,0 +1,153 @@ +.. + Copyright (C) 2008-2018 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. index:: single: EnsembleKalmanFilter +.. _section_ref_algorithm_EnsembleKalmanFilter: + +Calculation algorithm "*EnsembleKalmanFilter*" +---------------------------------------------- + +.. warning:: + + in its present version, this algorithm is experimental, and so changes can be + required in forthcoming versions. + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system by a +Ensemble Kalman Filter (EnKF), avoiding to have to perform the tangent and +adjoint operators for the observation and evolution operators, as in the simple +or extended Kalman filter. + +It applies to non-linear observation and incremental evolution (process) +operators with excellent robustness and performance qualities. It can be +compared to the :ref:`section_ref_algorithm_UnscentedKalmanFilter`, whose +qualities are similar for non-linear systems. + +In case of linear of "slightly" non-linear operators, one can easily use the +:ref:`section_ref_algorithm_ExtendedKalmanFilter` or even the +:ref:`section_ref_algorithm_KalmanFilter`, which are often far less expensive +to evaluate on small systems. One can verify the linearity of the operators +with the help of the :ref:`section_ref_algorithm_LinearityTest`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +The general required commands, available in the editing user interface, are the +following: + + .. include:: snippets/Background.rst + + .. include:: snippets/BackgroundError.rst + + .. include:: snippets/EvolutionError.rst + + .. include:: snippets/EvolutionModel.rst + + .. include:: snippets/Observation.rst + + .. include:: snippets/ObservationError.rst + + .. include:: snippets/ObservationOperator.rst + +The general optional commands, available in the editing user interface, are +indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters +of the command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_Algorithm_Parameters` for the good use of this +command. + +The options of the algorithm are the following: + + .. include:: snippets/NumberOfMembers.rst + + .. include:: snippets/EstimationOf.rst + + .. include:: snippets/SetSeed.rst + + StoreSupplementaryCalculations + .. index:: single: StoreSupplementaryCalculations + + This list indicates the names of the supplementary variables that can be + available at the end of the algorithm. It involves potentially costly + calculations or memory consumptions. The default is a void list, none of + these variables being calculated and stored by default. The possible names + are in the following list: ["APosterioriCorrelations", + "APosterioriCovariance", "APosterioriStandardDeviations", + "APosterioriVariances", "BMA", "CostFunctionJ", "CostFunctionJb", + "CostFunctionJo", "CurrentState"]. + + Example : + ``{"StoreSupplementaryCalculations":["CurrentState"]}`` + +Information and variables available at the end of the algorithm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +At the output, after executing the algorithm, there are variables and +information originating from the calculation. The description of +:ref:`section_ref_output_variables` show the way to obtain them by the method +named ``get`` of the variable "*ADD*" of the post-processing. The input +variables, available to the user at the output in order to facilitate the +writing of post-processing procedures, are described in the +:ref:`subsection_r_o_v_Inventaire`. + +The unconditional outputs of the algorithm are the following: + + .. include:: snippets/Analysis.rst + +The conditional outputs of the algorithm are the following: + + .. include:: snippets/APosterioriCorrelations.rst + + .. include:: snippets/APosterioriCovariance.rst + + .. include:: snippets/APosterioriStandardDeviations.rst + + .. include:: snippets/APosterioriVariances.rst + + .. include:: snippets/BMA.rst + + .. include:: snippets/CostFunctionJ.rst + + .. include:: snippets/CostFunctionJb.rst + + .. include:: snippets/CostFunctionJo.rst + + .. include:: snippets/CurrentState.rst + + .. include:: snippets/Innovation.rst + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` + +Bibliographical references: + - [Evensen94]_ + - [Burgers98]_ + - [Evensen03]_ + - [WikipediaEnKF]_ diff --git a/doc/en/reference.rst b/doc/en/reference.rst index f0a5fef..33ba4f9 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -99,6 +99,7 @@ The mathematical notations used afterward are explained in the section ref_algorithm_Blue ref_algorithm_DerivativeFreeOptimization ref_algorithm_EnsembleBlue + ref_algorithm_EnsembleKalmanFilter ref_algorithm_ExtendedBlue ref_algorithm_ExtendedKalmanFilter ref_algorithm_KalmanFilter diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index 2495a81..39a69e1 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -37,10 +37,16 @@ Bibliographie .. [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 + .. [Byrd95] Byrd R. H., Lu P., Nocedal J., *A Limited Memory Algorithm for Bound Constrained Optimization*, SIAM Journal on Scientific and Statistical Computing, 16(5), pp.1190-1208, 1995 .. [Cade03] Cade B. S., Noon B. R., *A Gentle Introduction to Quantile Regression for Ecologists*, Frontiers in Ecology and the Environment, 1(8), pp.412-420, 2003 +.. [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 + +.. [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 + .. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997 .. [Johnson08] Johnson S. G., *The NLopt nonlinear-optimization package*, http://ab-initio.mit.edu/nlopt @@ -81,19 +87,21 @@ Bibliographie .. [Tikhonov77] Tikhonov A. N., Arsenin V. Y., *Solution of Ill-posed Problems*, Winston & Sons, 1977 -.. [WikipediaDA] Wikipédia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation +.. [WikipediaDA] Wikipedia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation + +.. [WikipediaEnKF] Wikipedia, *Ensemble Kalman Filter*, http://en.wikipedia.org/wiki/Ensemble_Kalman_filter -.. [WikipediaMO] Wikipédia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_optimization +.. [WikipediaMO] Wikipedia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_optimization -.. [WikipediaND] Wikipédia, *Nondimensionalization*, https://en.wikipedia.org/wiki/Nondimensionalization +.. [WikipediaND] Wikipedia, *Nondimensionalization*, https://en.wikipedia.org/wiki/Nondimensionalization -.. [WikipediaPSO] Wikipédia, *Particle swarm optimization*, https://en.wikipedia.org/wiki/Particle_swarm_optimization +.. [WikipediaPSO] Wikipedia, *Particle Swarm Optimization*, https://en.wikipedia.org/wiki/Particle_swarm_optimization -.. [WikipediaQR] Wikipédia, *Quantile regression*, https://en.wikipedia.org/wiki/Quantile_regression +.. [WikipediaQR] Wikipedia, *Quantile regression*, https://en.wikipedia.org/wiki/Quantile_regression -.. [WikipediaTI] Wikipédia, *Tikhonov regularization*, https://en.wikipedia.org/wiki/Tikhonov_regularization +.. [WikipediaTI] Wikipedia, *Tikhonov regularization*, https://en.wikipedia.org/wiki/Tikhonov_regularization -.. [WikipediaUKF] Wikipédia, *Unscented Kalman filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter +.. [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 diff --git a/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst new file mode 100644 index 0000000..04e757b --- /dev/null +++ b/doc/fr/ref_algorithm_EnsembleKalmanFilter.rst @@ -0,0 +1,154 @@ +.. + Copyright (C) 2008-2018 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. index:: single: EnsembleKalmanFilter +.. _section_ref_algorithm_EnsembleKalmanFilter: + +Algorithme de calcul "*EnsembleKalmanFilter*" +--------------------------------------------- + +.. warning:: + + dans sa présente version, cet algorithme est expérimental, et reste donc + susceptible de changements dans les prochaines versions. + +Description ++++++++++++ + +Cet algorithme réalise une estimation de l'état d'un système dynamique par un +filtre de Kalman d'ensemble (EnKF), 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 comparé à +l':ref:`section_ref_algorithm_UnscentedKalmanFilter` dont les qualités sont +similaires pour les systèmes non-linéaires. + +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 é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`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + .. include:: snippets/Background.rst + + .. include:: snippets/BackgroundError.rst + + .. include:: snippets/EvolutionError.rst + + .. include:: snippets/EvolutionModel.rst + + .. include:: snippets/Observation.rst + + .. include:: snippets/ObservationError.rst + + .. include:: snippets/ObservationOperator.rst + +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: + + .. include:: snippets/NumberOfMembers.rst + + .. include:: snippets/EstimationOf.rst + + .. include:: snippets/SetSeed.rst + + StoreSupplementaryCalculations + .. index:: single: 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"]. + + Exemple : + ``{"StoreSupplementaryCalculations":["CurrentState"]}`` + +Informations et variables disponibles à la fin de l'algorithme +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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`. + +Les sorties non conditionnelles de l'algorithme sont les suivantes: + + .. include:: snippets/Analysis.rst + +Les sorties conditionnelles de l'algorithme sont les suivantes: + + .. include:: snippets/APosterioriCorrelations.rst + + .. include:: snippets/APosterioriCovariance.rst + + .. include:: snippets/APosterioriStandardDeviations.rst + + .. include:: snippets/APosterioriVariances.rst + + .. include:: snippets/BMA.rst + + .. include:: snippets/CostFunctionJ.rst + + .. include:: snippets/CostFunctionJb.rst + + .. include:: snippets/CostFunctionJo.rst + + .. include:: snippets/CurrentState.rst + + .. include:: snippets/Innovation.rst + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` + +Références bibliographiques : + - [Evensen94]_ + - [Burgers98]_ + - [Evensen03]_ + - [WikipediaEnKF]_ diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index 2a499c9..d4480ca 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -101,6 +101,7 @@ ADAO. Les notations mathématiques utilisées sont expliquées dans la section ref_algorithm_Blue ref_algorithm_DerivativeFreeOptimization ref_algorithm_EnsembleBlue + ref_algorithm_EnsembleKalmanFilter ref_algorithm_ExtendedBlue ref_algorithm_ExtendedKalmanFilter ref_algorithm_KalmanFilter -- 2.39.2