bin/qtEficas_adao_study.py
doc/Makefile
doc/en/Makefile
+ doc/fr/Makefile
])
AC_OUTPUT
#
# Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
-SUBDIRS = en
+SUBDIRS = en fr
================================================================================
This section presents advanced methods to use the ADAO module, how to get more
-information, or how to use it without the graphical user interface (GUI). It
-requires to know how to find files or commands included inside the whole SALOME
-installation. All the names to be replaced by user are indicated by the
-following syntax ``<...>``.
+information during calculation, or how to use it without the graphical user
+interface (GUI). It requires to know how to find files or commands included
+inside the whole SALOME installation. All the names to be replaced by user are
+indicated by the syntax ``<...>``.
Converting and executing an ADAO command file (JDC) using a shell script
------------------------------------------------------------------------
-It is possible to convert and execute an ADAO command file (JDC, or ".comm"
-file, which resides in ``<ADAO JDC file directory>``) automatically by using a
-template script containing all the required steps. The user has to know where
-are the main SALOME scripts, and in particular the ``runAppli`` one. The
-directory in which this script resides is symbolically named ``<SALOME main
-installation dir>`` and has to be replaced by the good one in the template.
-
-When an ADAO command file is build by the ADAO GUI editor and saved, if it is
-named for example "AdaoStudy1.comm", then a companion file named "AdaoStudy1.py"
-is automatically created in the same directory. It is named ``<ADAO Python
-file>`` in the template, and it is converted to YACS as an ``<ADAO YACS xml
-scheme>``. After that, it can be executed in console mode using the standard
-YACS console command (see YACS documentation for more information).
+It is possible to convert and execute an ADAO command file (JDC, or ".comm/.py"
+files pair, which resides in ``<ADAO JDC file directory>``) automatically by
+using a template shell script containing all the required steps. The user has to
+know where are the main SALOME launching files, and in particular the
+``runAppli`` one. The directory in which this script resides is symbolically
+named ``<SALOME main installation dir>`` and has to be replaced by the good one
+in the shell file template.
+
+When an ADAO command file is build by the ADAO GUI EFICAS editor and saved, if
+it is named for example "AdaoStudy1.comm", then a companion file named
+"AdaoStudy1.py" is automatically created in the same directory. It is named
+``<ADAO Python file>`` in the template, and it is converted to YACS as an
+``<ADAO YACS xml scheme>``. After that, it can be executed in console mode using
+the standard YACS console command (see YACS documentation for more information).
In the example, we choose to start and stop the SALOME application server in the
same script, which is not necessary, but useful to avoid stalling SALOME
-sessions. We choose also to remove the ``<ADAO YACS xml scheme>`` because it is
-a generated one. You only need to replace the text between these symbols
-``<...>`` to use it.
+sessions. We choose also to remove the ``<ADAO YACS xml scheme>`` file because
+it is a generated one. The user of this script only need to replace the text
+between these symbols ``<...>``.
The template of the shell script is the following::
This section describes how to execute in TUI (Text User Interface) mode a YACS
calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
the standard YACS TUI mode, which is briefly recalled here (see YACS
-documentation for more information) through a simple example. As seen in
+documentation for more information) through a simple example. As described in
documentation, a XML scheme can be loaded in a Python. We give here a whole
sequence of command lines to test the validity of the scheme before executing
it, adding some initial supplementary ones to explicitly load the types catalog
Getting information on special variables during the ADAO calculation in YACS
-----------------------------------------------------------------------------
-Some special variables, used during calculations, can be monitored during the
-ADAO calculation in YACS. These variables can be printed, plotted, saved, etc.
-This can be done using "*observers*", that are scripts associated with one
-variable. In order to use this feature, one has to build scripts using as
-standard inputs (available in the namespace) the variables ``var`` and ``info``.
-The variable ``var`` is to be used in the same way as for the final ADD object,
-that is as a list/tuple object.
+Some special internal optimization variables, used during calculations, can be
+monitored during the ADAO calculation in YACS. These variables can be printed,
+plotted, saved, etc. This can be done using "*observers*", that are scripts,
+each associated with one variable. In order to use this feature, the user has to
+build scripts using as standard inputs (e.g. available in the namespace) the
+variables ``var`` and ``info``. The variable ``var`` is to be used in the same
+way as for the final ADD object, that is as a list/tuple object.
Some templates are available when editing the ADAO case in EFICAS editor. These
-simple scripts can be customized by the user, either at the EFICAS edition stage
-or at the YACS edition stage, to improve the tuning of the ADAO calculation in
-YACS.
+simple scripts can be customized by the user, either at the EFICAS edition
+stage, or at the YACS edition stage, to improve the tuning of the ADAO
+calculation in YACS.
As an example, here is one very simple script (similar to the "*ValuePrinter*"
template) used to print the value of one monitored variable::
print " --->",info," Value =",var[-1]
-Stored in a python file, this script can be associated to each variable
+Stored in a Python file, this script can be associated to each variable
available in the "*SELECTION*" keyword of the "*Observers*" command:
"*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
variable will be printed at each step of the optimization or assimilation
-algorithm. The observers can embed plotting capabilities, storage, printing,
-etc.
+algorithm. The observers can embed plotting capabilities, storage, complex
+printing, statistical treatment, etc.
Getting more information when running a calculation
---------------------------------------------------
-When running, useful data and messages are logged. There are two ways to obtain
-theses information.
+When running a calculation, useful data and messages are logged. There are two
+ways to obtain theses information.
The first one, and the preferred way, is to use the built-in variable "*Debug*"
-available in every ADAO case. It is available through the GUI of the module.
-Setting it to "*1*" will send messages in the log window of the YACS scheme
-execution.
+available in every ADAO case. It is available through the edition GUI of the
+module. Setting it to "*1*" will send messages in the log window of the YACS
+scheme execution.
The second one consist in using the "*logging*" native module of Python (see the
Python documentation http://docs.python.org/library/logging.html for more
of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
"*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
certain level will be printed for whatever activated level above this particular
-one (included). The easiest way is to change the log level is to write the
+one (included). The easiest way is to change the log level by using the
following Python lines::
import logging
The standard logging module default level is "*WARNING*", the default level in
the ADAO module is "*INFO*".
-It is also recommended to include in the simulation code some logging or debug
-mechanisms and use them in conjunction with the two previous methods. But be
-careful not to store too big variables because it cost time, whatever logging
-level is chosen.
+It is also recommended to include some logging or debug mechanisms in the
+simulation code, and use them in conjunction with the two previous methods. But
+be careful not to store too big variables because it cost time, whatever logging
+level is chosen (that is, even if these variables are not printed).
Switching from a version of ADAO to a newer one
-----------------------------------------------
-The ADAO module and cases are identified as versions, with "Major", "Minor" and
-"Revision" characteristics. A particular version is numbered as
-"Major.Minor.Revision".
+The ADAO module and its ".comm" case files are identified by versions, with
+"Major", "Minor" and "Revision" characteristics. A particular version is
+numbered as "Major.Minor.Revision", with strong link with the numbering of the
+SALOME platform.
-Each version of the ADAO module can read ADAO case files of the previous minor
-version. In general, it can also read ADAO case files of all the previous minor
-versions for one major branch. In general also, an ADAO case file for one
-version can not be read by a previous minor or major version.
+Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
+of the previous minor version "Major.Minor-1.*". In general, it can also read
+ADAO case files of all the previous minor versions for one major branch, but it
+is not guaranteed for all the commands or keywords. In general also, an ADAO
+case file for one version can not be read by a previous minor or major version
+of the ADAO module.
Switching from 6.6 to 7.2
+++++++++++++++++++++++++
-There is no known incompatibility for the ADAO case file. The upgrade procedure
+There is no known incompatibility for the ADAO case files. The upgrade procedure
is to read the old ADAO case file with the new SALOME/ADAO module, and save it
with a new name.
There is one incompatibility introduced for the post-processing or observer
script files. The old syntax to call a result object, such as the "*Analysis*"
-one in a script provided through the "*UserPostAnalysis*" keyword), was for
+one (in a script provided through the "*UserPostAnalysis*" keyword), was for
example::
Analysis = ADD.get("Analysis").valueserie(-1)
Analysis = ADD.get("Analysis").valueserie()
-The new syntax is entirely similar to the classical one of a list/tuple object::
+The new syntax is entirely similar to the (classical) one of a list or tuple
+object::
Analysis = ADD.get("Analysis")[-1]
Analysis = ADD.get("Analysis")[:]
is to read the old ADAO case file with the new SALOME/ADAO module, and save it
with a new name.
-There is one incompatibility introduced for the designation of operators used to
-for the observation operator. The new mandatory names are "*DirectOperator*",
+There is one incompatibility introduced for the naming of operators used to for
+the observation operator. The new mandatory names are "*DirectOperator*",
"*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
-of the chapter :ref:`section_reference`.
+of the chapter :ref:`section_reference`. The operator scripts has to be
+modified.
Switching from 6.4 to 6.5
+++++++++++++++++++++++++
:scale: 50%
This section presents some examples on using the ADAO module in SALOME. The
-first one shows how to build a simple data assimilation case defining
-explicitly all the required data through the GUI. The second one shows, on the
-same case, how to define data using external sources through scripts.
+first one shows how to build a simple data assimilation case defining explicitly
+all the required input data through the GUI. The second one shows, on the same
+case, how to define input data using external sources through scripts. We
+describe here always Python scripts because they can be directly inserted in
+YACS script nodes, but external files can use other langages.
-Building a simple estimation case with explicit data definition
----------------------------------------------------------------
+The mathematical notations used afterward are explained in the section
+:ref:`section_theory`.
+
+Building an estimation case with explicit data definition
+---------------------------------------------------------
This simple example is a demonstration one, and describes how to set a BLUE
estimation framework in order to get *ponderated (or fully weighted) least
the weighted middle between the observation and the background vectors. All the
numerical values of this example are arbitrary.
-Experimental set up
-+++++++++++++++++++
+Experimental setup
+++++++++++++++++++
We choose to operate in a 3-dimensional space. 3D is chosen in order to restrict
the size of numerical object to explicitly enter by the user, but the problem is
-not dependant of the dimension and can be set in dimension 1000... The
-observation :math:`\mathbf{y}^o` is of value 1 in each direction, so:
+not dependant of the dimension and can be set in dimension 10, 100, 1000... The
+observation :math:`\mathbf{y}^o` is of value 1 in each direction, so::
- ``Yo = [1 1 1]``
+ Yo = [1 1 1]
The background state :math:`\mathbf{x}^b`, which represent some *a priori*
-knowledge or a regularization, is of value of 0 in each direction, which is:
+knowledge or a mathematical regularization, is of value of 0 in each direction,
+which is::
- ``Xb = [0 0 0]``
+ Xb = [0 0 0]
Data assimilation requires information on errors covariances :math:`\mathbf{R}`
-and :math:`\mathbf{B}` respectively for observation and background variables. We
-choose here to have uncorrelated errors (that is, diagonal matrices) and to have
-the same variance of 1 for all variables (that is, identity matrices). We get:
+and :math:`\mathbf{B}`, respectively for observation and background variables.
+We choose here to have uncorrelated errors (that is, diagonal matrices) and to
+have the same variance of 1 for all variables (that is, identity matrices). We
+set::
- ``B = R = [1 0 0 ; 0 1 0 ; 0 0 1]``
+ B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
Last, we need an observation operator :math:`\mathbf{H}` to convert the
-background value in the space of observation value. Here, because the space
-dimensions are the same, we can choose the identity as the observation
-operator:
+background value in the space of observation values. Here, because the space
+dimensions are the same, we can choose the identity as the observation
+operator::
- ``H = [1 0 0 ; 0 1 0 ; 0 0 1]``
+ H = [1 0 0 ; 0 1 0 ; 0 0 1]
-With such choices, the Best Linear Unbiased Estimator (BLUE) will be the average
-vector between :math:`\mathbf{y}^o` and :math:`\mathbf{x}^b`, named the
-*analysis* and denoted by :math:`\mathbf{x}^a`:
+With such choices, the "Best Linear Unbiased Estimator" (BLUE) will be the
+average vector between :math:`\mathbf{y}^o` and :math:`\mathbf{x}^b`, named the
+*analysis*, denoted by :math:`\mathbf{x}^a`, and its value is::
- ``Xa = [0.5 0.5 0.5]``
+ Xa = [0.5 0.5 0.5]
-As en extension of this example, one can change the variances for
-:math:`\mathbf{B}` or :math:`\mathbf{R}` independently, and the analysis will
-move to :math:`\mathbf{y}^o` or to :math:`\mathbf{x}^b` in inverse proportion of
-the variances in :math:`\mathbf{B}` and :math:`\mathbf{R}`. It is also
+As an extension of this example, one can change the variances represented by
+:math:`\mathbf{B}` or :math:`\mathbf{R}` independently, and the analysis
+:math:`\mathbf{x}^a` will move to :math:`\mathbf{y}^o` or to
+:math:`\mathbf{x}^b`, in inverse proportion of the variances in
+:math:`\mathbf{B}` and :math:`\mathbf{R}`. As an other extension, it is also
equivalent to search for the analysis thought a BLUE algorithm or a 3DVAR one.
-Using the GUI to build the ADAO case
-++++++++++++++++++++++++++++++++++++
+Using the graphical interface (GUI) to build the ADAO case
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
First, you have to activate the ADAO module by choosing the appropriate module
button or menu of SALOME, and you will see:
**Activating the module ADAO in SALOME**
Choose the "*New*" button in this window. You will directly get the EFICAS
-interface for variables definition, along with the "*Object browser*". You can
-then click on the "*New*" button |eficas_new| to create a new ADAO case, and you
-will see:
+interface for variables definition, along with the SALOME "*Object browser*".
+You can then click on the "*New*" button |eficas_new| to create a new ADAO case,
+and you will see:
.. _adao_viewer:
.. image:: images/adao_viewer.png
:align: center
:width: 100%
.. centered::
- **The EFICAS viewer for cases definition in module ADAO**
+ **The EFICAS editor for cases definition in module ADAO**
-Then fill in the variables to build the ADAO case by using the experimental set
+Then, fill in the variables to build the ADAO case by using the experimental set
up described above. All the technical information given above will be directly
inserted in the ADAO case definition, by using the *String* type for all the
variables. When the case definition is ready, save it to a "*JDC (\*.comm)*"
:align: center
:width: 100%
.. centered::
- **Definition of the experimental set up chosen for the ADAO case**
+ **Definition of the experimental setup chosen for the ADAO case**
To go further, we need now to generate the YACS scheme from the ADAO case
definition. In order to do that, right click on the name of the file case in the
**"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
This command will generate the YACS scheme, activate YACS module in SALOME, and
-open the new scheme in the GUI of the YACS module [#]_. After reordering the
-nodes by using the "*arrange local node*" sub-menu of the YACS graphical view of
-the scheme, you get the following representation of the generated ADAO scheme:
+open the new scheme in the GUI of the YACS module [#]_. After eventually
+reordering the nodes by using the "*arrange local nodes*" sub-menu of the YACS
+graphical view of the scheme, you get the following representation of the
+generated ADAO scheme:
.. _yacs_generatedscheme:
.. image:: images/yacs_generatedscheme.png
**YACS generated scheme from the ADAO case**
After that point, all the modifications, executions and post-processing of the
-data assimilation scheme will be done in YACS. In order to check the result in a
-simple way, we create here a new YACS node by using the "*in-line script node*"
-sub-menu of the YACS graphical view, and we name it "*PostProcessing*".
+data assimilation scheme will be done in the YACS module. In order to check the
+result in a simple way, we create here a new YACS node by using the "*in-line
+script node*" sub-menu of the YACS graphical view, and we name it
+"*PostProcessing*".
-This script will retrieve the data assimilation analysis from the
+This script node will retrieve the data assimilation analysis from the
"*algoResults*" output port of the computation bloc (which gives access to a
SALOME Python Object), and will print it on the standard output.
To obtain this, the in-line script node need to have an input port of type
-"*pyobj*" named "*results*" for example, that have to be linked graphically to
-the "*algoResults*" output port of the computation bloc. Then the code to fill
+"*pyobj*", named "*results*" for example, that have to be linked graphically to
+the "*algoResults*" output port of the computation bloc. Then, the code to fill
in the script node is::
Xa = results.ADD.get("Analysis")[-1]
print
The augmented YACS scheme can be saved (overwriting the generated scheme if the
-simple "*Save*" command or button are used, or with a new name). Ideally, the
-implementation of such post-processing procedure can be done in YACS to test,
-and then entirely saved in one script that can be integrated in the ADAO case by
-using the keyword "*UserPostAnalysis*".
+"*Save*" command or button are used, or with a new name through the "*Save as*"
+command). Ideally, the implementation of such post-processing procedure can be
+done in YACS to test, and then entirely saved in one Python script that can be
+integrated in the ADAO case by using the keyword "*UserPostAnalysis*".
-Then, classically in YACS, it have to be prepared for run, and then executed.
-After completion, the printing on standard output is available in the "*YACS
-Container Log*", obtained through the right click menu of the "*proc*" window in
-the YACS scheme as shown below:
+Then, classically in YACS, the scheme have to be compiled for run, and then
+executed. After completion, the printing on standard output is available in the
+"*YACS Container Log*", obtained through the right click menu of the "*proc*"
+window in the YACS scheme as shown below:
.. _yacs_containerlog:
.. image:: images/yacs_containerlog.png
.. centered::
**Defining an ADAO 3DVAR case looks completely similar to a BLUE case**
-There is only one command changing, with "*3DVAR*" value instead of "*Blue*".
+There is only one command changing, with "*3DVAR*" value in the "*Algorithm*"
+field instead of "*Blue*".
-Building a simple estimation case with external data definition by scripts
---------------------------------------------------------------------------
+Building a estimation case with external data definition by scripts
+-------------------------------------------------------------------
It is useful to get parts or all of the data from external definition, using
Python script files to provide access to the data. As an example, we build here
-an ADAO case representing the same experimental set up as in the above example
-`Building a simple estimation case with explicit data definition`_, but using
-data form a single one external Python script file.
+an ADAO case representing the same experimental setup as in the above example
+`Building an estimation case with explicit data definition`_, but using data
+from a single one external Python script file.
First, we write the following script file, using conventional names for the
-desired variables. Here, all the input variables are defined in the script, but
-the user can choose to split the file in several ones, or to mix explicit data
-definition in the ADAO GUI and implicit data definition by external files. The
-present script looks like::
+required variables. Here, all the input variables are defined in the same
+script, but the user can choose to split the file in several ones, or to mix
+explicit data definition in the ADAO GUI and implicit data definition by
+external files. The present script file looks like::
import numpy
#
ObservationOperator = numpy.identity(3)
The names of the Python variables above are mandatory, in order to define the
-right variables, but the Python script can be bigger and define classes,
-functions, etc. with other names. It shows different ways to define arrays and
-matrices, using list, string (as in Numpy or Octave), Numpy array type or Numpy
-matrix type, and Numpy special functions. All of these syntax are valid.
-
-After saving this script somewhere in your path (named here "*script.py*" for
-the example), we use the GUI to build the ADAO case. The procedure to fill in
-the case is similar except that, instead of selecting the "*String*" option for
-the "*FROM*" keyword, we select the "*Script*" one. This leads to a
-"*SCRIPT_DATA/SCRIPT_FILE*" entry in the tree, allowing to choose a file as:
+right case variables, but the Python script can be bigger and define classes,
+functions, file or database access, etc. with other names. Moreover, the above
+script shows different ways to define arrays and matrices, using list, string
+(as in Numpy or Octave), Numpy array type or Numpy matrix type, and Numpy
+special functions. All of these syntax are valid.
+
+After saving this script in a file (named here "*script.py*" for the example)
+somewhere in your path, we use the graphical interface (GUI) to build the ADAO
+case. The procedure to fill in the case is similar to the previous example
+except that, instead of selecting the "*String*" option for the "*FROM*" keyword
+of each variable, we select the "*Script*" one. This leads to a
+"*SCRIPT_DATA/SCRIPT_FILE*" entry in the graphical tree, allowing to choose a
+file as:
.. _adao_scriptentry01:
.. image:: images/adao_scriptentry01.png
.. centered::
**Defining an input value using an external script file**
-Other steps and results are exactly the same as in the `Building a simple
-estimation case with explicit data definition`_ previous example.
+Other steps and results are exactly the same as in the `Building an estimation
+case with explicit data definition`_ previous example.
-In fact, this script methodology allows to retrieve data from in-line or previous
-calculations, from static files, from database or from stream, all of them
-outside of SALOME. It allows also to modify easily some input data, for example
-for debug purpose or for repetitive execution process, and it is the most
-versatile method in order to parametrize the input data. **But be careful,
-script methodology is not a "safe" procedure, in the sense that erroneous
-data, or errors in calculations, can be directly injected into the YACS scheme
-execution.**
+In fact, this script methodology is the easiest way to retrieve data from
+in-line or previous calculations, from static files, from database or from
+stream, all of them inside or outside of SALOME. It allows also to modify easily
+some input data, for example for debug purpose or for repetitive execution
+process, and it is the most versatile method in order to parametrize the input
+data. **But be careful, script methodology is not a "safe" procedure, in the
+sense that erroneous data, or errors in calculations, can be directly injected
+into the YACS scheme execution.**
Adding parameters to control the data assimilation algorithm
------------------------------------------------------------
One can add some optional parameters to control the data assimilation algorithm
calculation. This is done by using the "*AlgorithmParameters*" keyword in the
-definition of the ADAO case, which is an keyword of the ASSIMILATION_STUDY. This
-keyword requires a Python dictionary, containing some key/value pairs. The list
-of possible optional parameters are given in the subsection
-:ref:`section_reference`.
-
-If no bounds at all are required on the control variables, then one can choose
-the "BFGS" or "CG" minimisation algorithm for the 3DVAR algorithm. For
-constrained optimization, the minimizer "LBFGSB" is often more robust, but the
-"TNC" is sometimes more performant.
+definition of the ADAO case, which is an keyword of the "*ASSIMILATION_STUDY*"
+general command. This keyword requires a Python dictionary, containing some
+key/value pairs. The list of possible optional parameters are given in the
+subsection :ref:`section_reference`.
This dictionary has to be defined, for example, in an external Python script
file, using the mandatory variable name "*AlgorithmParameters*" for the
"MaximumNumberOfSteps" : 10,
}
+If no bounds at all are required on the control variables, then one can choose
+the "*BFGS*" or "*CG*" minimisation algorithm for all the variational data
+assimilation or optimization algorithms. For constrained optimization, the
+minimizer "*LBFGSB*" is often more robust, but the "*TNC*" is sometimes more
+performant.
+
Then the script can be added to the ADAO case, in a file entry describing the
"*AlgorithmParameters*" keyword, as follows:
:align: center
:width: 100%
.. centered::
- **Adding parameters to control the algorithm**
+ **Adding parameters to control the algorithm and the outputs**
-Other steps and results are exactly the same as in the `Building a simple
-estimation case with explicit data definition`_ previous example. The dictionary
-can also be directly given in the input field associated with the keyword.
+Other steps and results are exactly the same as in the `Building an estimation
+case with explicit data definition`_ previous example. The dictionary can also
+be directly given in the input field of string type associated for the keyword.
Building a complex case with external data definition by scripts
----------------------------------------------------------------
This more complex and complete example has to been considered as a framework for
-user inputs, that need to be tailored for each real application. Nevertheless,
-the file skeletons are sufficiently general to have been used for various
-applications in neutronic, fluid mechanics... Here, we will not focus on the
-results, but more on the user control of inputs and outputs in an ADAO case. As
-previously, all the numerical values of this example are arbitrary.
-
-The objective is to set up the input and output definitions of a physical case
-by external python scripts, using a general non-linear operator, adding control
-on parameters and so on... The complete framework scripts can be found in the
-ADAO skeletons examples directory under the name
+user inputs treatment, that need to be tailored for each real application.
+Nevertheless, the file skeletons are sufficiently general to have been used for
+various applications in neutronic, fluid mechanics... Here, we will not focus on
+the results, but more on the user control of inputs and outputs in an ADAO case.
+As previously, all the numerical values of this example are arbitrary.
+
+The objective is to setup the input and output definitions of a physical
+estimation case by external python scripts, using a general non-linear operator,
+adding control on parameters and so on... The complete framework scripts can be
+found in the ADAO skeletons examples directory under the name
"*External_data_definition_by_scripts*".
-Experimental set up
-+++++++++++++++++++
+Experimental setup
+++++++++++++++++++
We continue to operate in a 3-dimensional space, in order to restrict
the size of numerical object shown in the scripts, but the problem is
-not dependant of the dimension.
+not dependant of the dimension.
We choose a twin experiment context, using a known true state
-:math:`\mathbf{x}^t` of arbitrary values:
+:math:`\mathbf{x}^t` but of arbitrary value::
- ``Xt = [1 2 3]``
+ Xt = [1 2 3]
The background state :math:`\mathbf{x}^b`, which represent some *a priori*
-knowledge of the true state, is build as a normal random perturbation of 20% the
-true state :math:`\mathbf{x}^t` for each component, which is:
+knowledge of the true state, is build as a normal random perturbation of 20% of
+the true state :math:`\mathbf{x}^t` for each component, which is::
- ``Xb = Xt + normal(0, 20%*Xt)``
+ Xb = Xt + normal(0, 20%*Xt)
To describe the background error covariances matrix :math:`\mathbf{B}`, we make
as previously the hypothesis of uncorrelated errors (that is, a diagonal matrix,
of size 3x3 because :math:`\mathbf{x}^b` is of lenght 3) and to have the same
-variance of 0.1 for all variables. We get:
+variance of 0.1 for all variables. We get::
- ``B = 0.1 * diagonal( length(Xb) )``
+ B = 0.1 * diagonal( length(Xb) )
We suppose that there exist an observation operator :math:`\mathbf{H}`, which
can be non linear. In real calibration procedure or inverse problems, the
Being in twin experiments, the observation :math:`\mathbf{y}^o` and its error
covariances matrix :math:`\mathbf{R}` are generated by using the true state
-:math:`\mathbf{x}^t` and the observation operator :math:`\mathbf{H}`:
+:math:`\mathbf{x}^t` and the observation operator :math:`\mathbf{H}`::
- ``Yo = H( Xt )``
+ Yo = H( Xt )
-and, with an arbitrary standard deviation of 1% on each error component:
+and, with an arbitrary standard deviation of 1% on each error component::
- ``R = 0.0001 * diagonal( lenght(Yo) )``
+ R = 0.0001 * diagonal( lenght(Yo) )
-All the required data assimilation informations are then defined.
+All the informations required for estimation by data assimilation are then
+defined.
Skeletons of the scripts describing the setup
+++++++++++++++++++++++++++++++++++++++++++++
-We give here the essential parts of each script used afterwards to build the ADAO
-case. Remember that using these scripts in real Python files requires to
+We give here the essential parts of each script used afterwards to build the
+ADAO case. Remember that using these scripts in real Python files requires to
correctly define the path to imported modules or codes (even if the module is in
-the same directory that the importing Python file ; we indicate the path
+the same directory that the importing Python file. We indicate the path
adjustment using the mention ``"# INSERT PHYSICAL SCRIPT PATH"``), the encoding
if necessary, etc. The indicated file names for the following scripts are
arbitrary. Examples of complete file scripts are available in the ADAO examples
return S
We can then define the background state :math:`\mathbf{x}^b` as a random
-perturbation of the true state, adding at the end of the script the definition
-of a *required ADAO variable* in order to export the defined value. It is done
-in a Python script file named ``Script_Background_xb.py``::
+perturbation of the true state, adding a *required ADAO variable* at the end of
+the script the definition, in order to export the defined value. It is done in a
+Python script file named ``Script_Background_xb.py``::
from Physical_data_and_covariance_matrices import True_state
import numpy
Background = list(xb)
In the same way, we define the background error covariance matrix
-:math:`\mathbf{B}` as a diagonal matrix of the same diagonal length as the
+:math:`\mathbf{B}` as a diagonal matrix, of the same diagonal length as the
background of the true state, using the convenient function already defined. It
is done in a Python script file named ``Script_BackgroundError_B.py``::
#
return numpy.array( HX )
-We does not need the operators ``"TangentOperator"`` and ``"AdjointOperator"``
-because they will be approximated using ADAO capabilities.
+We does not need the linear compagnion operators ``"TangentOperator"`` and
+``"AdjointOperator"`` because they will be approximated using ADAO capabilities.
We insist on the fact that these non-linear operator ``"DirectOperator"``,
tangent operator ``"TangentOperator"`` and adjoint operator
``"AdjointOperator"`` come from the physical knowledge, include the reference
-physical simulation code and its eventual adjoint, and have to be carefully set
-up by the data assimilation user. The errors in or missuses of the operators can
-not be detected or corrected by the data assimilation framework alone.
+physical simulation code, and have to be carefully setup by the data
+assimilation or optimization user. The simulation errors or missuses of the
+operators can not be detected or corrected by the data assimilation and
+optimization ADAO framework alone.
In this twin experiments framework, the observation :math:`\mathbf{y}^o` and its
error covariances matrix :math:`\mathbf{R}` can be generated. It is done in two
ObservationError = R
As in previous examples, it can be useful to define some parameters for the data
-assimilation algorithm. For example, if we use the standard 3DVAR algorithm, the
-following parameters can be defined in a Python script file named
+assimilation algorithm. For example, if we use the standard "*3DVAR*" algorithm,
+the following parameters can be defined in a Python script file named
``Script_AlgorithmParameters.py``::
# Creating the required ADAO variable
Finally, it is common to post-process the results, retrieving them after the
data assimilation phase in order to analyze, print or show them. It requires to
-use a intermediary Python script file in order to extract these results. The
-following example Python script file named ``Script_UserPostAnalysis.py``,
-illustrates the fact::
+use a intermediary Python script file in order to extract these results at the
+end of the adata assimilation or optimization process. The following example
+Python script file, named ``Script_UserPostAnalysis.py``, illustrates the fact::
from Physical_data_and_covariance_matrices import True_state
import numpy
print "xa = %s"%numpy.array(xa)
print
for i in range( len(x_series) ):
- print "Step %2i : J = %.5e et X = %s"%(i, J[i], x_series[i])
+ print "Step %2i : J = %.5e and X = %s"%(i, J[i], x_series[i])
print
At the end, we get a description of the whole case setup through a set of files
#. ``Script_UserPostAnalysis.py``
We insist here that all these scripts are written by the user and can not be
-automatically tested. So the user is required to verify the scripts (and in
-particular their input/output) in order to limit the difficulty of debug. We
+automatically tested by ADAO. So the user is required to verify the scripts (and
+in particular their input/output) in order to limit the difficulty of debug. We
recall: **script methodology is not a "safe" procedure, in the sense that
erroneous data, or errors in calculations, can be directly injected into the
YACS scheme execution.**
differential increment.
The other steps to build the ADAO case are exactly the same as in the `Building
-a simple estimation case with explicit data definition`_ previous section.
+an estimation case with explicit data definition`_ previous section.
Using the simple linear operator :math:`\mathbf{H}` from the Python script file
``Physical_simulation_functions.py`` in the ADAO examples standard directory,
xt = [1 2 3]
xa = [ 1.000014 2.000458 3.000390]
- Step 0 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
- Step 1 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
- Step 2 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
- Step 3 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
- Step 4 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
- Step 5 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
- Step 6 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
- Step 7 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
- Step 8 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
- Step 9 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
- Step 10 : J = 1.81568e+00 et X = [1.000013, 2.000458, 3.000390]
+ Step 0 : J = 1.81750e+03 and X = [1.014011, 2.459175, 3.390462]
+ Step 1 : J = 1.81750e+03 and X = [1.014011, 2.459175, 3.390462]
+ Step 2 : J = 1.79734e+01 and X = [1.010771, 2.040342, 2.961378]
+ Step 3 : J = 1.79734e+01 and X = [1.010771, 2.040342, 2.961378]
+ Step 4 : J = 1.81909e+00 and X = [1.000826, 2.000352, 3.000487]
+ Step 5 : J = 1.81909e+00 and X = [1.000826, 2.000352, 3.000487]
+ Step 6 : J = 1.81641e+00 and X = [1.000247, 2.000651, 3.000156]
+ Step 7 : J = 1.81641e+00 and X = [1.000247, 2.000651, 3.000156]
+ Step 8 : J = 1.81569e+00 and X = [1.000015, 2.000432, 3.000364]
+ Step 9 : J = 1.81569e+00 and X = [1.000015, 2.000432, 3.000364]
+ Step 10 : J = 1.81568e+00 and X = [1.000013, 2.000458, 3.000390]
...
The state at the first step is the randomly generated background state
-:math:`\mathbf{x}^b`. After completion, these printing on standard output is
-available in the "*YACS Container Log*", obtained through the right click menu
-of the "*proc*" window in the YACS scheme.
+:math:`\mathbf{x}^b`. During calculation, these printings on standard output are
+available in the "*YACS Container Log*" window, obtained through the right click
+menu of the "*proc*" window in the YACS executed scheme.
-.. [#] For more information on YACS, see the the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
+.. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME platform.
:sorted:
case
- One case is defined by a set of data and of choices, packed together
+ One ADAO case is defined by a set of data and of choices, packed together
through the user interface of the module. The data are physical
- measurements that have to be available before or during the case
- execution. The simulation code(s) and the assimilation methods and
- parameters has to be chosen, they define the execution properties of the
- case.
+ measurements that have technically to be available before or during the
+ case execution. The simulation code(s) and the data assimilation or
+ optimization method, and their parameters, has to be chosen, they define
+ the execution properties of the case.
iteration
One iteration occurs when using iterative optimizers (e.g. 3DVAR), and it
is entirely hidden in the main YACS OptimizerLoop Node named
- "compute_bloc". Nevertheless, the user can watch the iterative process
- through the *YACS Container Log* window, which is updated during the
- process, and using *Observers* attached to calculation variables.
+ "*compute_bloc*". Nevertheless, the user can watch the iterative process
+ through the "*YACS Container Log*" window, which is updated during the
+ process, and using "*Observers*" attached to calculation variables.
APosterioriCovariance
Keyword to indicate the covariance matrix of *a posteriori* analysis
errors.
BMA (Background minus Analysis)
- Difference between the simulation based on the background state and the
- one base on the optimal state estimation, noted as :math:`\mathbf{x}^b -
- \mathbf{x}^a`.
+ Difference between the background state and the optimal state estimation,
+ noted as :math:`\mathbf{x}^b - \mathbf{x}^a`.
OMA (Observation minus Analysis)
Difference between the observations and the result of the simulation based
SigmaBck2
Keyword to indicate the Desroziers-Ivanov parameter measuring the
background part consistency of the data assimilation optimal state
- estimation. It can be compared to 1.
+ estimation. Its value can be compared to 1, a "good" estimation leading to
+ a parameter "close" to 1.
SigmaObs2
Keyword to indicate the Desroziers-Ivanov parameter measuring the
observation part consistency of the data assimilation optimal state
- estimation. It can be compared to 1.
+ estimation. Its value can be compared to 1, a "good" estimation leading to
+ a parameter "close" to 1.
MahalanobisConsistency
Keyword to indicate the Mahalanobis parameter measuring the consistency of
- the data assimilation optimal state estimation. It can be compared to 1.
+ the data assimilation optimal state estimation. Its value can be compared
+ to 1, a "good" estimation leading to a parameter "close" to 1.
analysis
The optimal state estimation through a data assimilation or optimization
procedure.
+ background
+ The *a priori* known state, which is not optimal, and is used as a rought
+ estimate, or a "best estimate", before an optimal estimation.
+
innovation
Difference between the observations and the result of the simulation based
on the background state, filtered to be compatible with the observation.
================================================================================
-ADAO module documentation
+ADAO documentation
================================================================================
.. image:: images/ADAO_logo.png
================================================================================
The aim of the ADAO module is **to help using data assimilation or optimization
-methodology in conjunction with other modules in SALOME**. The ADAO module
-provides interface to some standard algorithms of data assimilation or
-optimization, and allows integration of them in a SALOME study. Calculation or
-simulation modules have to provide one or more specific calling methods in order
-to ba callable in the SALOME/ADAO framework, and all the SALOME modules can be
-used throught YACS integration of ADAO.
+methodology in conjunction with other modules or simulation codes in SALOME**.
+The ADAO module provides interface to some standard algorithms of data
+assimilation or optimization, and allows integration of their use in a SALOME
+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
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 setup to be
-performed. Its methodological and numerical scalability gives way to extend the
-application domain.
+The module covers a wide variety of practical applications, in a robust way,
+allowing real engineering applications but also quick experimental methodology
+setup to be performed. Its methodological and numerical scalability gives way to
+extend the application domain.
different pseudo-types are:
**Dict**
- This indicates a variable that has to be filled by a dictionary, usually
- given either as a string or as a script.
+ This indicates a variable that has to be filled by a Python dictionary
+ ``{"key":"value...}``, usually given either as a string or as a script file.
**Function**
- This indicates a variable that has to be filled by a function, usually given
- as a script or a component method.
+ This indicates a variable that has to be filled by a Python function,
+ usually given as a script file or a component method.
**Matrix**
This indicates a variable that has to be filled by a matrix, usually given
- either as a string or as a script.
+ either as a string or as a script file.
**ScalarSparseMatrix**
- This indicates a variable that has to be filled by a unique number, which
- will be used to multiply an identity matrix, usually given either as a
- string or as a script.
+ This indicates a variable that has to be filled by a unique number (which
+ will be used to multiply an identity matrix), usually given either as a
+ string or as a script file.
**DiagonalSparseMatrix**
- This indicates a variable that has to be filled by a vector, which will be
- over the diagonal of an identity matrix, usually given either as a string or
- as a script.
+ This indicates a variable that has to be filled by a vector (which will be
+ used to replace the diagonal of an identity matrix), usually given either as
+ a string or as a script file.
**Script**
This indicates a script given as an external file. It can be described by a
**String**
This indicates a string giving a literal representation of a matrix, a
- vector or a vector serie, such as "1 2 ; 3 4" for a square 2x2 matrix.
+ vector or a vector serie, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
+ square 2x2 matrix.
**Vector**
This indicates a variable that has to be filled by a vector, usually given
- either as a string or as a script.
+ either as a string or as a script file.
-**VectorSerie** This indicates a variable that has to be filled by a list of
- vectors, usually given either as a string or as a script.
+**VectorSerie**
+ This indicates a variable that has to be filled by a list of
+ vectors, usually given either as a string or as a script file.
When a command or keyword can be filled by a script file name, the script has to
contain a variable or a method that has the same name as the one to be filled.
In other words, when importing the script in a YACS Python node, it must create
-a variable of the good name in the current namespace.
+a variable of the good name in the current namespace of the node.
Reference description for ADAO calculation cases
------------------------------------------------
*Required command*. This is a string to indicate the data assimilation or
optimization algorithm chosen. The choices are limited and available through
the GUI. There exists for example "3DVAR", "Blue"... See below the list of
- algorithms and associated parameters in the following subsection `Options
+ algorithms and associated parameters in the following subsection `Optional
and required commands for calculation algorithms`_.
**AlgorithmParameters**
*Optional command*. This command allows to add some optional parameters to
- control the data assimilation or optimization algorithm. It is defined as a
- "*Dict*" type object, that is, given as a script. See below the list of
- algorithms and associated parameters in the following subsection `Options
- and required commands for calculation algorithms`_.
+ control the data assimilation or optimization algorithm. Its value is
+ defined as a "*Dict*" type object. See below the list of algorithms and
+ associated parameters in the following subsection `Optional and required
+ commands for calculation algorithms`_.
**Background**
*Required command*. This indicates the background or initial vector used,
- previously noted as :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type
- object, that is, given either as a string or as a script.
+ previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
+ "*Vector*" type object.
**BackgroundError**
*Required command*. This indicates the background error covariance matrix,
- previously noted as :math:`\mathbf{B}`. It is defined as a "*Matrix*" type
- object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
- type object, that is, given either as a string or as a script.
+ previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*"
+ type object, a "*ScalarSparseMatrix*" type object, or a
+ "*DiagonalSparseMatrix*" type object.
**ControlInput**
*Optional command*. This indicates the control vector used to force the
- evolution model at each step, usually noted as :math:`\mathbf{U}`. It is
- defined as a "*Vector*" or a *VectorSerie* type object, that is, given
- either as a string or as a script. When there is no control, it has to be a
- void string ''.
+ evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value
+ is defined as a "*Vector*" or a *VectorSerie* type object. When there is no
+ control, it has to be a void string ''.
**Debug**
*Required command*. This define the level of trace and intermediary debug
*Optional command*. This indicates the evolution error covariance matrix,
usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type
object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
- type object, that is, given either as a string or as a script.
+ type object.
**EvolutionModel**
*Optional command*. This indicates the evolution model operator, usually
- noted :math:`M`, which describes a step of evolution. It is defined as a
- "*Function*" type object, that is, given as a script. Different functional
- forms can be used, as described in the following subsection `Requirements
- for functions describing an operator`_. If there is some control :math:`U`
- included in the evolution model, the operator has to be applied to a pair
- :math:`(X,U)`.
+ noted :math:`M`, which describes an elementary step of evolution. Its value
+ is defined as a "*Function*" type object. Different functional forms can be
+ used, as described in the following subsection `Requirements for functions
+ describing an operator`_. If there is some control :math:`U` included in the
+ evolution model, the operator has to be applied to a pair :math:`(X,U)`.
**InputVariables**
*Optional command*. This command allows to indicates the name and size of
- physical variables that are bundled together in the control vector. This
+ physical variables that are bundled together in the state vector. This
information is dedicated to data processed inside an algorithm.
**Observation**
*Required command*. This indicates the observation vector used for data
assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
- is defined as a "*Vector*" or a *VectorSerie* type object, that is, given
- either as a string or as a script.
+ is defined as a "*Vector*" or a *VectorSerie* type object.
**ObservationError**
*Required command*. This indicates the observation error covariance matrix,
previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type
object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*"
- type object, that is, given either as a string or as a script.
+ type object.
**ObservationOperator**
*Required command*. This indicates the observation operator, previously
noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
results :math:`\mathbf{y}` to be compared to observations
- :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object, that is,
- given as a script. Different functional forms can be used, as described in
- the following subsection `Requirements for functions describing an
- operator`_. If there is some control :math:`U` included in the observation,
- the operator has to be applied to a pair :math:`(X,U)`.
+ :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object.
+ Different functional forms can be used, as described in the following
+ subsection `Requirements for functions describing an operator`_. If there is
+ some control :math:`U` included in the observation, the operator has to be
+ applied to a pair :math:`(X,U)`.
**Observers**
*Optional command*. This command allows to set internal observers, that are
vector. This information is dedicated to data processed inside an algorithm.
**Study_name**
- *Required command*. This is an open string to describe the study by a name
- or a sentence.
+ *Required command*. This is an open string to describe the ADAO study by a
+ name or a sentence.
**Study_repertory**
*Optional command*. If available, this directory is used as base name for
**UserDataInit**
*Optional command*. This commands allows to initialize some parameters or
- data automatically before data assimilation algorithm processing.
+ data automatically before data assimilation or optimisation algorithm input
+ processing. It indicates a script file name to be executed before entering
+ in initialization phase of chosen variables.
**UserPostAnalysis**
*Optional command*. This commands allows to process some parameters or data
- automatically after data assimilation algorithm processing. It is defined as
- a script or a string, allowing to put post-processing code directly inside
- the ADAO case. Common templates are provided to help the user to start or
- to quickly make his case.
+ automatically after data assimilation or optimization algorithm processing.
+ Its value is defined as a script file or a string, allowing to put
+ post-processing code directly inside the ADAO case. Common templates are
+ provided to help the user to start or to quickly make his case.
-Options and required commands for calculation algorithms
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Optional and required commands for calculation algorithms
+++++++++--++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: 3DVAR
.. index:: single: Blue
.. index:: single: StoreSupplementaryCalculations
.. index:: single: SwarmVelocity
-Each algorithm can be controlled using some generic or specific options given
-through the "*AlgorithmParameters*" optional command, as follows for example::
+Each algorithm can be controlled using some generic or specific options, given
+through the "*AlgorithmParameters*" optional command in a script file or a
+sring, as follows for example in a file::
AlgorithmParameters = {
"Minimizer" : "LBFGSB",
"StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
}
-This section describes the available options algorithm by algorithm. If an
-option is specified for an algorithm that doesn't support it, the option is
-simply left unused. The meaning of the acronyms or particular names can be found
-in the :ref:`genindex` or the :ref:`section_glossary`. In addition, for each
-algorithm, the required commands/keywords are given, being described in `List of
-commands and keywords for an ADAO calculation case`_.
+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
+an option is specified by the user for an algorithm that doesn't support it, the
+option is simply left unused and don't stop the treatment. The meaning of the
+acronyms or particular names can be found in the :ref:`genindex` or the
+:ref:`section_glossary`.
**"Blue"**
is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
- unconstrained minimizer), "NCG" (Newton CG minimizer).
+ unconstrained minimizer), "NCG" (Newton CG minimizer). It is recommended to
+ stay with the default.
Bounds
- This key allows to define upper and lower bounds for every control
- variable being optimized. Bounds can be given by a list of list of pairs
- of lower/upper bounds for each variable, with possibly ``None`` every time
+ This key allows to define upper and lower bounds for every state variable
+ being optimized. Bounds can be given by a list of list of pairs of
+ lower/upper bounds for each variable, with possibly ``None`` every time
there is no bound. The bounds can always be specified, but they are taken
into account only by the constrained minimizers.
optimization. The default is 15000, which is very similar to no limit on
iterations. It is then recommended to adapt this parameter to the needs on
real problems. For some minimizers, the effective stopping step can be
- slightly different due to algorithm internal control requirements.
+ slightly different of the limit due to algorithm internal control
+ requirements.
CostDecrementTolerance
This key indicates a limit value, leading to stop successfully the
"ObservationOperator"*
Minimizer
- This key allows to choose the optimization minimizer. The default choice
- is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
+ This key allows to choose the optimization minimizer. The default choice is
+ "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
minimizer, see [Byrd95]_ and [Zhu97]_), "TNC" (nonlinear constrained
minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
- unconstrained minimizer), "NCG" (Newton CG minimizer).
+ unconstrained minimizer), "NCG" (Newton CG minimizer). It is recommended to
+ stay with the default.
Bounds
- This key allows to define upper and lower bounds for every control
- variable being optimized. Bounds can be given by a list of list of pairs
- of lower/upper bounds for each variable, with possibly ``None`` every time
+ This key allows to define upper and lower bounds for every state variable
+ being optimized. Bounds can be given by a list of list of pairs of
+ lower/upper bounds for each variable, with possibly ``None`` every time
there is no bound. The bounds can always be specified, but they are taken
into account only by the constrained minimizers.
EstimationOf
This key allows to choose the type of estimation to be performed. It can be
- either state-estimation, named "State", or parameter-estimation, named
- "Parameters". The default choice is "State".
+ either state-estimation, with a value of "State", or parameter-estimation,
+ with a value of "Parameters". The default choice is "State".
StoreInternalVariables
This boolean key allows to store default internal variables, mainly the
"ObservationOperator"*
Bounds
- This key allows to define upper and lower bounds for every control variable
+ This key allows to define upper and lower bounds for every state variable
being optimized. Bounds can be given by a list of list of pairs of
lower/upper bounds for each variable, with extreme values every time there
is no bound. The bounds can always be specified, but they are taken into
EstimationOf
This key allows to choose the type of estimation to be performed. It can be
- either state-estimation, named "State", or parameter-estimation, named
- "Parameters". The default choice is "State".
+ either state-estimation, with a value of "State", or parameter-estimation,
+ with a value of "Parameters". The default choice is "State".
StoreInternalVariables
This boolean key allows to store default internal variables, mainly the
"ObservationOperator"*
Bounds
- This key allows to define upper and lower bounds for every control variable
+ This key allows to define upper and lower bounds for every state variable
being optimized. Bounds can be given by a list of list of pairs of
lower/upper bounds for each variable, with extreme values every time there
is no bound. The bounds can always be specified, but they are taken into
EstimationOf
This key allows to choose the type of estimation to be performed. It can be
- either state-estimation, named "State", or parameter-estimation, named
- "Parameters". The default choice is "State".
+ either state-estimation, with a value of "State", or parameter-estimation,
+ with a value of "Parameters". The default choice is "State".
Alpha, Beta, Kappa, Reconditioner
These keys are internal scaling parameters. "Alpha" requires a value between
- 1.e-4 and 1. "Beta" has an optimal value of 2 for gaussian priori
+ 1.e-4 and 1. "Beta" has an optimal value of 2 for gaussian *a priori*
distribution. "Kappa" requires an integer value, and the right default is
obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3
and 10, it defaults to 1.
case. It hierarchically contains all the other commands.
**Algorithm**
- *Required command*. This is a string to indicate the data assimilation or
- optimization algorithm chosen. The choices are limited and available through
- the GUI. There exists for example "FunctionTest", "AdjointTest"... See below
- the list of algorithms and associated parameters in the following subsection
- `Options and required commands for checking algorithms`_.
+ *Required command*. This is a string to indicate the test algorithm chosen.
+ The choices are limited and available through the GUI. There exists for
+ example "FunctionTest", "AdjointTest"... See below the list of algorithms
+ and associated parameters in the following subsection `Optional and required
+ commands for checking algorithms`_.
**AlgorithmParameters**
*Optional command*. This command allows to add some optional parameters to
and required commands for checking algorithms`_.
**CheckingPoint**
- *Required command*. This indicates the vector used,
- previously noted as :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type
- object, that is, given either as a string or as a script.
+ *Required command*. This indicates the vector used, previously noted as
+ :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object.
**Debug**
*Required command*. This define the level of trace and intermediary debug
*Required command*. This indicates the observation operator, previously
noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
results :math:`\mathbf{y}` to be compared to observations
- :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object, that is,
- given as a script. Different functional forms can be used, as described in
- the following subsection `Requirements for functions describing an
- operator`_.
+ :math:`\mathbf{y}^o`. It is defined as a "*Function*" type object. Different
+ functional forms can be used, as described in the following subsection
+ `Requirements for functions describing an operator`_. If there is some
+ control :math:`U` included in the observation, the operator has to be
+ applied to a pair :math:`(X,U)`.
**Study_name**
*Required command*. This is an open string to describe the study by a name
or a sentence.
**Study_repertory**
- *Optional command*. If available, this repertory is used to find all the
- script files that can be used to define some other commands by scripts.
+ *Optional command*. If available, this directory is used as base name for
+ calculation, and used to find all the script files, given by name without
+ path, that can be used to define some other commands by scripts.
**UserDataInit**
*Optional command*. This commands allows to initialize some parameters or
data automatically before data assimilation algorithm processing.
-Options and required commands for checking algorithms
+Optional and required commands for checking algorithms
+++++++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: AdjointTest
.. index:: single: SetSeed
We recall that each algorithm can be controlled using some generic or specific
-options given through the "*AlgorithmParameters*" optional command, as follows
+options, given through the "*AlgorithmParameters*" optional command, as follows
for example::
AlgorithmParameters = {
"EpsilonMinimumExponent" : -8,
}
-If an option is specified for an algorithm that doesn't support it, the option
-is simply left unused. The meaning of the acronyms or particular names can be
-found in the :ref:`genindex` or the :ref:`section_glossary`. In addition, for
-each algorithm, the required commands/keywords are given, being described in
-`List of commands and keywords for an ADAO checking case`_.
+If an option is specified by the user for an algorithm that doesn't support it,
+the option is simply left unused and don't stop the treatment. The meaning of
+the acronyms or particular names can be found in the :ref:`genindex` or the
+:ref:`section_glossary`. In addition, for each algorithm, the required
+commands/keywords are given, being described in `List of commands and keywords
+for an ADAO checking case`_.
**"AdjointTest"**
This key indicates the minimal exponent value of the power of 10 coefficient
to be used to decrease the increment multiplier. The default is -8, and it
has to be between 0 and -20. For example, its default value leads to
- calculate the residue of the scalar product formula with a fixed increment
- multiplied from 1.e0 to 1.e-8.
+ calculate the residue of the formula with a fixed increment multiplied from
+ 1.e0 to 1.e-8.
InitialDirection
This key indicates the vector direction used for the directional derivative
SetDebug
This key requires the activation, or not, of the debug mode during the
- function evaluation. The default is True, the choices are True of False.
+ function evaluation. The default is "True", the choices are "True" or
+ "False".
**"GradientTest"**
ResiduFormula
This key indicates the residue formula that has to be used for the test. The
default choice is "Taylor", and the possible ones are "Taylor" (residue of
- the Taylor development of the operator, which has to decrease with the power
- of 2 in perturbation) and "Norm" (residue obtained by taking the norm of the
- Taylor development at zero order approximation, which approximate the
- gradient, and which has to remain constant).
+ the Taylor development of the operator, which has to decrease with the
+ square power of the perturbation) and "Norm" (residue obtained by taking the
+ norm of the Taylor development at zero order approximation, which
+ approximate the gradient, and which has to remain constant).
SetSeed
This key allow to give an integer in order to fix the seed of the random
-------------------------------------------------
The operators for observation and evolution are required to implement the data
-assimilation or optimization procedures. They include the physical simulation
-numerical simulations, but also the filtering and restriction to compare the
+assimilation or optimization procedures. They include the physical simulation by
+numerical calculations, but also the filtering and restriction to compare the
simulation to observation. The evolution operator is considered here in its
incremental form, representing the transition between two successive states, and
is then similar to the observation operator.
...
return Y=O(X)
-In this case, the user can also provide a value for the differential increment,
-using through the GUI the keyword "*DifferentialIncrement*", which has a default
-value of 1%. This coefficient will be used in the finite difference
-approximation to build the tangent and adjoint operators. The finite difference
-approximation order can also be chosen through the GUI, using the keyword
-"*CenteredFiniteDifference*", with 0 for an uncentered schema of first order,
-and with 1 for a centered schema of second order (of twice the first order
-computational cost). The keyword has a default value of 0.
+In this case, the user has also provide a value for the differential increment
+(or keep the devault value), using through the GUI the keyword
+"*DifferentialIncrement*", which has a default value of 1%. This coefficient
+will be used in the finite difference approximation to build the tangent and
+adjoint operators. The finite difference approximation order can also be chosen
+through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an
+uncentered schema of first order (which is the default value), and with 1 for a
+centered schema of second order (of twice the first order computational cost).
-This first operator definition allow easily to test the functional form before
-its use in an ADAO case, greatly reducing the complexity of implementation.
+This first operator definition form allows easily to test the functional form
+before its use in an ADAO case, greatly reducing the complexity of
+operator implementation.
**Important warning:** the name "*DirectOperator*" is mandatory, and the type of
-the X argument can be either a python list, a numpy array or a numpy 1D-matrix.
-The user has to treat these cases in his script.
+the ``X`` argument can be either a list, a numpy array or a numpy 1D-matrix. The
+user has to treat these cases in his function.
Second functional form: using "*ScriptWithFunctions*"
+++++++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: TangentOperator
.. index:: single: AdjointOperator
+**In general, it is recommended to use the first functionnal form rather than
+the second one. A small performance improvement is not a good reason to use a
+detailled implementation as this second functional form.**
+
The second one consist in providing directly the three associated operators
:math:`O`, :math:`\mathbf{O}` and :math:`\mathbf{O}^*`. This is done by using
the keyword "*ScriptWithFunctions*" for the description of the chosen operator
Another time, this second operator definition allow easily to test the
functional forms before their use in an ADAO case, reducing the complexity of
-implementation.
+operator implementation.
+
+For some algorithms, it is required that the tangent and adjoint functions can
+return the matrix equivalent to the linear operator. In this case, when
+respectivly the ``dX`` or the ``Y`` arguments are ``None``, the user has to
+return the associated matrix.
**Important warning:** the names "*DirectOperator*", "*TangentOperator*" and
-"*AdjointOperator*" are mandatory, and the type of the X, Y, dX arguments can be
-either a python list, a numpy array or a numpy 1D-matrix. The user has to treat
-these cases in his script.
+"*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX``
+arguments can be either a python list, a numpy array or a numpy 1D-matrix. The
+user has to treat these cases in his script.
Third functional form: using "*ScriptWithSwitch*"
+++++++++++++++++++++++++++++++++++++++++++++++++
.. index:: single: TangentOperator
.. index:: single: AdjointOperator
+**It is recommended not to use this third functional form without a solid
+numerical or physical reason. A performance improvement is not a good reason to
+use the implementation complexity of this third functional form. Only an
+inability to use the first or second forms justifies the use of the third.**
+
This third form give more possibilities to control the execution of the three
functions representing the operator, allowing advanced usage and control over
each execution of the simulation code. This is done by using the keyword
introduce more complexity in the argument treatment of the functions. But it
will be far more complicated to implement and debug.
-**It is recommended not to use this third functional form without a solid
-numerical or physical reason.**
-
If, however, you want to use this third form, we recommend using the following
-template for the switch. It requires an external script or code named
+template for the switch. It requires an external script or code named here
"*Physical_simulation_functions.py*", containing three functions named
"*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously.
Here is the switch template::
All various modifications could be done from this template hypothesis.
-Special case of controled evolution operator
-++++++++++++++++++++++++++++++++++++++++++++
+Special case of controled evolution or observation operator
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-In some cases, the evolution or the observation operators are required to be
-controled by an external input control, given a priori. In this case, the
-generic form of the incremental evolution model is slightly modified as follows:
+In some cases, the evolution or the observation operator is required to be
+controled by an external input control, given *a priori*. In this case, the
+generic form of the incremental model is slightly modified as follows:
.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
--------------------------------------------
Multiple covariance matrices are required to implement the data assimilation or
-optimization procedures. The main ones are the background error covariance
-matrix, noted as :math:`\mathbf{B}` and the observation error covariance matrix,
+optimization procedures. The main ones are the background error covariance
+matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix,
noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symetric
semi-definite positive matrix.
There are 3 practical methods for the user to provide a covariance matrix. These
-methods are chosen as the "*INPUT_TYPE*" of each defined covariance matrix, as
-shown by the following figure:
+methods are chosen by the "*INPUT_TYPE*" keyword of each defined covariance
+matrix, as shown by the following figure:
.. eficas_covariance_matrix:
.. image:: images/eficas_covariance_matrix.png
\end{pmatrix}
It can be either a Python Numpy array or a matrix, or a list of lists of values
-(that is, a list of rows). For example, a simple diagonal unitary background error
-covariance matrix :math:`\mathbf{B}` can be described in a python script as::
+(that is, a list of rows). For example, a simple diagonal unitary background
+error covariance matrix :math:`\mathbf{B}` can be described in a Python script
+file as::
- BackgroundError = numpy.eye(...)
+ BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
-ou::
+or::
- BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
+ BackgroundError = numpy.eye(...)
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. The matrix can then be specified only by this
-multiplier:
+multiple of the identity matrix. This matrix can then be specified only by the
+multiplier :math:`m`:
.. math:: \mathbf{M} = m \times \begin{pmatrix}
1 & 0 & \cdots & 0 \\
\end{pmatrix}
The multiplier :math:`m` has to be a floating point or integer positive value
-(if it is negative, which is impossible, converted to positive value). For example, a simple diagonal unitary background error
-covariance matrix :math:`\mathbf{B}` can be described in a python script as::
+(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::
BackgroundError = 1.
.. index:: single: ObservationError
This third form is also a simplified method to provide a matrix, but a little
-more powerful. The covariance matrix :math:`\mathbf{M}` is already supposed to
-be diagonal, but the user has to specify all the positive diagonal values. The
-matrix can then be specified only by a vector :math:`\mathbf{V}` which will be
-set on a diagonal matrix:
+more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is
+already supposed to be diagonal, but the user has to specify all the positive
+diagonal values. The matrix can then be specified only by a vector
+:math:`\mathbf{V}` which will be set on a diagonal matrix:
.. math:: \mathbf{M} = \begin{pmatrix}
v_{1} & 0 & \cdots & 0 \\
\end{pmatrix}
It can be either a Python Numpy array or a matrix, or a list or a list of list
-of positive values (if some are negative, which is impossible, converted to
-positive values). For example, a simple diagonal unitary background error
-covariance matrix :math:`\mathbf{B}` can be described in a python script as::
+of positive values (in all cases, if some are negative, which is impossible,
+they are converted to positive values). For example, a simple diagonal unitary
+background error covariance matrix :math:`\mathbf{B}` can be described in a
+python script file as::
BackgroundError = [1, 1 ... 1]
-ou::
+or::
BackgroundError = numpy.ones(...)
true state and of its stochastic properties. Note that this true state can not
be reached, but can only be estimated. Moreover, despite the fact that the used
information are stochastic by nature, data assimilation provides deterministic
-techniques in order to realize the estimation.
+techniques in order to perform very efficiently the estimation.
Because data assimilation look for the **best possible** estimate, its
underlying procedure always integrates optimization in order to find this
estimate: particular optimization methods are always embedded in data
-assimilation algorithms. Optimization methods can be seen here as a way to
+assimilation algorithms. Optimization methods can be seen in ADAO as a way to
extend data assimilation applications. They will be introduced this way in the
section `Going further in the state estimation by optimization methods`_, but
they are far more general and can be used without data assimilation concepts.
Two main types of applications exist in data assimilation, being covered by the
same formalism: **parameters identification** and **fields reconstruction**.
-Before introducing the `Simple description of the data assimilation framework`_
-in a next section, we describe briefly these two types. At the end, some
-references allow `Going further in the data assimilation framework`_.
+Before introducing the `Simple description of the data assimilation
+methodological framework`_ in a next section, we describe briefly these two
+types. At the end, some references allow `Going further in the data assimilation
+framework`_.
Fields reconstruction or measures interpolation
-----------------------------------------------
.. index:: single: fields reconstruction
+.. index:: single: measures interpolation
Fields reconstruction 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
+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.
If the system evolves in time, the reconstruction has to be established on every
-time step, as a whole. The interpolation process in this case is more
-complicated since it is temporal, not only in terms of instantaneous values of
-the field.
+time step, of the field as a whole. The interpolation process in this case is
+more complicated since it is temporal, and not only in terms of instantaneous
+values of the field.
A simple example of fields reconstruction comes from meteorology, in which one
look for value of variables such as temperature or pressure in all points of the
a "consistent" manner with the evolution equations and with the measures of the
previous time steps.
-Parameters identification or calibration
-----------------------------------------
+Parameters identification, models adjustment, calibration
+---------------------------------------------------------
.. index:: single: parameters identification
-
-The identification of parameters by data assimilation is a form of calibration
-which uses both the measurement and an *a priori* 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.
+.. index:: single: models adjustment
+.. index:: single: calibration
+.. index:: single: background
+.. index:: single: regularization
+
+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
+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.
In practice, the two observed gaps "*calculation-background*" and
-"*calculation-measures*" are added to build the calibration correction of
+"*calculation-measures*" 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 measured by the covariance of the errors on the
+information. This confidence is depicted by the covariance of the errors on the
background and on the observations. Thus the stochastic aspect of information,
measured or *a priori*, is essential for building the calibration error
function.
simulation process involving a parametrized model. For example, a static
mechanical simulation of a beam constrained by some forces is described by beam
parameters, such as a Young coefficient, or by the intensity of the force. The
-parameter estimation problem consists in finding for example the right Young
-coefficient in order that the simulation of the beam corresponds to
+parameters estimation problem consists in finding for example the right Young
+coefficient value in order that the simulation of the beam corresponds to
measurements, including the knowledge of errors.
-Simple description of the data assimilation framework
------------------------------------------------------
+Simple description of the data assimilation methodological framework
+--------------------------------------------------------------------
.. index:: single: background
.. index:: single: background error covariances
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), which transforms the input parameters :math:`\mathbf{x}`
-to results :math:`\mathbf{y}` to be compared to observations
+(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 incorrect. We therefore introduce errors of observations
-additively, in the form of a random vector :math:`\mathbf{\epsilon}^o` such
-that:
+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
.. 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`:
+introducing the error vector :math:`\mathbf{\epsilon}^b` such that:
.. math:: \mathbf{x}^b = \mathbf{x}^t + \mathbf{\epsilon}^b
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. The
-parameters vector :math:`\mathbf{x}` realizing the minimum of this function
+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 and Hessian
+: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...).
It is indicated here that these methods of "*3D-VAR*" and "*BLUE*" may be
extended to dynamic problems, called respectively "*4D-VAR*" and "*Kalman
filter*". They can take into account the evolution operator to establish an
-analysis at the right time steps of the gap between observations and simulations,
-and to have, at every moment, the propagation of the background through the
-evolution model. Many other variants have been developed to improve the
-numerical quality or to take into account computer requirements such as
-calculation size and time.
+analysis at the right time steps of the gap between observations and
+simulations, and to have, at every moment, the propagation of the background
+through the evolution model. Many other variants have been developed to improve
+the numerical quality of the methods or to take into account computer
+requirements such as calculation size and time.
Going further in the data assimilation framework
------------------------------------------------
.. index:: single: Bayesian estimation
.. index:: single: optimal interpolation
.. index:: single: mathematical regularization
+.. index:: single: regularization methods
.. index:: single: data smoothing
-To get more information about all the data assimilation techniques, the reader
-can consult introductory documents like [Argaud09]_, on-line training courses or
+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]_.
-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 science
-and technology where the effective use of observed but incomplete data is
-crucial.
+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
+science and technology where the effective use of observed but incomplete data
+is crucial.
Some aspects of data assimilation are also known as *state estimation*,
*parameter estimation*, *inverse problems*, *Bayesian estimation*, *optimal
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* state estimation.
+minimization of the :math:`J` function leads to the *best* `\mathbf{x}` state
+estimation.
State estimation possibilities extension, by using more explicitly optimization
methods and their properties, can be imagined in two ways.
estimation possibilities is then to use a whole range of optimizers, allowing
global minimization, various robust search properties, etc**. There is a lot of
minimizing methods, such as stochastic ones, evolutionary ones, heuristics and
-meta-heuristics for real-valued problems, etc. They can treat partially irregular
-or noisy function :math:`J`, can characterize local minima, etc. The main
-drawback is a greater numerical cost to find state estimates, and no guarantee
-of convergence in finite time. Here, we only point the following
-topics, as the methods are available in the ADAO module: *Quantile regression*
-[WikipediaQR]_ and *Particle swarm optimization* [WikipediaPSO]_.
+meta-heuristics for real-valued problems, etc. They can treat partially
+irregular or noisy function :math:`J`, can characterize local minima, etc. The
+main drawback is a greater numerical cost to find state estimates, and no
+guarantee of convergence in finite time. Here, we only point the following
+topics, as the methods are available in the ADAO module: *Quantile Regression*
+[WikipediaQR]_ and *Particle Swarm Optimization* [WikipediaPSO]_.
Secondly, optimization methods try usually to minimize quadratic measures of
errors, as the natural properties of such goal functions are well suited for
:align: middle
:scale: 50%
-This section presents the usage of the ADAO module in SALOME. It is complemented
-by the detailed description of all the commands and keywords in the section
-:ref:`section_reference`, by advanced usage procedures in the section
+This section presents the usage of the ADAO module in SALOME platform. It is
+complemented by the detailed description of all the commands and keywords in the
+section :ref:`section_reference`, by advanced usage procedures in the section
:ref:`section_advanced`, and by examples in the section :ref:`section_examples`.
-Logical procedure to build an ADAO test case
---------------------------------------------
+Logical procedure to build an ADAO case
+---------------------------------------
The construction of an ADAO case follows a simple approach to define the set of
input data, and then generates a complete executable block diagram used in YACS.
**Basically, the procedure of using ADAO involves the following steps:**
#. **Activate the ADAO module and use the editor GUI,**
-#. **Build and/or modify the ADAO case and save it,**
+#. **Build and/or modify the ADAO case, and save it,**
#. **Export the ADAO case as a YACS scheme,**
-#. **Supplement and modify the YACS scheme and save it,**
+#. **Supplement and modify the YACS scheme, and save it,**
#. **Execute the YACS case and obtain the results.**
Each step will be detailed in the next section.
-------------------------------------------------------
As always for a module, it has to be activated by choosing the appropriate
-module button (or menu) in the toolbar of SALOME. If there is no SALOME study
-loaded, a popup appears, allowing to choose between creating a new study, or
-opening an already existing one:
+module button (or the menu) in the toolbar of SALOME. If there is no SALOME
+study loaded, a popup appears, allowing to choose between creating a new study,
+or opening an already existing one:
.. _adao_activate1:
.. image:: images/adao_activate.png
.. centered::
**The EFICAS editor for cases definition in module ADAO**
-STEP 2: Build and modify the ADAO case and save it
---------------------------------------------------
+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.
order to execute the data assimilation calculation. This can be easily done by
using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
"*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
-menu in the object browser.
+menu in the SALOME object browser.
.. _adao_exporttoyacs01:
.. image:: images/adao_exporttoyacs.png
This will lead to automatically generate a YACS scheme, and open the YACS module
on this scheme. The YACS file, associated with the scheme, will be stored in the
same directory and with the same base name as the ADAO saved case, only changing
-its extension to "*.xml*". Be careful, *if the XML file name already exist, it
-will be overwritten without prompting for replacing the file*.
+its extension to "*.xml*". Be careful, *if the XML file name already exist, the
+file will be overwritten without prompting for replacing the XML file*.
-STEP 4: Supplement and modify the YACS scheme and save it
----------------------------------------------------------
+STEP 4: Supplement and modify the YACS scheme, and save it
+----------------------------------------------------------
.. index:: single: Analysis
When the YACS scheme is generated and opened in SALOME through the YACS module
-GUI, you can modify or supplement the scheme like any YACS scheme. Nodes or
-blocs can be added, copied or modified to elaborate complex analysis, or to
-insert data assimilation or optimization capabilities into more complex YACS
-calculation schemes. It is recommended to save the modified scheme with a new
-name, in order to preserve the XML file in the case you re-export the ADAO case
-to YACS.
+GUI, you can modify or supplement the scheme like any standard YACS scheme.
+Nodes or blocs can be added, copied or modified to elaborate complex analysis,
+or to insert data assimilation or optimization capabilities into more complex
+YACS calculation schemes. It is recommended to save the modified scheme with a
+new name, in order to preserve the XML file in the case you re-export the ADAO
+case to YACS.
The main supplement needed in the YACS scheme is a post-processing step. The
evaluation of the results has to be done in the physical context of the
simulation used by the data assimilation procedure. The post-processing can be
provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
-by templates, or can be build as YACS nodes using all SALOME possibilities.
+by templates, or can be build as YACS nodes. These two ways of building the
+post-processing can use all the SALOME possibilities.
-The YACS scheme has an "*algoResults*" output port of the computation bloc,
-which gives access to a "*pyobj*" named hereafter "*ADD*", containing all the
-processing results. These results can be obtained by retrieving the named
-variables stored along the calculation. The main is the "*Analysis*" one, that
-can be obtained by the python command (for example in an in-line script node or
-a script provided through the "*UserPostAnalysis*" keyword)::
+In details, the YACS scheme has an "*algoResults*" output port of the
+computation bloc, which gives access to an object of type "*pyobj*" named
+hereafter "*ADD*", containing all the calculation results. These results can be
+obtained by retrieving the named variables stored along the calculation. The
+main information is the "*Analysis*" one, that can be obtained by the python
+command (for example in an in-line script node or a script provided through the
+"*UserPostAnalysis*" keyword)::
Analysis = ADD.get("Analysis")[:]
"*Analysis*" is a complex object, similar to a list of values calculated at each
step of data assimilation calculation. In order to get and print the optimal
-data assimilation state evaluation, in script provided through the
+data assimilation state evaluation, in a script provided through the
"*UserPostAnalysis*" keyword, one can use::
Xa = ADD.get("Analysis")[-1]
print "Optimal state:", Xa
print
-This ``Xa`` is a vector of values, that represents the solution of the data
-assimilation or optimization evaluation problem, noted as :math:`\mathbf{x}^a`
-in the section :ref:`section_theory`.
+This ``Xa`` variable is a vector of values, that represents the solution of the
+data assimilation or optimization evaluation problem, noted as
+:math:`\mathbf{x}^a` in the section :ref:`section_theory`.
-Such command can be used to print results, or to convert these ones to
+Such method can be used to print results, or to convert these ones to
structures that can be used in the native or external SALOME post-processing. A
simple example is given in the section :ref:`section_examples`.
----------------------------------------------------
The YACS scheme is now complete and can be executed. Parametrization and
-execution of a YACS case is fully compliant with the standard way to deal with a
-YACS scheme, and is described in the *YACS module User's Guide*.
+execution of this YACS case is fully compliant with the standard way to deal
+with a YACS scheme, as described in the *YACS module User's Guide*.
To recall the simplest way to proceed, the YACS scheme has to be compiled using
the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
The standard output will be pushed into the "*YACS Container Log*", obtained
through the right click menu of the "*proc*" window in the YACS GUI. The errors
are shown either in the "*YACS Container Log*", or at the command line in the
-shell window (if SALOME has been launched by its explicit command and not by
-menu). As an example, the output of the above simple case is the following::
+shell window (if SALOME has been launched by its explicit command, and not by a
+menu or a desktop icon). As an example, the output of the above simple case is
+of the following form::
Entering in the assimilation study
Name is set to........: Test
The execution can also be done using a shell script, as described in the section
:ref:`section_advanced`.
-.. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
+.. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME platform.
-.. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
+.. [#] 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`.
--- /dev/null
+# Copyright (C) 2010-2013 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
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License.
+#
+# 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
+
+include $(top_srcdir)/adm_local/make_common_starter.am
+
+# You can set these variables from the command line.
+DOCLANG = fr
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = $(top_builddir)/doc/build/$(DOCLANG)
+SRCDIR = $(top_srcdir)/doc/$(DOCLANG)
+
+EXTRA_DIST = conf.py advanced.rst examples.rst index.rst intro.rst theory.rst using.rst \
+ resources/ADAO.png \
+ resources/ADAO_small.png \
+ resources/ADAO_small_rouge.png \
+ resources/ADAO_small_vert.png \
+ images/adao_activate.png \
+ images/adao_jdcexample01.png \
+ images/adao_scriptentry01.png \
+ images/adao_viewer.png \
+ images/eficas_new.png \
+ images/eficas_save.png \
+ images/eficas_yacs.png \
+ images/yacs_generatedscheme.png \
+ images/adao_exporttoyacs.png \
+ images/adao_jdcexample02.png \
+ images/adao_scriptentry02.png \
+ images/eficas_close.png \
+ images/eficas_open.png \
+ images/eficas_saveas.png \
+ images/yacs_containerlog.png
+
+install-data-local:
+ make html
+ ${mkinstalldirs} $(DESTDIR)$(docdir)/$(DOCLANG)
+ ${mkinstalldirs} $(DESTDIR)$(salomeresdir)
+ cp -R $(BUILDDIR)/html/* $(DESTDIR)$(docdir)/$(DOCLANG)
+ cp $(SRCDIR)/resources/*.png $(DESTDIR)$(salomeresdir)
+ cp $(SRCDIR)/images/eficas_*.png $(DESTDIR)$(salomeresdir)
+
+uninstall-local:
+ chmod -R +w $(DESTDIR)$(docdir)/$(DOCLANG)
+ rm -rf $(DESTDIR)$(docdir)
+ rm -f $(DESTDIR)$(salomeresdir)/*.png
+
+clean-local:
+ -rm -rf $(BUILDDIR)
+
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ADAO.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ADAO.qhc"
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
--- /dev/null
+.. _section_advanced:
+
+================================================================================
+Usages avancés du module ADAO
+================================================================================
+
+Cette section présente des méthodes avancées d'usage du module ADAO, comment
+obtenir plus d'information lors d'un calcul, ou comment l'utiliser sans
+l'interface graphique (GUI). Cela nécessite de savoir comment trouver les
+fichiers ou les commandes incuses dans l'installation complète de SALOME. Tous
+les noms à remplacer par l'utilisateur sont indiqués par la syntaxe ``<...>``.
+
+Convertir et exécuter un fichier de commandes ADAO (JDC) par l'intermédiaire d'un script shell
+----------------------------------------------------------------------------------------------
+
+Il est possible de convertir et exécuter une fichier de commandes ADAO (JDC, ou
+paire de fichiers ".comm/.py", qui se trouvent dans le répertoire ``<Répertoire
+du fichier JDC ADAO>``) automatiquement en utilisant un script de commandes
+shell "type" contenant toutes les étapes requises. L'utilisateur doit savoir où
+se trouvent les principaux fichiers de lancement de SALOME, et en particulier le
+fichier ``runAppli``. Le répertoire dans lequel ce fichier réside est
+symboliquement nommé ``<Répertoire principal d'installation de SALOME>`` et doit
+être remplacé par le bon dans le modèle "type" de fichier shell.
+
+Lorsqu'un fichier de commande ADAO est construit par l'interface d'édition
+EFICAS d'ADAO et est enregistré, s'il est nommé par exemple "EtudeAdao1.comm",
+alors un fichier compagnon nommé "EtudeAdao1.py" est automatiquement créé dans
+la même répertoire. Il est nommé ``<Fichier Python ADAO>`` dans le modèle
+"type", et il est converti vers YACS comme un ``<Schéma xml YACS ADAO>``.
+Ensuite, il peut être exécuté en mode console en utilisant la commande standard
+en mode console de YACS (voir la documentation YACS pour de plus amples
+informations).
+
+Dans l'exemple, on choisit de démarrer et arrêter le serveur d'application
+SALOME dans le même script, ce qui n'est pas nécessaire, mais utile pour éviter
+des sessions SALOME en attente. On choisit aussi de supprimer le fichier de
+``<Schéma xml YACS ADAO>`` car c'est un fichier généré. L'utilisateur de ce
+script a seulement besoin de remplacer le texte contenu entre les symboles
+``<...>``
+
+Le modèle "type" de ce script de commandes shell est le suivant::
+
+ #!/bin/bash
+ export USERDIR=<Répertoire du fichier JDC ADAO>
+ export SALOMEDIR=<Répertoire principal d'installation de SALOME>
+ $SALOMEDIR/runAppli -k -t
+ $SALOMEDIR/runSession python \
+ $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py \
+ $USERDIR/<Fichier Python ADAO> $USERDIR/<Schéma xml YACS ADAO>
+ $SALOMEDIR/runSession driver $USERDIR/<Schéma xml YACS ADAO>
+ $SALOMEDIR/runSession killSalome.py
+ rm -f $USERDIR/<Schéma xml YACS ADAO>
+
+Les sorties standard et d'erreur se font à la console.
+
+Exécuter un schéma de calcul ADAO dans YACS en utilisant le mode "texte" (TUI)
+------------------------------------------------------------------------------
+
+Cette section décrit comment exécuter en mode TUI (Text User Interface) un
+schéma de calcul YACS, obtenu par la fonction "*Exporter vers YACS*" d'ADAO.
+Cela utilise le mode texte standard de YACS, qui est rapidement rappelé ici
+(voir la documentation YACS pour de plus amples informations) à travers un
+exemple simple. Comme décrit dans la documentation, un schéma XML peut être
+chargé en python. On donne ici une séquence complète de commandes pour tester la
+validité du schéma avant de l'exécuter, ajoutant des lignes supplémentaires
+initiales pour charger de manière explicite le catalogue de types pour éviter
+des difficultés obscures::
+
+ #-*-coding:iso-8859-1-*-
+ import pilot
+ import SALOMERuntime
+ import loader
+ SALOMERuntime.RuntimeSALOME_setRuntime()
+
+ r = pilot.getRuntime()
+ xmlLoader = loader.YACSLoader()
+ xmlLoader.registerProcCataLoader()
+ try:
+ catalogAd = r.loadCatalog("proc", "<Schéma xml YACS ADAO>")
+ except:
+ pass
+ r.addCatalog(catalogAd)
+
+ try:
+ p = xmlLoader.load("<Schéma xml YACS ADAO>")
+ except IOError,ex:
+ print "IO exception:",ex
+
+ logger = p.getLogger("parser")
+ if not logger.isEmpty():
+ print "The imported file has errors :"
+ print logger.getStr()
+
+ if not p.isValid():
+ print "Le schéma n'est pas valide et ne peut pas être exécuté"
+ print p.getErrorReport()
+
+ info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
+ p.checkConsistency(info)
+ if info.areWarningsOrErrors():
+ print "Le schéma n'est pas cohérent et ne peut pas être exécuté"
+ print info.getGlobalRepr()
+
+ e = pilot.ExecutorSwig()
+ e.RunW(p)
+ if p.getEffectiveState() != pilot.DONE:
+ print p.getErrorReport()
+
+Cette démarche permet par exemple d'éditer le schéma YACS XML en mode texte TUI,
+ou pour rassembler les résultats pour un usage ultérieur.
+
+Obtenir des informations sur des variables spéciales au cours d'un calcul ADAO en YACS
+--------------------------------------------------------------------------------------
+
+Certaines variables spéciales internes à l'optimisation, utilisées au cours des
+calculs, peuvent être surveillées durant un calcul ADAO en YACS. Ces variables
+peuvent être affichées, tracées, enregistrées, etc. C'est réalisable en
+utilisant des "*observers*", qui sont des scripts, chacun associé à une
+variable. Pour pouvoir utiliser cette capacité, l'utilisateur doit construire
+des scripts disposant en entrée standard (i.e. disponible dans l'espace de
+nommage) des variables ``var`` et ``info``. La variable ``var`` est à utiliser
+de la même manière que l'objet final ADD, c'est-à-dire comme un objet de type
+liste/tuple.
+
+Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans
+l'éditeur EFICAS. Ces scripts simples peuvent être adaptés par l'utilisateur,
+soit dans l'étape EFICAS, ou dans l'étape d'édition YACS, pour améliorer
+l'adaptation du calcul ADAO dans YACS.
+
+A titre d'exemple, voici un script trés simple (similaire au modèle
+"*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée::
+
+ print " --->",info," Value =",var[-1]
+
+Stocké comme un fichier Python, ce script peut être associé à chaque variable
+présente dans le mot-clé "*SELECTION*" de la commande "*Observers*":
+"*Analysis*", "*CurrentState*", "*CostFunction*"... La valeur courante de la
+variable sera affichée à chaque étape de l'algorithme d'optimisation ou
+d'assimilation. Les "*observers*" peuvent inclure des capacités d'affichage
+graphique, de stockage, d'affichage complexe, de traitement statistique, etc.
+
+Obtenir plus d'information lors du déroulement d'un calcul
+----------------------------------------------------------
+
+Lors du déroulement d'un calcul, des données et messages utiles sont
+disponibles. Il y a deux manières d'obtenir ces informations.
+
+La première, et la manière préférentielle, est d'utiliser la variable interne
+"*Debug*" disponible dans chaque cas ADAO. Elle est atteignable dans l'interface
+graphique d'édition du module. La mettre à "*1*" permet d'envoyer des messages
+dans la fenêtre de sortie de l'exécution dans YACS ("*YACS Container Log*").
+
+La seconde consiste à utiliser le module Python natif "*logging*" (voir la
+documentation Python http://docs.python.org/library/logging.html pour de plus
+amples informations sur ce module). Dans l'ensemble du schéma YACS,
+principalement à travers les entrées sous forme de scripts, l'utilisateur peut
+fixer le niveau de logging en accord avec les besoins d'informations détaillées.
+Les différents niveaux de logging sont : "*DEBUG*", "*INFO*", "*WARNING*",
+"*ERROR*", "*CRITICAL*". Toutes les informations associées à un niveau sont
+affichées à tous les niveaux au-dessus de celui-ci (inclut). La méthode la plus
+facile consiste à changer le niveau de surveillance en utilisant les lignes
+Python suivantes::
+
+ import logging
+ logging.getLogger().setLevel(logging.DEBUG)
+
+Le niveau par défaut standard de surveillance par logging est "*WARNING*", le
+niveau par défaut dans le module ADAO est "*INFO*".
+
+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,
+quel que soit le niveau de surveillance choisi (c'est-à-dire même si ces
+variables ne sont pas affichées).
+
+Passer d'une version d'ADAO à une nouvelle
+------------------------------------------
+
+Le module ADAO et ses fichiers de cas ".comm" sont identifiés par des versions,
+avec des caractéristiques "Major", "Minor" et "Revision". Une version
+particulière est numérotée "Major.Minor.Revision", avec un lien fort avec la
+numérotation de la plateforme SALOME.
+
+Chaque version "Major.Minor.Revision" du module ADAO peut lire les fichiers de
+cas ADAO de la précédente version mineure "Major.Minor-1.*". En général, elle
+peut aussi lire les fichiers de cas de toutes les versions mineures "Major.*.*"
+d'une branche majeure, mais ce n'est pas obligatoirement vrai pour toutes les
+commandes ou tous les mots-clés. En général aussi, un fichier de cas ADAO d'une
+version ne peut pas être lu par une précédente version mineure ou majeure du
+module ADAO.
+
+Passer de la version 6.6 à la 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.
+
+Il y a une incompatibilité introduite dans les fichiers de script de
+post-processing ou d'observers. L'ancienne syntaxe pour interroger un objet
+résultat, comme celui d'analyse "*Analysis*" (fourni dans un script à travers le
+mot-clé "*UserPostAnalysis*"), était par exemple::
+
+ Analysis = ADD.get("Analysis").valueserie(-1)
+ Analysis = ADD.get("Analysis").valueserie()
+
+La nouvelle syntaxe est entièrement compatible avec celle (classique) pour les
+objets de type liste ou tuple::
+
+ Analysis = ADD.get("Analysis")[-1]
+ Analysis = ADD.get("Analysis")[:]
+
+Les scripts de post-processing doivent être modifiés.
+
+Passer de la version 6.5 à la 6.6
++++++++++++++++++++++++++++++++++
+
+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.
+
+Il y a une incompatibilité introduite dans la dénomination des opérateurs
+élémentaires utilisés pour l'opérateur d'observation par script. Les nouveaux
+noms requis sont "*DirectOperator*", "*TangentOperator*" et "*AdjointOperator*",
+comme décrit dans la quatrième partie du chapitre :ref:`section_reference`. Les
+scripts d'opérateur doivent être modifiés.
+
+Passer de la version 6.4 à la 6.5
++++++++++++++++++++++++++++++++++
+
+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.
+
+Passer de la version 6.3 à la 6.4
++++++++++++++++++++++++++++++++++
+
+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.
--- /dev/null
+.. _section_bibliography:
+
+================================================================================
+Bibliographie
+================================================================================
+
+.. [Argaud09] Argaud J.-P., Bouriquet B., Hunt J., *Data Assimilation from Operational and Industrial Applications to Complex Systems*, Mathematics Today, pp.150-152, October 2009
+
+.. [Bouttier99] Bouttier B., Courtier P., *Data assimilation concepts and methods*, Meteorological Training Course Lecture Series, ECMWF, 1999, http://www.ecmwf.int/newsevents/training/rcourse_notes/pdf_files/Assim_concepts.pdf
+
+.. [Bocquet04] Bocquet M., *Introduction aux principes et méthodes de l'assimilation de données en géophysique*, Lecture Notes, 2004-2008, http://cerea.enpc.fr/HomePages/bocquet/assim.pdf
+
+.. [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
+
+.. [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
+
+.. [Kalnay03] Kalnay E., *Atmospheric Modeling, Data Assimilation and Predictability*, Cambridge University Press, 2003
+
+.. [Salome] *SALOME The Open Source Integration Platform for Numerical Simulation*, http://www.salome-platform.org/
+
+.. [Tarantola87] Tarantola A., *Inverse Problem: Theory Methods for Data Fitting and Parameter Estimation*, Elsevier, 1987
+
+.. [Talagrand97] Talagrand O., *Assimilation of Observations, an Introduction*, Journal of the Meteorological Society of Japan, 75(1B), pp.191-209, 1997
+
+.. [WikipediaDA] Wikipedia, *Data assimilation*, http://en.wikipedia.org/wiki/Data_assimilation
+
+.. [WikipediaMO] Wikipedia, *Mathematical optimization*, https://en.wikipedia.org/wiki/Mathematical_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
+
+.. [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, Vol 23(4), pp.550-560, 1997
--- /dev/null
+# -*- coding: utf-8 -*-
+# Copyright (C) 2008-2013 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
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License.
+#
+# 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
+
+#
+# ADAO documentation build configuration file, created by
+# sphinx-quickstart on Wed Jun 16 15:48:00 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ["sphinx.ext.pngmath"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ADAO'
+copyright = u'2008-2013, 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.2.0'
+version = '7\_main'
+# The full version, including alpha/beta/rc tags.
+release = '7.2.0'
+release = '7\_main'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'fr'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ADAOdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+latex_paper_size = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'ADAO.tex', u'Documentation ADAO',
+ u'Jean-Philippe ARGAUD', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+source_encoding = 'iso-8859-15'
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'ADAO'
+epub_author = u'Jean-Philippe ARGAUD'
+epub_publisher = u'Jean-Philippe ARGAUD'
+epub_copyright = u'2008-2013, Jean-Philippe ARGAUD'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# -- Options for PDF output --------------------------------------------------
+# Grouping the document tree into PDF files. List of tuples
+# (source start file, target name, title, author, options).
+#
+# If there is more than one author, separate them with \\.
+# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
+#
+# The options element is a dictionary that lets you override
+# this config per-document.
+# For example,
+# ('index', u'MyProject', u'My Project', u'Author Name',
+# dict(pdf_compressed = True))
+# would mean that specific document would be compressed
+# regardless of the global pdf_compressed setting.
+pdf_documents = [
+ ('contents', u'ADAO', u'ADAO', u'Jean-Philippe ARGAUD', dict(pdf_compressed = True)),
+]
+# A comma-separated list of custom stylesheets. Example:
+pdf_stylesheets = ['sphinx','kerning','a4']
+# Create a compressed PDF
+# Use True/False or 1/0
+# Example: compressed=True
+#pdf_compressed = False
+pdf_compressed = True
+# A colon-separated list of folders to search for fonts. Example:
+# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']
+# Language to be used for hyphenation support
+#pdf_language = "en_US"
+# Mode for literal blocks wider than the frame. Can be
+# overflow, shrink or truncate
+#pdf_fit_mode = "shrink"
+# Section level that forces a break page.
+# For example: 1 means top-level sections start in a new page
+# 0 means disabled
+#pdf_break_level = 0
+# When a section starts in a new page, force it to be 'even', 'odd',
+# or just use 'any'
+#pdf_breakside = 'any'
+# Insert footnotes where they are defined instead of
+# at the end.
+#pdf_inline_footnotes = True
+# verbosity level. 0 1 or 2
+#pdf_verbosity = 0
+# If false, no index is generated.
+#pdf_use_index = True
+# If false, no modindex is generated.
+#pdf_use_modindex = True
+# If false, no coverpage is generated.
+#pdf_use_coverpage = True
+# Name of the cover page template to use
+#pdf_cover_template = 'sphinxcover.tmpl'
+# Documents to append as an appendix to all manuals.
+#pdf_appendices = []
+# Enable experimental feature to split table cells. Use it
+# if you get "DelayedTable too big" errors
+#pdf_splittables = False
+# Set the default DPI for images
+#pdf_default_dpi = 72
+# Enable rst2pdf extension modules (default is empty list)
+# you need vectorpdf for better sphinx's graphviz support
+#pdf_extensions = ['vectorpdf']
+# Page template name for "regular" pages
+#pdf_page_template = 'cutePage'
--- /dev/null
+.. _section_examples:
+
+================================================================================
+Tutoriaux sur l'utilisation du module ADAO
+================================================================================
+
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+ :scale: 50%
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+ :scale: 50%
+.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 50%
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+ :scale: 50%
+
+Cette section présente quelques exemples d'utilisation du module ADAO dans
+SALOME. Le premier montre comment construire un cas simple d'assimilation de
+données définissant explicitement toutes les données d'entrée requises à travers
+l'interface graphique d'édition (GUI). Le second montre, sur le même cas,
+comment définir les données d'entrée à partir de sources externes à travers des
+scripts. On présente ici toujours des scripts Python car ils sont directement
+insérables dans les noeuds de script de YACS, mais les fichiers externes peuvent
+utiliser d'autres langages.
+
+Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
+:ref:`section_theory`.
+
+Construire un cas d'estimation avec une définition explicite des données
+------------------------------------------------------------------------
+
+Cet exemple simple est un cas de démonstration, et il décrit comment mettre au
+point un environnement d'estimation par BLUE de manière à obtenir un *état
+estimé par méthode de moindres carrés pondérés* d'un système à partir d'une
+observation de l'état et d'une connaissance *a priori* (ou ébauche) de cet état.
+En d'autres termes, on cherche l'intermédiaire pondéré entre les vecteurs
+d'observation et d'ébauche. Toutes les valeurs numériques de cet exemple sont
+arbitraires.
+
+Conditions d'expérience
++++++++++++++++++++++++
+
+On choisit d'opérer dans un espace à 3 dimensions. La 3D est choisie de manière
+à restreindre la taille des objets numériques à entrer explicitement par
+l'utilisateur, mais le problème n'est pas dépendant de la dimension et peut être
+posé en dimension 10, 100, 1000... L'observation :math:`\mathbf{y}^o` vaut 1
+dans chaque direction, donc::
+
+ Yo = [1 1 1]
+
+L'ébauche :math:`\mathbf{x}^b` de l'état , qui représente une connaissance *a
+priori* ou une régularisation mathématique, vaut 0 dans chaque direction, ce qui
+donne donc::
+
+ Xb = [0 0 0]
+
+La mise en oeuvre de l'assimilation de données requiert des informations sur les
+covariances d'erreur :math:`\mathbf{R}` et :math:`\mathbf{B}`, respectivement
+pour les variables d'observation et d'ébauche. On choisit ici des erreurs
+décorrélées (c'est-à-dire des matrices diagonales) et d'avoir la même variance
+de 1 pour toutes les variables (c'est-à-dire des matrices identité). On pose
+donc::
+
+ B = R = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Enfin, on a besoin d'un opérateur d'observation :math:`\mathbf{H}` pour
+convertir l'état d'ébauche dans l'espace des observations. Ici, comme les
+dimensions d'espace sont les mêmes, on peut choisir l'identité comme opérateur
+d'observation::
+
+ H = [1 0 0 ; 0 1 0 ; 0 0 1]
+
+Avec de tels choix, l'estimateur "Best Linear Unbiased Estimator" (BLUE) sera le
+vecteur moyen entre :math:`\mathbf{y}^o` et :math:`\mathbf{x}^b`, nommé
+*analysis*, noté :math:`\mathbf{x}^a`, et valant::
+
+
+ Xa = [0.5 0.5 0.5]
+
+Pour étendre cet exemple, on peut modifier les variances représentées par
+:math:`\mathbf{B}` ou :math:`\mathbf{R}` indépendamment, et l'analyse
+:math:`\mathbf{x}^a` se déplacera vers :math:`\mathbf{y}^o` ou vers
+:math:`\mathbf{x}^b`, en proportion inverse des variances dans
+:math:`\mathbf{B}` et :math:`\mathbf{R}`. Comme autre extension, on peut aussi
+dire qu'il est équivalent de rechercher l'analyse à l'aide d'un algorithme de
+BLUE ou d'un algorithme de 3DVAR.
+
+Utiliser l'interface graphique (GUI) pour construire le cas ADAO
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+En premier lieu, il faut activer le module ADAO en choisissant le bouton ou le
+menu approprié de module de SALOME, et on voit :
+
+ .. _adao_activate2:
+ .. image:: images/adao_activate.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Activation du module ADAO dans SALOME**
+
+Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement
+l'interface EFICAS pour la définition de variables, en même temps que l'"*Arbre
+d'étude*" de SALOME. On peut alors choisir le bouton "*Nouveau*" |eficas_new|
+pour créer un nouveau cas ADAO, et on voit :
+
+ .. _adao_viewer:
+ .. image:: images/adao_viewer.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **L'éditeur EFICAS pour la définition de cas dans le module ADAO**
+
+Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant
+les conditions d'expérience décrites ci-dessus. L'ensemble des informations
+techniques données au-dessus sont à insérer directement dans la définition du
+cas ADAO, en utilisant le type *String* pour toutes les variables. Lorsque la
+définition du cas est prête, il faut l'enregistrer comme un fichier natif de ype
+"*JDC (\*.comm)*" à un endroit quelconque dans l'arborescence de l'utilisateur.
+Il faut bien se rappeler que d'autres fichiers seront aussi créés à côté de ce
+premier, donc il est judicieux de faire un répertoire spécifique pour ce cas, et
+d'enregistrer dedans le fichier. Le nom du fichier apparaît dans la fenêtre de
+l'"*Arbre d'étude*", sous le menu "*ADAO*". La définition finale du cas
+ressemble à :
+
+ .. _adao_jdcexample01:
+ .. image:: images/adao_jdcexample01.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définition des conditions d'expérience choisies pour le cas ADAO**
+
+Pour poursuivre, on a besoin de générer le schéma YACS à partir de la définition
+du cas ADAO. Pour faire cela, on peut activer le menu contextuel par click droit
+sur le nom du cas dans la fenêtre de l'"*Arbre d'étude*", et choisir le
+sous-menu "*Exporter vers YACS*" (ou le bouton "*Exporter vers YACS*"
+|eficas_yacs|) comme ci-dessous :
+
+ .. _adao_exporttoyacs00:
+ .. image:: images/adao_exporttoyacs.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Sous-menu contextuel "*Exporter vers YACS*" pour générer le schéma YACS à partir du cas ADAO**
+
+Cette commande conduit à la génération d'un schéma YACS, à l'activation du module
+YACS dans SALOME, et à ouvrir le nouveau schéma dans l'interface graphique du
+module YACS [#]_. Après avoir éventuellement réorganisé les noeuds en utilisant
+le sous-menu contextuel "*arranger les noeuds locaux*" de la vue graphique du
+schéma YACS, on obtient la représentation suivante du schéma ADAO généré :
+
+ .. _yacs_generatedscheme:
+ .. image:: images/yacs_generatedscheme.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Schéma YACS généré à partir du cas ADAO**
+
+Après ce point, toutes les modifications, exécutions et post-processing du
+schéma d'assimilation de données seront effectués dans le module YACS. De
+manière à vérifier les résultats d'une manière simple, on crée ici un nouveau
+noeud YACS en utilisant le sous-menu "*Noeud de script in-line*" dans la vue
+graphique de YACS, et on le nomme "*PostProcessing*".
+
+Ce noeud de script va récupérer l'analyse issue de l'assimilation de données
+depuis le port de sortie "*algoResults*" du bloc de calcul (qui donne accés à un
+objet Python SALOME), et va l'afficher à la sortie standard.
+
+Pour obtenir ceci, ce noeud de script doit comporter un port d'entrée de type
+"*pyobj*", nommé "*results*" par exemple, qui doit être relié graphiquement au
+port de sortie "*algoResults*" du bloc de calcul. Ensuite, le code pour remplir
+le noeud de script est::
+
+ Xa = results.ADD.get("Analysis")[-1]
+
+ print
+ print "Analysis =",Xa
+ print
+
+Le schéma YACS complété peut être enregistré (en écrasant le schéma généré si la
+commande ou le bouton "*Enregistrer*" sont utilisés, ou sinon avec un nom
+nouveau par la commande "*Enregistrer sous*"). De manière pratique, la mise au
+point d'une telle procédure de post-processing peut être réalisée dans YACS pour
+la tester, et ensuite entièrement enregistrée dans un script Python qui peut
+être intégré au cas ADAO en utilisant le mot-clé "*UserPostAnalysis*".
+
+Ensuite, de manière classique dans YACS, le schéma doit être compilé, et ensuite
+être exécuté. Après la fin de l'exécution, les affichages sur la sortie standard
+sont disponibles dans la fenêtre "*fenêtre de sortie de YACS*" (ou "*YACS
+Container Log*"), obtenue par clic droit à l'aide du menu contextuel de la
+fenêtre "*proc*" du schéma YACS comme montré ci-dessous:
+
+ .. _yacs_containerlog:
+ .. image:: images/yacs_containerlog.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **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:
+
+ Analysis = [0.5, 0.5, 0.5]
+
+comme montré dans l'image précédente.
+
+Pour étendre cet exemple, on peut remarquer que le même problème résolu par un
+algorithme de 3DVAR donne le même résultat. Cet algorithme peut être choisi lors
+de l'étape de construction du cas ADAO, avant d'entrer dans l'étape YACS. Le cas
+ADAO en 3DVAR est entièrement similaire au cas algorithmique du BLUE, comme
+montré dans la figure suivante:
+
+ .. _adao_jdcexample02:
+ .. image:: images/adao_jdcexample02.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définir un cas ADAO en 3DVAR est entièrement similaire à un cas en BLUE**
+
+Il n'y a qu'une seule commande qui change, avec "*3DVAR*" dans le champ
+"*Algorithm*" à la place de "*Blue*".
+
+Construire un cas d'estimation avec une définition de données externes par scripts
+----------------------------------------------------------------------------------
+
+Il est utile d'acquérir une partie ou la totalité des données depuis une
+définition externe, en utilisant des scripts Python pour donner accès à ces
+données. À titre d'exemple, on construit ici un cas ADAO présentant le même
+dispositif expérimental que dans l'exemple ci-dessus `Construire un cas
+d'estimation avec une définition explicite des données`_, mais en utilisant des
+données issues d'un unique fichier script Python externe.
+
+En premier lieu, on écrit le fichier script suivant, utilisant des noms
+conventionnels pour les variables requises. Ici toutes les variables sont
+définies dans le même script, mais l'utilisateur peut choisir de séparer le
+fichier en plusieurs autres, ou de mélanger une définition explicite des données
+dans l'interface graphique ADAO et une définition implicite dans des fichiers
+externes. Le fichier script actuel ressemble à::
+
+ import numpy
+ #
+ # Definition of the Background as a vector
+ # ----------------------------------------
+ Background = [0, 0, 0]
+ #
+ # Definition of the Observation as a vector
+ # -----------------------------------------
+ Observation = "1 1 1"
+ #
+ # Definition of the Background Error covariance as a matrix
+ # ---------------------------------------------------------
+ BackgroundError = numpy.array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])
+ #
+ # Definition of the Observation Error covariance as a matrix
+ # ----------------------------------------------------------
+ ObservationError = numpy.matrix("1 0 0 ; 0 1 0 ; 0 0 1")
+ #
+ # Definition of the Observation Operator as a matrix
+ # --------------------------------------------------
+ ObservationOperator = numpy.identity(3)
+
+Les noms des variables Python sont obligatoires, de manière à définir les bonnes
+variables dans le cas, mais le script Python peut être plus conséquent et
+définir des classes, des fonctions, des accès à des fichiers ou des bases de
+données, etc. avec des noms différents. De plus, le fichier ci-dessus présente
+différentes manières de définir des vecteurs ou des matrices, utilisant des
+listes, des chaînes de caractères (comme dans Numpy ou Octave), des types
+vecteur ou matrice de Numpy, et des fonctions spéciales de Numpy. Toutes ces
+syntaxes sont valides.
+
+Après avoir enregistré ce script dans un fichier (nommé ici "*script.py*" pour
+l'exemple) à un endroit quelconque dans l'arborescence de l'utilisateur, on
+utilise l'interface graphique (GUI) pour construire le cas ADAO. La procédure
+pour compléter le cas est similaire à celle de l'exemple précédent à part le
+fait que, au lieu de choisir l'option "*String*" pour le mot-clé "*FROM*" de
+chaque variable, on choisit l'option "*Script*". Cela conduit à une entrée
+"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique, permettant de choisir un
+fichier de la manière suivante:
+
+ .. _adao_scriptentry01:
+ .. image:: images/adao_scriptentry01.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Définir une variable d'entrée en utilisant un fichier script externe**
+
+Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
+précédent `Construire un cas d'estimation avec une définition explicite des
+données`_.
+
+Dans la pratique, cette démarche par scripts est la manière la plus facile pour
+récupérer des information depuis des calculs en ligne ou préalables, depuis des
+fichiers statiques, depuis des bases de données ou des flux informatiques,
+chacun pouvant être dans ou hors SALOME. Cela permet aussi de modifier aisément
+des données d'entrée, par exemple à des fin de débogage ou pour des traitements
+répétitifs, et c'est la méthode la plus polyvalente pour paramétrer les données
+d'entrée. **Mais attention, la méthodologie par scripts n'est pas une procédure
+"sûre", en ce sens que des données erronées ou des erreurs dans les calculs,
+peuvent être directement introduites dans l'exécution du schéma YACS.**
+
+Ajout de paramètres pour contrôler l'algorithme d'assimilation de données
+-------------------------------------------------------------------------
+
+On peut ajouter des paramètres optionnels pour contrôler le calcul de
+l'algorithme d'assimilation de données. Ceci se fait en utilisant le mot-clé
+"*AlgorithmParameters*" dans la définition du cas ADAO, qui est un mot-clé de la
+commande générale "*ASSIMILATION_STUDY*". Ce mot-clé nécessite un dictionnaire
+Python, contenant des paires clé/valeur. La liste des paramètres optionnels
+possibles sont donnés dans la section :ref:`section_reference`.
+
+Le dictionnaire doit être défini, par exemple, dans un fichiers externe de
+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:
+
+ AlgorithmParameters = {
+ "Minimizer" : "CG", # Choix possible : "LBFGSB", "TNC", "CG", "BFGS"
+ "MaximumNumberOfSteps" : 10,
+ }
+
+Si aucune borne n'est requise sur les variables de contrôle, alors on peut
+choisir les algorithmes de minimisation "*BFGS*" ou "*CG*" pour tous les
+algorithmes variationnels d'assimilation de données ou d'optimisation. Pour
+l'optimisation sous contraintes, le minimiseur "*LBFGSB*" est souvent plus
+robuste, mais le "*TNC*" est parfois plus performant.
+
+Ensuite le script peut être ajouté au cas ADAO, dans une entrée de type fichier
+pour le mot-clé "*AlgorithmParameters*", de la manière suivante:
+
+ .. _adao_scriptentry02:
+ .. image:: images/adao_scriptentry02.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Ajouter des paramètres pour contrôler l'algorithme et les sorties**
+
+Les autres étapes et résultats sont exactement les mêmes que dans l'exemple
+précédent `Construire un cas d'estimation avec une définition explicite des
+données`_. Le dictionnaire peut aussi être donné directement dans le champ
+d'entrée de type chaîne de caractères pour le mot-clé.
+
+Construire un cas complexe avec une définition de données externes par scripts
+------------------------------------------------------------------------------
+
+Cet exemple plus complexe et complet peut être considéré comme un cadre de base
+pour le traitement des entrées de l'utilisateur, qui doit ensuite être adapté à
+chaque application réelle. Néanmoins, les squelettes de fichiers sont
+suffisamment généraux pour avoir été utilisés pour des applications variées en
+neutronique, mécanique des fluides... Ici, on ne s'intéresse pas aux résultats,
+mais plus sur le contrôle de l'utilisateur des entrées et sorties dans un cas
+ADAO. Comme précédemment, toutes les valeurs numériques de cet exemple sont
+arbitraires.
+
+L'objectif est de configurer les entrées et les sortie d'un problème physique
+d'estimation par des scripts externes Python, en utilisant un opérateur
+non-linéaire général, en ajoutant un contrôle sur les paramètres et ainsi de
+suite... Les scripts complets peuvent être trouvés dans le répertoire des
+exemples de squelettes ADAO sous le nom de
+"*External_data_definition_by_scripts*".
+
+Conditions d'expérience
++++++++++++++++++++++++
+
+On continue à opérer dans un espace à 3 dimensions, afin de limiter la taille de
+l'objet numérique indiqué dans les scripts, mais le problème ne dépend pas de la
+dimension.
+
+On choisit un contexte d'expériences jumelles, en utilisant un état vrai
+:math:`\mathbf{x}^t` connu, mais de valeur arbitraire::
+
+ Xt = [1 2 3]
+
+L'état d'ébauche :math:`\mathbf{x}^b`, qui représentent une connaissance *a
+priori* de l'état vrai, est construit comme une perturbation aléatoire
+gaussienne de 20% de l'état vrai :math:`\mathbf{x}^t` pour chaque composante,
+qui est::
+
+ Xb = Xt + normal(0, 20%*Xt)
+
+Pour décrire la matrice des covariances d'erreur d'ébauche math:`\mathbf{B}`, on
+fait comme précédemment l'hypothèse d'erreurs décorrélées (c'est-à-dire, une
+matrice diagonale, de taille 3x3 parce-que :math:`\mathbf{x}^b` est de taille 3)
+et d'avoir la même variance de 0,1 pour toutes les variables. On obtient::
+
+ B = 0.1 * diagonal( length(Xb) )
+
+On suppose qu'il existe un opérateur d'observation :math:`\mathbf{H}`, qui peut
+être non linéaire. Dans une procédure réelle de recalage ou de problème inverse,
+les codes de simulation physique sont intégrés dans l'opérateur d'observation.
+On a également besoin de connaître son gradient par rapport à chaque variable
+estimée, ce qui est une information rarement connu avec les codes industriels.
+Mais on verra plus tard comment obtenir un gradient approché dans ce cas.
+
+Étant en expériences jumelles, les observations :math:`\mathbf{y}^o` et leur
+matrice de covariances d'erreurs :math:`\mathbf{R}` sont générées en utilisant
+l'état vrai :math:`\mathbf{x}^t` et l'opérateur d'observation
+:math:`\mathbf{H}`::
+
+ Yo = H( Xt )
+
+et, avec un écart-type arbitraire de 1% sur chaque composante de l'erreur::
+
+ R = 0.0001 * diagonal( lenght(Yo) )
+
+Toutes les informations requises pour l'estimation par assimilation de données
+sont maintenant définies.
+
+Squelettes des scripts décrivant les conditions d'expérience
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+On donne ici les éléments essentiels de chaque script utilisé par la suite pour
+construire le cas ADAO. On rappelle que l'utilisation de ces scripts dans de
+réels fichiers Python nécessite de définir correctement le chemin de modules ou
+des codes importés (même si le module est dans le même répertoire que le fichier
+Python qui l'importe. On indique le chemin à renseigner en utilisant la mention
+``"# INSERT PHYSICAL SCRIPT PATH"``), l'encodage si nécessaire, etc. Les noms de
+fichiers indiqués pour les scripts qui suivent sont arbitraires. Des exemples
+complets de fichiers scripts sont disponibles dans le répertoire standard des
+exemples ADAO.
+
+On définit en premier lieu l'état vrai :math:`\mathbf{x}^t` et une fonction
+utiles à la construction de matrices, dans un fichier script Python nommé
+``Physical_data_and_covariance_matrices.py``::
+
+ import numpy
+ #
+ def True_state():
+ """
+ Arbitrary values and names, as a tuple of two series of same length
+ """
+ return (numpy.array([1, 2, 3]), ['Para1', 'Para2', 'Para3'])
+ #
+ def Simple_Matrix( size, diagonal=None ):
+ """
+ Diagonal matrix, with either 1 or a given vector on the diagonal
+ """
+ if diagonal is not None:
+ S = numpy.diag( diagonal )
+ else:
+ S = numpy.matrix(numpy.identity(int(size)))
+ return S
+
+On définit ensuite l'état d'ébauche :math:`\mathbf{x}^b` comme une perturbation
+aléatoire de l'état vrai, en ajoutant une *variable ADAO requise* à la fin du
+script de définition, de manière à exporter la valeur définie. C'est réalisé
+dans un fichier de script Python nommé ``Script_Background_xb.py``::
+
+ from Physical_data_and_covariance_matrices import True_state
+ import numpy
+ #
+ xt, names = True_state()
+ #
+ Standard_deviation = 0.2*xt # 20% for each variable
+ #
+ xb = xt + abs(numpy.random.normal(0.,Standard_deviation,size=(len(xt),)))
+ #
+ # Creating the required ADAO variable
+ # ------------------------------------
+ Background = list(xb)
+
+De la même manière, on définit la matrice des covariances de l'erreur d'ébauche
+:math:`\mathbf{B}` comme une matrice diagonale, de la même longueur de diagonale
+que l'ébauche de la valeur vraie, en utilisant la fonction d'aide déjà définie.
+C'est réalisé dans un fichier script Python nommé
+``Script_BackgroundError_B.py``::
+
+ from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
+ #
+ xt, names = True_state()
+ #
+ B = 0.1 * Simple_Matrix( size = len(xt) )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ BackgroundError = B
+
+Pour poursuivre, on a besoin de l'opérateur d'observation :math:`\mathbf{H}`
+comme une fonction de l'état. Il est ici défini dans un fichier externe nommé
+``"Physical_simulation_functions.py"``, qui doit contenir une fonction appelée
+``"DirectOperator"``. Cette fonction est une une fonction utilisateur,
+représentant de manière programmée l'opérateur :math:`\mathbf{H}`. On suppose
+que cette fonction est donnée par l'utilisateur. Un squelette simple est donné
+ici par facilité::
+
+ def DirectOperator( XX ):
+ """ Direct non-linear simulation operator """
+ #
+ # --------------------------------------> EXAMPLE TO BE REMOVED
+ if type(XX) is type(numpy.matrix([])): # EXAMPLE TO BE REMOVED
+ HX = XX.A1.tolist() # EXAMPLE TO BE REMOVED
+ elif type(XX) is type(numpy.array([])): # EXAMPLE TO BE REMOVED
+ HX = numpy.matrix(XX).A1.tolist() # EXAMPLE TO BE REMOVED
+ else: # EXAMPLE TO BE REMOVED
+ HX = XX # EXAMPLE TO BE REMOVED
+ # --------------------------------------> EXAMPLE TO BE REMOVED
+ #
+ return numpy.array( HX )
+
+On n'a pas besoin des opérateurs linéaires associés ``"TangentOperator"`` et
+``"AdjointOperator"`` car ils vont être approximés en utilisant les capacités
+d'ADAO.
+
+On insiste sur le fait que ces opérateurs non-linéaire ``"DirectOperator"``,
+linéaire tangent ``"TangentOperator"`` et linéaire adjoint ``"AdjointOperator"``
+proviennent de la connaissance de la physique, incluant le code de simulation de
+référence physique, et doivent être soigneusement mis au point par l'utilisateur
+de l'assimilation de données ou de l'optimisation. Les erreurs de simulation ou
+d'usage des opérateurs ne peuvent pas être détectés ou corrigés par
+l'environnement seul ADAO d'assimilation de données et d'optimisation.
+
+Dans cet environnement d'expériences jumelles, l'observation
+:math:`\mathbf{y}^o` et sa matrice des covariances d'erreur :math:`\mathbf{R}`
+peuvent être générées. C'est réalisé dans deux fichiers de script Python, le
+premier étant nommé ``Script_Observation_yo.py``::
+
+ from Physical_data_and_covariance_matrices import True_state
+ from Physical_simulation_functions import DirectOperator
+ #
+ xt, noms = True_state()
+ #
+ yo = DirectOperator( xt )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ Observation = list(yo)
+
+et le second nommé ``Script_ObservationError_R.py``::
+
+ from Physical_data_and_covariance_matrices import True_state, Simple_Matrix
+ from Physical_simulation_functions import DirectOperator
+ #
+ xt, names = True_state()
+ #
+ yo = DirectOperator( xt )
+ #
+ R = 0.0001 * Simple_Matrix( size = len(yo) )
+ #
+ # Creating the required ADAO variable
+ # -----------------------------------
+ ObservationError = R
+
+Comme dans les exemples précédents, il peut être utile de définir certains
+paramètres pour l'algorithme d'assimilation de données. Par exemple, si on
+utilise l'algorithme standard de "*3DVAR*", les paramètres suivants peuvent être
+définis dans un fichier de script Python nommé
+``Script_AlgorithmParameters.py``::
+
+ # Creating the required ADAO variable
+ # -----------------------------------
+ AlgorithmParameters = {
+ "Minimizer" : "TNC", # Possible : "LBFGSB", "TNC", "CG", "BFGS"
+ "MaximumNumberOfSteps" : 15, # Number of global iterative steps
+ "Bounds" : [
+ [ None, None ], # Bound on the first parameter
+ [ 0., 4. ], # Bound on the second parameter
+ [ 0., None ], # Bound on the third parameter
+ ],
+ }
+
+Enfin, il est courant de post-traiter les résultats, en les récupérant aprés la
+phase d'assimilation de données de manière à les analyser, les afficher ou les
+représenter. Cela nécessite d'utiliser un fichier script Python intermédiaire de
+manière à extraire ces résultats à la fin de la procédure d'assimilation de
+données ou d'optimisation. L'exemple suivant de fichier script Python, nommé
+``Script_UserPostAnalysis.py``, illustre le fait::
+
+ from Physical_data_and_covariance_matrices import True_state
+ import numpy
+ #
+ xt, names = True_state()
+ xa = ADD.get("Analysis")[-1]
+ x_series = ADD.get("CurrentState")[:]
+ J = ADD.get("CostFunctionJ")[:]
+ #
+ # Verifying the results by printing
+ # ---------------------------------
+ print
+ print "xt = %s"%xt
+ print "xa = %s"%numpy.array(xa)
+ print
+ for i in range( len(x_series) ):
+ 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:
+
+#. ``Physical_data_and_covariance_matrices.py``
+#. ``Physical_simulation_functions.py``
+#. ``Script_AlgorithmParameters.py``
+#. ``Script_BackgroundError_B.py``
+#. ``Script_Background_xb.py``
+#. ``Script_ObservationError_R.py``
+#. ``Script_Observation_yo.py``
+#. ``Script_UserPostAnalysis.py``
+
+On insiste ici sur le fait que tous ces scripts sont écrits par l'utilisateur et
+ne peuvent être testés automatiquement par ADAO. Ainsi, l'utilisateur est tenu
+de vérifier les scripts (et en particulier leurs entrées/sorties) afin de
+limiter les difficultés de débogage. On rappelle que: **la méthodologie par
+scripts n'est pas une procédure "sûre", en ce sens que des données erronées ou
+des erreurs dans les calculs, peuvent être directement introduites dans
+l'exécution du schéma YACS.**
+
+Construire la cas avec une définition de données externes par scripts
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Tous ces scripts peuvent ensuite être utilisés pour définir le cas ADAO avec une
+définition de données externes par des fichiers de script Python. Cela se
+réalise de manière tout à fait similaire à la méthode décrite dans la partie
+précédente `Construire un cas d'estimation avec une définition de données
+externes par scripts`_. Pour chaque variable à définir, on sélectionne l'option
+"*Script*" du mot-clé "*FROM*", ce qui conduit à une entrée
+"*SCRIPT_DATA/SCRIPT_FILE*" dans l'arbre graphique. Pour le mot-clé
+"*ObservationOperator*", on choisit la forme "*ScriptWithOneFunction*" et on
+conserve la valeur par défaut de l'incrément différentiel.
+
+Les autres étapes pour construire le cas ADAO sont exactement les mêmes que dans
+la partie précédente `Construire un cas d'estimation avec une définition
+explicite des données`_.
+
+En utilisant l'opérateur linéaire simple :math:`\mathbf{H}` du fichier script
+Python ``Physical_simulation_functions.py`` disponible dans le répertoire
+standard des exemples, les résultats ressemblent à::
+
+ xt = [1 2 3]
+ xa = [ 1.000014 2.000458 3.000390]
+
+ Etape 0 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
+ Etape 1 : J = 1.81750e+03 et X = [1.014011, 2.459175, 3.390462]
+ Etape 2 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
+ Etape 3 : J = 1.79734e+01 et X = [1.010771, 2.040342, 2.961378]
+ Etape 4 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
+ Etape 5 : J = 1.81909e+00 et X = [1.000826, 2.000352, 3.000487]
+ Etape 6 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
+ Etape 7 : J = 1.81641e+00 et X = [1.000247, 2.000651, 3.000156]
+ Etape 8 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
+ Etape 9 : J = 1.81569e+00 et X = [1.000015, 2.000432, 3.000364]
+ Etape 10 : J = 1.81568e+00 et X = [1.000013, 2.000458, 3.000390]
+ ...
+
+L'état au premier pas est l'état d'ébauche :math:`\mathbf{x}^b` généré
+aléatoirement. Au cours du calcul, ces affichages sur la sortie standard sont
+disponibles dans la fenêtre "*fenêtre de sortie de YACS*", que l'on obtient par
+clic droit sur la fenêtre "*proc*" du schéma YACS exécuté.
+
+.. [#] Pour de plus amples informations sur YACS, voir le *Guide utilisateur du module YACS* disponible dans le menu principal *Aide* de l'environnement SALOME.
--- /dev/null
+.. _section_glossary:
+
+Glossaire
+=========
+
+.. glossary::
+ :sorted:
+
+ cas
+ Un cas ADAO est défini par un jeu de données et de choix, rassemblés par
+ l'intermédiaire de l'interface utilisateur du module. Les données sont les
+ mesures physiques qui doivent être techniquement disponibles avant ou
+ pendant l'exécution du cas. Le (ou les) code(s) de simulation et la
+ méthode d'assimilation de données ou d'optimisation, ainsi que leurs
+ paramètres, doivent être choisis, ils définissent les propriétés
+ d'exécution du cas.
+
+ itération
+ Une itération a lieu lorsque l'on utilise des méthodes d'optimisation
+ itératives (par exemple le 3DVAR), et c'est entièrement caché à
+ l'intérieur du noeud principal de type YACS OptimizerLoop nommé
+ "*compute_bloc*". Néanmoins, l'utilisateur peut observer le processus
+ itératif à l'aide de la fenêtre "*YACS Container Log*", qui est mise à
+ jour au fur et à mesure du déroulement du calcul, et en utilisant des
+ "*Observers*" attachés à des variables de calcul.
+
+ APosterioriCovariance
+ Mot-clé indiquant la matrice de covariance des erreurs *a posteriori*
+ d'analyse.
+
+ BMA (Background minus Analysis)
+ Différence entre l'état d'ébauche et l'état optimal estimé, notée
+ :math:`\mathbf{x}^b - \mathbf{x}^a`.
+
+ OMA (Observation minus Analysis)
+ Différence entre les observations et le résultat de la simulation basée
+ sur l'état optimal estimé, l'analyse, filtré pour être compatible avec les
+ observations, notée :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^a`.
+
+ OMB (Observation minus Background)
+ Différence entre les observations et le résultat de la simulation basée
+ sur l'état d'ébauche, filtré pour être compatible avec les observations,
+ notée :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^b`.
+
+ SigmaBck2
+ Mot-clé indiquant le paramètre de Desroziers-Ivanov mesurant la
+ consistance de la partie due à l'ébauche dans l'estimation optimale d'état
+ par assimilation de données. Sa valeur peut être comparée à 1, une "bonne"
+ estimation conduisant à un paramètre "proche" de 1.
+
+ SigmaObs2
+ Mot-clé indiquant le paramètre de Desroziers-Ivanov mesurant la
+ consistance de la partie due à l'observation dans l'estimation optimale
+ d'état par assimilation de données. Sa valeur peut être comparée à 1, une
+ "bonne" estimation conduisant à un paramètre "proche" de 1.
+
+ MahalanobisConsistency
+ Mot-clé indiquant le paramètre de Mahalanobis mesurant la consistance de
+ l'estimation optimale d'état par assimilation de données. Sa valeur peut
+ être comparée à 1, une "bonne" estimation conduisant à un paramètre
+ "proche" de 1.
+
+ analyse
+ L'état optimal estimé par une procédure d'assimilation de données ou
+ d'optimisation.
+
+ background
+ C'est le terme anglais pour désigner l'ébauche.
+
+ ébauche
+ C'est l'état du système connu *a priori*, qui n'est pas optimal, et qui
+ est utilisé comme une estimation grossière, ou "la meilleure connue",
+ avant une estimation optimale.
+
+ innovation
+ Différence entre les observations et le résultat de la simulation basée
+ sur l'état d'ébauche, filtré pour être compatible avec les observations.
+ C'est similaire à OMB dans les cas statiques.
+
+ CostFunctionJ
+ Mot-clé indiquant la fonction de minimisation, notée :math:`J`.
+
+ CostFunctionJo
+ Mot-clé indiquant la partie due aux observations dans la fonction de
+ minimisation, notée :math:`J^o`.
+
+ CostFunctionJb
+ Mot-clé indiquant la partie due à l'ébauche dans la fonction de
+ minimisation, notée :math:`J^b`.
--- /dev/null
+================================================================================
+Documentation ADAO
+================================================================================
+
+.. image:: images/ADAO_logo.png
+ :align: center
+ :width: 20%
+
+Le module ADAO fournit des fonctionnalités d'**assimilation des données et
+d'optimisation** dans un contexte SALOME. Il est basé sur l'utilisation d'autres
+modules, à savoir YACS et EFICAS, et sur l'utilisation d'une bibliothèque
+générique sous-jacente d'assimilation de données.
+
+En bref, l'assimilation des données est un cadre méthodologique pour calculer
+l'estimation optimale de la valeur réelle (inaccessible) de l'état d'un système
+au cours du temps. Il utilise des informations provenant de mesures
+expérimentales, ou observations, et de modèles numériques *a priori*, y compris
+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
+: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
+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.
+
+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
+l'optimisation. En particulier, les vecteurs sont écrits horizontalement ou
+verticalement sans faire la différence. Les matrices sont écrites soit
+normalement, ou avec une notation condensée, consistant à utiliser un espace
+pour séparer les valeurs, et un "``;``" pour séparer les lignes de la matrice,
+de façon continue sur une ligne.
+
+Table des matières
+------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ theory
+ using
+ reference
+ examples
+ advanced
+ licence
+ bibliography
+
+Index et tables
+---------------
+
+* :ref:`genindex`
+* :ref:`search`
+* :ref:`section_glossary`
--- /dev/null
+.. _section_intro:
+
+================================================================================
+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
+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
+une ou plusieurs méthodes d'appel spécifiques afin d'être appelable dans le
+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
+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.
+
+Le module couvre une grande variété d'applications pratiques, de façon robuste,
+permettant des applications réelles, mais aussi d'effectuer de l'expérimentation
+méthodologique rapide. Son évolutivité, des points de vue méthodologique et
+numérique, permettra l'extension de son domaine d'application.
--- /dev/null
+.. _section_reference:
+
+================================================================================
+Description de référence des commandes et mots-clés ADAO
+================================================================================
+
+Cette section présente la description de référence des commandes et mots-clés
+ADAO disponibles à travers l'interface graphique (GUI) ou à travers des scripts.
+Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des
+propriétés particulières. La première propriété est d'être *requise*,
+*optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde
+propriété est d'être une variable "ouverte" avec un type fixé mais avec
+n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée
+à des valeurs spécifiées. L'éditeur graphique EFICAS disposant de capacités
+intrinsèques de validation, les propriétés des commandes ou mots-clés données à
+l'aide de l'interface graphique sont automatiquement correctes.
+
+Les notations mathématiques utilisées ci-dessous sont expliquées dans la section
+:ref:`section_theory`.
+
+Des exemples sur l'usage de ces commandes sont disponibles dans la section
+:ref:`section_examples` et dans les fichiers d'exemple installés avec le module
+ADAO.
+
+Liste des types d'entrées possibles
+-----------------------------------
+
+.. index:: single: Dict
+.. index:: single: Function
+.. index:: single: Matrix
+.. index:: single: ScalarSparseMatrix
+.. index:: single: DiagonalSparseMatrix
+.. index:: single: String
+.. index:: single: Script
+.. index:: single: Vector
+
+Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la
+valider. Les différents pseudo-types sont:
+
+**Dict**
+ Cela indique une variable qui doit être remplie avec un dictionnaire Python
+ ``{"clé":"valeur"...}``, usuellement donné soit par une chaîne de caractères
+ soit par un fichier script.
+
+**Function**
+ Cela indique une variable qui doit être donnée comme une fonction Python,
+ usuellement donnée soit par une chaîne de caractères soit par un fichier
+ script.
+
+**Matrix**
+ Cela indique une variable qui doit être donnée comme une matrice,
+ usuellement donnée soit par une chaîne de caractères soit par un fichier
+ script.
+
+**ScalarSparseMatrix**
+ Cela indique une variable qui doit être donnée comme un nombre unique (qui
+ sera utilisé pour multiplier une matrice identité), usuellement donné soit
+ par une chaîne de caractères soit par un fichier script.
+
+**DiagonalSparseMatrix**
+ Cela indique une variable qui doit , (qui sera
+ utilisé pour remplacer la diagonale d'une matrice identité), usuellement
+ donné soit par une chaîne de caractères soit par un fichier script.
+
+**Script**
+ Cela indique un script donné comme un fichier externe. Il peut être désigné
+ par un nom de fichier avec chemin complet ou seulement par un nom de fichier
+ sans le chemin. Si le fichier est donné uniquement par un nom sans chemin,
+ et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans
+ le répertoire d'étude donné.
+
+**String**
+ Cela indique une chaîne de caractères fournissant une représentation
+ littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme
+ par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille
+ 2x2.
+
+**Vector**
+ Cela indique une variable qui doit être remplie comme un vecteur,
+ usuellement donné soit par une chaîne de caractères soit par un fichier
+ script.
+
+**VectorSerie**
+ Cela indique une variable qui doit être remplie comme une liste de vecteurs,
+ usuellement donnée soit par une chaîne de caractères soit par un fichier
+ script.
+
+Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script,
+ce script doit présenter une variable ou une méthode que porte le même nom que
+la variable à remplir. En d'autres mots, lorsque l'on importe le script dans un
+noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de
+nommage courant du noeud.
+
+Description de référence pour les cas de calcul ADAO
+----------------------------------------------------
+
+Liste des commandes et mots-clés pour un cas de calcul ADAO
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: ASSIMILATION_STUDY
+.. index:: single: Algorithm
+.. index:: single: AlgorithmParameters
+.. index:: single: Background
+.. index:: single: BackgroundError
+.. index:: single: ControlInput
+.. index:: single: Debug
+.. index:: single: EvolutionError
+.. index:: single: EvolutionModel
+.. index:: single: InputVariables
+.. index:: single: Observation
+.. index:: single: ObservationError
+.. index:: single: ObservationOperator
+.. index:: single: Observers
+.. index:: single: OutputVariables
+.. index:: single: Study_name
+.. index:: single: Study_repertory
+.. index:: single: UserDataInit
+.. index:: single: UserPostAnalysis
+
+La première série de commandes est liée à la description d'un cas de calcul, qui
+est une procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes
+sont classés par ordre alphabétique, sauf le premier, qui décrit le choix entre
+le calcul ou la vérification. Les différentes commandes sont les suivantes:
+
+**ASSIMILATION_STUDY**
+ *Commande obligatoire*. C'est la commande générale qui décrit le cas
+ d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement
+ toutes les autres commandes.
+
+**Algorithm**
+ *Commande obligatoire*. C'est une chaîne de caractère qui indique l'algorithme
+ d'assimilation de données ou d'optimisation choisi. Les choix sont limités
+ et disponibles à travers l'interface graphique. Il existe par exemple le
+ "3DVAR", le "Blue"... Voir plus loin la liste des algorithmes et des
+ paramètres associés dans la sous-section `Commandes optionnelles et requises
+ pour les algorithmes de calcul`_.
+
+**AlgorithmParameters**
+ *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour
+ contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa
+ valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste
+ des algorithmes et des paramètres associés dans la sous-section `Commandes
+ optionnelles et requises pour les algorithmes de calcul`_.
+
+**Background**
+ *Commande obligatoire*. Elle définit le vecteur d'ébauche ou
+ d'initialisation, noté précédemment :math:`\mathbf{x}^b`. Sa valeur est
+ définie comme un objet de type "*Vector*".
+
+**BackgroundError**
+ *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
+ d'ébauche, notée précédemment :math:`\mathbf{B}`. Sa valeur est définie
+ comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
+ type "*DiagonalSparseMatrix*".
+
+**ControlInput**
+ *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour
+ forcer le modèle d'évolution à chaque pas, usuellement noté
+ :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*"
+ ou de type *VectorSerie*. Lorsqu'il n'y a pas de contrôle, sa valeur doit
+ être une chaîne vide ''.
+
+**Debug**
+ *Commande obligatoire*. Elle définit le niveau de sorties et d'informations
+ intermédiaires de débogage. Les choix sont limités entre 0 (pour False) and
+ 1 (pour True).
+
+**EvolutionError**
+ *Commande optionnelle*. Elle définit la matrice de covariance des erreurs
+ d'évolution, usuellement notée :math:`\mathbf{Q}`. Sa valeur est définie
+ comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
+ type "*DiagonalSparseMatrix*".
+
+**EvolutionModel**
+ *Commande optionnelle*. Elle indique l'opérateur d'évolution du modèle,
+ usuellement noté :math:`M`, qui décrit un pas élémentaire d'évolution. Sa
+ valeur est définie comme un objet de type "*Function*". Différentes formes
+ fonctionnelles peuvent être utilisées, comme décrit dans la sous-section
+ suivante `Exigences pour les fonctions décrivant un opérateur`_. Si un
+ contrôle :math:`U` est inclus dans le modèle d'évolution, l'opérateur doit
+ être appliqué à une paire :math:`(X,U)`.
+
+**InputVariables**
+ *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
+ variables physiques qui sont rassemblées dans le vecteur d'état. Cette
+ information est destinée à être utilisée dans le traitement algorithmique
+ interne des données.
+
+**Observation**
+ *Commande obligatoire*. Elle définit le vecteur d'observation utilisé en
+ assimilation de données ou en optimisation, et noté précédemment
+ :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type "*Vector*"
+ ou de type *VectorSerie*".
+
+**ObservationError**
+ *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
+ d'ébauche, notée précédemment :math:`\mathbf{R}`. Sa valeur est définie
+ comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
+ type "*DiagonalSparseMatrix*".
+
+**ObservationOperator**
+ *Commande obligatoire*. Elle indique l'opérateur d'observation, notée
+ précédemment :math:`H`, qui transforme les paramètres d'entrée
+ :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
+ observations :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de
+ type "*Function*". Différentes formes fonctionnelles peuvent être utilisées,
+ comme décrit dans la sous-section suivante `Exigences pour les fonctions
+ décrivant un opérateur`_. Si un contrôle :math:`U` est inclus dans le modèle
+ d'observation, l'opérateur doit être appliqué à une paire :math:`(X,U)`.
+
+**Observers**
+ *Commande optionnelle*. Elle permet de définir des observateurs internes,
+ qui sont des fonctions liées à une variable particulière, qui sont exécutées
+ chaque fois que cette variable est modifiée. C'est une manière pratique de
+ suivre des variables d'intérêt durant le processus d'assimilation de données
+ ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples
+ courants (squelettes) sont fournis pour aider l'utilisateur ou pour
+ faciliter l'élaboration d'un cas.
+
+**OutputVariables**
+ *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des
+ variables physiques qui sont rassemblées dans le vecteur d'observation.
+ Cette information est destinée à être utilisée dans le traitement
+ algorithmique interne des données.
+
+**Study_name**
+ *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
+ décrire l'étude ADAO par un nom ou une déclaration.
+
+**Study_repertory**
+ *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
+ pour les calculs, et il est utilisé pour trouver les fichiers de script,
+ donnés par nom sans répertoire, qui peuvent être utilisés pour définir
+ certaines variables.
+
+**UserDataInit**
+ *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
+ certaines données automatiquement avant le traitement de données d'entrée
+ pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
+ nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
+ variables choisies.
+
+**UserPostAnalysis**
+ *Commande optionnelle*. Elle permet de traiter des paramètres ou des
+ résultats après le déroulement de l'algorithme d'assimilation de données ou
+ d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne
+ de caractères, permettant de produire directement du code de post-processing
+ dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider
+ l'utilisateur ou pour faciliter l'élaboration d'un cas.
+
+Commandes optionnelles et requises pour les algorithmes de calcul
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: 3DVAR
+.. index:: single: Blue
+.. index:: single: ExtendedBlue
+.. index:: single: EnsembleBlue
+.. index:: single: KalmanFilter
+.. index:: single: ExtendedKalmanFilter
+.. index:: single: UnscentedKalmanFilter
+.. index:: single: LinearLeastSquares
+.. index:: single: NonLinearLeastSquares
+.. index:: single: ParticleSwarmOptimization
+.. index:: single: QuantileRegression
+
+.. index:: single: AlgorithmParameters
+.. index:: single: Bounds
+.. index:: single: CostDecrementTolerance
+.. index:: single: GradientNormTolerance
+.. index:: single: GroupRecallRate
+.. index:: single: MaximumNumberOfSteps
+.. index:: single: Minimizer
+.. index:: single: NumberOfInsects
+.. index:: single: ProjectedGradientTolerance
+.. index:: single: QualityCriterion
+.. index:: single: Quantile
+.. index:: single: SetSeed
+.. index:: single: StoreInternalVariables
+.. index:: single: StoreSupplementaryCalculations
+.. index:: single: SwarmVelocity
+
+Chaque algorithme peut être contrôlé en utilisant des options génériques ou
+particulières, données à travers la commande optionnelle "*AlgorithmParameters*"
+dans un fichier script ou une chaîne de caractères, à la manière de l'exemple
+qui suit dans un fichier::
+
+ AlgorithmParameters = {
+ "Minimizer" : "LBFGSB",
+ "MaximumNumberOfSteps" : 25,
+ "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"],
+ }
+
+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
+pas, cette option est simplement laissée inutilisée et ne bloque pas le
+traitement. La signification des acronymes ou des noms particuliers peut être
+trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`.
+
+**"Blue"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB",
+ "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
+
+**"ExtendedBlue"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB",
+ "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"].
+
+**"LinearLeastSquares"**
+
+ *Commandes obligatoires*
+ *"Observation", "ObservationError",
+ "ObservationOperator"*
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["OMA"].
+
+**"3DVAR"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ Minimizer
+ Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par
+ défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non
+ linéaire sous contraintes, see [Byrd95]_ and [Zhu97]_), "TNC" (minimisation
+ non linéaire sous contraintes), "CG" (minimisation non linéaire sans
+ contraintes), "BFGS" (minimisation non linéaire sans contraintes), "NCG"
+ (minimisation de type gradient conjugué de Newton). On conseille de
+ conserver la valeur par défaut.
+
+ Bounds
+ Cette clé permet de définir des bornes supérieure et inférieure pour
+ chaque variable d'état optimisée. Les bornes peuvent être données par une
+ liste de liste de paires de bornes inférieure/supérieure pour chaque
+ variable, avec une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les
+ bornes peuvent toujours être spécifiées, mais seuls les optimiseurs sous
+ contraintes les prennent en compte.
+
+ MaximumNumberOfSteps
+ Cette clé indique le nombre maximum d'itérations possibles en optimisation
+ itérative. Le défaut est 15000, qui est très similaire à une absence de
+ limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
+ aux besoins pour des problèmes réels. Pour certains optimiseurs, le nombre
+ de pas effectif d'arrêt peut être légèrement différent de la limite à cause
+ d'exigences de contrôle interne de l'algorithme.
+
+ CostDecrementTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque la fonction coût décroît moins que cette
+ tolérance au dernier pas. Le défaut est de 1.e-7, et il est recommandé
+ de l'adapter aux besoins pour des problèmes réels.
+
+ ProjectedGradientTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque toutes les composantes du gradient projeté
+ sont en-dessous de cette limite. C'est utilisé uniquement par les
+ optimiseurs sous contraintes. Le défaut est -1, qui désigne le défaut
+ interne de chaque optimiseur (usuellement 1.e-5), et il n'est pas recommandé
+ de le changer.
+
+ GradientNormTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque la norme du gradient est en dessous de cette
+ limite. C'est utilisé uniquement par les optimiseurs sans contraintes. Le
+ défaut est 1.e-5 et il n'est pas recommandé de le changer.
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB",
+ "Innovation", "SigmaObs2", "MahalanobisConsistency"].
+
+**"NonLinearLeastSquares"**
+
+ *Commandes obligatoires*
+ *"Background",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ Minimizer
+ Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par
+ défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non
+ linéaire sous contraintes, voir [Byrd95]_ and [Zhu97]_), "TNC" (minimisation
+ non linéaire sous contraintes), "CG" (minimisation non linéaire sans
+ contraintes), "BFGS" (minimisation non linéaire sans contraintes), "NCG"
+ (minimisation de type gradient conjugué de Newton). On conseille de
+ conserver la valeur par défaut.
+
+ Bounds
+ Cette clé permet de définir des bornes supérieure et inférieure pour
+ chaque variable d'état optimisée. Les bornes peuvent être données par une
+ liste de liste de paires de bornes inférieure/supérieure pour chaque
+ variable, avec une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les
+ bornes peuvent toujours être spécifiées, mais seuls les optimiseurs sous
+ contraintes les prennent en compte.
+
+ MaximumNumberOfSteps
+ Cette clé indique le nombre maximum d'itérations possibles en optimisation
+ itérative. Le défaut est 15000, qui est très similaire à une absence de
+ limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
+ aux besoins pour des problèmes réels. Pour certains optimiseurs, le nombre
+ de pas effectif d'arrêt peut être légèrement différent de la limite à cause
+ d'exigences de contrôle interne de l'algorithme.
+
+ CostDecrementTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque la fonction coût décroît moins que cette
+ tolérance au dernier pas. Le défaut est de 1.e-7, et il est recommandé
+ de l'adapter aux besoins pour des problèmes réels.
+
+ ProjectedGradientTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque toutes les composantes du gradient projeté
+ sont en-dessous de cette limite. C'est utilisé uniquement par les
+ optimiseurs sous contraintes. Le défaut est -1, qui désigne le défaut
+ interne de chaque optimiseur (usuellement 1.e-5), et il n'est pas recommandé
+ de le changer.
+
+ GradientNormTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque la norme du gradient est en dessous de cette
+ limite. C'est utilisé uniquement par les optimiseurs sans contraintes. Le
+ défaut est 1.e-5 et il n'est pas recommandé de le changer.
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB",
+ "Innovation", "SigmaObs2", "MahalanobisConsistency"].
+
+**"EnsembleBlue"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ SetSeed
+ Cette clé permet de donner un nombre entier pour fixer la graine du
+ générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
+ par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
+ utilise ainsi l'initialisation de l'ordinateur.
+
+**"KalmanFilter"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ EstimationOf
+ Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
+ soit une estimation de l'état, avec la valeur "State", ou une estimation de
+ paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"].
+
+**"ExtendedKalmanFilter"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ Bounds
+ Cette clé permet de définir des bornes supérieure et inférieure pour chaque
+ variable d'état optimisée. Les bornes peuvent être données par une liste de
+ liste de paires de bornes inférieure/supérieure pour chaque variable, avec
+ une valeur extrême chaque fois qu'il n'y a pas de borne. Les bornes peuvent
+ toujours être spécifiées, mais seuls les optimiseurs sous contraintes les
+ prennent en compte.
+
+ ConstrainedBy
+ Cette clé permet de définir la méthode pour prendre en compte les bornes. Les
+ méthodes possibles sont dans la liste suivante : ["EstimateProjection"].
+
+ EstimationOf
+ Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
+ soit une estimation de l'état, avec la valeur "State", ou une estimation de
+ paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"].
+
+**"UnscentedKalmanFilter"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ Bounds
+ Cette clé permet de définir des bornes supérieure et inférieure pour chaque
+ variable d'état optimisée. Les bornes peuvent être données par une liste de
+ liste de paires de bornes inférieure/supérieure pour chaque variable, avec
+ une valeur extrême chaque fois qu'il n'y a pas de borne. Les bornes peuvent
+ toujours être spécifiées, mais seuls les optimiseurs sous contraintes les
+ prennent en compte.
+
+ ConstrainedBy
+ Cette clé permet de définir la méthode pour prendre en compte les bornes. Les
+ méthodes possibles sont dans la liste suivante : ["EstimateProjection"].
+
+ EstimationOf
+ Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être
+ soit une estimation de l'état, avec la valeur "State", ou une estimation de
+ paramètres, avec la valeur "Parameters". Le choix par défaut est "State".
+
+ Alpha, Beta, Kappa, Reconditioner
+ Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert
+ une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour
+ une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière,
+ dont la bonne valeur par défaut est obtenue en la mettant à 0.
+ "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut
+ étant 1.
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"].
+
+**"ParticleSwarmOptimization"**
+
+ *Commandes obligatoires*
+ *"Background", "BackgroundError",
+ "Observation", "ObservationError",
+ "ObservationOperator"*
+
+ MaximumNumberOfSteps
+ Cette clé indique le nombre maximum d'itérations possibles en optimisation
+ itérative. Le défaut est 50, qui est une limite arbitraire. Il est ainsi
+ recommandé d'adapter ce paramètre aux besoins pour des problèmes réels.
+
+ NumberOfInsects
+ Cette clé indique le nombre d'insectes ou de particules dans l'essaim. La
+ valeur par défaut est 100, qui est une valeur par défaut usuelle pour cet
+ algorithme.
+
+ SwarmVelocity
+ Cette clé indique la part de la vitesse d'insecte qui est imposée par
+ l'essaim. C'est une valeur réelle positive. Le défaut est de 1.
+
+ GroupRecallRate
+ Cette clé indique le taux de rappel vers le meilleur insecte de l'essaim.
+ C'est une valeur réelle comprise entre 0 et 1. Le défaut est de 0.5.
+
+ QualityCriterion
+ Cette clé indique le critère de qualité, qui est minimisé 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 "=" :
+ ["AugmentedPonderatedLeastSquares"="APLS"="DA",
+ "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2",
+ "AbsoluteValue"="L1", "MaximumError"="ME"]
+
+ SetSeed
+ Cette clé permet de donner un nombre entier pour fixer la graine du
+ générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
+ par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
+ utilise ainsi l'initialisation par défaut de l'ordinateur.
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["BMA", "OMA", "OMB", "Innovation"].
+
+**"QuantileRegression"**
+
+ *Commandes obligatoires*
+ *"Background",
+ "Observation",
+ "ObservationOperator"*
+
+ Quantile
+ Cette clé permet de définir la valeur réelle du quantile recherché, entre 0
+ et 1. La valeur par défaut est 0.5, correspondant à la médiane.
+
+ Minimizer
+ Cette clé permet de choisir l'optimiseur pour l'optimisation. Le choix par
+ défaut et le seul disponible est "MMQR" (Majorize-Minimize for Quantile
+ Regression).
+
+ MaximumNumberOfSteps
+ Cette clé indique le nombre maximum d'itérations possibles en optimisation
+ itérative. Le défaut est 15000, qui est très similaire à une absence de
+ limite sur les itérations. Il est ainsi recommandé d'adapter ce paramètre
+ aux besoins pour des problèmes réels.
+
+ CostDecrementTolerance
+ Cette clé indique une valeur limite, conduisant à arrêter le processus
+ itératif d'optimisation lorsque la fonction coût décroît moins que cette
+ tolérance au dernier pas. Le défaut est de 1.e-6, et il est recommandé de
+ l'adapter aux besoins pour des problèmes réels.
+
+ StoreInternalVariables
+ Cette clé booléenne permet de stocker les variables internes par défaut,
+ principalement l'état courant lors d'un processus itératif. Attention, cela
+ peut être un choix numériquement coûteux dans certains cas de calculs. La
+ valeur par défaut est "False".
+
+ StoreSupplementaryCalculations
+ Cette liste indique les noms des variables supplémentaires qui peuvent être
+ disponibles à la fin de l'algorithme. Cela implique potentiellement des
+ calculs 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 : ["BMA", "OMA", "OMB", "Innovation"].
+
+Description de référence pour les cas de vérification ADAO
+----------------------------------------------------------
+
+Liste des commandes et mots-clés pour un cas de vérification ADAO
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: CHECKING_STUDY
+.. index:: single: Algorithm
+.. index:: single: AlgorithmParameters
+.. index:: single: CheckingPoint
+.. index:: single: Debug
+.. index:: single: ObservationOperator
+.. index:: single: Study_name
+.. index:: single: Study_repertory
+.. index:: single: UserDataInit
+
+Le second jeu de commandes est liée à la description d'un cas de vérification,
+qui est une procédure pour vérifier les propriétés requises ailleurs sur
+l'information par un cas de calcul. Les termes sont classés par ordre
+alphabétique, sauf le premier, qui décrit le choix entre le calcul ou la
+vérification. Les différentes commandes sont les suivantes:
+
+**CHECKING_STUDY**
+ *Commande obligatoire*. C'est la commande générale qui décrit le cas de
+ vérification. Elle contient hiérarchiquement toutes les autres commandes.
+
+**Algorithm**
+ *Commande obligatoire*. C'est une chaîne de caractère qui indique
+ l'algorithme de test choisi. Les choix sont limités et disponibles à travers
+ l'interface graphique. Il existe par exemple "FunctionTest",
+ "AdjointTest"... Voir plus loin la liste des algorithmes et des paramètres
+ associés dans la sous-section `Commandes optionnelles et requises pour les
+ algorithmes de vérification`_.
+
+**AlgorithmParameters**
+ *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour
+ contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa
+ valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste
+ des algorithmes et des paramètres associés dans la sous-section `Commandes
+ optionnelles et requises pour les algorithmes de vérification`_.
+
+**CheckingPoint**
+ *Commande obligatoire*. Elle définit le vecteur utilisé, noté précédemment
+ :math:`\mathbf{x}`. Sa valeur est définie comme un objet de type "*Vector*".
+
+**Debug**
+ *Commande obligatoire*. Elle définit le niveau de sorties et d'informations
+ intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et
+ 1 (pour True).
+
+**ObservationOperator**
+ *Commande obligatoire*. Elle indique l'opérateur d'observation, notée
+ précédemment :math:`H`, qui transforme les paramètres d'entrée
+ :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
+ observations :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de
+ type "*Function*". Différentes formes fonctionnelles peuvent être utilisées,
+ comme décrit dans la sous-section suivante `Exigences pour les fonctions
+ décrivant un opérateur`_. Si un contrôle :math:`U` est inclus dans le modèle
+ d'observation, l'opérateur doit être appliqué à une paire :math:`(X,U)`.
+
+**Study_name**
+ *Commande obligatoire*. C'est une chaîne de caractères quelconque pour
+ décrire l'étude ADAO par un nom ou une déclaration.
+
+**Study_repertory**
+ *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base
+ pour les calculs, et il est utilisé pour trouver les fichiers de script,
+ donnés par nom sans répertoire, qui peuvent être utilisés pour définir
+ certaines variables.
+
+**UserDataInit**
+ *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou
+ certaines données automatiquement avant le traitement de données d'entrée
+ pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un
+ nom de fichier de script à exécuter avant d'entrer dans l'initialisation des
+ variables choisies.
+
+Commandes optionnelles et requises pour les algorithmes de vérification
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: AdjointTest
+.. index:: single: FunctionTest
+.. index:: single: GradientTest
+.. index:: single: LinearityTest
+
+.. index:: single: AlgorithmParameters
+.. index:: single: AmplitudeOfInitialDirection
+.. index:: single: EpsilonMinimumExponent
+.. index:: single: InitialDirection
+.. index:: single: ResiduFormula
+.. index:: single: SetSeed
+
+On rappelle que chaque algorithme peut être contrôlé en utilisant des options
+génériques ou particulières, données à travers la commande optionnelle
+"*AlgorithmParameters*", à la manière de l'exemple qui suit dans un fichier::
+
+ AlgorithmParameters = {
+ "AmplitudeOfInitialDirection" : 1,
+ "EpsilonMinimumExponent" : -8,
+ }
+
+Si une option est spécifiée par l'utilisateur pour un algorithme qui ne la
+supporte pas, cette option est simplement laissée inutilisée et ne bloque pas le
+traitement. La signification des acronymes ou des noms particuliers peut être
+trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`. De plus, pour
+chaque algorithme, les commandes/mots-clés sont donnés, décrits dans `Liste des
+commandes et mots-clés pour un cas de vérification ADAO`_.
+
+**"AdjointTest"**
+
+ *Commandes obligatoires*
+ *"CheckingPoint",
+ "ObservationOperator"*
+
+ AmplitudeOfInitialDirection
+ Cette clé indique la mise à l'échelle de la perturbation initiale construite
+ comme un vecteur utilisé pour la dérivée directionnelle autour du point
+ nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
+ de mise à l'échelle.
+
+ EpsilonMinimumExponent
+ Cette clé indique la valeur de l'exposant minimal du coefficient en
+ puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
+ de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
+ -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
+ formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
+
+ InitialDirection
+ Cette clé indique la direction vectorielle utilisée pour la dérivée
+ directionnelle autour du point nominal de vérification. Cela doit être un
+ vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
+ perturbation par défaut autour de zéro de la même taille vectorielle que le
+ point de vérification.
+
+ SetSeed
+ Cette clé permet de donner un nombre entier pour fixer la graine du
+ générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
+ par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
+ utilise ainsi l'initialisation par défaut de l'ordinateur.
+
+**"FunctionTest"**
+
+ *Commandes obligatoires*
+ *"CheckingPoint",
+ "ObservationOperator"*
+
+ NumberOfPrintedDigits
+ Cette clé indique le nombre de décimales de précision pour les affichages de
+ valeurs réelles. La valeur par défaut est de 5, avec un minimum de 0.
+
+ NumberOfRepetition
+ Cette clé indique le nombre de fois où répéter l'évaluation de la fonction.
+ La valeur vaut 1.
+
+ SetDebug
+ Cette clé requiert l'activation, ou pas, du mode de débogage durant
+ l'évaluation de la fonction. La valeur par défaut est "True", les choix sont
+ "True" ou "False".
+
+**"GradientTest"**
+
+ *Commandes obligatoires*
+ *"CheckingPoint",
+ "ObservationOperator"*
+
+ AmplitudeOfInitialDirection
+ Cette clé indique la mise à l'échelle de la perturbation initiale construite
+ comme un vecteur utilisé pour la dérivée directionnelle autour du point
+ nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
+ de mise à l'échelle.
+
+ EpsilonMinimumExponent
+ Cette clé indique la valeur de l'exposant minimal du coefficient en
+ puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
+ de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
+ -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
+ formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
+
+ InitialDirection
+ Cette clé indique la direction vectorielle utilisée pour la dérivée
+ directionnelle autour du point nominal de vérification. Cela doit être un
+ vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
+ perturbation par défaut autour de zéro de la même taille vectorielle que le
+ point de vérification.
+
+ ResiduFormula
+ Cette clé indique la formule de résidu qui doit être utilisée pour le test.
+ Le choix par défaut est "Taylor", et les choix possibles sont "Taylor"
+ (résidu du développement de Taylor de l'opérateur, qui doit décroître comme
+ le carré de la perturbation) et "Norm" (résidu obtenu en prenant la norme du
+ développement de Taylor à l'ordre 0, qui approxime le gradient, et qui doit
+ rester constant).
+
+ SetSeed
+ Cette clé permet de donner un nombre entier pour fixer la graine du
+ générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
+ par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
+ utilise ainsi l'initialisation par défaut de l'ordinateur.
+
+**"LinearityTest"**
+
+ *Commandes obligatoires*
+ *"CheckingPoint",
+ "ObservationOperator"*
+
+ AmplitudeOfInitialDirection
+ Cette clé indique la mise à l'échelle de la perturbation initiale construite
+ comme un vecteur utilisé pour la dérivée directionnelle autour du point
+ nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas
+ de mise à l'échelle.
+
+ EpsilonMinimumExponent
+ Cette clé indique la valeur de l'exposant minimal du coefficient en
+ puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur
+ de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et
+ -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la
+ formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8.
+
+ InitialDirection
+ Cette clé indique la direction vectorielle utilisée pour la dérivée
+ directionnelle autour du point nominal de vérification. Cela doit être un
+ vecteur. Si elle n'est pas spécifiée, la direction par défaut est une
+ perturbation par défaut autour de zero de la même taille vectorielle que le
+ point de vérification.
+
+ ResiduFormula
+ Cette clé indique la formule de résidu qui doit être utilisée pour le test.
+ Le choix par défaut est "CenteredDL", et les choix possibles sont
+ "CenteredDL" (résidu de la différence entre la fonction au point nominal et
+ ses valeurs avec des incréments positif et négatif, qui doit rester très
+ faible), "Taylor" (résidu du développement de Taylor de l'opérateur
+ normalisé par sa valeur nominal, qui doit rester très faible),
+ "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur,
+ normalisé au point nominal, qui doit rester proche de 1), et
+ "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur,
+ normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit
+ rester proche de 0).
+
+ SetSeed
+ Cette clé permet de donner un nombre entier pour fixer la graine du
+ générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
+ par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
+ utilise ainsi l'initialisation par défaut de l'ordinateur.
+
+Exigences pour les fonctions décrivant un opérateur
+---------------------------------------------------
+
+Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en
+oeuvre les procédures d'assimilation de données ou d'optimisation. Ils
+comprennent la simulation physique par des calculs numériques, mais aussi le
+filtrage et de restriction pour comparer la simulation à l'observation.
+L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui
+représente la transition entre deux états successifs, et il est alors similaire
+à l'opérateur d'observation.
+
+Schématiquement, un opérateur doit donner une solution étant donné les
+paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au
+cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un
+tel processus est une fonction. Il a été brièvement décrit dans la section
+:ref:`section_theory` et il est généralisée ici par la relation:
+
+.. math:: \mathbf{y} = O( \mathbf{x} )
+
+entre les pseudo-observations :math:`\mathbf{y}` et les paramètres
+:math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution
+:math:`O`. La même représentation fonctionnelle peut être utilisée pour le
+modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint
+:math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes
+d'assimilation de données ou d'optimisation.
+
+
+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
+complète**.
+
+Cette fonction est généralement donnée comme un script qui peut être exécuté
+dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes
+externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme
+nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme
+adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer.
+
+Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation
+fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*"
+de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le
+montre la figure suivante:
+
+ .. eficas_operator_function:
+ .. image:: images/eficas_operator_function.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Choisir une représentation fonctionnelle de l'opérateur**
+
+Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: ScriptWithOneFunction
+.. index:: single: DirectOperator
+.. index:: single: DifferentialIncrement
+.. index:: single: CenteredFiniteDifference
+
+La première consiste à ne fournir qu'une seule fonction potentiellement non
+linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en
+utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de
+l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir
+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 """
+ ...
+ ...
+ ...
+ return Y=O(X)
+
+Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément
+différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface
+graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par
+défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies
+pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation
+différences finies peut aussi être choisi à travers l'interface, en utilisant le
+mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du
+premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du
+second ordre (qui coûte numériquement deux fois plus cher que le premier ordre).
+
+Cette première forme de définition de l'opérateur permet aisément de tester la
+forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
+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.
+L'utilisateur doit traiter ces cas dans sa fonction.
+
+Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: ScriptWithFunctions
+.. index:: single: DirectOperator
+.. index:: single: TangentOperator
+.. index:: single: AdjointOperator
+
+**En général, il est recommandé d'utiliser la première forme fonctionnelle
+plutôt que la seconde. Un petit accroissement de performances n'est pas une
+bonne raison pour utiliser l'implémentation détaillée de cette seconde forme
+fonctionnelle.**
+
+La seconde consiste à fournir directement les trois opérateurs liés :math:`O`,
+:math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le
+mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans
+l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions
+dans un script, avec trois noms obligatoires "*DirectOperator*",
+"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre
+le squelette suivant::
+
+ def DirectOperator( X ):
+ """ Direct non-linear simulation operator """
+ ...
+ ...
+ ...
+ return something like Y
+
+ def TangentOperator( (X, dX) ):
+ """ Tangent linear operator, around X, applied to dX """
+ ...
+ ...
+ ...
+ return something like Y
+
+ def AdjointOperator( (X, Y) ):
+ """ Adjoint operator, around X, applied to Y """
+ ...
+ ...
+ ...
+ return something like 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
+complexité de l'implémentation de l'opérateur.
+
+Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse
+renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque,
+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.
+
+Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: ScriptWithSwitch
+.. index:: single: DirectOperator
+.. index:: single: TangentOperator
+.. index:: single: AdjointOperator
+
+**Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans
+une solide raison numérique ou physique. Un accroissement de performances n'est
+pas une bonne raison pour utiliser la complexité de cette troisième forme
+fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes
+justifie l'usage de la troisième.**
+
+La troisième forme donne de plus grandes possibilités de contrôle de l'exécution
+des trois fonctions représentant l'opérateur, permettant un usage et un contrôle
+avancés sur chaque exécution du code de simulation. C'est réalisable en
+utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à
+travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script
+unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente
+et adjointe du code de simulation. L'utilisateur peut alors, par exemple,
+utiliser des approximations pour les codes tangent et adjoint, ou introduire une
+plus grande complexité du traitement des arguments des fonctions. Mais cette
+démarche sera plus difficile à implémenter et à déboguer.
+
+Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se
+baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier
+script ou un code externe nommé ici "*Physical_simulation_functions.py*",
+contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" and
+"*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage::
+
+ import Physical_simulation_functions
+ import numpy, logging
+ #
+ method = ""
+ for param in computation["specificParameters"]:
+ if param["name"] == "method":
+ method = param["value"]
+ if method not in ["Direct", "Tangent", "Adjoint"]:
+ raise ValueError("No valid computation method is given")
+ logging.info("Found method is \'%s\'"%method)
+ #
+ logging.info("Loading operator functions")
+ Function = Physical_simulation_functions.DirectOperator
+ Tangent = Physical_simulation_functions.TangentOperator
+ Adjoint = Physical_simulation_functions.AdjointOperator
+ #
+ logging.info("Executing the possible computations")
+ data = []
+ if method == "Direct":
+ logging.info("Direct computation")
+ Xcurrent = computation["inputValues"][0][0][0]
+ data = Function(numpy.matrix( Xcurrent ).T)
+ if method == "Tangent":
+ logging.info("Tangent computation")
+ Xcurrent = computation["inputValues"][0][0][0]
+ dXcurrent = computation["inputValues"][0][0][1]
+ data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T)
+ if method == "Adjoint":
+ logging.info("Adjoint computation")
+ Xcurrent = computation["inputValues"][0][0][0]
+ Ycurrent = computation["inputValues"][0][0][1]
+ data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T))
+ #
+ logging.info("Formatting the output")
+ it = numpy.ravel(data)
+ outputValues = [[[[]]]]
+ for val in it:
+ outputValues[0][0][0].append(val)
+ #
+ result = {}
+ result["outputValues"] = outputValues
+ result["specificOutputInfos"] = []
+ result["returnCode"] = 0
+ result["errorMessage"] = ""
+
+Toutes les modifications envisageables peuvent être faites à partir de cette
+hypothèse de squelette.
+
+Cas spécial d'un opérateur d'évolution avec contrôle
+++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé
+par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la
+forme générique du modèle incrémental est légèrement modifié comme suit:
+
+.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u})
+
+où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. Dans ce cas,
+l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`.
+Schématiquement, l'opérateur doit être constuit comme suit::
+
+ def DirectOperator( (X, U) ):
+ """ Direct non-linear simulation operator """
+ ...
+ ...
+ ...
+ return something like X(n+1) or Y(n+1)
+
+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
+à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième
+forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme
+fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées.
+
+Exigences pour décrire les matrices de covariance
+-------------------------------------------------
+
+De multiples matrices de covariance sont nécessaires pour mettre en oeuvre des
+procédures d'assimilation des données ou d'optimisation. Les principales sont la
+matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la
+matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`. Une
+telle matrice doit être une matrice carré symétrique semi-définie positive.
+
+Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de
+covariance. Ces méthodes sont choisies à l'aide du mot-clé "*INPUT_TYPE*" de
+chaque matrice de covariance, comme montré dans la figure qui suit :
+
+ .. eficas_covariance_matrix:
+ .. image:: images/eficas_covariance_matrix.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **Choisir la représentation d'une matrice de covariance**
+
+Première forme matricielle : utiliser la représentation "*Matrix*"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: Matrix
+.. index:: single: BackgroundError
+.. index:: single: EvolutionError
+.. index:: single: ObservationError
+
+La première forme est le défaut et la plus générale. La matrice de covariance
+:math:`\mathbf{M}` doit être entièrement spécifiée. Même si la matrice est
+symétrique par nature, la totalité de la matrice :math:`\mathbf{M}` doit être
+donnée.
+
+.. math:: \mathbf{M} = \begin{pmatrix}
+ m_{11} & m_{12} & \cdots & m_{1n} \\
+ m_{21} & m_{22} & \cdots & m_{2n} \\
+ \vdots & \vdots & \vdots & \vdots \\
+ m_{n1} & \cdots & m_{nn-1} & m_{nn}
+ \end{pmatrix}
+
+
+Cela peut être réalisé soit par un vecteur ou une matrice Numpy, soit par une
+liste de listes de valeurs (c'est-à-dire une liste de lignes). 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::
+
+ BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]]
+
+ou::
+
+ BackgroundError = numpy.eye(...)
+
+Seconde forme matricielle : utiliser la représentation "*ScalarSparseMatrix*"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: ScalarSparseMatrix
+.. index:: single: BackgroundError
+.. index:: single: EvolutionError
+.. index:: single: ObservationError
+
+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`:
+
+.. math:: \mathbf{M} = m \times \begin{pmatrix}
+ 1 & 0 & \cdots & 0 \\
+ 0 & 1 & \cdots & 0 \\
+ \vdots & \vdots & \vdots & \vdots \\
+ 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::
+
+ BackgroundError = 1.
+
+ou, mieux, par un "*String*" directement dans le cas ADAO.
+
+Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*"
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. index:: single: DiagonalSparseMatrix
+.. index:: single: BackgroundError
+.. index:: single: EvolutionError
+.. index:: single: ObservationError
+
+La troisième forme est aussi une méthode simplifiée pour fournir la matrice,
+mais un peu plus puissante que la seconde. La matrice de covariance
+:math:`\mathbf{M}` est toujours considérée comme diagonale, mais l'utilisateur
+doit spécifier toutes les valeurs positives situées sur la diagonale. La matrice
+peut alors être définie uniquement par un vecteur :math:`\mathbf{V}` qui se
+retrouve ensuite sur la diagonale:
+
+.. math:: \mathbf{M} = \begin{pmatrix}
+ v_{1} & 0 & \cdots & 0 \\
+ 0 & v_{2} & \cdots & 0 \\
+ \vdots & \vdots & \vdots & \vdots \\
+ 0 & \cdots & 0 & v_{n}
+ \end{pmatrix}
+
+Cela peut être réalisé soit par vecteur ou une matrice Numpy, soit par
+une liste, soit par une liste de listes de valeurs positives (dans tous les cas,
+si certaines valeurs sont négatives, elles sont converties en valeurs
+positives). Par exemple, un matrice simple diagonale unitaire des covariances
+des erreurs d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de
+script Python par::
+
+ BackgroundError = [1, 1 ... 1]
+
+ou::
+
+ BackgroundError = numpy.ones(...)
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="210mm"
+ height="297mm"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.47 r22583"
+ sodipodi:docname="ADAOlogo.svg">
+ <defs
+ id="defs4">
+ <inkscape:perspective
+ sodipodi:type="inkscape:persp3d"
+ inkscape:vp_x="0 : 526.18109 : 1"
+ inkscape:vp_y="0 : 1000 : 0"
+ inkscape:vp_z="744.09448 : 526.18109 : 1"
+ inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+ id="perspective10" />
+ <inkscape:perspective
+ id="perspective2825"
+ inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+ inkscape:vp_z="1 : 0.5 : 1"
+ inkscape:vp_y="0 : 1000 : 0"
+ inkscape:vp_x="0 : 0.5 : 1"
+ sodipodi:type="inkscape:persp3d" />
+ <inkscape:perspective
+ id="perspective2829"
+ inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+ inkscape:vp_z="1 : 0.5 : 1"
+ inkscape:vp_y="0 : 1000 : 0"
+ inkscape:vp_x="0 : 0.5 : 1"
+ sodipodi:type="inkscape:persp3d" />
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.6158153"
+ inkscape:cx="202.61978"
+ inkscape:cy="837.66928"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1254"
+ inkscape:window-height="1029"
+ inkscape:window-x="1"
+ inkscape:window-y="25"
+ inkscape:window-maximized="0" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Calque 1"
+ inkscape:groupmode="layer"
+ id="layer1">
+ <text
+ xml:space="preserve"
+ style="font-size:72px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Ecliptic BRK;-inkscape-font-specification:Ecliptic BRK Italic"
+ x="287.29449"
+ y="75.354118"
+ id="text2816"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/ahbhhjp/PERSONNEL/COURS/JPA/Sources/Assimilation/Documents/ADAO/doc/ressources/path3620.png"
+ inkscape:export-xdpi="12.990827"
+ inkscape:export-ydpi="12.990827"><tspan
+ sodipodi:role="line"
+ id="tspan3618"
+ x="287.29449"
+ y="75.354118">DA</tspan></text>
+ <path
+ sodipodi:type="spiral"
+ style="fill:#ff9955;fill-opacity:1;stroke:#000000;stroke-width:1.00032222;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+ id="path2849"
+ sodipodi:cx="100.91638"
+ sodipodi:cy="321.9491"
+ sodipodi:expansion="1"
+ sodipodi:revolution="6.0214381"
+ sodipodi:radius="37.473236"
+ sodipodi:argument="-20.442327"
+ sodipodi:t0="0"
+ d="m 100.91638,321.9491 c -0.0206,-0.93586 1.25137,-0.48945 1.55545,-0.0342 0.82406,1.23372 -0.29038,2.735 -1.48707,3.14509 -2.140611,0.73355 -4.253352,-0.96239 -4.734729,-3.00834 -0.70644,-3.00252 1.636961,-5.79857 4.529599,-6.32436 3.85544,-0.70081 7.35415,2.31158 7.914,6.05086 0.70452,4.70551 -2.98602,8.91487 -7.57213,9.50364 -5.554388,0.71308 -10.478513,-3.66031 -11.09327,-9.09339 -0.724469,-6.4027 4.334506,-12.04401 10.61466,-12.68291 7.25068,-0.73765 13.61071,5.00863 14.27254,12.13591 0.75202,8.09848 -5.68272,15.17829 -13.65718,15.86219 -8.946142,0.76723 -16.746483,-6.35677 -17.45182,-15.17845 -0.783058,-9.79373 7.030805,-18.31515 16.69971,-19.04146 10.64126,-0.79935 19.88417,7.70483 20.63109,18.22098 0.816,11.48874 -8.37882,21.45348 -19.74223,22.22073 -12.336196,0.83293 -23.023024,-9.05282 -23.810371,-21.2635 -0.850083,-13.18362 9.726814,-24.59274 22.784761,-25.40001 14.03104,-0.86742 26.16262,10.4008 26.98965,24.30603 0.8849,14.87843 -11.07478,27.73262 -25.82729,28.57928 -15.725817,0.90252 -29.302728,-11.74876 -30.168922,-27.34855 -0.920242,-16.57319 12.422731,-30.87292 28.869812,-31.75856 17.42055,-0.93805 32.4432,13.09671 33.3482,30.39108 0.95594,18.26791 -13.77068,34.01354 -31.91235,34.93783 -19.115258,0.97389 -35.583936,-14.44464 -36.527463,-33.4336 -0.991904,-19.96261 15.11861,-37.1544 34.954873,-38.11711 1.67818,-0.0814 3.36179,-0.0494 5.03569,0.0954"
+ transform="matrix(1.1558135,0,0,1.2320798,-44.152477,-284.63311)"
+ inkscape:export-filename="/home/ahbhhjp/text2820.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90" />
+ <text
+ xml:space="preserve"
+ style="font-size:83.2216568px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#0000ff;fill-opacity:1;stroke:none;font-family:'3D LET BRK';-inkscape-font-specification:'3D LET BRK'"
+ x="36.218281"
+ y="77.264725"
+ id="text2820"
+ sodipodi:linespacing="125%"
+ transform="scale(0.76903058,1.3003384)"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"><tspan
+ sodipodi:role="line"
+ id="tspan2822"
+ x="36.218281"
+ y="77.264725">DA</tspan></text>
+ <path
+ sodipodi:type="spiral"
+ style="fill:#ff9955;fill-opacity:1;stroke:#000000;stroke-width:1.00032222;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+ id="path2849-6"
+ sodipodi:cx="100.91638"
+ sodipodi:cy="321.9491"
+ sodipodi:expansion="1"
+ sodipodi:revolution="6.0214381"
+ sodipodi:radius="37.473236"
+ sodipodi:argument="-20.442327"
+ sodipodi:t0="0"
+ d="m 100.91638,321.9491 c -0.0206,-0.93586 1.25137,-0.48945 1.55545,-0.0342 0.82406,1.23372 -0.29038,2.735 -1.48707,3.14509 -2.140611,0.73355 -4.253352,-0.96239 -4.734729,-3.00834 -0.70644,-3.00252 1.636961,-5.79857 4.529599,-6.32436 3.85544,-0.70081 7.35415,2.31158 7.914,6.05086 0.70452,4.70551 -2.98602,8.91487 -7.57213,9.50364 -5.554388,0.71308 -10.478513,-3.66031 -11.09327,-9.09339 -0.724469,-6.4027 4.334506,-12.04401 10.61466,-12.68291 7.25068,-0.73765 13.61071,5.00863 14.27254,12.13591 0.75202,8.09848 -5.68272,15.17829 -13.65718,15.86219 -8.946142,0.76723 -16.746483,-6.35677 -17.45182,-15.17845 -0.783058,-9.79373 7.030805,-18.31515 16.69971,-19.04146 10.64126,-0.79935 19.88417,7.70483 20.63109,18.22098 0.816,11.48874 -8.37882,21.45348 -19.74223,22.22073 -12.336196,0.83293 -23.023024,-9.05282 -23.810371,-21.2635 -0.850083,-13.18362 9.726814,-24.59274 22.784761,-25.40001 14.03104,-0.86742 26.16262,10.4008 26.98965,24.30603 0.8849,14.87843 -11.07478,27.73262 -25.82729,28.57928 -15.725817,0.90252 -29.302728,-11.74876 -30.168922,-27.34855 -0.920242,-16.57319 12.422731,-30.87292 28.869812,-31.75856 17.42055,-0.93805 32.4432,13.09671 33.3482,30.39108 0.95594,18.26791 -13.77068,34.01354 -31.91235,34.93783 -19.115258,0.97389 -35.583936,-14.44464 -36.527463,-33.4336 -0.991904,-19.96261 15.11861,-37.1544 34.954873,-38.11711 1.67818,-0.0814 3.36179,-0.0494 5.03569,0.0954"
+ transform="matrix(1.1558135,0,0,1.2320798,58.717362,-286.46093)"
+ inkscape:export-filename="/home/ahbhhjp/PERSONNEL/COURS/JPA/Sources/Assimilation/Documents/ADAO/doc/ressources/text2820-9.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90" />
+ <text
+ xml:space="preserve"
+ style="font-size:72px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#0000ff;fill-opacity:1;stroke:none;font-family:Arial Black;-inkscape-font-specification:'Arial Black,'"
+ x="169.98389"
+ y="71.244904"
+ id="text2820-7"
+ sodipodi:linespacing="125%"
+ transform="scale(0.76903058,1.3003384)"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90"
+ inkscape:export-filename="/home/ahbhhjp/PERSONNEL/COURS/JPA/Sources/Assimilation/Documents/ADAO/doc/ressources/text2820-9.png"><tspan
+ sodipodi:role="line"
+ id="tspan2822-3"
+ x="169.98389"
+ y="71.244904">DA</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:48px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Ecliptic BRK;-inkscape-font-specification:Ecliptic BRK"
+ x="29.026806"
+ y="228.65573"
+ id="text2816-6"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan2818-3"
+ x="29.026806"
+ y="228.65573">D A</tspan></text>
+ <path
+ style="fill:#ffe200;fill-opacity:1;stroke:#000000;stroke-width:2.66750574;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+ d="m 289.28798,155.39574 18.54471,-58.365903 17.58255,54.165013 17.09456,-66.636614 19.61805,48.653494 21.10261,-8.67601 9.33238,-43.280447"
+ id="path3620"
+ sodipodi:nodetypes="ccccccc"
+ inkscape:export-xdpi="12.990827"
+ inkscape:export-ydpi="12.990827" />
+ </g>
+</svg>
--- /dev/null
+.. _section_theory:
+
+================================================================================
+Une brève introduction à l'Assimilation de Données et à l'Optimisation
+================================================================================
+
+.. index:: single: Data Assimilation
+.. index:: single: Assimilation de données
+.. index:: single: état vrai
+.. index:: single: observation
+.. index:: single: a priori
+
+L'**assimilation de données** est un cadre général pour le calcul de
+l'estimation optimale de l'état réel d'un système, au cours du temps si
+nécessaire. Il utilise les valeurs obtenues en combinant des observations et des
+modèles *a priori*, incluant de plus des informations sur leurs erreurs.
+
+En d'autres termes, l'assimilation de données rassemble les données mesurées
+d'un système, qui sont les observations, avec une connaissance physique et
+mathématique *a priori* du système, intégrée dans les modèles numériques, afin
+d'obtenir la meilleure estimation possible de l'état réel du système et de ses
+propriétés stochastiques. On note que cet état réel (ou "état" vrai") ne peut
+être atteint, mais peut seulement être estimé. De plus, malgré le fait que les
+informations utilisées sont stochastiques par nature, l'assimilation de données
+fournit des techniques déterministes afin de réaliser l'estimation de manière
+très efficace.
+
+L'assimilation de données cherchant l'estimation la **meilleure possible**, la
+démarche technique sous-jacente intègre toujours de l'optimisation afin de
+trouver cette estimation : des méthodes d'optimisation choisies sont toujours
+intégrés dans les algorithmes d'assimilation de données. Par ailleurs, les
+méthodes d'optimisation peuvent être vues dans ADAO comme un moyen d'étendre les
+applications d'assimilation de données. Elles seront présentées de cette façon
+dans la section pour `Approfondir l'estimation d'état par des méthodes
+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 des données, qui
+sont couvert 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
+
+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 consistance 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
+priori* du champ que l'on cherche à identifier.
+
+Si le système évolue dans le temps, la reconstruction doit être établie à chaque
+pas de temps, du champ dans son ensemble. Le processus d'interpolation est dans
+ce cas plus compliqué car il est temporel, et plus seulement en termes de
+valeurs instantanées du champ.
+
+Un exemple simple de reconstruction de champs provient de la météorologie, dans
+laquelle on recherche les valeurs de variables comme la température ou la
+pression en tout point du domaine spatial. On dispose de mesures instantanées de
+ces quantités en certains points, mais aussi d'un historique de ces mesures. De
+plus, ces variables sont contraintes par les équations d'évolution de
+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
+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 modèles
+.. index:: single: calibration
+.. index:: single: ébauche
+.. index:: single: régularisation
+
+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
+"*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
+que l'on donne à chaque information utilisée. Cette confiance est représentée
+par la covariance des erreurs sur l'ébauche et sur les observations. Ainsi
+l'aspect stochastique des informations, mesuré *a priori*, est essentiel pour
+construire une fonction d'erreur pour la calibration.
+
+Un exemple simple d'identification de paramètres provient de tout type de
+simulation physique impliquant un modèle paramétré. Par exemple, une simulation
+de mécanique statique d'une poutre contrainte par des forces est décrite par les
+paramètres de la poutre, comme un coefficient de Young, ou par l'intensité des
+forces appliquées. Le problème d'estimation de paramètres consiste à chercher
+par exemple la bonne valeur du coefficient de Young de telle manière à ce que la
+simulation de la poutre corresponde aux mesures, en y incluant la connaissance
+des erreurs.
+
+Description simple du cadre méthodologique de l'assimilation de données
+-----------------------------------------------------------------------
+
+.. index:: single: ébauche
+.. index:: single: covariances d'erreurs d'ébauche
+.. index:: single: covariances d'erreurs d'observation
+.. index:: single: covariances
+
+On peut décrire ces démarches de manière simple. Par défaut, toutes les
+variables sont des vecteurs, puisqu'il y a plusieurs paramètres à ajuster.
+
+Selon les notations standard 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,
+:math:`\mathbf{x}^b` l'ébauche (valeurs *a priori*, ou valeurs de
+régularisation) des paramètres cherchés, :math:`\mathbf{x}^t` les paramètres
+inconnus idéaux qui donneraient exactement les observations (en supposant que
+toutes les erreurs soient nulles et que le modèle soit exact) en sortie.
+
+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:: \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 :
+
+.. 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 :
+
+.. 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 :
+
+.. 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).
+
+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})
+
+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...).
+
+En **assimilation par filtrage**, dans ce cas simple usuellement dénommé
+"*BLUE*" (pour "*Best Linear Unbiased Estimator*"), l'analyse
+:math:`\mathbf{x}^a` est donnée comme une correction de l'ébauche
+:math:`\mathbf{x}^b` par un terme proportionnel à la différence entre les
+observations :math:`\mathbf{y}^o` et les calculs :math:`\mathbf{H}\mathbf{x}^b` :
+
+.. math:: \mathbf{x}^a = \mathbf{x}^b + \mathbf{K}(\mathbf{y}^o - \mathbf{H}\mathbf{x}^b)
+
+où :math:`\mathbf{K}` est la matrice de gain de Kalman, qui s'exprime à l'aide
+des matrices de covariance sous la forme suivante :
+
+.. math:: \mathbf{K} = \mathbf{B}\mathbf{H}^T(\mathbf{H}\mathbf{B}\mathbf{H}^T+\mathbf{R})^{-1}
+
+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.
+
+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
+de Kalman*". Elles peuvent prendre en compte l'opérateur d'évolution pour
+établir aux bons pas de temps une analyse de l'écart entre les observations et
+les simulations et pour avoir, à chaque instant, la propagation de l'ébauche à
+travers le modèle d'évolution. Un grand nombre de variantes ont été développées
+pour accroître la qualité numérique des méthodes ou pour prendre en compte des
+contraintes informatiques comme la taille ou la durée des calculs.
+
+Approfondir le cadre méthodologique de l'assimilation de données
+----------------------------------------------------------------
+
+.. index:: single: estimation d'état
+.. index:: single: estimation de paramètres
+.. index:: single: problèmes inverses
+.. index:: single: estimation bayésienne
+.. index:: single: interpolation optimale
+.. index:: single: régularisation mathématique
+.. index:: single: méthodes de régularisation
+.. 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]_.
+
+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.
+Il y a de nombreux champs d'applications scientifiques et technologiques dans
+lesquels l'utilisation efficace des données observées, mais incomplètes, est
+cruciale.
+
+Certains aspects de l'assimilation de données sont aussi connus sous les noms
+d'*estimation d'état*, d'*estimation de paramètres*, de *problèmes inverses*,
+d'*estimation bayésienne*, d'*interpolation optimale*, de *régularisation
+mathématique*, de *lissage de données*, etc. Ces termes peuvent être utilisés
+dans les recherches bibliographiques.
+
+Approfondir l'estimation d'état par des méthodes d'optimisation
+---------------------------------------------------------------
+
+.. index:: single: estimation d'état
+.. index:: single: méthodes d'optimisation
+
+Comme vu précédemment, dans un cas de simulation statique, l'assimilation
+variationnelle de données nécessite de minimiser la fonction objectif :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})
+
+qui est dénommée la fonctionnelle du "*3D-VAR*". Elle peut être vue comme la
+forme étendue d'une *minimisation moindres carrés*, obtenue en ajoutant un terme
+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}`.
+
+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
+imaginées de deux manières.
+
+En premier lieu, les méthodes classiques d'optimisation impliquent l'usage de
+méthodes de minimisation variées basées sur un gradient. Elles sont extrêmement
+efficaces pour rechercher un minimum local isolé. Mais elles nécessitent que la
+fonctionnelle :math:`J` soit suffisamment régulière et différentiable, et elles
+ne sont pas en mesure de saisir des propriétés globales du problème de
+minimisation, comme par exemple : minimum global, ensemble de solutions
+équivalentes dues à une sur-paramétrisation, multiples minima locaux, etc. **Une
+méthode pour étendre les possibilités d'estimation consiste donc à utiliser
+l'ensemble des méthodes d'optimisation existantes, permettant la minimisation
+globale, diverses propriétés de robustesse de la recherche, etc**. Il existe de
+nombreuses méthodes de minimisation, comme les méthodes stochastiques,
+évolutionnaires, les heuristiques et méta-heuristiques pour les problèmes à
+valeurs réelles, etc. Elles peuvent traiter des fonctionnelles :math:`J` en
+partie irrégulières ou bruitées, peuvent caractériser des minima locaux, etc. Le
+principal désavantage de ces méthodes est un coût numérique souvent bien
+supérieur pour trouver les estimations d'états, et pas de garantie de
+convergence en temps fini. Ici, on ne mentionne que des méthodes qui sont
+disponibles dans le module ADAO : la *régression de quantile (Quantile
+Regression)* [WikipediaQR]_ and l'*optimisation par essaim de particules
+(Particle Swarm Optimization)* [WikipediaPSO]_.
+
+En second lieu, les méthodes d'optimisation cherchent usuellement à minimiser
+des mesures quadratiques d'erreurs, car les propriétés naturelles de ces
+fonctions objectifs sont bien adaptées à l'optimisation classique par gradient.
+Mais d'autres mesures d'erreurs peuvent être mieux adaptées aux problèmes de
+simulation de la physique réelle. Ainsi, **une autre manière d'étendre les
+possibilités d'estimation consiste à utiliser d'autres mesures d'erreurs à
+réduire**. Par exemple, on peut citer l'**erreur absolue**, l'**erreur
+maximale**, etc. Ces mesures d'erreurs ne sont pas différentiables, mais
+certaines méthodes d'optimisation peuvent les traiter: heuristiques et
+méta-heuristiques pour les problèmes à valeurs réelles, etc. Comme précédemment,
+le principal désavantage de ces méthodes est un coût numérique souvent bien
+supérieur pour trouver les estimations d'états, et pas de garantie de
+convergence en temps fini. Ici, on ne mentionne encore que des méthodes qui sont
+disponibles dans le module ADAO : l'*optimisation par essaim de particules
+(Particle Swarm Optimization)* [WikipediaPSO]_.
+
+Le lecteur intéressé par le sujet de l'optimisation pourra utilement commencer
+sa recherche grâce au point d'entrée [WikipediaMO]_.
--- /dev/null
+.. _section_using:
+
+================================================================================
+Utiliser le module ADAO
+================================================================================
+
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+ :scale: 50%
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+ :scale: 50%
+.. |eficas_saveas| image:: images/eficas_saveas.png
+ :align: middle
+ :scale: 50%
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+ :scale: 50%
+.. |yacs_compile| image:: images/yacs_compile.png
+ :align: middle
+ :scale: 50%
+
+Cette section présente l'usage du module ADAO dans la plateforme SALOME. Il est
+complété par la description détaillée de l'ensemble des commandes et mots-clés
+dans la section :ref:`section_reference`, par des procédures avancées d'usage
+dans la section :ref:`section_advanced`, et par des exemples dans la section
+:ref:`section_examples`.
+
+Procédure logique pour construire un cas ADAO
+---------------------------------------------
+
+La construction d'un cas ADAO suit une démarche simple pour définir l'ensemble
+des données d'entrée, et ensuite générer un diagramme complet d'exécution
+utilisé dans YACS. De nombreuses variations existent pour la définition des
+données d'entrée, mais la séquence logique reste inchangée.
+
+De manière générale, l'utilisateur doit connaître ses données d'entrées,
+requises pour mettre au point une étude d'assimilation de données. Ces données
+peuvent être disponibles dans SALOME ou non.
+
+**Fondamentalement, la procédure d'utilisation de ADAO comprend les étapes
+suivantes:**
+
+#. **Activez le module ADAO et utiliser l'éditeur graphique (GUI),**
+#. **Construire et/ou modifier le cas ADAO et l'enregistrer,**
+#. **Exporter le cas ADAO comme un schéma YACS,**
+#. **Compléter et modifier le schéma YACS, et l'enregistrer,**
+#. **Exécutez le cas YACS et obtenir les résultats.**
+
+Chaque étape est détaillée dans la section suivante.
+
+ÉTAPE 1 : Activer le module ADAO et utiliser l'interface graphique d'édition (GUI)
+----------------------------------------------------------------------------------
+
+Comme toujours pour un module, il doit être préalablement activé en
+sélectionnant le bouton de module approprié (ou le menu) dans la barre d'outils
+de SALOME. S'il n'existe aucune étude SALOME chargée, un menu contextuel
+apparaît, permettant de choisir entre la création d'une nouvelle étude, ou
+l'ouverture d'une étude déjà existante:
+
+ .. _adao_activate1:
+ .. image:: images/adao_activate.png
+ :align: center
+ .. centered::
+ **Activation du module ADAO dans SALOME**
+
+En choisissant le bouton "*Nouveau*", un éditeur intégré de cas EFICAS [#]_ sera
+ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors
+cliquer sur le bouton "*Nouveau*"(ou choisir l'entrée "*Nouveau*" dans le dans
+le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient :
+
+ .. _adao_viewer:
+ .. image:: images/adao_viewer.png
+ :align: center
+ :width: 100%
+ .. centered::
+ **L'éditeur EFICAS pour la définition des cas dans le module ADAO**
+
+ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer
+---------------------------------------------------------
+
+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.
+
+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
+un indicateur d'erreur visuel rouge. Les valeurs possibles sont indiquées pour
+les mots-clés par la définition d'une liste limitée de valeurs, et les entrées
+adaptées sont données pour les autres mots-clés. Des messages d'aide sont
+fournis de manière contextuelle aux places réservées de l'éditeur.
+
+Un nouveau cas est mis en place avec la liste minimale des commandes. Toutes les
+commandes ou les mots-clés obligatoires sont déjà présents, aucun d'eux ne peut
+être supprimé. Des mots-clés optionnels peuvent être ajoutés en les choisissant
+dans une liste de suggestions de ceux autorisés pour la commande principale, par
+exemple la commande "*ASSIMILATION_STUDY*". À titre d'exemple, on peut ajouter
+un mot-clé "*AlgorithmParameters*", comme décrit dans la dernière partie de la
+section :ref:`section_examples`.
+
+A la fin de ces actions, lorsque tous les champs ou les mots-clés ont été
+correctement définis, chaque ligne de l'arborescence des commandes doit
+présenter un drapeau vert. Cela signifie que l'ensemble du cas est valide et
+dûment rempli (et qu'il peut être sauvegardé).
+
+ .. _adao_jdcexample00:
+ .. image:: images/adao_jdcexample01.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Exemple d'un cas ADAO valide**
+
+Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*"
+|eficas_save|, ou le bouton "*Enregistrer sous*" |eficas_saveas|, ou en
+choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il
+est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et
+un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers
+JDC d'EFICAS. Cette action va générer une paire de fichiers décrivant le cas
+ADAO, avec le même nom de base, le premier présentant une extension "*.comm*" et
+le second une extension "*.py*" [#]_.
+
+ÉTAPE 3 : Exporter le cas ADAO comme un schéma YACS
+---------------------------------------------------
+
+Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme
+d'un schéma YACS [#]_ pour pouvoir exécuter le calcul d'assimilation de
+données. Cela peut être réalisé facilement en utilisant le bouton "*Exporter
+vers YACS*" |eficas_yacs|, ou de manière équivalente en choisissant l'entrée
+"*Exporter vers YACS*" dans le menu principal "*ADAO*", ou dans le menu
+contextuel du cas dans le navigateur d'objets SALOME.
+
+ .. _adao_exporttoyacs01:
+ .. image:: images/adao_exporttoyacs.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **Sous-menu "Exporter vers YACS" pour générer le schéma YACS à partir d'un cas ADAO**
+
+Cela conduit à générer automatiquement un schéma YACS, et à activer le module
+YACS sur ce schéma. Le fichier YACS, associé au schéma, est stocké dans le même
+répertoire et avec le même nom de base de fichier que le cas ADAO enregistré,
+changeant simplement son extension en "*.xml*". Attention, *si le nom de fichier
+XML existe déjà, le fichier est écrasé sans avertissement sur le remplacement du
+fichier XML*.
+
+ÉTAPE 4 : Compléter et modifier le schéma YACS, et l'enregistrer
+----------------------------------------------------------------
+
+.. index:: single: Analysis
+
+Lorsque le schéma YACS est généré et ouvert dans SALOME à travers le l'interface
+graphique du module YACS, on peut modifier ou compléter le schéma comme tout
+schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou
+modifiés pour élaborer une analyse complexe, ou pour insérer des capacités
+d'assimilation de données ou d'optimisation dans des schémas de calculs YACS
+plus complexes.
+
+Le principal complément nécessaire dans un schéma YACS est une étape de
+post-processing. L'évaluation du résultat doit être réalisé dans le contexte
+physique de simulation utilisé par la procédure d'assimilation de données. Le
+post-processing peut être fournit à travers le mot-clé "*UserPostAnalysis*"
+d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par
+des patrons ("templates"), ou peut être construit comme des noeuds YACS. Ces
+deux manières de construire le post-processing peuvent utiliser toutes les
+capacités de SALOME.
+
+Dans le détail, le schéma YACS dispose d'un port de sortie "*algoResults*" dans
+le bloc de calcul, qui donne accès à un objet de type "*pyobj*" nommé ci-aprés
+"*ADD*", qui contient tous les résultats de calcul. Ces résultats peuvent être
+obtenus en récupérant les variables nommées stockées au cours des calculs.
+L'information principale est la variable "*Analysis*", qui peut être obtenue par
+une commande python (par exemple dans un noeud script intégré ("in-line script
+node") ou un script fourni à travers le mot-clé "*UserPostAnalysis*"::
+
+ Analysis = ADD.get("Analysis")[:]
+
+"*Analysis*" est un objet complexe, similaire à une liste de valeurs calculées à
+chaque étape du calcul d'assimilation. Pour obtenir et afficher l'évaluation
+optimale de l'état par assimilation de données, dans un script fournit par
+l'intermédiaire du mot-clé "*UserPostAnalysis*", on peut utiliser::
+
+ Xa = ADD.get("Analysis")[-1]
+ print "Optimal state:", Xa
+ print
+
+Cette variable ``Xa`` est un vecteur de valeurs, qui représente la solution du
+problème d'évaluation par assimilation de données ou par optimisation, notée
+:math:`\mathbf{x}^a` dans la section :ref:`section_theory`.
+
+Une telle méthode peut être utilisée pour imprimer les résultats, ou pour les
+convertir dans des structures qui peuvent être nécessaires à un post-processing
+natif ou externe à SALOME. Un exemple simple est disponible dans la section
+:ref:`section_examples`.
+
+ÉTAPE 5 : Exécuter le schéma YACS et obtenir les résultats
+----------------------------------------------------------
+
+Le schéma YACS est maintenant complet et peut être exécuté. La paramétrisation
+et l'exécution de ce cas YACS est entièrement compatible avec la manière
+standard de traiter un schéma YACS, comme décrit dans le *Guide de l'utilisateur
+du module YACS*.
+
+Pour rappeler la manière la plus simple de procéder, le schéma YACS doit être
+compilé en utilisant le bouton |yacs_compile|, ou l'entrée équivalente du menu
+YACS, pour préparer le schéma à son exécution. Ensuite, le schéma compilé peut
+être démarré, exécuté pas à pas ou en utilisant des points d'arrêt, etc.
+
+La sortie standard est restituée dans la "*fenêtre de sortie de YACS*" (ou
+"*YACS Container Log*"), à laquelle on accède par un clic droit sur la fenêtre
+"*proc*" dans l'interface graphique YACS. Les erreurs sont présentées soit
+dans la "*fenêtre de sortie de YACS*", ou à la ligne de commande dans la fenêtre
+de commandes (si l'environnement SALOME a été lancé par une commande explicite,
+et non par un menu ou une icône de bureau). Par exemple, la sortie de l'exemple
+simple ci-dessus est de la forme suivante::
+
+ Entering in the assimilation study
+ Name is set to........: Test
+ Algorithm is set to...: Blue
+ Launching the analyse
+
+ Optimal state: [0.5, 0.5, 0.5]
+
+présentée dans la "*fenêtre de sortie de YACS*".
+
+L'exécution peut aussi être conduite en utilisant un script de commandes shell,
+comme décrit dans la section :ref:`section_advanced`.
+
+.. [#] Pour de plus amples informations sur EFICAS, voir le *module EFICAS* et son aide disponible dans l'environnement SALOME.
+
+.. [#] 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`.
</section>
<section name="adao_help">
<parameter name="sub_menu" value="%1 module"/>
- <parameter name="User's Guide" value="${ADAO_ROOT_DIR}/share/doc/salome/gui/ADAO/en/index.html"/>
+ <parameter name="(EN) User's Guide" value="${ADAO_ROOT_DIR}/share/doc/salome/gui/ADAO/en/index.html"/>
+ <parameter name="(FR) Guide de l'utilisateur" value="${ADAO_ROOT_DIR}/share/doc/salome/gui/ADAO/fr/index.html"/>
</section>
</document>
