2 Copyright (C) 2008-2018 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, following :ref:`section_methodology`. These
63 data can already be available in SALOME or not.
65 Basically, the procedure of using ADAO involves the following steps:
67 - :ref:`section_u_step1`
68 - :ref:`section_u_step2`
69 - :ref:`section_u_step3`
70 - :ref:`section_u_step4`
71 - :ref:`section_u_step5`
73 Each step will be detailed in the next section.
75 Detailed procedure to build an ADAO case
76 ----------------------------------------
80 STEP 1: Activate the ADAO module and use the editor GUI
81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
83 As always for a module, it has to be activated by choosing the appropriate
84 module button (or the menu) in the toolbar of SALOME. If there is no SALOME
85 study loaded, a popup appears, allowing to choose between creating a new study,
86 or opening an already existing one:
89 .. image:: images/adao_activate.png
92 **Activating the module ADAO in SALOME**
94 Choosing the "*New*" button, an embedded case editor [#]_ will be opened, along
95 with the standard "*Object browser*". You can then click on the "*New*" button
96 |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to create a
97 new ADAO case, and you will see:
100 .. image:: images/adao_viewer.png
104 **The embedded editor for cases definition in module ADAO**
108 STEP 2: Build and modify the ADAO case, and save it
109 +++++++++++++++++++++++++++++++++++++++++++++++++++
111 To build a case using the embedded editor, you have to go through a series of
112 sub-steps, by selecting, at each sub-step, a keyword and then filling in its
113 value. It is noted that it is in this step that is needed, among other things,
114 to define the call to the simulation code used in observation or evolution
115 operators describing the problem [#]_.
117 The structured editor indicates hierarchical types, values or keywords allowed.
118 Incomplete or incorrect keywords are identified by a visual error red flag.
119 Possible values are indicated for keywords defined with a limited list of
120 values, and adapted entries are given for the other keywords. Some help messages
121 are contextually provided in the editor reserved places.
123 A new case is set up with the minimal list of commands. All the mandatory
124 commands or keywords are already present, none of them can be suppressed.
125 Optional keywords can be added by choosing them in a list of suggestions of
126 allowed ones for the main command, for example the "*ASSIMILATION_STUDY*"
127 command. As an example, one can add parameters in the "*AlgorithmParameters*"
128 keyword, as described in the last part of the section :ref:`section_examples`.
130 At the end, when all fields or keywords have been correctly defined, each line
131 of the commands tree must have a green flag. This indicates that the whole case
132 is valid and completed (and can be saved).
134 .. _adao_jdcexample00:
135 .. image:: images/adao_jdcexample01.png
139 **Example of a valid ADAO case**
141 Finally, you have to save your ADAO case by pushing the "*Save*" button
142 |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the
143 "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location
144 in your file tree and a name, that will be completed by a "*.comm*" extension
145 used for the embedded case editor. This will generate a pair of files describing
146 the ADAO case, with the same base name, the first one being completed by a
147 "*.comm*" extension and the second one by a "*.py*" extension [#]_.
151 STEP 3: Export the ADAO case as a YACS scheme
152 +++++++++++++++++++++++++++++++++++++++++++++
154 When the ADAO case is completed, you have to export it as a YACS scheme in order
155 to execute the data assimilation calculation. This can be easily done by using
156 the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the "*Export
157 to YACS*" entry in the "*ADAO*" main menu, or in the contextual case menu in the
158 SALOME object browser.
160 .. _adao_exporttoyacs01:
161 .. image:: images/adao_exporttoyacs.png
165 **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
167 This will lead to automatically generate a YACS scheme, and open the YACS module
168 on this scheme. The YACS file, associated with the scheme, will be stored in the
169 same directory and with the same base name as the ADAO saved case, only changing
170 its extension to "*.xml*". Be careful, *if the XML file name already exist, the
171 file will be overwritten without prompting for replacing the XML file*.
175 STEP 4: Supplement and modify the YACS scheme, and save it
176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
178 .. index:: single: Analysis
180 When the YACS scheme is generated and opened in SALOME through the YACS module
181 GUI, you can modify or supplement the scheme like any standard YACS scheme.
182 Nodes or blocs can be added, copied or modified to elaborate complex analysis,
183 or to insert data assimilation or optimization capabilities into more complex
184 YACS calculation schemes. It is recommended to save the modified scheme with a
185 new name, in order to preserve the XML file in the case you re-export the ADAO
188 The main supplement needed in the YACS scheme is a post-processing step. The
189 evaluation of the results has to be done in the physical context of the
190 simulation used by the data assimilation procedure. The post-processing can be
191 provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
192 by templates, or can be build as YACS nodes. These two ways of building the
193 post-processing can use all the SALOME possibilities. See the part describing
194 :ref:`section_ref_output_variables`, or the help for each algorithm, for the
195 full description of these elements.
197 In practice, the YACS scheme has an "*algoResults*" output port of the
198 computation bloc, which gives access to a structured object named hereafter
199 "*ADD*" for example, containing all the calculation results. These results can
200 be obtained by retrieving the named variables stored along the calculation. The
201 main information is the "*Analysis*" one, that can be obtained by the python
202 command (for example in an in-line script node or a script provided through the
203 "*UserPostAnalysis*" keyword)::
205 Analysis = ADD.get("Analysis")[:]
207 "*Analysis*" is a complex object, similar to a list of values calculated at each
208 step of data assimilation calculation. In order to get and print the optimal
209 data assimilation state evaluation, in a script provided through the
210 "*UserPostAnalysis*" keyword, one can use::
212 Xa = ADD.get("Analysis")[-1]
213 print "Optimal state:", Xa
216 This ``Xa`` variable is a vector of values, that represents the solution of the
217 data assimilation or optimization evaluation problem, noted as
218 :math:`\mathbf{x}^a` in the section :ref:`section_theory`.
220 Such method can be used to print results, or to convert these ones to
221 structures that can be used in the native or external SALOME post-processing. A
222 simple example is given in the section :ref:`section_examples`.
226 STEP 5: Execute the YACS case and obtain the results
227 ++++++++++++++++++++++++++++++++++++++++++++++++++++
229 The YACS scheme is now complete and can be executed. Parametrization and
230 execution of this YACS case is fully compliant with the standard way to deal
231 with a YACS scheme, as described in the *YACS module User's Guide*.
233 To recall the simplest way to proceed, the YACS scheme has to be compiled using
234 the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
235 scheme to run. Then the compiled scheme can be started, executed step by step or
236 using breakpoints, etc.
238 The standard output will be pushed into the "*YACS Container Log*", obtained
239 through the right click menu of the "*proc*" window in the YACS GUI. The errors
240 are shown either in the "*YACS Container Log*", or at the command line in the
241 terminal window (if SALOME has been launched by its explicit command, and not by
242 a menu or a desktop icon). As an example, the output of the above simple case is
243 of the following form::
245 Entering in the assimilation study
246 Name is set to........: Test
247 Algorithm is set to...: Blue
248 Launching the analysis
250 Optimal state: [0.5, 0.5, 0.5]
252 shown in the "*YACS Container Log*".
254 The execution can also be done using a Shell script, as described in the section
255 :ref:`section_advanced`.
257 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.
259 .. [#] 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.
261 .. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts.
263 .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.
