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. It is
47 complemented by the detailed description of all the commands and keywords in the
48 section :ref:`section_reference`, by advanced usage procedures in the section
49 :ref:`section_advanced`, and by examples in the section :ref:`section_examples`.
51 Logical procedure to build an ADAO case
52 ---------------------------------------
54 The construction of an ADAO case follows a simple approach to define the set of
55 input data, and then generates a complete executable block diagram used in YACS.
56 Many variations exist for the definition of input data, but the logical sequence
59 First of all, the user is considered to know its personal input data needed to
60 set up the data assimilation study. These data can already be available in
63 **Basically, the procedure of using ADAO involves the following steps:**
65 #. **Activate the ADAO module and use the editor GUI,**
66 #. **Build and/or modify the ADAO case, and save it,**
67 #. **Export the ADAO case as a YACS scheme,**
68 #. **Supplement and modify the YACS scheme, and save it,**
69 #. **Execute the YACS case and obtain the results.**
71 Each step will be detailed in the next section.
75 STEP 1: Activate the ADAO module and use the editor GUI
76 -------------------------------------------------------
78 As always for a module, it has to be activated by choosing the appropriate
79 module button (or the menu) in the toolbar of SALOME. If there is no SALOME
80 study loaded, a popup appears, allowing to choose between creating a new study,
81 or opening an already existing one:
84 .. image:: images/adao_activate.png
87 **Activating the module ADAO in SALOME**
89 Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened,
90 along with the standard "*Object browser*". You can then click on the "*New*"
91 button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to
92 create a new ADAO case, and you will see:
95 .. image:: images/adao_viewer.png
99 **The EFICAS editor for cases definition in module ADAO**
103 STEP 2: Build and modify the ADAO case, and save it
104 ---------------------------------------------------
106 To build a case using EFICAS, you have to go through a series of sub-steps, by
107 selecting, at each sub-step, a keyword and then filling in its value. It is
108 noted that it is in this step that is needed, among other things, to define the
109 call to the simulation code used in observation or evolution operators
110 describing the problem [#]_.
112 The structured editor indicates hierarchical types, values or keywords allowed.
113 Incomplete or incorrect keywords are identified by a visual error red flag.
114 Possible values are indicated for keywords defined with a limited list of
115 values, and adapted entries are given for the other keywords. Some help messages
116 are contextually provided in the editor reserved places.
118 A new case is set up with the minimal list of commands. All the mandatory
119 commands or keywords are already present, none of them can be suppressed.
120 Optional keywords can be added by choosing them in a list of suggestions of
121 allowed ones for the main command, for example the "*ASSIMILATION_STUDY*"
122 command. As an example, one can add parameters in the "*AlgorithmParameters*"
123 keyword, as described in the last part of the section :ref:`section_examples`.
125 At the end, when all fields or keywords have been correctly defined, each line
126 of the commands tree must have a green flag. This indicates that the whole case
127 is valid and completed (and can be saved).
129 .. _adao_jdcexample00:
130 .. image:: images/adao_jdcexample01.png
134 **Example of a valid ADAO case**
136 Finally, you have to save your ADAO case by pushing the "*Save*" button
137 |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the
138 "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location
139 in your file tree and a name, that will be completed by a "*.comm*" extension
140 used for JDC EFICAS files. This will generate a pair of files describing the
141 ADAO case, with the same base name, the first one being completed by a "*.comm*"
142 extension and the second one by a "*.py*" extension [#]_.
146 STEP 3: Export the ADAO case as a YACS scheme
147 ---------------------------------------------
149 When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in
150 order to execute the data assimilation calculation. This can be easily done by
151 using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the
152 "*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case
153 menu in the SALOME object browser.
155 .. _adao_exporttoyacs01:
156 .. image:: images/adao_exporttoyacs.png
160 **"Export to YACS" sub-menu to generate the YACS scheme from the ADAO case**
162 This will lead to automatically generate a YACS scheme, and open the YACS module
163 on this scheme. The YACS file, associated with the scheme, will be stored in the
164 same directory and with the same base name as the ADAO saved case, only changing
165 its extension to "*.xml*". Be careful, *if the XML file name already exist, the
166 file will be overwritten without prompting for replacing the XML file*.
170 STEP 4: Supplement and modify the YACS scheme, and save it
171 ----------------------------------------------------------
173 .. index:: single: Analysis
175 When the YACS scheme is generated and opened in SALOME through the YACS module
176 GUI, you can modify or supplement the scheme like any standard YACS scheme.
177 Nodes or blocs can be added, copied or modified to elaborate complex analysis,
178 or to insert data assimilation or optimization capabilities into more complex
179 YACS calculation schemes. It is recommended to save the modified scheme with a
180 new name, in order to preserve the XML file in the case you re-export the ADAO
183 The main supplement needed in the YACS scheme is a post-processing step. The
184 evaluation of the results has to be done in the physical context of the
185 simulation used by the data assimilation procedure. The post-processing can be
186 provided through the "*UserPostAnalysis*" ADAO keyword as a script or a string,
187 by templates, or can be build as YACS nodes. These two ways of building the
188 post-processing can use all the SALOME possibilities. See the part describing
189 :ref:`section_ref_output_variables`, or the help for each algorithm, for the
190 full description of these elements.
192 In practice, the YACS scheme has an "*algoResults*" output port of the
193 computation bloc, which gives access to an object of type "*pyobj*" named
194 hereafter "*ADD*", containing all the calculation results. These results can be
195 obtained by retrieving the named variables stored along the calculation. The
196 main information is the "*Analysis*" one, that can be obtained by the python
197 command (for example in an in-line script node or a script provided through the
198 "*UserPostAnalysis*" keyword)::
200 Analysis = ADD.get("Analysis")[:]
202 "*Analysis*" is a complex object, similar to a list of values calculated at each
203 step of data assimilation calculation. In order to get and print the optimal
204 data assimilation state evaluation, in a script provided through the
205 "*UserPostAnalysis*" keyword, one can use::
207 Xa = ADD.get("Analysis")[-1]
208 print "Optimal state:", Xa
211 This ``Xa`` variable is a vector of values, that represents the solution of the
212 data assimilation or optimization evaluation problem, noted as
213 :math:`\mathbf{x}^a` in the section :ref:`section_theory`.
215 Such method can be used to print results, or to convert these ones to
216 structures that can be used in the native or external SALOME post-processing. A
217 simple example is given in the section :ref:`section_examples`.
221 STEP 5: Execute the YACS case and obtain the results
222 ----------------------------------------------------
224 The YACS scheme is now complete and can be executed. Parametrization and
225 execution of this YACS case is fully compliant with the standard way to deal
226 with a YACS scheme, as described in the *YACS module User's Guide*.
228 To recall the simplest way to proceed, the YACS scheme has to be compiled using
229 the button |yacs_compile|, or the equivalent YACS menu entry, to prepare the
230 scheme to run. Then the compiled scheme can be started, executed step by step or
231 using breakpoints, etc.
233 The standard output will be pushed into the "*YACS Container Log*", obtained
234 through the right click menu of the "*proc*" window in the YACS GUI. The errors
235 are shown either in the "*YACS Container Log*", or at the command line in the
236 terminal window (if SALOME has been launched by its explicit command, and not by
237 a menu or a desktop icon). As an example, the output of the above simple case is
238 of the following form::
240 Entering in the assimilation study
241 Name is set to........: Test
242 Algorithm is set to...: Blue
243 Launching the analyse
245 Optimal state: [0.5, 0.5, 0.5]
247 shown in the "*YACS Container Log*".
249 The execution can also be done using a Shell script, as described in the section
250 :ref:`section_advanced`.
252 .. [#] For more information on EFICAS, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform.
254 .. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts.
256 .. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform.
258 .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`.
