From 58422153f839106b1d9e47ed6ba2647711406412 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Sun, 14 Dec 2014 09:02:50 +0100 Subject: [PATCH] Documentation minor corrections and improvements --- bin/module_version.py | 3 +- doc/en/bibliography.rst | 4 +++ doc/en/conf.py | 8 ++--- doc/en/intro.rst | 10 +++---- doc/en/theory.rst | 66 ++++++++++++++++++++++------------------- doc/fr/bibliography.rst | 4 +++ doc/fr/conf.py | 8 ++--- doc/fr/intro.rst | 2 +- doc/fr/theory.rst | 49 ++++++++++++++++-------------- 9 files changed, 85 insertions(+), 69 deletions(-) diff --git a/bin/module_version.py b/bin/module_version.py index 24d51d7..3dd2f64 100644 --- a/bin/module_version.py +++ b/bin/module_version.py @@ -21,5 +21,6 @@ # Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D name = "ADAO" -version = "V7_5_0" # Version pour catalogue, avec des "_" entre les numeros +version = "V7_5_1" # Version pour catalogue, avec des "_" entre les numeros date = "" +year = "2015" # Annee de copyright diff --git a/doc/en/bibliography.rst b/doc/en/bibliography.rst index 785d556..8ca8c7e 100644 --- a/doc/en/bibliography.rst +++ b/doc/en/bibliography.rst @@ -57,6 +57,8 @@ Bibliography .. [Talagrand97] Talagrand O., *Assimilation of Observations, an Introduction*, Journal of the Meteorological Society of Japan, 75(1B), pp.191-209, 1997 +.. [Tikhonov77] Tikhonov A. N., Arsenin V. Y., *Solution of Ill-posed Problems*, Winston & Sons, 1977 + .. [WikipediaDA] Wikipedia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation .. [WikipediaMO] Wikipedia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_optimization @@ -65,6 +67,8 @@ Bibliography .. [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 .. [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/conf.py b/doc/en/conf.py index 016f110..2f03a03 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Copyright (C) 2008-2014 EDF R&D +# Copyright (C) 2008-2015 EDF R&D # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public @@ -60,7 +60,7 @@ master_doc = 'index' # General information about the project. project = u'%s'%module_version.name -copyright = u'2008-2014, Jean-Philippe ARGAUD' +copyright = u'2008-%s, Jean-Philippe ARGAUD'%module_version.year # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -222,10 +222,10 @@ source_encoding = 'iso-8859-15' # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = u'ADAO' +epub_title = project epub_author = u'Jean-Philippe ARGAUD' epub_publisher = u'Jean-Philippe ARGAUD' -epub_copyright = u'2008-2014, Jean-Philippe ARGAUD' +epub_copyright = copyright # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/doc/en/intro.rst b/doc/en/intro.rst index b4542fe..191670f 100644 --- a/doc/en/intro.rst +++ b/doc/en/intro.rst @@ -35,11 +35,11 @@ study. Calculation or simulation modules have to provide one or more specific calling methods in order to be callable in the SALOME/ADAO framework, and all the SALOME modules can be used through YACS integration of ADAO. -Its main objective is to **facilitate the use of various standard data -assimilation or optimization methods, while remaining easy to use and providing -a path to help the implementation**. For an end user, having already gathered -his physical input information, it's a matter of "point\&click" to build an ADAO -valid case and to evaluate it. +Its main objective is **to provide the use of various standard data +assimilation or optimization methods, while remaining easy to use and providing +a path to help the implementation**. For an end user, having already gathered +his physical input information, it's a matter of "point\&click" to build an +ADAO valid case and to evaluate it. The module covers a wide variety of practical applications, in a robust way, allowing real engineering applications but also quick experimental methodology diff --git a/doc/en/theory.rst b/doc/en/theory.rst index ad7e8a7..819626f 100644 --- a/doc/en/theory.rst +++ b/doc/en/theory.rst @@ -108,15 +108,16 @@ The **identification (or adjustment) of parameters** by data assimilation is a form of state calibration which uses both the physical measurement and an *a priori* parameters estimation (called the "*background*") of the state that one seeks to identify, as well as a characterization of their errors. From this -point of view, it uses all available information on the physical system (even if -assumptions about errors are relatively restrictive) to find the "*optimal +point of view, it uses all available information on the physical system, with +restrictive yet realistic assumptions about errors, to find the "*optimal estimation*" from the true state. We note, in terms of optimization, that the -background realizes a "*regularization*", in a mathematical meaning, of the main -problem of parameters identification. One can also use the terms "*inverse -problems*" to refer to this process. +background realizes a "*regularization*", in the mathematical meaning of +Tikhonov [[Tikhonov77]_ [WikipediaTI]_, of the main problem of parameters +identification. One can also use the term "*inverse problem*" to refer to this +process. -In practice, the two observed gaps "*calculation-background*" and -"*calculation-measures*" are combined to build the calibration correction of +In practice, the two observed gaps "*calculation-measures*" and +"*calculation-background*" are combined to build the calibration correction of parameters or initial conditions. The addition of these two gaps requires a relative weight, which is chosen to reflect the trust we give to each piece of information. This confidence is depicted by the covariance of the errors on the @@ -176,45 +177,47 @@ random vector :math:`\mathbf{\epsilon}^o` such that: The errors represented here are not only those from observation, but also from the simulation. We can always consider that these errors are of zero mean. Noting :math:`E[.]` the classical mathematical expectation, we can then define a -matrix :math:`\mathbf{R}` of the observation error covariances by: +matrix :math:`\mathbf{R}` of the observation error covariances by the +expression: .. math:: \mathbf{R} = E[\mathbf{\epsilon}^o.{\mathbf{\epsilon}^o}^T] -The background can also be written as a function of the true value, by -introducing the error vector :math:`\mathbf{\epsilon}^b` such that: +The background can also be written formally as a function of the true value, by +introducing the errors vector :math:`\mathbf{\epsilon}^b` such that: .. math:: \mathbf{x}^b = \mathbf{x}^t + \mathbf{\epsilon}^b -where errors are also assumed of zero mean, in the same manner as for -observations. We define the :math:`\mathbf{B}` matrix of background error -covariances by: +The errors :math:`\mathbf{\epsilon}^b` are also assumed of zero mean, in the +same manner as for observations. We define the :math:`\mathbf{B}` matrix of +background error covariances by: .. math:: \mathbf{B} = E[\mathbf{\epsilon}^b.{\mathbf{\epsilon}^b}^T] The optimal estimation of the true parameters :math:`\mathbf{x}^t`, given the background :math:`\mathbf{x}^b` and the observations :math:`\mathbf{y}^o`, is then the "*analysis*" :math:`\mathbf{x}^a` and comes from the minimisation of an -error function (in variational assimilation) or from the filtering correction (in -assimilation by filtering). +error function, explicit in variational assimilation, or from the filtering +correction in assimilation by filtering. In **variational assimilation**, in a static case, one classically attempts to minimize the following function :math:`J`: -.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) - -which is usually designed as the "*3D-VAR*" function (see for example -[Talagrand97]_). Since :math:`\mathbf{B}` and :math:`\mathbf{R}` covariance -matrices are proportional to the variances of errors, their presence in both -terms of the function :math:`J` can effectively weight the differences by -confidence in the background or observations errors. The parameters vector -:math:`\mathbf{x}` realizing the minimum of this function therefore constitute -the analysis :math:`\mathbf{x}^a`. It is at this level that we have to use the -full panoply of function minimization methods otherwise known in optimization -(see also section `Going further in the state estimation by optimization -methods`_). Depending on the size of the parameters vector :math:`\mathbf{x}` to -identify, and of the availability of gradient or Hessian of :math:`J`, it is -appropriate to adapt the chosen optimization method (gradient, Newton, -quasi-Newton...). +.. 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 +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 +proportional to the variances of errors, their presence in both terms of the +function :math:`J` can effectively weight the gap terms by the confidence in the +background or observations errors. The parameters vector :math:`\mathbf{x}` +realizing the minimum of this function therefore constitute the analysis +:math:`\mathbf{x}^a`. It is at this level that we have to use the full panoply +of function minimization methods otherwise known in optimization (see also +section `Going further in the state estimation by optimization methods`_). +Depending on the size of the parameters vector :math:`\mathbf{x}` to identify, +and of the availability of gradient or Hessian of :math:`J`, it is appropriate +to adapt the chosen optimization method (gradient, Newton, quasi-Newton...). In **assimilation by filtering**, in this simple case usually referred to as "*BLUE*" (for "*Best Linear Unbiased Estimator*"), the :math:`\mathbf{x}^a` @@ -261,7 +264,8 @@ To get more information about the data assimilation techniques, the reader can consult introductory documents like [Talagrand97]_ or [Argaud09]_, on-line training courses or lectures like [Bouttier99]_ and [Bocquet04]_ (along with other materials coming from geosciences applications), or general documents like -[Talagrand97]_, [Tarantola87]_, [Kalnay03]_, [Ide97]_ and [WikipediaDA]_. +[Talagrand97]_, [Tarantola87]_, [Kalnay03]_, [Ide97]_, [Tikhonov77]_ and +[WikipediaDA]_. Note that data assimilation is not restricted to meteorology or geo-sciences, but is widely used in other scientific domains. There are several fields in diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index 7154dce..9740a92 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -57,6 +57,8 @@ Bibliographie .. [Talagrand97] Talagrand O., *Assimilation of Observations, an Introduction*, Journal of the Meteorological Society of Japan, 75(1B), pp.191-209, 1997 +.. [Tikhonov77] Tikhonov A. N., Arsenin V. Y., *Solution of Ill-posed Problems*, Winston & Sons, 1977 + .. [WikipediaDA] Wikipedia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation .. [WikipediaMO] Wikipedia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_optimization @@ -65,6 +67,8 @@ Bibliographie .. [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 .. [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/conf.py b/doc/fr/conf.py index 401cb64..cd37f3a 100644 --- a/doc/fr/conf.py +++ b/doc/fr/conf.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Copyright (C) 2008-2014 EDF R&D +# Copyright (C) 2008-2015 EDF R&D # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public @@ -60,7 +60,7 @@ master_doc = 'index' # General information about the project. project = u'%s'%module_version.name -copyright = u'2008-2014, Jean-Philippe ARGAUD' +copyright = u'2008-%s, Jean-Philippe ARGAUD'%module_version.year # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -222,10 +222,10 @@ source_encoding = 'iso-8859-15' # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = u'ADAO' +epub_title = project epub_author = u'Jean-Philippe ARGAUD' epub_publisher = u'Jean-Philippe ARGAUD' -epub_copyright = u'2008-2014, Jean-Philippe ARGAUD' +epub_copyright = copyright # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/doc/fr/intro.rst b/doc/fr/intro.rst index 71d30bb..955bed2 100644 --- a/doc/fr/intro.rst +++ b/doc/fr/intro.rst @@ -36,7 +36,7 @@ une ou plusieurs m cadre SALOME/ADAO, et tous les modules SALOME peuvent être utilisés grace à l'intégration dans YACS de ADAO. -Son principal objectif est de **faciliter l'usage de diverses méthodes standards +Son principal objectif est de **permettre l'usage de diverses méthodes standards d'assimilation de données ou d'optimisation, tout en restant facile à utiliser et en fournissant une démarche pour aider à la mise en oeuvre**. Pour l'utilisateur final, qui a préalablement recueilli les informations sur son diff --git a/doc/fr/theory.rst b/doc/fr/theory.rst index 75e726f..66197a0 100644 --- a/doc/fr/theory.rst +++ b/doc/fr/theory.rst @@ -116,15 +116,15 @@ est une forme de calibration d' physiques et une estimation *a priori* des paramètres (appelée l'"*ébauche*") d'état que l'on cherche à identifier, ainsi qu'une caractérisation de leurs erreurs. De ce point de vue, cette démarche utilise toutes les informations -disponibles sur le système physique (même si les hypothèses sur les erreurs sont -relativement restrictives) pour trouver l'"*estimation optimale*" de l'état +disponibles sur le système physique, avec des hypothèses restrictives mais +réalistes sur les erreurs, pour trouver l'"*estimation optimale*" de l'état vrai. On peut noter, en termes d'optimisation, que l'ébauche réalise la -"*régularisation*", au sens mathématique, du problème principal d'identification -de paramètres. On peut aussi désigner cette démarche comme une résolution de -type "*problèmes inverses*". +"*régularisation*", au sens mathématique de Tikhonov [Tikhonov77]_ +[WikipediaTI]_, du problème principal d'identification de paramètres. On peut +aussi désigner cette démarche comme une résolution de type "*problème inverse*". -En pratique, les deux écarts (ou incréments) observés "*calculs-ébauche*" et -"*calculs-mesures*" sont combinés pour construire la correction de calibration +En pratique, les deux écarts (ou incréments) observés "*calculs-mesures*" et +"*calculs-ébauche*" sont combinés pour construire la correction de calibration des paramètres ou des conditions initiales. L'ajout de ces deux incréments requiert une pondération relative, qui est choisie pour refléter la confiance que l'on donne à chaque information utilisée. Cette confiance est représentée @@ -155,7 +155,7 @@ On peut d variables sont des vecteurs, puisqu'il y a plusieurs paramètres à ajuster, ou un champ discretisé à reconstruire. -Selon les notations standard en assimilation de données, on note +Selon les notations standards en assimilation de données, on note :math:`\mathbf{x}^a` les paramètres optimaux qui doivent être déterminés par calibration, :math:`\mathbf{y}^o` les observations (ou les mesures expérimentales) auxquelles on doit comparer les sorties de simulation, @@ -186,37 +186,40 @@ Les erreurs repr sont aussi celles de la simulation. On peut toujours considérer que ces erreurs sont de moyenne nulle. En notant :math:`E[.]` l'espérance mathématique classique, on peut alors définir une matrice :math:`\mathbf{R}` des covariances -d'erreurs d'observation par : +d'erreurs d'observation par l'expression : .. math:: \mathbf{R} = E[\mathbf{\epsilon}^o.{\mathbf{\epsilon}^o}^T] -L'ébauche peut aussi être écrite comme une fonction de la valeur vraie, en -introduisant le vecteur d'erreurs :math:`\mathbf{\epsilon}^b` tel que : +L'ébauche peut aussi être écrite formellement comme une fonction de la valeur +vraie, en introduisant le vecteur d'erreurs :math:`\mathbf{\epsilon}^b` tel que +: .. math:: \mathbf{x}^b = \mathbf{x}^t + \mathbf{\epsilon}^b -où les erreurs sont aussi supposées de moyenne nulle, de la même manière que -pour les observations. On définit la matrice :math:`\mathbf{B}` des covariances -d'erreurs d'ébauche par : +Les erreurs :math:`\mathbf{\epsilon}^b` sont aussi supposées de moyenne nulle, +de la même manière que pour les observations. On définit la matrice +:math:`\mathbf{B}` des covariances d'erreurs d'ébauche par : .. math:: \mathbf{B} = E[\mathbf{\epsilon}^b.{\mathbf{\epsilon}^b}^T] L'estimation optimale des paramètres vrais :math:`\mathbf{x}^t`, étant donné l'ébauche :math:`\mathbf{x}^b` et les observations :math:`\mathbf{y}^o`, est ainsi l'"*analyse*" :math:`\mathbf{x}^a` et provient de la minimisation d'une -fonction d'erreur (en assimilation variationnelle) ou d'une correction de -filtrage (en assimilation par filtrage). +fonction d'erreur, explicite en assimilation variationnelle, ou d'une correction +de filtrage en assimilation par filtrage. En **assimilation variationnelle**, dans un cas statique, on cherche classiquement à minimiser la fonction :math:`J` suivante : -.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) +.. 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 usuellement désignée comme la fonctionnelle "*3D-VAR*" (voir par exemple -[Talagrand97]_). Comme les matrices de covariance :math:`\mathbf{B}` et -:math:`\mathbf{R}` sont proportionnelles aux variances d'erreurs, leur présence -dans les deux termes de la fonctionnelle :math:`J` permet effectivement de -pondérer les différences par la confiance dans les erreurs d'ébauche ou +: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}` +et :math:`\mathbf{R}` sont proportionnelles aux variances d'erreurs, leur +présence dans les deux termes de la fonctionnelle :math:`J` permet effectivement +de pondérer les termes d'écarts par la confiance dans les erreurs d'ébauche ou d'observations. Le vecteur :math:`\mathbf{x}` des paramètres réalisant le minimum de cette fonction constitue ainsi l'analyse :math:`\mathbf{x}^a`. C'est à ce niveau que l'on doit utiliser toute la panoplie des méthodes de @@ -272,7 +275,7 @@ donn [Talagrand97]_ ou [Argaud09]_, des supports de formations ou de cours comme [Bouttier99]_ et [Bocquet04]_ (ainsi que d'autres documents issus des applications des géosciences), ou des documents généraux comme [Talagrand97]_, -[Tarantola87]_, [Kalnay03]_, [Ide97]_ et [WikipediaDA]_. +[Tarantola87]_, [Kalnay03]_, [Ide97]_, [Tikhonov77]_ et [WikipediaDA]_. On note que l'assimilation de données n'est pas limitée à la météorologie ou aux géo-sciences, mais est largement utilisée dans d'autres domaines scientifiques. -- 2.39.2