]> SALOME platform Git repositories - modules/adao.git/blob - doc/en/advanced.rst
Salome HOME
Correcting Bash launching advanced example
[modules/adao.git] / doc / en / advanced.rst
1 ..
2    Copyright (C) 2008-2015 EDF R&D
3
4    This file is part of SALOME ADAO module.
5
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.
10
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.
15
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
19
20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
21
22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
23
24 .. _section_advanced:
25
26 ================================================================================
27 **[DocU]** Advanced usage of the ADAO module
28 ================================================================================
29
30 This section presents advanced methods to use the ADAO module, how to get more
31 information during calculation, or how to use it without the graphical user
32 interface (GUI). It requires to know how to find files or commands included
33 inside the whole SALOME installation. All the names to be replaced by user are
34 indicated by the syntax ``<...>``.
35
36 Converting and executing an ADAO command file (JDC) using a shell script
37 ------------------------------------------------------------------------
38
39 It is possible to convert and execute an ADAO command file (JDC, or ".comm/.py"
40 files pair, which resides in ``<ADAO JDC file directory>``) automatically by
41 using a template shell script containing all the required steps. The user has to
42 know where are the main SALOME launching files, and in particular the
43 ``salome`` one. The directory in which this script resides is symbolically
44 named ``<SALOME main installation dir>`` and has to be replaced by the good one
45 in the shell file template.
46
47 When an ADAO command file is build by the ADAO graphical editor and saved, if
48 it is named for example "AdaoStudy1.comm", then a companion file named
49 "AdaoStudy1.py" is automatically created in the same directory. It is named
50 ``<ADAO Python file>`` in the template, and it is converted to YACS as an
51 ``<ADAO YACS xml scheme>``. After that, it can be executed in console mode using
52 the standard YACS console command (see YACS documentation for more information).
53
54 In the example, we choose to start and stop the SALOME application server in the
55 same script, which is not necessary, but useful to avoid stalling SALOME
56 sessions. We choose also to remove the ``<ADAO YACS xml scheme>`` file because
57 it is a generated one. The user of this script only need to replace the text
58 between these symbols ``<...>``.
59
60 The template of the shell script is the following::
61
62     #!/bin/bash
63     USERDIR=<ADAO JDC file directory>
64     SALOMEDIR=<SALOME main installation directory>
65     $SALOMEDIR/salome start -k -t
66     $SALOMEDIR/salome shell -- "python $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py $USERDIR/<ADAO Python file> $USERDIR/<ADAO YACS xml scheme>"
67     $SALOMEDIR/salome shell -- "driver $USERDIR/<ADAO YACS xml scheme>"
68     $SALOMEDIR/salome shell killSalome.py
69     rm -f $USERDIR/<ADAO YACS xml scheme>
70
71 Standard output and errors come on console.
72
73 Running an ADAO calculation scheme in YACS using a TUI user mode
74 ----------------------------------------------------------------
75
76 This section describes how to execute in TUI (Text User Interface) mode a YACS
77 calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
78 the standard YACS TUI mode, which is briefly recalled here (see YACS
79 documentation for more information) through a simple example. As described in
80 documentation, a XML scheme can be loaded in a Python. We give here a whole
81 sequence of command lines to test the validity of the scheme before executing
82 it, adding some initial supplementary ones to explicitly load the types catalog
83 to avoid weird difficulties::
84
85     import pilot
86     import SALOMERuntime
87     import loader
88     SALOMERuntime.RuntimeSALOME_setRuntime()
89
90     r = pilot.getRuntime()
91     xmlLoader = loader.YACSLoader()
92     xmlLoader.registerProcCataLoader()
93     try:
94      catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
95     except:
96       pass
97     r.addCatalog(catalogAd)
98
99     try:
100         p = xmlLoader.load("<ADAO YACS xml scheme>")
101     except IOError,ex:
102         print "IO exception:",ex
103
104     logger = p.getLogger("parser")
105     if not logger.isEmpty():
106         print "The imported file has errors :"
107         print logger.getStr()
108
109     if not p.isValid():
110         print "The schema is not valid and can not be executed"
111         print p.getErrorReport()
112
113     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
114     p.checkConsistency(info)
115     if info.areWarningsOrErrors():
116         print "The schema is not consistent and can not be executed"
117         print info.getGlobalRepr()
118
119     e = pilot.ExecutorSwig()
120     e.RunW(p)
121     if p.getEffectiveState() != pilot.DONE:
122         print p.getErrorReport()
123
124 This method allows for example to edit the YACS XML scheme in TUI, or to gather
125 results for further use.
126
127 .. _section_advanced_observer:
128
129 Getting information on special variables during the ADAO calculation in YACS
130 -----------------------------------------------------------------------------
131
132 .. index:: single: Observer
133 .. index:: single: Observers
134 .. index:: single: Observer Template
135
136 Some special internal optimization variables, used during calculations, can be
137 monitored during the ADAO calculation in YACS. These variables can be printed,
138 plotted, saved, etc. This can be done using "*observers*", that are scripts,
139 each associated with one variable. In order to use this feature, the user has to
140 build scripts using as standard inputs (e.g. available in the namespace) the
141 variables ``var`` and ``info``. The variable ``var`` is to be used in the same
142 way as for the final ADD object, that is as a list/tuple object.
143
144 Some templates are available when editing the ADAO case in graphical editor.
145 These simple scripts can be customized by the user, either at the EFICAS edition
146 stage, or at the YACS edition stage, to improve the tuning of the ADAO
147 calculation in YACS.
148
149 As an example, here is one very simple script (similar to the "*ValuePrinter*"
150 template) used to print the value of one monitored variable::
151
152     print "    --->",info," Value =",var[-1]
153
154 Stored in a Python file, this script can be associated to each variable
155 available in the "*SELECTION*" keyword of the "*Observers*" command:
156 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
157 variable will be printed at each step of the optimization or assimilation
158 algorithm. The observers can embed plotting capabilities, storage, complex
159 printing, statistical treatment, etc.
160
161 Getting more information when running a calculation
162 ---------------------------------------------------
163
164 .. index:: single: Logging
165
166 When running a calculation, useful data and messages are logged. There are two
167 ways to obtain theses information.
168
169 The first one, and the preferred way, is to use the built-in variable "*Debug*"
170 available in every ADAO case. It is available through the edition GUI of the
171 module. Setting it to "*1*" will send messages in the log window of the YACS
172 scheme execution.
173
174 The second one consist in using the "*logging*" native module of Python (see the
175 Python documentation http://docs.python.org/library/logging.html for more
176 information on this module). Everywhere in the YACS scheme, mainly through the
177 scripts entries, the user can set the logging level in accordance to the needs
178 of detailed information. The different logging levels are: "*DEBUG*", "*INFO*",
179 "*WARNING*", "*ERROR*", "*CRITICAL*". All the information flagged with a
180 certain level will be printed for whatever activated level above this particular
181 one (included). The easiest way is to change the log level by using the
182 following Python lines::
183
184     import logging
185     logging.getLogger().setLevel(logging.DEBUG)
186
187 The standard logging module default level is "*WARNING*", the default level in
188 the ADAO module is "*INFO*". 
189
190 It is also recommended to include some logging or debug mechanisms in the
191 simulation code, and use them in conjunction with the two previous methods. But
192 be careful not to store too big variables because it cost time, whatever logging
193 level is chosen (that is, even if these variables are not printed).
194
195 .. _subsection_ref_parallel_df:
196
197 Accelerating numerical derivatives calculations by using a parallel mode
198 ------------------------------------------------------------------------
199
200 .. index:: single: EnableMultiProcessing
201
202 When setting an operator, as described in
203 :ref:`section_ref_operator_requirements`, the user can choose a functional form
204 "*ScriptWithOneFunction*". This form explicitly leads to approximate the tangent
205 and adjoint operators by a finite differences calculation. It requires several
206 calls to the direct operator (user defined function), at least as many times as
207 the dimension of the state vector. This are these calls that can potentially be
208 executed in parallel.
209
210 Under some conditions, it is then possible to accelerate the numerical
211 derivatives calculations by using a parallel mode for the finite differences
212 approximation. When setting up an ADAO case, it is done by adding the optional
213 sub-command "*EnableMultiProcessing*", set to "1", for the
214 "*SCRIPTWITHONEFUNCTION*" command in the operator definition. The parallel mode
215 will only use local resources (both multi-cores or multi-processors) of the
216 computer on which SALOME is running, requiring as many resources as available.
217 By default, this parallel mode is disabled ("*EnableMultiProcessing=0*").
218
219 The main conditions to perform parallel calculations come from the user defined
220 function, that represents the direct operator. This function has at least to be
221 "thread safe" to be executed in Python parallel environment (notions out of
222 scope of this paragraph). It is not obvious to give general rules, so it's
223 recommended, for the user who enable this internal parallelism, to carefully
224 verify his function and the obtained results.
225
226 From a user point of view, some conditions, that have to be met to set up
227 parallel calculations for tangent and the adjoint operators approximations, are
228 the following ones:
229
230 #. The dimension of the state vector is more than 2 or 3.
231 #. Unitary calculation of user defined direct function "last for long time", that is, more than few minutes.
232 #. The user defined direct function doesn't already use parallelism (or parallel execution is disabled in the user calculation).
233 #. The user defined direct function avoids read/write access to common resources, mainly stored data, output files or memory capacities.
234 #. The observers added by the user avoid read/write access to common resources, such as files or memory.
235
236 If these conditions are satisfied, the user can choose to enable the internal
237 parallelism for the numerical derivative calculations. Despite the simplicity of
238 activating, by setting one variable only, the user is urged to verify the
239 results of its calculations. One must at least doing them one time with
240 parallelism enabled, and an another time with parallelism disabled, to compare
241 the results. If it does fail somewhere, you have to know that this parallel
242 scheme is working for complex codes, like *Code_Aster* in *SalomeMeca*
243 [SalomeMeca]_ for example. So, if it does not work in your case, check your
244 operator function before and during enabling parallelism...
245
246 .. warning::
247
248   in case of doubt, it is recommended NOT TO ACTIVATE this parallelism.
249
250 Switching from a version of ADAO to a newer one
251 -----------------------------------------------
252
253 .. index:: single: Version
254
255 The ADAO module and its ".comm" case files are identified by versions, with
256 "Major", "Minor" and "Revision" characteristics. A particular version is
257 numbered as "Major.Minor.Revision", with strong link with the numbering of the
258 SALOME platform.
259
260 Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
261 of the previous minor version "Major.Minor-1.*". In general, it can also read
262 ADAO case files of all the previous minor versions for one major branch, but it
263 is not guaranteed for all the commands or keywords. In general also, an ADAO
264 case file for one version can not be read by a previous minor or major version
265 of the ADAO module.
266
267 Switching from 7.5 to 7.6
268 +++++++++++++++++++++++++
269
270 There is no known incompatibility for the ADAO case files. The upgrade procedure
271 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
272 with a new name. This procedure proceed automatically to the required
273 modifications of the storage tree of the ADAO case file.
274
275 Switching from 7.4 to 7.5
276 +++++++++++++++++++++++++
277
278 There is no known incompatibility for the ADAO case files. The upgrade procedure
279 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
280 with a new name.
281
282 Switching from 7.3 to 7.4
283 +++++++++++++++++++++++++
284
285 There is no known incompatibility for the ADAO case files. The upgrade procedure
286 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
287 with a new name.
288
289 Switching from 7.2 to 7.3
290 +++++++++++++++++++++++++
291
292 There is no known incompatibility for the ADAO case files. The upgrade procedure
293 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
294 with a new name.
295
296 Switching from 6.6 to 7.2
297 +++++++++++++++++++++++++
298
299 There is no known incompatibility for the ADAO case files. The upgrade procedure
300 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
301 with a new name.
302
303 There is one incompatibility introduced for the post-processing or observer
304 script files. The old syntax to call a result object, such as the "*Analysis*"
305 one (in a script provided through the "*UserPostAnalysis*" keyword), was for
306 example::
307
308     Analysis = ADD.get("Analysis").valueserie(-1)
309     Analysis = ADD.get("Analysis").valueserie()
310
311 The new syntax is entirely similar to the (classical) one of a list or tuple
312 object::
313
314     Analysis = ADD.get("Analysis")[-1]
315     Analysis = ADD.get("Analysis")[:]
316
317 The post-processing scripts has to be modified.
318
319 Switching from 6.5 to 6.6
320 +++++++++++++++++++++++++
321
322 There is no known incompatibility for the ADAO case file. The upgrade procedure
323 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
324 with a new name.
325
326 There is one incompatibility introduced for the naming of operators used to for
327 the observation operator. The new mandatory names are "*DirectOperator*",
328 "*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
329 of the chapter :ref:`section_reference`. The operator scripts has to be
330 modified.
331
332 Switching from 6.4 to 6.5
333 +++++++++++++++++++++++++
334
335 There is no known incompatibility for the ADAO case file or the accompanying
336 scripts. The upgrade procedure is to read the old ADAO case file with the new
337 SALOME/ADAO module, and save it with a new name.
338
339 Switching from 6.3 to 6.4
340 +++++++++++++++++++++++++
341
342 There is no known incompatibility for the ADAO case file or the accompanying
343 scripts. The upgrade procedure is to read the old ADAO case file with the new
344 SALOME/ADAO module, and save it with a new name.