2 Copyright (C) 2008-2015 EDF R&D
4 This file is part of SALOME ADAO module.
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
26 ================================================================================
27 **[DocU]** Using the ADAO module
28 ================================================================================
30 .. |eficas_new| image:: images/eficas_new.png
33 .. |eficas_save| image:: images/eficas_save.png
36 .. |eficas_saveas| image:: images/eficas_saveas.png
39 .. |eficas_yacs| image:: images/eficas_yacs.png
42 .. |yacs_compile| image:: images/yacs_compile.png
46 This section presents the usage of the ADAO module in SALOME platform. Here we
47 describe the general progression to establish an ADAO case, the details being
48 given in the following chapters. It is completed by the detailed description of
49 all the commands and keywords in the section :ref:`section_reference`, by
50 advanced usage procedures in the section :ref:`section_advanced`, and by
51 examples in the section :ref:`section_examples`.
53 Logical procedure to build an ADAO case
54 ---------------------------------------
56 The construction of an ADAO case follows a simple approach to define the set of
57 input data, and then generates a complete executable block diagram used in YACS
58 [#]_. Many variations exist for the definition of input data, but the logical
59 sequence remains unchanged.
61 First of all, the user is considered to know its personal input data needed to
62 set up the data assimilation study. These data can already be available in
65 **Basically, the procedure of using ADAO involves the following steps:**
67 #. **Activate the ADAO module and use the editor GUI,**
68 #. **Build and/or modify the ADAO case, and save it,**
69 #. **Export the ADAO case as a YACS scheme,**
70 #. **Supplement and modify the YACS scheme, and save it,**
71 #. **Execute the YACS case and obtain the results.**
73 Each step will be detailed in the next section.
77 STEP 1: Activate the ADAO module and use the editor GUI
78 -------------------------------------------------------
80 As always for a module, it has to be activated by choosing the appropriate
81 module button (or the menu) in the toolbar of SALOME. If there is no SALOME
82 study loaded, a popup appears, allowing to choose between creating a new study,
83 or opening an already existing one:
86 .. image:: images/adao_activate.png
89 **Activating the module ADAO in SALOME**
91 Choosing the "*New*" button, an embedded case editor [#]_ will be opened, along
92 with the standard "*Object browser*". You can then click on the "*New*" button
93 |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to create a
94 new ADAO case, and you will see:
97 .. image:: images/adao_viewer.png
101 **The embedded editor for cases definition in module ADAO**
105 STEP 2: Build and modify the ADAO case, and save it
106 ---------------------------------------------------
108 To build a case using the embedded editor, you have to go through a series of
109 sub-steps, by selecting, at each sub-step, a keyword and then filling in its
110 value. It is noted that it is in this step that is needed, among other things,
111 to define the call to the simulation code used in observation or evolution
112 operators describing the problem [#]_.
114 The structured editor indicates hierarchical types, values or keywords allowed.
115 Incomplete or incorrect keywords are identified by a visual error red flag.
116 Possible values are indicated for keywords defined with a limited list of
117 values, and adapted entries are given for the other keywords. Some help messages
118 are contextually provided in the editor reserved places.
120 A new case is set up with the minimal list of commands. All the mandatory
121 commands or keywords are already present, none of them can be suppressed.
122 Optional keywords can be added by choosing them in a list of suggestions of
123 allowed ones for the main command, for example the "*ASSIMILATION_STUDY*"
124 command. As an example, one can add parameters in the "*AlgorithmParameters*"
125 keyword, as described in the last part of the section :ref:`section_examples`.
127 At the end, when all fields or keywords have been correctly defined, each line
128 of the commands tree must have a green flag. This indicates that the whole case
129 is valid and completed (and can be saved).
131 .. _adao_jdcexample00:
132 .. image:: images/adao_jdcexample01.png
136 **Example of a valid ADAO case**
138 Finally, you have to save your ADAO case by pushing the "*Save*" button
139 |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the
140 "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location
141 in your file tree and a name, that will be completed by a "*.comm*" extension
142 used for the embedded case editor. This will generate a pair of files describing
143 the ADAO case, with the same base name, the first one being completed by a
144 "*.comm*" extension and the second one by a "*.py*" extension [#]_.
148 STEP 3: Export the ADAO case as a YACS scheme
149 ---------------------------------------------
151 When the ADAO case is completed, you have to export it as a YACS scheme in order
152 to execute the data assimilation calculation. This can be easily done by using
153 the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the "*Export
154 to YACS*" entry in the "*ADAO*" main menu, or in the contextual case menu in the
155 SALOME object browser.
157 .. _adao_exporttoyacs01:
158 .. image:: images/adao_exporttoyacs.png
162 **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
164 This will lead to automatically generate a YACS scheme, and open the YACS module
165 on this scheme. The YACS file, associated with the scheme, will be stored in the
166 same directory and with the same base name as the ADAO saved case, only changing
167 its extension to "*.xml*". Be careful, *if the XML file name already exist, the
168 file will be overwritten without prompting for replacing the XML file*.
172 STEP 4: Supplement and modify the YACS scheme, and save it
173 ----------------------------------------------------------
175 .. index:: single: Analysis
177 When the YACS scheme is generated and opened in SALOME through the YACS module
178 GUI, you can modify or supplement the scheme like any standard YACS scheme.
179 Nodes or blocs can be added, copied or modified to elaborate complex analysis,
180 or to insert data assimilation or optimization capabilities into more complex
181 YACS calculation schemes. It is recommended to save the modified scheme with a
182 new name, in order to preserve the XML file in the case you re-export the ADAO
185 The main supplement needed in the YACS scheme is a post-processing step. The
186 evaluation of the results has to be done in the physical context of the
187 simulation used by the data assimilation procedure. The post-processing can be
188 provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
189 by templates, or can be build as YACS nodes. These two ways of building the
190 post-processing can use all the SALOME possibilities. See the part describing
191 :ref:`section_ref_output_variables`, or the help for each algorithm, for the
192 full description of these elements.
194 In practice, the YACS scheme has an "*algoResults*" output port of the
195 computation bloc, which gives access to a structured object named hereafter
196 "*ADD*" for example, containing all the calculation results. These results can
197 be obtained by retrieving the named variables stored along the calculation. The
198 main information is the "*Analysis*" one, that can be obtained by the python
199 command (for example in an in-line script node or a script provided through the
200 "*UserPostAnalysis*" keyword)::
202 Analysis = ADD.get("Analysis")[:]
204 "*Analysis*" is a complex object, similar to a list of values calculated at each
205 step of data assimilation calculation. In order to get and print the optimal
206 data assimilation state evaluation, in a script provided through the
207 "*UserPostAnalysis*" keyword, one can use::
209 Xa = ADD.get("Analysis")[-1]
210 print "Optimal state:", Xa
213 This ``Xa`` variable is a vector of values, that represents the solution of the
214 data assimilation or optimization evaluation problem, noted as
215 :math:`\mathbf{x}^a` in the section :ref:`section_theory`.
217 Such method can be used to print results, or to convert these ones to
218 structures that can be used in the native or external SALOME post-processing. A
219 simple example is given in the section :ref:`section_examples`.
223 STEP 5: Execute the YACS case and obtain the results
224 ----------------------------------------------------
226 The YACS scheme is now complete and can be executed. Parametrization and
227 execution of this YACS case is fully compliant with the standard way to deal
228 with a YACS scheme, as described in the *YACS module User's Guide*.
230 To recall the simplest way to proceed, the YACS scheme has to be compiled using
231 the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
232 scheme to run. Then the compiled scheme can be started, executed step by step or
233 using breakpoints, etc.
235 The standard output will be pushed into the "*YACS Container Log*", obtained
236 through the right click menu of the "*proc*" window in the YACS GUI. The errors
237 are shown either in the "*YACS Container Log*", or at the command line in the
238 terminal window (if SALOME has been launched by its explicit command, and not by
239 a menu or a desktop icon). As an example, the output of the above simple case is
240 of the following form::
242 Entering in the assimilation study
243 Name is set to........: Test
244 Algorithm is set to...: Blue
245 Launching the analyse
247 Optimal state: [0.5, 0.5, 0.5]
249 shown in the "*YACS Container Log*".
251 The execution can also be done using a Shell script, as described in the section
252 :ref:`section_advanced`.
254 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.
256 .. [#] For more information on the embedded case editor, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform.
258 .. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts.
260 .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.
