From 6f8b685474cd302ff63bf0b6e8578ab9e182599c Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Tue, 11 Feb 2014 07:57:57 +0100 Subject: [PATCH] Documentation review corrections --- doc/Makefile.am | 2 +- doc/en/Makefile.am | 2 +- doc/en/conf.py | 10 ++-- doc/en/index.rst | 27 +++++----- doc/en/intro.rst | 8 +-- doc/en/licence.rst | 2 +- doc/en/reference.rst | 25 +++++++--- doc/en/theory.rst | 99 ++++++++++++++++++++----------------- doc/en/using.rst | 7 ++- doc/fr/Makefile.am | 2 +- doc/fr/advanced.rst | 6 +-- doc/fr/conf.py | 12 ++--- doc/fr/examples.rst | 8 +-- doc/fr/index.rst | 33 ++++++------- doc/fr/intro.rst | 10 ++-- doc/fr/licence.rst | 2 +- doc/fr/reference.rst | 48 +++++++++++------- doc/fr/theory.rst | 115 +++++++++++++++++++++++-------------------- doc/fr/using.rst | 6 ++- 19 files changed, 235 insertions(+), 189 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 1197a3d..c659b7f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -# Copyright (C) 2010-2013 EDF R&D +# Copyright (C) 2010-2014 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 diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am index e531baf..d374278 100644 --- a/doc/en/Makefile.am +++ b/doc/en/Makefile.am @@ -1,4 +1,4 @@ -# Copyright (C) 2010-2013 EDF R&D +# Copyright (C) 2010-2014 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 diff --git a/doc/en/conf.py b/doc/en/conf.py index 4550d14..0d8f111 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Copyright (C) 2008-2013 EDF R&D +# Copyright (C) 2008-2014 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 @@ -58,18 +58,18 @@ master_doc = 'index' # General information about the project. project = u'ADAO' -copyright = u'2008-2013, Jean-Philippe ARGAUD' +copyright = u'2008-2014, Jean-Philippe ARGAUD' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. +version = '7.4.0' version = '7\_main' -version = '7.3.0' # The full version, including alpha/beta/rc tags. +release = '7.4.0' release = '7\_main' -release = '7.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -223,7 +223,7 @@ source_encoding = 'iso-8859-15' epub_title = u'ADAO' epub_author = u'Jean-Philippe ARGAUD' epub_publisher = u'Jean-Philippe ARGAUD' -epub_copyright = u'2008-2013, Jean-Philippe ARGAUD' +epub_copyright = u'2008-2014, Jean-Philippe ARGAUD' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/doc/en/index.rst b/doc/en/index.rst index 0b896a5..4b875e7 100644 --- a/doc/en/index.rst +++ b/doc/en/index.rst @@ -18,18 +18,16 @@ the framework are also known under the names of *parameter estimation*, *inverse problems*, *Bayesian estimation*, *optimal interpolation*, etc. More details can be found in the section :ref:`section_theory`. -The documentation of this module is divided in parts. The first one -:ref:`section_intro` is an introduction. The second part :ref:`section_theory` -briefly introduces data assimilation, optimization and concepts. The third part -:ref:`section_using` describes how to use the module ADAO. The fourth part -:ref:`section_reference` gives a detailed description of all the ADAO commands -and keywords. The fifth part :ref:`section_examples` gives examples on ADAO -usage. Users interested in quick use of the module can jump to this section, but -a valuable use of the module requires to read and come back regularly to the -third and fourth ones. The last part :ref:`section_advanced` focuses on advanced -usages of the module, how to get more information, or how to use it by -scripting, without the graphical user interface (GUI). And be sure to read the -part :ref:`section_licence` to respect the module requirements. +The documentation of this module is divided in parts. The first one is an +:ref:`section_intro`. The second part introduces :ref:`section_theory`, and +their concepts. The third part describes :ref:`section_using`. The fourth part +gives examples on ADAO usage as :ref:`section_examples`. The fifth part gives a +detailed :ref:`section_reference`. Users interested in quick use of the module +can stop reading before this fifth part, but a valuable use of the module +requires to read and come back regularly to the third and fifth ones. The last +part focuses on :ref:`section_advanced`, how to get more information, or how to +use it by scripting, without the graphical user interface (GUI). And, to respect +the module requirements, be sure to read the part :ref:`section_licence`. In all this documentation, we use standard notations of linear algebra, data assimilation (as described in [Ide97]_) and optimization. In particular, vectors @@ -47,10 +45,11 @@ Table of contents intro theory using - reference examples + reference advanced licence + glossary bibliography Indices and tables @@ -58,4 +57,4 @@ Indices and tables * :ref:`genindex` * :ref:`search` -* :ref:`section_glossary` +.. * :ref:`section_glossary` diff --git a/doc/en/intro.rst b/doc/en/intro.rst index 1e5095b..893ba92 100644 --- a/doc/en/intro.rst +++ b/doc/en/intro.rst @@ -12,10 +12,10 @@ 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 throught 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 +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. The module covers a wide variety of practical applications, in a robust way, diff --git a/doc/en/licence.rst b/doc/en/licence.rst index 44bdd70..1d995ed 100644 --- a/doc/en/licence.rst +++ b/doc/en/licence.rst @@ -13,7 +13,7 @@ GPL), as stated here and in the source files:: - Copyright (C) 2008-2013 EDF R&D + Copyright (C) 2008-2014 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 diff --git a/doc/en/reference.rst b/doc/en/reference.rst index e05d887..64b8fb0 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -271,6 +271,11 @@ sring, as follows for example in a file:: "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], } +To give the "*AlgorithmParameters*" values by string, one must enclose a +standard dictionnary definition between simple quotes, as for example:: + + '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}' + This section describes the available options algorithm by algorithm. In addition, for each algorithm, the required commands/keywords are given, being described in `List of commands and keywords for an ADAO calculation case`_. If @@ -747,7 +752,7 @@ commands are the following: data automatically before data assimilation algorithm processing. Optional and required commands for checking algorithms -+++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. index:: single: AdjointTest .. index:: single: FunctionTest @@ -930,6 +935,11 @@ same functional representation can be used for the linear tangent model :math:`\mathbf{O}` of :math:`O` and its adjoint :math:`\mathbf{O}^*`, also required by some data assimilation or optimization algorithms. +On input and output of these operators, the :math:`\mathbf{x}` and +:math:`\mathbf{y}` variables or their increments are mathematically vectors, +and they are given as non-orented vectors (of type list or Numpy array) or +oriented ones (of type Numpy matrix). + Then, **to describe completely an operator, the user has only to provide a function that fully and only realize the functional operation**. @@ -1137,7 +1147,7 @@ Schematically, the operator has to be set as:: ... ... ... - return something like X(n+1) or Y(n+1) + return something like X(n+1) (evolution) or Y(n+1) (observation) The tangent and adjoint operators have the same signature as previously, noting that the derivatives has to be done only partially against :math:`\mathbf{x}`. @@ -1205,8 +1215,8 @@ Second matrix form: using "*ScalarSparseMatrix*" representation On the opposite, this second form is a very simplified method to provide a matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive -multiple of the identity matrix. This matrix can then be specified only by the -multiplier :math:`m`: +multiple of the identity matrix. This matrix can then be specified in a unique +way by the multiplier :math:`m`: .. math:: \mathbf{M} = m \times \begin{pmatrix} 1 & 0 & \cdots & 0 \\ @@ -1216,9 +1226,10 @@ multiplier :math:`m`: \end{pmatrix} The multiplier :math:`m` has to be a floating point or integer positive value -(if it is negative, which is impossible, it is converted to positive value). For -example, a simple diagonal unitary background error covariance matrix -:math:`\mathbf{B}` can be described in a python script file as:: +(if it is negative, which is impossible for a positive covariance matrix, it is +converted to positive value). For example, a simple diagonal unitary background +error covariance matrix :math:`\mathbf{B}` can be described in a python script +file as:: BackgroundError = 1. diff --git a/doc/en/theory.rst b/doc/en/theory.rst index 5b0e82b..34eba10 100644 --- a/doc/en/theory.rst +++ b/doc/en/theory.rst @@ -42,13 +42,15 @@ Fields reconstruction or measures interpolation .. index:: single: fields reconstruction .. index:: single: measures interpolation +.. index:: single: fields interpolation -Fields reconstruction consists in finding, from a restricted set of real -measures, the physical field which is the most *consistent* with these measures. +**Fields reconstruction (or interpolation)** consists in finding, from a +restricted set of real measures, the physical field which is the most +*consistent* with these measures. -This consistency is to understand in terms of interpolation, that is to say that -the field we want to reconstruct, using data assimilation on measures, has to -fit at best the measures, while remaining constrained by the overall field +This *consistency* is to understand in terms of interpolation, that is to say +that the field we want to reconstruct, using data assimilation on measures, has +to fit at best the measures, while remaining constrained by the overall field calculation. The calculation is thus an *a priori* estimation of the field that we seek to identify. @@ -72,20 +74,23 @@ Parameters identification, models adjustment, calibration --------------------------------------------------------- .. index:: single: parameters identification +.. index:: single: parameters adjustment .. index:: single: models adjustment .. index:: single: calibration .. index:: single: background .. index:: single: regularization +.. index:: single: inverse problems -The identification 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 +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 estimation*" from the true state. We note, in terms of optimization, that the -background realizes a mathematical regularization of the main problem of -parameters identification. +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. In practice, the two observed gaps "*calculation-background*" and "*calculation-measures*" are combined to build the calibration correction of @@ -127,22 +132,25 @@ are zero and the model is exact) as output. In the simplest case, which is static, the steps of simulation and of observation can be combined into a single observation operator noted :math:`H` (linear or nonlinear). It transforms the input parameters :math:`\mathbf{x}` to -results :math:`\mathbf{y}` to be directly compared to observations -:math:`\mathbf{y}^o`. Moreover, we use the linearized operator -:math:`\mathbf{H}` to represent the effect of the full operator :math:`H` around -a linearization point (and we omit thereafter to mention :math:`H` even if it is -possible to keep it). In reality, we have already indicated that the stochastic -nature of variables is essential, coming from the fact that model, background -and observations are all incorrect. We therefore introduce errors of -observations additively, in the form of a random vector -:math:`\mathbf{\epsilon}^o` such that: +results :math:`\mathbf{y}`, to be directly compared to observations +:math:`\mathbf{y}^o`: + +.. math:: \mathbf{y} = H(\mathbf{x}) + +Moreover, we use the linearized operator :math:`\mathbf{H}` to represent the +effect of the full operator :math:`H` around a linearization point (and we omit +thereafter to mention :math:`H` even if it is possible to keep it). In reality, +we have already indicated that the stochastic nature of variables is essential, +coming from the fact that model, background and observations are all incorrect. +We therefore introduce errors of observations additively, in the form of a +random vector :math:`\mathbf{\epsilon}^o` such that: .. math:: \mathbf{y}^o = \mathbf{H} \mathbf{x}^t + \mathbf{\epsilon}^o 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. We -can then define a matrix :math:`\mathbf{R}` of the observation error covariances -by: +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: .. math:: \mathbf{R} = E[\mathbf{\epsilon}^o.{\mathbf{\epsilon}^o}^T] @@ -168,18 +176,19 @@ 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. 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...). +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...). In **assimilation by filtering**, in this simple case usually referred to as "*BLUE*" (for "*Best Linear Unbiased Estimator*"), the :math:`\mathbf{x}^a` @@ -197,9 +206,9 @@ covariance matrices in the following form: The advantage of filtering is to explicitly calculate the gain, to produce then the *a posteriori* covariance analysis matrix. -In this simple static case, we can show, under the assumption of Gaussian error -distributions, that the two *variational* and *filtering* approaches are -equivalent. +In this simple static case, we can show, under an assumption of Gaussian error +distributions (very little restrictive in practice), 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 @@ -223,10 +232,10 @@ Going further in the data assimilation framework .. index:: single: data smoothing To get more information about the data assimilation techniques, the reader can -consult introductory documents like [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]_. +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]_. 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 @@ -253,8 +262,8 @@ which is named the "*3D-VAR*" 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 -minimization of the :math:`J` function leads to the *best* `\mathbf{x}` state -estimation. +minimization of the :math:`J` function leads to the *best* :math:`\mathbf{x}` +state estimation. State estimation possibilities extension, by using more explicitly optimization methods and their properties, can be imagined in two ways. diff --git a/doc/en/using.rst b/doc/en/using.rst index 8129eed..0c8bf5c 100644 --- a/doc/en/using.rst +++ b/doc/en/using.rst @@ -77,7 +77,10 @@ STEP 2: Build and modify the ADAO case, and save it --------------------------------------------------- To build a case using EFICAS, you have to go through a series of sub-steps, by -selecting, at each sub-step, a keyword and then filling in its value. +selecting, at each sub-step, a keyword and then filling in its value. It is +noted that it is in this step that is needed, among other things, to define the +call to the simulation code used in observation or evolution operators +describing the problem [#]_. The structured editor indicates hierarchical types, values or keywords allowed. Incomplete or incorrect keywords are identified by a visual error red flag. @@ -213,6 +216,8 @@ The execution can also be done using a shell script, as described in the section .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME platform. +.. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts. + .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME platform. .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`. diff --git a/doc/fr/Makefile.am b/doc/fr/Makefile.am index b91054a..4e18530 100644 --- a/doc/fr/Makefile.am +++ b/doc/fr/Makefile.am @@ -1,4 +1,4 @@ -# Copyright (C) 2010-2013 EDF R&D +# Copyright (C) 2010-2014 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 diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst index d48029e..f6276fc 100644 --- a/doc/fr/advanced.rst +++ b/doc/fr/advanced.rst @@ -170,7 +170,7 @@ niveau par d Il est aussi recommandé d'inclure de la surveillance par logging ou des mécanismes de débogage dans le code de simulation, et de les utiliser en conjonction avec les deux méthodes précédentes. Néanmoins, il convient d'être -prudent dans le stockage de "grosses" variables car cela coute du temps, +prudent dans le stockage de "grosses" variables car cela coûte du temps, quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces variables ne sont pas affichées). @@ -194,8 +194,8 @@ Passer de la version 7.2 +++++++++++++++++++++++++++++++++ Il n'y a pas d'incompatibilité connue pour les fichiers de cas ADAO. La -procédure de montée en version consiste à lire l'ancien fichier de cas ADAO avec -le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom. +procédure de montée en version consiste à lire l'ancien fichier de cas ADAO +avec le nouveau module SALOME/ADAO, et de l'enregistrer avec un nouveau nom. Passer de la version 6.6 à la 7.2 +++++++++++++++++++++++++++++++++ diff --git a/doc/fr/conf.py b/doc/fr/conf.py index c377cc7..f268da5 100644 --- a/doc/fr/conf.py +++ b/doc/fr/conf.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Copyright (C) 2008-2013 EDF R&D +# Copyright (C) 2008-2014 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 @@ -58,18 +58,18 @@ master_doc = 'index' # General information about the project. project = u'ADAO' -copyright = u'2008-2013, Jean-Philippe ARGAUD' +copyright = u'2008-2014, Jean-Philippe ARGAUD' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. +version = '7.4.0' version = '7\_main' -version = '7.3.0' # The full version, including alpha/beta/rc tags. +release = '7.4.0' release = '7\_main' -release = '7.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -125,7 +125,7 @@ html_theme = 'default' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = "Documentation ADAO v7_main" # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -223,7 +223,7 @@ source_encoding = 'iso-8859-15' epub_title = u'ADAO' epub_author = u'Jean-Philippe ARGAUD' epub_publisher = u'Jean-Philippe ARGAUD' -epub_copyright = u'2008-2013, Jean-Philippe ARGAUD' +epub_copyright = u'2008-2014, Jean-Philippe ARGAUD' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/doc/fr/examples.rst b/doc/fr/examples.rst index fcedd64..07e47f8 100644 --- a/doc/fr/examples.rst +++ b/doc/fr/examples.rst @@ -200,7 +200,7 @@ fen **Menu YACS de la fenêtre de sortie, et boite de dialogue montrant la sortie** On vérifie que le résultat est correct en observant si la fenêtre de sortie -contient la ligne suivante: +contient la ligne suivante:: Analysis = [0.5, 0.5, 0.5] @@ -314,7 +314,7 @@ Le dictionnaire doit script Python, en utilisant le nom obligatoire de variable "*AlgorithmParameters*" pour le dictionnaire. Toutes les clés dans le dictionnaire sont optionnelles, elles disposent toutes d'une valeur par défaut, -et elles peuvent être présentes sans être utiles. Par exemple: +et elles peuvent être présentes sans être utiles. Par exemple:: AlgorithmParameters = { "Minimizer" : "CG", # Choix possible : "LBFGSB", "TNC", "CG", "BFGS" @@ -585,8 +585,8 @@ donn print "Etape %2i : J = %.5e et X = %s"%(i, J[i], x_series[i]) print -Finalement, on obtient la description de l'ensemble des conditions d'expériences -à travers un ensemble de fichiers listés ici: +Finalement, on obtient la description de l'ensemble des conditions +d'expériences à travers la série de fichiers listée ici: #. ``Physical_data_and_covariance_matrices.py`` #. ``Physical_simulation_functions.py`` diff --git a/doc/fr/index.rst b/doc/fr/index.rst index f087d17..a501238 100644 --- a/doc/fr/index.rst +++ b/doc/fr/index.rst @@ -18,24 +18,22 @@ exp des informations sur leurs erreurs. Certaines des méthodes incluses dans ce cadre sont également connues sous les noms d'*estimation des paramètres*, de *problèmes inverses*, d'*estimation bayésienne*, d'*interpolation optimale*, -etc. De plus amples détails peuvent être trouvés dans la section +etc. De plus amples détails peuvent être trouvés dans la partie :ref:`section_theory`. -La documentation de ce module est divisée en plusieurs parties. La première -:ref:`section_intro` est une introduction. La deuxième partie -:ref:`section_theory` présente brièvement l'assimilation de données, -l'optimisation et les concepts. La troisième partie :ref:`section_using` -explique comment utiliser le module ADAO. La quatrième partie -:ref:`section_reference` donne une description détaillée de toutes les commandes -ADAO et des mots-clés. La cinquième partie :ref:`section_examples` donne des -exemples sur l'utilisation d'ADAO. Les utilisateurs intéressés par une -accès rapide au module peuvent sauter cette section, mais un usage utile +La documentation de ce module est divisée en plusieurs parties. La première est +une :ref:`section_intro`. La seconde partie présente :ref:`section_theory`, et à +leurs concepts. La troisième partie explique comment :ref:`section_using`. La +quatrième partie présente des exemples d'utilisation sous la forme de +:ref:`section_examples`. La cinquième partie détaille la +:ref:`section_reference`. Les utilisateurs intéressés par un accès rapide au +module peuvent s'arrêter avant la lecture de cette partie, mais un usage utile du module nécessite de lire et de revenir régulièrement aux troisième et -quatrième parties. La dernière partie :ref:`section_advanced` se focalise sur -des usages avancés du module, sur l'obtention de plus de renseignements, ou sur -l'usage par scripting, sans interface utilisateur graphique (GUI). Enfin, -n'oubliez pas de lire la partie :ref:`section_licence` pour respecter les -exigences de licence du module. +cinquième parties. La dernière partie se focalise sur des +:ref:`section_advanced`, sur l'obtention de renseignements supplémentaires, ou +sur l'usage par scripts, sans interface utilisateur graphique (GUI). Enfin, pour +respecter les exigences de licence du module, n'oubliez pas de lire la partie +:ref:`section_licence`. Dans cette documentation, on utilise les notations standards de l'algèbre linéaire, de l'assimilation de données (comme décrit dans [Ide97]_) et de @@ -54,10 +52,11 @@ Table des mati intro theory using - reference examples + reference advanced licence + glossary bibliography Index et tables @@ -65,4 +64,4 @@ Index et tables * :ref:`genindex` * :ref:`search` -* :ref:`section_glossary` +.. * :ref:`section_glossary` diff --git a/doc/fr/intro.rst b/doc/fr/intro.rst index 88bd094..9995c75 100644 --- a/doc/fr/intro.rst +++ b/doc/fr/intro.rst @@ -4,8 +4,8 @@ Introduction à ADAO ================================================================================ -L'objectif du module est ADAO **d'aider à l'usage de l'assimilation de données -ou de l'optimisation en lien avec d'autres modules ou codes de simulation dans +Le but du module est ADAO **d'aider à l'usage de l'assimilation de données ou de +l'optimisation en lien avec d'autres modules ou codes de simulation dans SALOME**. Le module ADAO fournit une interface à des algorithmes classiques d'assimilation de données ou d'optimisation, et permet d'intégrer leur usage dans une étude SALOME. Les modules de calcul ou de simulation doivent fournir @@ -13,9 +13,9 @@ 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 -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 +Son principal objectif est de **faciliter 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 problème physique, l'environnement lui permet d'avoir une démarche de type "souris\&click" pour construire un cas ADAO valide et pour l'évaluer. diff --git a/doc/fr/licence.rst b/doc/fr/licence.rst index 13bae49..6c71e35 100644 --- a/doc/fr/licence.rst +++ b/doc/fr/licence.rst @@ -13,7 +13,7 @@ tel qu'il est d - Copyright (C) 2008-2013 EDF R&D + Copyright (C) 2008-2014 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 diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index 26dc88b..f07ec3b 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -290,6 +290,12 @@ qui suit dans un fichier:: "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], } +Pour donner les valeurs de la commande "*AlgorithmParameters*" par une chaîne de +caractères, on doit utiliser des guillemets simples pour fournir une définition +standard de dictionnaire, comme par exemple:: + + '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}' + Cette section décrit les options disponibles algorithme par algorithme. De plus, pour chaque algorithme, les commandes/mots-clés obligatoires sont indiqués. Si une option est spécifiée par l'utilisateur pour un algorithme qui ne la supporte @@ -975,6 +981,10 @@ mod :math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes d'assimilation de données ou d'optimisation. +En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et +:math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et +ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur +Numpy) ou orientés (de type matrice Numpy). Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière @@ -1014,7 +1024,7 @@ la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par exemple, le script peut suivre le modèle suivant:: def DirectOperator( X ): - """ Direct non-linear simulation operator """ + """ Opérateur direct de simulation non-linéaire """ ... ... ... @@ -1035,7 +1045,7 @@ forme fonctionnelle avant son usage dans un cas ADAO, r complexité de l'implémentation de l'opérateur. **Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le -type de l'argument X peut être une liste, un vecteur ou une matrice Numpy 1D. +type de l'argument X peut être une liste, un vecteur ou une matrice Numpy. L'utilisateur doit traiter ces cas dans sa fonction. Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*" @@ -1060,25 +1070,25 @@ dans un script, avec trois noms obligatoires "*DirectOperator*", le squelette suivant:: def DirectOperator( X ): - """ Direct non-linear simulation operator """ + """ Opérateur direct de simulation non-linéaire """ ... ... ... - return something like Y + return quelque chose comme Y def TangentOperator( (X, dX) ): - """ Tangent linear operator, around X, applied to dX """ + """ Opérateur linéaire tangent, autour de X, appliqué à dX """ ... ... ... - return something like Y + return quelque chose comme Y def AdjointOperator( (X, Y) ): - """ Adjoint operator, around X, applied to Y """ + """ Opérateur adjoint, autour de X, appliqué à Y """ ... ... ... - return something like X + return quelque chose comme X Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la @@ -1090,9 +1100,9 @@ respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur doit renvoyer la matrice associée. **Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*" -et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``, Y``, -``dX`` peut être une liste, un vecteur ou une matrice Numpy 1D. L'utilisateur -doit traiter ces cas dans ses fonctions. +et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``, +``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy. +L'utilisateur doit traiter ces cas dans ses fonctions. Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*" +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -1187,11 +1197,11 @@ l'op Schématiquement, l'opérateur doit être constuit comme suit:: def DirectOperator( (X, U) ): - """ Direct non-linear simulation operator """ + """ Opérateur direct de simulation non-linéaire """ ... ... ... - return something like X(n+1) or Y(n+1) + return quelque chose comme X(n+1) (évolution) ou Y(n+1) (observation) Les opérateurs tangent et adjoint ont la même signature que précédemment, en notant que les dérivées doivent être faites seulement partiellement par rapport @@ -1262,7 +1272,7 @@ Seconde forme matricielle : utiliser la repr Au contraire, la seconde forme matricielle est une méthode très simplifiée pour définir une matrice. La matrice de covariance :math:`\mathbf{M}` est supposée être un multiple positif de la matrice identité. Cette matrice peut alors être -spécifiée uniquement par le multiplicateur :math:`m`: +spécifiée de manière unique par le multiplicateur :math:`m`: .. math:: \mathbf{M} = m \times \begin{pmatrix} 1 & 0 & \cdots & 0 \\ @@ -1271,11 +1281,11 @@ sp 0 & \cdots & 0 & 1 \end{pmatrix} -Le multiplicateur :math:`m` doit être un nombre réel ou entier positif (s'il est -négatif, ce qui est impossible, il est convertit en nombre positif). Par -exemple, une matrice simple diagonale unitaire de covariances des erreurs -d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de script Python -par:: +Le multiplicateur :math:`m` doit être un nombre réel ou entier positif (s'il +est négatif, ce qui est impossible car une matrice de covariance est positive, +il est convertit en nombre positif). Par exemple, une simple matrice diagonale +unitaire de covariances des erreurs d'ébauche :math:`\mathbf{B}` peut être +décrite dans un fichier de script Python par:: BackgroundError = 1. diff --git a/doc/fr/theory.rst b/doc/fr/theory.rst index 56d8b9b..c464032 100644 --- a/doc/fr/theory.rst +++ b/doc/fr/theory.rst @@ -5,7 +5,7 @@ Une br ================================================================================ .. index:: single: Data Assimilation -.. index:: single: Assimilation de données +.. index:: single: assimilation de données .. index:: single: état vrai .. index:: single: observation .. index:: single: a priori @@ -35,26 +35,27 @@ dans la section pour `Approfondir l'estimation d' d'optimisation`_, mais elles sont beaucoup plus générale et peuvent être utilisés sans les concepts d'assimilation de données. -Deux types principaux d'applications existent en l'assimilation de données, qui -sont couvert par le même formalisme : l'**identification de paramètres** et la +Deux types principaux d'applications existent en assimilation de données, qui +sont couverts par le même formalisme : l'**identification de paramètres** et la **reconstruction de champs**. Avant d'introduire la `Description simple du cadre méthodologique de l'assimilation de données`_ dans une prochaine section, nous décrivons brièvement ces deux types d'applications. A la fin de ce chapitre, quelques références permettent d'`Approfondir le cadre méthodologique de l'assimilation de données`_ et d'`Approfondir l'estimation d'état par des méthodes d'optimisation`_. - + Reconstruction de champs ou interpolation de données ---------------------------------------------------- .. index:: single: reconstruction de champs .. index:: single: interpolation de données +.. index:: single: interpolation de champs -La reconstruction de champs consiste à trouver, à partir d'un nombre restreint -de mesures réelles, le champs physique qui est le plus *consistant* avec ces -mesures. +La **reconstruction (ou l'interpolation) de champs** consiste à trouver, à +partir d'un nombre restreint de mesures réelles, le champs physique qui est le +plus *cohérent* avec ces mesures. -La consistance est à comprendre en termes d'interpolation, c'est-à-dire que le +La *cohérence* est à comprendre en termes d'interpolation, c'est-à-dire que le champ que l'on cherche à reconstruire, en utilisant de l'assimilation de données sur les mesures, doit s'adapter au mieux aux mesures, tout en restant contraint par la simulation globale du champ. Le champ calculé est donc une estimation *a @@ -73,29 +74,33 @@ plus, ces variables sont contraintes par les l'atmosphère, qui indiquent par exemple que la pression en un point ne peut pas prendre une valeur quelconque indépendamment de la valeur au même point à un temps précédent. On doit donc faire la reconstruction d'un champ en tout point -de l'espace, de manière "consistante" avec les équations d'évolution et avec les +de l'espace, de manière "cohérente" avec les équations d'évolution et avec les mesures aux précédents pas de temps. Identification de paramètres, ajustement de modèles, calibration ---------------------------------------------------------------- .. index:: single: identification de paramètres +.. index:: single: ajustement de paramètres .. index:: single: ajustement de modèles .. index:: single: calibration .. index:: single: ébauche .. index:: single: régularisation +.. index:: single: problèmes inverses -L'identification de paramètres par assimilation de données est une forme de -calibration d'état qui utilise simultanément les mesures 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 vrai. On peut -noter, en termes d'optimisation, que l'ébauche réalise la régularisation -mathématique du problème principal d'identification de paramètres. - -En pratique, les deux incrément observés "*calculs-ébauche*" et +L'**identification (ou l'ajustement) de paramètres** par assimilation de données +est une forme de calibration d'état qui utilise simultanément les mesures +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 +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*". + +En pratique, les deux écarts (ou incréments) observés "*calculs-ébauche*" et "*calculs-mesures*" 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 @@ -135,23 +140,27 @@ toutes les erreurs soient nulles et que le mod Dans le cas le plus simple, qui est statique, les étapes de simulation et d'observation peuvent être combinées en un unique opérateur d'observation noté -:math:`H` (linéaire ou non-linéaire). Il transforme les paramètres -:math:`\mathbf{x}` en entrée en résultats :math:`\mathbf{y}` qui peuvent être -directement comparés aux observations :math:`\mathbf{y}^o`. De plus, on utilise -l'opérateur linéarisé :math:`\mathbf{H}` pour représenter l'effet de l'opérateur -complet :math:`H` autour d'un point de linéarisation (et on omettra ensuite de -mentionner :math:`H` même si l'on peut le conserver). En réalité, on a déjà -indiqué que la nature stochastique des variables est essentielle, provenant du -fait que le modèle, l'ébauche et les observations sont tous incorrects. On -introduit donc des erreurs d'observations additives, sous la forme d'un vecteur -aléatoire :math:`\mathbf{\epsilon}^o` tel que : +:math:`H` (linéaire ou non-linéaire). Il transforme formellement les paramètres +:math:`\mathbf{x}` en entrée en résultats :math:`\mathbf{y}`, qui peuvent être +directement comparés aux observations :math:`\mathbf{y}^o` : + +.. math:: \mathbf{y} = H(\mathbf{x}) + +De plus, on utilise l'opérateur linéarisé :math:`\mathbf{H}` pour représenter +l'effet de l'opérateur complet :math:`H` autour d'un point de linéarisation (et +on omettra ensuite de mentionner :math:`H` même si l'on peut le conserver). En +réalité, on a déjà indiqué que la nature stochastique des variables est +essentielle, provenant du fait que le modèle, l'ébauche et les observations sont +tous incorrects. On introduit donc des erreurs d'observations additives, sous la +forme d'un vecteur aléatoire :math:`\mathbf{\epsilon}^o` tel que : .. math:: \mathbf{y}^o = \mathbf{H} \mathbf{x}^t + \mathbf{\epsilon}^o Les erreurs représentées ici ne sont pas uniquement celles des observations, ce sont aussi celles de la simulation. On peut toujours considérer que ces erreurs -sont de moyenne nulle. On peut alors définir une matrice :math:`\mathbf{R}` des -covariances d'erreurs d'observation par : +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 : .. math:: \mathbf{R} = E[\mathbf{\epsilon}^o.{\mathbf{\epsilon}^o}^T] @@ -177,19 +186,19 @@ classiquement .. 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}) -qui est usuellement désignée comme la fonctionnelle "*3D-VAR*". Comme les -matrices de covariance :math:`\mathbf{B}` et :math:`\mathbf{R}` sont -proportionnelles aux variances d'erreurs, leur présente 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 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 tout la panoplie des méthodes de minimisation de fonctions connues par -ailleurs en optimisation (voir aussi la section `Approfondir l'estimation d'état -par des méthodes d'optimisation`_). Selon la taille du vecteur -:math:`\mathbf{x}` des paramètres à identifier, et la disponibilité du gradient -ou de la hessienne de :math:`J`, il est judicieux d'adapter la méthode -d'optimisation choisie (gradient, Newton, quasi-Newton...). +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 +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 +minimisation de fonctions connues par ailleurs en optimisation (voir aussi la +section `Approfondir l'estimation d'état par des méthodes d'optimisation`_). +Selon la taille du vecteur :math:`\mathbf{x}` des paramètres à identifier, et la +disponibilité du gradient ou de la hessienne de :math:`J`, il est judicieux +d'adapter la méthode d'optimisation choisie (gradient, Newton, quasi-Newton...). En **assimilation par filtrage**, dans ce cas simple usuellement dénommé "*BLUE*" (pour "*Best Linear Unbiased Estimator*"), l'analyse @@ -208,8 +217,8 @@ L'avantage du filtrage est le calcul explicite du gain, pour produire ensuite la matrice *a posteriori* de covariance d'analyse. Dans ce cas statique simple, on peut montrer, sous une hypothèse de -distributions gaussiennes d'erreurs, que les deux approches *variationnelle* et -*de filtrage* sont équivalentes. +distributions gaussiennes d'erreurs (très peu restrictive en pratique), 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 "*filtre @@ -233,11 +242,11 @@ Approfondir le cadre m .. index:: single: méthodes de lissage Pour obtenir de plus amples informations sur les techniques d'assimilation de -données, le lecteur pour consulter les documents introductifs comme [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]_. +données, le lecteur peut consulter les documents introductifs comme +[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]_. 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. @@ -267,7 +276,7 @@ forme 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 :math:`\mathbf{R}`. La minimisation de la fonctionnelle :math:`J` conduit à la -*meilleure* estimation de l'état `\mathbf{x}`. +*meilleure* estimation de l'état :math:`\mathbf{x}`. Les possibilités d'extension de cette estimation d'état, en utilisant de manière plus explicite des méthodes d'optimisation et leurs propriétés, peuvent être diff --git a/doc/fr/using.rst b/doc/fr/using.rst index cc73884..0a7e18d 100644 --- a/doc/fr/using.rst +++ b/doc/fr/using.rst @@ -81,7 +81,9 @@ le menu principal "*ADAO*") pour cr Pour construire un cas en utilisant EFICAS, on doit passer par une série de sous-étapes, en choisissant, à chaque étape, un mot-clé puis en remplissant ses -valeurs. +valeurs. On note que c'est dans cette étape qu'il faut, entre autres, définir +l'**appel au code de simulation** utilisé dans les opérateurs d'observation ou +d'évolution décrivant le problème [#]_. L'éditeur structuré indique des types hiérarchiques, des valeurs ou des mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par @@ -227,6 +229,8 @@ comme d .. [#] Pour de plus amples informations sur EFICAS, voir le *module EFICAS* et son aide disponible dans l'environnement SALOME. +.. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent. + .. [#] Pour de plus amples informations sur YACS, voir le *Guide utilisateur du module YACS* disponible dans le menu principal *Aide* de l'environnement SALOME. .. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`. -- 2.39.2