: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
+by advanced usage procedures the section :ref:`section_advanced`, and by
examples in the section :ref:`section_examples`.
Logical procedure to build an ADAO test case
The construction of an ADAO case follows a simple approach to define the set of
input data, either static or dynamic data, and then generates a complete block
-diagram used in Y. Many variations exist for the definition of input data, but
-the logical sequence remains unchanged.
+diagram used in YACS. Many variations exist for the definition of input data,
+but the logical sequence remains unchanged.
First of all, the user is considered to know the input data needed to set up the
data assimilation study. These data can be in SALOME or not.
-**Basically, the procedure involves the following steps:**
+**Basically, the procedure of using ADAO involves the following steps:**
-#. **Activate the ADAO module and use the editor GUI,**
-#. **Build and modify the ADAO case and save it,**
-#. **Export the ADAO case as a YACS scheme,**
-#. **Modify and supplement the YACS scheme and save it,**
-#. **Execute the YACS case and obtain the results.**
+#. **Activate the ADAO module and use the editor GUI,**
+#. **Build and modify the ADAO case and save it,**
+#. **Export the ADAO case as a YACS scheme,**
+#. **Modify and supplement the YACS scheme and save it,**
+#. **Execute the YACS case and obtain the results.**
-Each step will be detailed later in the next section.
+Each step will be detailed in the next section.
Detailed procedure to build an ADAO test case
---------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++++
As always for a module, it has to be activated by choosing the appropriate
-module button (or menu) in the toolbar of SALOME. A popup appears, allowing to
-choose between creating a new study, or opening an already existing one:
+module button (or menu) in the toolbar of SALOME. If there is no 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
:align: center
- :width: 100%
.. centered::
**Activating the module ADAO in SALOME**
"*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
menu in the object browser.
- .. _adao_exporttoyacs:
+ .. _adao_exporttoyacs01:
.. 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" sub-menu 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
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*.
+YACS scheme, and is described in the *YACS module User's Guide*.
Results can be obtained, through the "*algoResults*" output port, using YACS
nodes to retrieve all the informations in the "*pyobj*" object, to transform
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
+in the data assimilation optimization 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.
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`.
+describing a type of input. 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 used afterwards are
+explained in the section :ref:`section_theory`.
+
+List of possible input types
+++++++++++++++++++++++++++++
The different type-style commands are:
:Dict:
- Type of an input. This indicates a variable that has to be filled by a
+ *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
+ *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
+ *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
+ *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.
+ *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
+ *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.
+List of commands
+++++++++++++++++
+
The different commands are the following:
:ASSIM_STUDY:
- Required command. This is the general command describing an ADAO case. It
+ *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
+ *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".
+ There exists for example: "3DVAR", "Blue"... See below the list of
+ algorithms and associated parameters.
:AlgorithmParameters:
- Optional command. This command allows to add some optional parameters to
+ *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.
+ "*Dict*" type object. See below the list of algorithms and associated
+ parameters.
:Background:
- Required command. This indicates the backgroud vector used for data
+ *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,
+ *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.
+ *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
+ *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
+ *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,
+ *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
+ *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
+ *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.
+ *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
+ *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.
+ *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
+ *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.
+.. _subsection_algo_options:
+
+List of possible options for the algorithms
++++++++++++++++++++++++++++++++++++++++++++
+
+Each algorithm can be controled using some generic or specific options given
+throught the "*AlgorithmParameters*" optional command, as follows::
+
+ AlgorithmParameters = {
+ "Minimizer" : "CG",
+ "MaximumNumberOfSteps" : 10,
+ }
+
+This section describes the available options by algorithm. If an option is
+specified for an algorithm that doesn't support it, the option is simply left
+unused.
+
+:"Blue":
+ no option
+
+:"LinearLeastSquares":
+ no option
+
+:"3DVAR":
+
+ :Minimizer:
+ 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).
+
+ :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
+ there is no bound. The bounds can always be specified, but they are taken
+ into account only by the constrained minimizers.
+
+ :MaximumNumberOfSteps:
+ This key indicates the maximum number of iterations allowed for iterative
+ optimization. The default is 15000, which very similar to no limit on
+ iterations. It is then recommended to adapt this parameter to the needs on
+ real problems. For some algorithms, the effective stopping step can be
+ slightly different due to algorihtm internal control requirements.
+
+ :ProjectedGradientTolerance:
+ This key indicates a limit value, leading to stop successfully the
+ iterative optimization process when all the components of the projected
+ gradient are under this limit. It is only used for constrained algorithms.
+
+ :GradientNormTolerance:
+ This key indicates a limit value, leading to stop successfully the
+ iterative optimization process when the norm of the gradient is under this
+ limit. It is only used for non-constrained algorithms.
+
+:"NonLinearLeastSquares":
+
+ :Minimizer:
+ 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).
+
+ :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
+ there is no bound. The bounds can always be specified, but they are taken
+ into account only by the constrained minimizers.
+
+ :MaximumNumberOfSteps:
+ This key indicates the maximum number of iterations allowed for iterative
+ optimization. The default is 15000, which very similar to no limit on
+ iterations. It is then recommended to adapt this parameter to the needs on
+ real problems. For some algorithms, the effective stopping step can be
+ slightly different due to algorihtm internal control requirements.
+
+ :ProjectedGradientTolerance:
+ This key indicates a limit value, leading to stop successfully the
+ iterative optimization process when all the components of the projected
+ gradient are under this limit. It is only used for constrained algorithms.
+
+ :GradientNormTolerance:
+ This key indicates a limit value, leading to stop successfully the
+ iterative optimization process when the norm of the gradient is under this
+ limit. It is only used for non-constrained algorithms.
+
+:"EnsembleBlue":
+ no option
+
+:"KalmanFilter":
+ no option
+
Examples of using these commands are available in the section
-:ref:`section_examples` and in examples files installed with ADAO module.
+:ref:`section_examples` and in example files installed with ADAO module.
-.. [#] For more information on EFICAS, see the the *EFICAS User Guide* available in the main "*Help*" menu of SALOME GUI.
+.. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
-.. [#] For more information on YACS, see the the *YACS User 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 GUI.
.. [#] This intermediary python file can be safely removed after YACS export, but can also be used as described in the section :ref:`section_advanced`.
-
-.. [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
