3 ================================================================================
5 ================================================================================
7 .. |eficas_new| image:: images/eficas_new.png
9 .. |eficas_save| image:: images/eficas_save.png
11 .. |eficas_yacs| image:: images/eficas_yacs.png
14 This section presents the usage of the ADAO module in SALOME. It is complemented
15 by advanced usage procedures the section :ref:`section_advanced`, and by
16 examples in the section :ref:`section_examples`.
18 Logical procedure to build an ADAO test case
19 --------------------------------------------
21 The construction of an ADAO case follows a simple approach to define the set of
22 input data, either static or dynamic data, and then generates a complete block
23 diagram used in YACS. Many variations exist for the definition of input data,
24 but the logical sequence remains unchanged.
26 First of all, the user is considered to know the input data needed to set up the
27 data assimilation study. These data can be in SALOME or not.
29 **Basically, the procedure of using ADAO involves the following steps:**
31 #. **Activate the ADAO module and use the editor GUI,**
32 #. **Build and modify the ADAO case and save it,**
33 #. **Export the ADAO case as a YACS scheme,**
34 #. **Modify and supplement the YACS scheme and save it,**
35 #. **Execute the YACS case and obtain the results.**
37 Each step will be detailed in the next section.
39 Detailed procedure to build an ADAO test case
40 ---------------------------------------------
42 Activate the ADAO module and use the editor GUI
43 +++++++++++++++++++++++++++++++++++++++++++++++
45 As always for a module, it has to be activated by choosing the appropriate
46 module button (or menu) in the toolbar of SALOME. If there is no study loaded, a
47 popup appears, allowing to choose between creating a new study, or opening an
51 .. image:: images/adao_activate.png
54 **Activating the module ADAO in SALOME**
56 Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
57 along with the standard "*Object browser*". You can then click on the "*New*"
58 button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
59 create a new ADAO case, and you will see:
62 .. image:: images/adao_viewer.png
66 **The EFICAS editor for cases definition in module ADAO**
68 It is a good habit to save the ADAO case now, by pushing the "*Save*" button
69 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
70 You will be prompted for a location in your file tree and a name, that will be
71 completed by a "*.comm*" extension used for JDC EFICAS files.
73 Build and modify the ADAO case and save it
74 ++++++++++++++++++++++++++++++++++++++++++
76 To build a case using EFICAS, you have to go through a series of steps, by
77 selecting a keyword and then filling in its value.
79 The structured editor indicates hierarchical types, values or keywords allowed.
80 Incomplete or incorrect keywords are identified by a visual error red flag.
81 Possible values are indicated for keywords defined with a limited list of
82 values, and adapted entries are given for the other keywords. All the mandatory
83 command or keyword are already present, and optionnal commands can be added.
85 A new case is set up with the minimal list of commands. No mandatory command can
86 be suppressed, but others can be added as allowed keywords for an
87 "*ASSIMILATION_STUDY*" command. As an example, one can add an
88 "*AlgorithmParameters*" keyword, as described in the last part of the section
89 :ref:`section_examples`.
91 At the end, when all fields or keywords have been correctly defined, each line
92 of the commands tree must have a green flag. This indicates that the whole case
93 is valid and completed.
95 .. _adao_jdcexample00:
96 .. image:: images/adao_jdcexample01.png
100 **Example of a valid ADAO case**
102 Finally, you have to save your ADAO case by pushing the "*Save*" button
103 |eficas_save| or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu.
105 Export the ADAO case as a YACS scheme
106 +++++++++++++++++++++++++++++++++++++
108 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
109 order to execute the data assimilation calculation. This can be easily done by
110 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
111 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
112 menu in the object browser.
114 .. _adao_exporttoyacs01:
115 .. image:: images/adao_exporttoyacs.png
119 **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
121 This will lead to automatically generate an XML file for the YACS scheme, and
122 open YACS module on this file. The YACS file will be stored in the same
123 directory and with the same name as the ADAO saved case, only changing its
124 extension from "*.comm*" to "*.xml*". *Be careful, if the name already exist, it
125 will overwrite it without prompting for replacing the file*. In the same time,
126 an intermediary python file is also stored in the same place, with a "*.py*"
127 extension replacing the "*.comm*" one [#]_.
129 Modify and supplement the YACS scheme and save it
130 +++++++++++++++++++++++++++++++++++++++++++++++++
132 When the YACS scheme is generated and opened in SALOME through the YACS module
133 GUI, you can modify or supplement the scheme like any YACS scheme. It is
134 recommended to save the modified scheme with a new name, in order to preserve in
135 the case you re-export to YACS the ADAO case.
137 The main supplement needed in the YACS scheme is a postprocessing step. The
138 evaluation of the results has to be done in the physical context of the
139 simulation used by the data assimilation procedure.
141 The YACS scheme has an "*algoResults*" output port of the computation bloc,
142 which gives access to a "*pyobj*" containing all the results. These results can
143 be obtained by retrieving the named variables stored along the calculation. The
144 main is the "*Analysis*" one, that can be obtained by the python command (for
145 example in an in-line script node)::
147 Analysis = results.ADD.get("Analysis").valueserie(-1)
149 This is a complex object, similar to a list of values calculated at each step of
150 data assimilation calculation. In order to get the last data assimilation
151 analysis, one can use::
153 Xa = results.ADD.get("Analysis").valueserie(-1)
155 This ``Xa`` is a vector of values, that represents the solution of the data
156 assimilation evaluation problem, noted as :math:`\mathbf{x}^a` in the section
157 :ref:`section_theory`.
159 Such command can be used to print results, or to convert these ones to
160 structures that can be used in the native or external SALOME postprocessing. A
161 simple example is given in the section :ref:`section_examples`.
163 Execute the YACS case and obtain the results
164 ++++++++++++++++++++++++++++++++++++++++++++
166 The YACS scheme is now complete and can be executed. Parametrisation and
167 execution of a YACS case is fully compliant with the standard way to deal with a
168 YACS scheme, and is described in the *YACS module User's Guide*.
170 Results can be obtained, through the "*algoResults*" output port, using YACS
171 nodes to retrieve all the informations in the "*pyobj*" object, to transform
172 them, to convert them, to save part of them, etc.
174 The data assimilation results and complementary calculations can be retrieved
175 using the "*get*" method af the "*algoResults.ADD*" object. This method pick the
176 different output variables identified by their name. Indicating in parenthesis
177 their availability as automatic (for every algorithm) or optional (depending on
178 the algorithm), and their notation coming from section :ref:`section_theory`,
179 the main available output variables are the following:
181 #. "Analysis" (automatic): the control state evaluated by the data assimilation
182 procedure, noted as :math:`\mathbf{x}^a`.
183 #. "Innovation" (automatic): the difference between the observations and the
184 control state transformed by the observation operator, noted as
185 :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^b`.
186 #. "APosterioriCovariance" (optional): the covariance matrix of the *a
187 posteriori* analysis errors, noted as :math:`\mathbf{A}`.
188 #. "OMB" (optional): the difference between the observations and the
189 background, similar to the innovation.
190 #. "BMA" (optional): the difference between the background and the analysis,
191 noted as :math:`\mathbf{x}^b - \mathbf{x}^a`.
192 #. "OMA" (optional): the difference between the observations and the analysis,
193 noted as :math:`\mathbf{y}^o - \mathbf{H}\mathbf{x}^a`.
194 #. "CostFunctionJ" (optional): the minimisation function, noted as :math:`J`.
195 #. "CostFunctionJo" (optional): the observation part of the minimisation
196 function, noted as :math:`J^o`.
197 #. "CostFunctionJb" (optional): the background part of the minimisation
198 function, noted as :math:`J^b`.
200 Input variables are also available as output in order to gather all the
201 information at the end of the procedure.
203 All the variables are list of typed values, each item of the list
204 corresponding to the value of the variable at a time step or an iteration step
205 in the data assimilation optimization procedure. The variable value at a given
206 "*i*" step can be obtained by the method "*valueserie(i)*". The last one
207 (consisting in the solution of the evaluation problem) can be obtained using the
208 step "*-1*" as in a standard list.
210 Reference description of the commands and keywords available through the GUI
211 -----------------------------------------------------------------------------
213 Each command or keyword to be defined through the ADAO GUI has some properties.
214 The first property is to be a required command, an optional command or a keyword
215 describing a type of input. The second property is to be an "open" variable with
216 a fixed type but with any value allowed by the type, or a "restricted" variable,
217 limited to some specified values. The mathematical notations used afterwards are
218 explained in the section :ref:`section_theory`.
220 List of possible input types
221 ++++++++++++++++++++++++++++
223 The different type-style commands are:
226 *Type of an input*. This indicates a variable that has to be filled by a
227 dictionary, usually given as a script.
230 *Type of an input*. This indicates a variable that has to be filled by a
231 function, usually given as a script.
234 *Type of an input*. This indicates a variable that has to be filled by a
235 matrix, usually given either as a string or as a script.
238 *Type of an input*. This indicates a string, such as a name or a literal
239 representation of a matrix or vector, such as "1 2 ; 3 4".
242 *Type of an input*. This indicates a script given as an external file.
245 *Type of an input*. This indicates a variable that has to be filled by a
246 vector, usually given either as a string or as a script.
251 The different commands are the following:
254 *Required command*. This is the general command describing an ADAO case. It
255 hierarchicaly contains all the other commands.
258 *Required command*. This is a string to indicates the data assimilation
259 algorithm chosen. The choices are limited and available through the GUI.
260 There exists for example: "3DVAR", "Blue"... See below the list of
261 algorithms and associated parameters.
263 :AlgorithmParameters:
264 *Optional command*. This command allows to add some optional parameters to
265 control the data assimilation algorithm calculation. It is defined as a
266 "*Dict*" type object. See below the list of algorithms and associated
270 *Required command*. This indicates the backgroud vector used for data
271 assimilation, previously noted as :math:`\mathbf{x}^b`. It is defined as a
272 "*Vector*" type object, that is, given either as a string or as a script.
275 *Required command*. This indicates the backgroud error covariance matrix,
276 previously noted as :math:`\mathbf{B}`.It is defined as a "*Matrix*" type
277 object, that is, given either as a string or as a script.
280 *Required command*. This let choose the level of trace and intermediary
281 debug informations. The choices are limited between 0 (for False) and 1 (for
282 True) and available through the GUI.
285 *Optional command*. This command allows to indicates the name and size of
286 physical variables that are bundled together in the control vector. This
287 information is dedicated to data processed inside of data assimilation
291 *Required command*. This indicates the observation vector used for data
292 assimilation, previously noted as :math:`\mathbf{y}^o`. It is defined as a
293 "*Vector*" type object, that is, given either as a string or as a script.
296 *Required command*. This indicates the observation error covariance matrix,
297 previously noted as :math:`\mathbf{R}`.It is defined as a "*Matrix*" type
298 object, that is, given either as a string or as a script.
300 :ObservationOperator:
301 *Required command*. This indicates the observation operator, previously
302 noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}`
303 to results :math:`\mathbf{y}` to be compared to observations
304 :math:`\mathbf{y}^o`.
307 *Optional command*. This command allows to set internal observers, that are
308 functions linked with a particular variable, which will be executed each
309 time this variable is modified. It is a convenient way to monitor interest
310 variables during the data assimilation process, by printing or plotting it,
314 *Optional command*. This command allows to indicates the name and size of
315 physical variables that are bundled together in the output observation
316 vector. This information is dedicated to data processed inside of data
317 assimilation algorithm.
320 *Required command*. This is an open string to describe the study by a name
324 *Optional command*. If available, this repertory is used to find all the
325 script files that can be used to define some other commands by scripts.
328 *Optional command*. This commands allows to initialise some parameters or
329 data automatically before data assimilation algorithm processing.
332 *Optional command*. This commands allows to process some parameters or data
333 automatically after data assimilation algorithm processing. It is defined as
334 a script or a string, allowing to put simple code directly inside the ADAO
337 .. _subsection_algo_options:
339 List of possible options for the algorithms
340 +++++++++++++++++++++++++++++++++++++++++++
342 Each algorithm can be controled using some generic or specific options given
343 throught the "*AlgorithmParameters*" optional command, as follows::
345 AlgorithmParameters = {
347 "MaximumNumberOfSteps" : 10,
350 This section describes the available options by algorithm. If an option is
351 specified for an algorithm that doesn't support it, the option is simply left
356 :CalculateAPosterioriCovariance:
357 This boolean key allows to enable the calculation and the storage of the
358 covariance matrix of a posteriori anlysis errors. Be careful, this is a
359 numericaly costly step. The default is "False".
361 :"LinearLeastSquares":
367 This key allows to choose the optimization minimizer. The default choice
368 is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
369 minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear constrained
370 minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
371 unconstrained minimizer), "NCG" (Newton CG minimizer).
374 This key allows to define upper and lower bounds for every control
375 variable being optimized. Bounds can be given by a list of list of pairs
376 of lower/upper bounds for each variable, with possibly ``None`` every time
377 there is no bound. The bounds can always be specified, but they are taken
378 into account only by the constrained minimizers.
380 :MaximumNumberOfSteps:
381 This key indicates the maximum number of iterations allowed for iterative
382 optimization. The default is 15000, which very similar to no limit on
383 iterations. It is then recommended to adapt this parameter to the needs on
384 real problems. For some algorithms, the effective stopping step can be
385 slightly different due to algorihtm internal control requirements.
387 :CalculateAPosterioriCovariance:
388 This boolean key allows to enable the calculation and the storage of the
389 covariance matrix of a posteriori anlysis errors. Be careful, this is a
390 numericaly costly step. The default is "False".
392 :CostDecrementTolerance:
393 This key indicates a limit value, leading to stop successfully the
394 iterative optimization process when the cost function decreases less than
395 this tolerance at the last step. The default is 10e-7, and it is
396 recommended to adapt it the needs on real problems.
398 :ProjectedGradientTolerance:
399 This key indicates a limit value, leading to stop successfully the
400 iterative optimization process when all the components of the projected
401 gradient are under this limit. It is only used for constrained algorithms.
402 The default is -1, that is the internal default of each algorithm, and it
403 is not recommended to change it.
405 :GradientNormTolerance:
406 This key indicates a limit value, leading to stop successfully the
407 iterative optimization process when the norm of the gradient is under this
408 limit. It is only used for non-constrained algorithms. The default is
409 10e-5 and it is not recommended to change it.
411 :"NonLinearLeastSquares":
414 This key allows to choose the optimization minimizer. The default choice
415 is "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained
416 minimizer, see [Byrd95] and [Zhu97]), "TNC" (nonlinear constrained
417 minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" (nonlinear
418 unconstrained minimizer), "NCG" (Newton CG minimizer).
421 This key allows to define upper and lower bounds for every control
422 variable being optimized. Bounds can be given by a list of list of pairs
423 of lower/upper bounds for each variable, with possibly ``None`` every time
424 there is no bound. The bounds can always be specified, but they are taken
425 into account only by the constrained minimizers.
427 :MaximumNumberOfSteps:
428 This key indicates the maximum number of iterations allowed for iterative
429 optimization. The default is 15000, which very similar to no limit on
430 iterations. It is then recommended to adapt this parameter to the needs on
431 real problems. For some algorithms, the effective stopping step can be
432 slightly different due to algorihtm internal control requirements.
434 :CostDecrementTolerance:
435 This key indicates a limit value, leading to stop successfully the
436 iterative optimization process when the cost function decreases less than
437 this tolerance at the last step. The default is 10e-7, and it is
438 recommended to adapt it the needs on real problems.
440 :ProjectedGradientTolerance:
441 This key indicates a limit value, leading to stop successfully the
442 iterative optimization process when all the components of the projected
443 gradient are under this limit. It is only used for constrained algorithms.
444 The default is -1, that is the internal default of each algorithm, and it
445 is not recommended to change it.
447 :GradientNormTolerance:
448 This key indicates a limit value, leading to stop successfully the
449 iterative optimization process when the norm of the gradient is under this
450 limit. It is only used for non-constrained algorithms. The default is
451 10e-5 and it is not recommended to change it.
456 This key allow to give an integer in order to fix the seed of the random
457 generator used to generate the ensemble. A convenient value is for example
458 1000. By default, the seed is left uninitialized, and so use the default
459 initialization from the computer.
463 :CalculateAPosterioriCovariance:
464 This boolean key allows to enable the calculation and the storage of the
465 covariance matrix of a posteriori anlysis errors. Be careful, this is a
466 numericaly costly step. The default is "False".
468 Examples of using these commands are available in the section
469 :ref:`section_examples` and in example files installed with ADAO module.
471 .. [#] For more information on EFICAS, see the *EFICAS module* available in SALOME GUI.
473 .. [#] For more information on YACS, see the *YACS module User's Guide* available in the main "*Help*" menu of SALOME GUI.
475 .. [#] This intermediary python file can be safely removed after YACS export, but can also be used as described in the section :ref:`section_advanced`.