.. _section_advanced:
================================================================================
-Advanced usage of ADAO
+Advanced usage of the ADAO module
================================================================================
This section presents advanced methods to use the ADAO module, how to get more
#. using the SALOME application including ADAO module, launch SALOME with ``./runAppli -k``
#. initialise the command line session with: ``./runSession``
+#. change to the YACS calculation scheme directory to be executed
#. execute the export command: ``python ${ADAO_ROOT_DIR}/bin/salome/AdaoYacsSchemaCreator.py <input Python file> <output YACS xml scheme>``
#. standard output comes on console, successive executions can be done
-#. stop SALOME: ``shutdownSalome.py`` or ``killSalome.py``
+#. stop SALOME: ``killSalome.py``
#. exit from the session: ``CTRL+D``
-Be careful, if the output YACS xml scheme already exists, this command replace
-it without asking the user. The command accepts files with or without path
-specifications.
+Be careful, if the output YACS xml scheme file already exists, this command
+replace it without asking the user. The command accepts files with or without
+path specifications.
It is not necessary to launch and shut down SALOME each time if the application
is already running.
#. change to the YACS calculation scheme directory to be executed
#. execute the YACS supervisor: ``driver <ADAO YACS xml scheme>``
#. standard output comes on console, successive executions can be done
-#. stop SALOME: ``shutdownSalome.py`` or ``killSalome.py``
+#. stop SALOME: ``killSalome.py``
#. exit from the session: ``CTRL+D``
It is not necessary to launch and shut down SALOME each time if the application
Getting more information when running an assimilation calculation
--------------------------------------------------------------------------------
---TODO--
-
-(Use the logging functionality of the library)
-
-
-Complex time or step treatments during an assimilation calculation
---------------------------------------------------------------------------------
-
---TODO--
-
-(Scheduling input data)
+When running, the ADAO module is logging useful data and messages. There are two
+ways to obtain theses informations.
+
+The first one, and the preferred way, is to use the built-in variable "*Debug*"
+integrated in every "*ASSIMILATION_STUDY*". It is available through the GUI of
+the module. Setting it to "*1*" will send a lot of 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
+informations on this module). Everywhere in the YACS scheme, mainly through the
+scripts entries, the user can set the logging level in accordance to the needs
+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
+following Python lines::
+
+ import logging
+ logging.getLogger().setLevel(logging.DEBUG)
+
+The standard logging module default level is "*WARNING*", the default level in
+the ADAO module is "*INFO*".
Examples on using the ADAO module
================================================================================
-This section presents some examples on using the ADAO module in SALOME.
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+
+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.
Building a simple 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 *weighted least square estimated state* of
``Yo = [1 1 1]``
-The background state, wich represent some *a priori* knowledge or a
+The background state, which represent some *a priori* knowledge or a
regularization, is of value of 0 in each direction, which is:
``Xb = [0 0 0]``
``Xa = [0.5 0.5 0.5]``
As en extension of this example, one can change the variances for ``B`` or ``R``
-independantly, and the analysis will move to ``Yo`` or ``Xb`` in inverse
-proportion of the variances in ``B`` and ``R``. It is also equivalent to serach
+independently, and the analysis will move to ``Yo`` or ``Xb`` in inverse
+proportion of the variances in ``B`` and ``R``. 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
.. _adao_activate2:
.. image:: images/adao_activate.png
:align: center
+ :width: 100%
.. centered::
**Activating the module ADAO in SALOME**
-.. |eficas_new| image:: images/eficas_new.png
- :align: middle
-
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
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
-"*Object browser*" window, and choose the "*Export to YACS*" submenu as below:
+"*Object browser*" window, and choose the "*Export to YACS*" sub-menu (or the
+"*Export to YACS*" button |eficas_yacs|) as below:
.. _adao_exporttoyacs:
.. image:: images/adao_exporttoyacs.png
:align: center
:scale: 75%
.. centered::
- **"*Export to YACS*" submenu to generate the YACS scheme from the ADAO case**
+ **"Export to YACS" submenu 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 YACS module GUI [#]. After reordering the nodes by
-using the "*arrange local node*" submenu 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 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:
.. _yacs_generatedscheme:
.. image:: images/yacs_generatedscheme.png
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 "*inline script node*"
-submenu of the YACS graphical view, and we name it "*PostProcessing*".
+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
"*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 inline script node need to have an input port of type
-"*pyobj*" named "*results*", 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::
+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
+in the script node is::
Xa = results.ADD.get("Analysis").valueserie(-1)
print
The augmented YACS scheme can be saved (overwriting the generated scheme if the
-simple "*Save*" command or button is used, or with a new name). Then,
+simple "*Save*" command or button are used, or with a new name). 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 throught the right click menu of the "*proc*" window in the YACS
+Log*", obtained through the right click menu of the "*proc*" window in the YACS
scheme as shown below:
.. _yacs_containerlog:
.. centered::
**YACS menu for Container Log, and dialog window showing the log**
-We verify that the result is correct by checking that the log contains the
-following line::
+We verify that the result is correct by checking that the log dialog window
+contains the following line::
Analysis = [0.5, 0.5, 0.5]
As a simple extension of this example, one can notice that the same problem
solved with a 3DVAR algorithm gives the same result. This algorithm can be
chosen at the ADAO case building step, before entering in YACS step. The
-ADAO 3DVAR case will look completly similar to the BLUE algoritmic case, as
+ADAO 3DVAR case will look completely similar to the BLUE algorithmic case, as
shown by the following figure:
- .. _adao_jdcexample01:
+ .. _adao_jdcexample02:
.. image:: images/adao_jdcexample02.png
:align: center
:width: 100%
.. centered::
- **Defining an ADAO 3DVAR case looks completly similar to a BLUE case**
+ **Defining an ADAO 3DVAR case looks completely similar to a BLUE case**
-There is only one keyword changing, with "*ThreeDVAR*" instead of "*Blue*".
+There is only one command changing, with "*3DVAR*" value instead of "*Blue*".
Building a simple estimation case with external data definition by functions
---------------------------------------------------------------------------------
+----------------------------------------------------------------------------
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
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. This
-script looks like::
+definition in the ADAO GUI and implicit data definition by external files. The
+present script looks like::
#-*-coding:iso-8859-1-*-
import numpy
matrices, using list, string (as in Numpy or Octave), Numpy array type or Numpy
matrix type, and Numpy special functions. All of these syntaxes are valid.
-After saving this script somewhere in your path (named here
-"*test003_ADAO_example_scripts.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:
+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:
.. _adao_scriptentry01:
.. image:: images/adao_scriptentry01.png
Other steps and results are exactly the same as in the `Building a simple
estimation case with explicit data definition`_ previous example.
-In fact, this script methodology allows to retrieve data from inline or previous
+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
-debug purpose or for repetitive process. **But be careful, it is not a "safe"
-process, in the sense that erroneous data, or errors in calculations, can be
-directly injected into the YACS scheme execution.**
+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 option of the algorithm. This keyword
-requires a Python dictionary containing some key/value pairs.
+definition of the ADAO case, which is an keyword of the ASSIMILATION_STUDY. This
+keyword requires a Python dictionary, containing some key/value pairs.
For example, with a 3DVAR algorithm, the possible keys are "*Minimizer*",
-"*MaximumNumberOfSteps*", "*Bounds*". 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. 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.
-
-This dictionary has to be defined in an external Python script file, using the
-mandatory variable name "*AlgorithmParameters*" for the dictionary. All the keys
-inside the dictionary are optional, they all have default values, and can exist
-without being used. For example::
+"*MaximumNumberOfSteps*", and "*Bounds*":
+
+#. The "*Minimizer*" key allows to choose the optimisation minimizer, the
+ default choice being "LBFGSB", and the possible ones "LBFGSB" (nonlinear
+ constrained minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear
+ constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS"
+ (nonlinear unconstrained minimizer).
+#. The "*MaximumNumberOfSteps*" key indicates the maximum number of iterations
+ allowed for iterative optimisation. The default is 15000, which very
+ similar of no limit on iterations. It is then recommended to adapt this
+ parameter to the needs on real problems.
+#. The "*Bounds*" 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 there is no bound.
+
+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.
+
+This dictionary has to be defined, for example, in an external Python script
+file, using the mandatory variable name "*AlgorithmParameters*" for the
+dictionary. All the keys inside the dictionary are optional, they all have
+default values, and can exist without being used. For example::
#-*-coding:iso-8859-1-*-
#
**Adding parameters to control the algorithm**
Other steps and results are exactly the same as in the `Building a simple
-estimation case with explicit data definition`_ previous example.
+estimation case with explicit data definition`_ previous example. The dictionary
+can also be directly given in the input field associated with the keyword.
.. [#] For more information on YACS, see the the *YACS User Guide* available in the main "*Help*" menu of SALOME GUI.
-
In all this documentation, we use standard notations of data assimilation.
Moreover, vectors are written horizontally or vertically without difference.
-Matrices are written either normally, either with a condensed notation,
-consisting in the use of a "``;``" to separate the rows in a continuous line.
+Matrices are written either normally, or with a condensed notation, consisting
+in the use of a "``;``" to separate the rows in a continuous line.
.. toctree::
:maxdepth: 2
Introduction to ADAO
================================================================================
-The aim of ADAO module is to help using *data assimilation* methodology in
-conjunction with other calculation modules in SALOME.
-
-
---TODO--
+The aim of the ADAO module is to help using *data assimilation* methodology in
+conjunction with other calculation modules in SALOME. The module provides
+interface to some standard algorithms of data assimilation or optimization, and
+allows integration of them in a SALOME study.
exact).
In the simplest case, static, the steps of simulation and of observation can be
-combined into a single 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 :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:
+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 :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:
.. math:: \mathbf{y}^o = \mathbf{H} \mathbf{x}^t + \mathbf{\epsilon}^o
.. [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
+.. [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
.. [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
+.. [Talagrand97] Talagrand O., *Assimilation of Observations, an Introduction*, Journal of the Meteorological Society of Japan, 75(1B), pp.191-209, 1997
.. [Kalnay03] Kalnay E., *Atmospheric Modeling, Data Assimilation and Predictability*, Cambridge University Press, 2003
.. _section_using:
================================================================================
-Using the module ADAO
+Using the ADAO module
================================================================================
-This section presents the usage of the ADAO module in SALOME.
+.. |eficas_new| image:: images/eficas_new.png
+ :align: middle
+.. |eficas_save| image:: images/eficas_save.png
+ :align: middle
+.. |eficas_yacs| image:: images/eficas_yacs.png
+ :align: middle
+
+This section presents the usage of the ADAO module in SALOME. It is complemented
+by advanced usage procedures the section :ref:`section_advanced`, and by some
+examples in the section :ref:`section_examples`.
Logical procedure to build an ADAO test case
--------------------------------------------
.. _adao_activate1:
.. image:: images/adao_activate.png
:align: center
+ :width: 100%
.. centered::
**Activating the module ADAO in SALOME**
-.. |eficas_new| image:: images/eficas_new.png
- :align: middle
-.. |eficas_save| image:: images/eficas_save.png
- :align: middle
-
Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
along with the standard "*Object browser*". You can then click on the "*New*"
-button |eficas_new| (or choose the "*New*" entry in the "*File*" menu) to create
-a new ADAO case, and you will see:
+button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
+create a new ADAO case, and you will see:
.. _adao_viewer:
.. image:: images/adao_viewer.png
**The EFICAS editor for cases definition in module ADAO**
It is a good habit to save the ADAO case now, by pushing the "*Save*" button
-|eficas_save| or by choosing the "*Save/Save as*" entry in the "*File*" menu.
+|eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
You will be prompted for a location in your file tree and a name, that will be
completed by a "*.comm*" extension used for JDC EFICAS files.
Build and modify the ADAO case and save it
++++++++++++++++++++++++++++++++++++++++++
-To build a case using EFICAS, you have to go through a series of steps for
-selecting a keyword and then filling in its value. The structured editor
-indicates hierarchical types, values or keywords allowed. Incomplete or
-incorrect keywords are identified by a visual error red flag.
-
+To build a case using EFICAS, you have to go through a series of steps, by
+selecting a keyword and then filling in its value.
+The structured editor indicates hierarchical types, values or keywords allowed.
+Incomplete or incorrect keywords are identified by a visual error red flag.
+Possible values are indicated for keywords defined with a limited list of
+values, and adapted entries are given for the other keywords. All the mandatory
+command or keyword are already present, and optionnal commands can be added.
+A new case is set up with the minimal list of commands. No mandatory command can
+be suppressed, but others can be added as allowed keywords for an
+"*ASSIMILATION_STUDY*" command. As an example, one can add an
+"*AlgorithmParameters*" keyword, as described in the last part of the section
+:ref:`section_examples`.
+At the end, when all fields or keywords have been correctly defined, each line
+of the commands tree must have a green flag. This indicates that the whole case
+is valid and completed.
+ .. _adao_jdcexample00:
+ .. image:: images/adao_jdcexample01.png
+ :align: center
+ :width: 50%
+ .. centered::
+ **Example of a valid ADAO case**
-At the end, you have to save your ADAO case.
+Finally, you have to save your ADAO case by pushing the "*Save*" button
+|eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
Export the ADAO case as a YACS scheme
+++++++++++++++++++++++++++++++++++++
+When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
+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.
+
+ .. _adao_exporttoyacs:
+ .. image:: images/adao_exporttoyacs.png
+ :align: center
+ :scale: 75%
+ .. centered::
+ **"Export to YACS" submenu to generate the YACS scheme from the ADAO case**
+This will lead to automatically generate an XML file for the YACS scheme, and
+open YACS module on this file. The YACS file will be stored in the same
+directory and with the same name as the ADAO saved case, only changing its
+extension from "*.comm*" to "*.xml*". *Be careful, if the name already exist, it
+will overwrite it without prompting for replacing the file*. In the same time,
+an intermediary python file is also stored in the same place, with a "*.py*"
+extension replacing the "*.comm*" one [#]_.
Modify and supplement the YACS scheme and save it
+++++++++++++++++++++++++++++++++++++++++++++++++
+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. It is
+recommended to save the modified scheme with a new name, in order to preserve in
+the case you re-export to YACS the ADAO case.
-Execute the YACS case and obtain the results
-++++++++++++++++++++++++++++++++++++++++++++
-
-
-
-
-
-
-Reference description of the commands and keywords available throught the GUI
------------------------------------------------------------------------------
+The main supplement needed in the YACS scheme is a postprocessing step. The
+evaluation of the results has to be done in the physical context of the
+simulation used by the data assimilation procedure.
---TODO--
+The YACS scheme has an "*algoResults*" output port of the computation bloc,
+which gives access to a "*pyobj*" containing all the 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)::
+ Analysis = results.ADD.get("Analysis").valueserie(-1)
-ASSIM_STUDY
+This is a complex object, similar to a list of values calculated at each step of
+data assimilation calculation. In order to get the last data assimilation
+analysis, one can use::
-String
+ Xa = results.ADD.get("Analysis").valueserie(-1)
-Script
+This ``Xa`` is a vector of values, that represents the solution of the data
+assimilation evaluation problem, noted as :math:`\mathbf{x}^a` in the section
+:ref:`section_theory`.
-Vector
+Such command can be used to print results, or to convert these ones to
+structures that can be used in the native or external SALOME postprocessing. A
+simple example is given in the section :ref:`section_examples`.
-Matrix
-
-Function
-
-Dict
-
-Background
-
-BackgroundError
+Execute the YACS case and obtain the results
+++++++++++++++++++++++++++++++++++++++++++++
-Observation
+The YACS scheme is now complete and can be executed. Parametrisation 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 User Guide*.
+
+Results can be obtained, through the "*algoResults*" output port, using YACS
+nodes to retrieve all the informations in the "*pyobj*" object, to transform
+them, to convert them, to save part of them, etc.
+
+The data assimilation results and complementary calculations can be retrieved
+using the "*get*" method af the "*algoResults.ADD*" object. This method pick the
+different output variables identified by their name. Indicating in parenthesis
+their availability as automatic (for every algorithm) or optional (depending on
+the algorithm), and their notation coming from section :ref:`section_theory`,
+the main available output variables are the following:
+
+#. "Analysis" (automatic): the control state evaluated by the data assimilation
+ procedure, noted as :math:`\mathbf{x}^a`.
+#. "Innovation" (automatic): the difference between the observations and the
+ control state transformed by the observation operator, noted as
+ :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^b`.
+#. "OMB" (optional): the difference between the observations and the
+ background, similar to the innovation.
+#. "BMA" (optional): the difference between the background and the analysis,
+ noted as :math:`\mathbf{x}^b - \mathbf{x}^a`.
+#. "OMA" (optional): the difference between the observations and the analysis,
+ noted as :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^a`.
+
+Input variables are also available as output in order to gather all the
+information at the end of the procedure.
+
+All the variables are list of typed values, each item of the list
+corresponding to the value of the variable at a time step or an iteration step
+in the data assimilation optimisation procedure. The variable value at a given
+"*i*" step can be obtained by the method "*valueserie(i)*". The last one
+(consisting in the solution of the evaluation problem) can be obtained using the
+step "*-1*" as in a standard list.
+
+Reference description of the commands and keywords available through the GUI
+-----------------------------------------------------------------------------
-ObservationError
+Each command or keyword to be defined through the ADAO GUI has some properties.
+The first property is to be a required command, an optional command or a keyword
+describing a type. The second property is to be an "open" variable with a fixed
+type but with any value allowed by the type, or a "restricted" variable, limited
+to some specified values. The mathematical notations are explained in the
+section :ref:`section_theory`.
+
+The different type-style commands are:
+
+:Dict:
+ Type of an input. This indicates a variable that has to be filled by a
+ dictionary, usually given as a script.
+
+:Function:
+ Type of an input. This indicates a variable that has to be filled by a
+ function, usually given as a script.
+
+:Matrix:
+ Type of an input. This indicates a variable that has to be filled by a
+ matrix, usually given either as a string or as a script.
+
+:String:
+ Type of an input. This indicates a string, such as a name or a literal
+ representation of a matrix or vector, such as "1 2 ; 3 4".
+
+:Script:
+ Type of an input. This indicates a script given as an external file.
+
+:Vector:
+ Type of an input. This indicates a variable that has to be filled by a
+ vector, usually given either as a string or as a script.
+
+The different commands are the following:
+
+:ASSIM_STUDY:
+ Required command. This is the general command describing an ADAO case. It
+ hierarchicaly contains all the other commands.
+
+:Algorithm:
+ Required command. This is a string to indicates the data assimilation
+ algorithm chosen. The choices are limited and available through the GUI.
+ There exists for example: "3DVAR", "Blue", "EnsembleBlue", "KalmanFilter".
+
+:AlgorithmParameters:
+ Optional command. This command allows to add some optional parameters to
+ control the data assimilation algorithm calculation. It is defined as a
+ "*Dict*" type object.
+
+:Background:
+ Required command. This indicates the backgroud vector used for data
+ assimilation, 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.
+
+:BackgroundError:
+ Required command. This indicates the backgroud error covariance matrix,
+ previously noted as :math:`\mathbf{B}`.It is defined as a "*Matrix*" type
+ object, that is, given either as a string or as a script.
+
+:Debug:
+ Required command. This let choose the level of trace and intermediary debug
+ informations.The choices are limited between 0 (for False) and 1 (for True)
+ and available through the GUI.
+
+:InputVariables:
+ Optional command. This command allows to indicates the name and size of
+ physical variables that are bundled together in the control vector. This
+ information is dedicated to data processed inside of data assimilation
+ algorithm.
+
+:Observation:
+ Required command. This indicates the observation vector used for data
+ assimilation, previously noted as :math:`\mathbf{y}^o`. It is defined as a
+ "*Vector*" type object, that is, given either as a string or as a script.
+
+:ObservationError:
+ Required command. This indicates the observation error covariance matrix,
+ previously noted as :math:`\mathbf{R}`.It is defined as a "*Matrix*" type
+ object, that is, given either as a string or as a script.
+
+: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`.
+
+:OutputVariables:
+ Optional command. This command allows to indicates the name and size of
+ physical variables that are bundled together in the output observation
+ vector. This information is dedicated to data processed inside of data
+ assimilation algorithm.
+
+: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.
+
+:UserDataInit:
+ Optional command. This commands allows to initialise some parameters or data
+ automatically before data assimilation algorithm processing.
+
+: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 simple code directly inside the ADAO
+ case.
+
+Examples of using these commands are available in the section
+:ref:`section_examples` and in examples files installed with ADAO module.
-ObservationOperator
+.. [#] For more information on EFICAS, see the the *EFICAS User Guide* available in the main "*Help*" menu of SALOME GUI.
-AlgorithmParameters
+.. [#] For more information on YACS, see the the *YACS User Guide* available in the main "*Help*" menu of SALOME GUI.
-Algorithm : "ThreeDVAR", "Blue", "EnsembleBlue", "Kalman"...
+.. [#] This intermediary python file can be safely removed after YACS export, but can also be used as described in the section :ref:`section_advanced`.
-.. [#] For more information on EFICAS, see the the *EFICAS User Guide* available in the main "*Help*" menu of SALOME GUI.
+.. [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
+.. [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
