3 ================================================================================
4 Advanced usage of the ADAO module
5 ================================================================================
7 This section presents advanced methods to use the ADAO module, how to get more
8 information during calculation, or how to use it without the graphical user
9 interface (GUI). It requires to know how to find files or commands included
10 inside the whole SALOME installation. All the names to be replaced by user are
11 indicated by the syntax ``<...>``.
13 Converting and executing an ADAO command file (JDC) using a shell script
14 ------------------------------------------------------------------------
16 It is possible to convert and execute an ADAO command file (JDC, or ".comm/.py"
17 files pair, which resides in ``<ADAO JDC file directory>``) automatically by
18 using a template shell script containing all the required steps. The user has to
19 know where are the main SALOME launching files, and in particular the
20 ``runAppli`` one. The directory in which this script resides is symbolically
21 named ``<SALOME main installation dir>`` and has to be replaced by the good one
22 in the shell file template.
24 When an ADAO command file is build by the ADAO GUI EFICAS editor and saved, if
25 it is named for example "AdaoStudy1.comm", then a companion file named
26 "AdaoStudy1.py" is automatically created in the same directory. It is named
27 ``<ADAO Python file>`` in the template, and it is converted to YACS as an
28 ``<ADAO YACS xml scheme>``. After that, it can be executed in console mode using
29 the standard YACS console command (see YACS documentation for more information).
31 In the example, we choose to start and stop the SALOME application server in the
32 same script, which is not necessary, but useful to avoid stalling SALOME
33 sessions. We choose also to remove the ``<ADAO YACS xml scheme>`` file because
34 it is a generated one. The user of this script only need to replace the text
35 between these symbols ``<...>``.
37 The template of the shell script is the following::
40 export USERDIR=<ADAO JDC file directory>
41 export SALOMEDIR=<SALOME main installation directory>
42 $SALOMEDIR/runAppli -k -t
43 $SALOMEDIR/runSession python \
44 $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py \
45 $USERDIR/<ADAO Python file> $USERDIR/<ADAO YACS xml scheme>
46 $SALOMEDIR/runSession driver $USERDIR/<ADAO YACS xml scheme>
47 $SALOMEDIR/runSession killSalome.py
48 rm -f $USERDIR/<ADAO YACS xml scheme>
50 Standard output and errors come on console.
52 Running an ADAO calculation scheme in YACS using a TUI user mode
53 ----------------------------------------------------------------
55 This section describes how to execute in TUI (Text User Interface) mode a YACS
56 calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
57 the standard YACS TUI mode, which is briefly recalled here (see YACS
58 documentation for more information) through a simple example. As described in
59 documentation, a XML scheme can be loaded in a Python. We give here a whole
60 sequence of command lines to test the validity of the scheme before executing
61 it, adding some initial supplementary ones to explicitly load the types catalog
62 to avoid weird difficulties::
67 SALOMERuntime.RuntimeSALOME_setRuntime()
69 r = pilot.getRuntime()
70 xmlLoader = loader.YACSLoader()
71 xmlLoader.registerProcCataLoader()
73 catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
76 r.addCatalog(catalogAd)
79 p = xmlLoader.load("<ADAO YACS xml scheme>")
81 print "IO exception:",ex
83 logger = p.getLogger("parser")
84 if not logger.isEmpty():
85 print "The imported file has errors :"
89 print "The schema is not valid and can not be executed"
90 print p.getErrorReport()
92 info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
93 p.checkConsistency(info)
94 if info.areWarningsOrErrors():
95 print "The schema is not consistent and can not be executed"
96 print info.getGlobalRepr()
98 e = pilot.ExecutorSwig()
100 if p.getEffectiveState() != pilot.DONE:
101 print p.getErrorReport()
103 This method allows for example to edit the YACS XML scheme in TUI, or to gather
104 results for further use.
106 Getting information on special variables during the ADAO calculation in YACS
107 -----------------------------------------------------------------------------
109 .. index:: single: Observer
110 .. index:: single: Observers
111 .. index:: single: Observer Template
113 Some special internal optimization variables, used during calculations, can be
114 monitored during the ADAO calculation in YACS. These variables can be printed,
115 plotted, saved, etc. This can be done using "*observers*", that are scripts,
116 each associated with one variable. In order to use this feature, the user has to
117 build scripts using as standard inputs (e.g. available in the namespace) the
118 variables ``var`` and ``info``. The variable ``var`` is to be used in the same
119 way as for the final ADD object, that is as a list/tuple object.
121 Some templates are available when editing the ADAO case in EFICAS editor. These
122 simple scripts can be customized by the user, either at the EFICAS edition
123 stage, or at the YACS edition stage, to improve the tuning of the ADAO
126 As an example, here is one very simple script (similar to the "*ValuePrinter*"
127 template) used to print the value of one monitored variable::
129 print " --->",info," Value =",var[-1]
131 Stored in a Python file, this script can be associated to each variable
132 available in the "*SELECTION*" keyword of the "*Observers*" command:
133 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
134 variable will be printed at each step of the optimization or assimilation
135 algorithm. The observers can embed plotting capabilities, storage, complex
136 printing, statistical treatment, etc.
138 Getting more information when running a calculation
139 ---------------------------------------------------
141 When running a calculation, useful data and messages are logged. There are two
142 ways to obtain theses information.
144 The first one, and the preferred way, is to use the built-in variable "*Debug*"
145 available in every ADAO case. It is available through the edition GUI of the
146 module. Setting it to "*1*" will send messages in the log window of the YACS
149 The second one consist in using the "*logging*" native module of Python (see the
150 Python documentation http://docs.python.org/library/logging.html for more
151 information on this module). Everywhere in the YACS scheme, mainly through the
152 scripts entries, the user can set the logging level in accordance to the needs
153 of detailed information. The different logging levels are: "*DEBUG*", "*INFO*",
154 "*WARNING*", "*ERROR*", "*CRITICAL*". All the information flagged with a
155 certain level will be printed for whatever activated level above this particular
156 one (included). The easiest way is to change the log level by using the
157 following Python lines::
160 logging.getLogger().setLevel(logging.DEBUG)
162 The standard logging module default level is "*WARNING*", the default level in
163 the ADAO module is "*INFO*".
165 It is also recommended to include some logging or debug mechanisms in the
166 simulation code, and use them in conjunction with the two previous methods. But
167 be careful not to store too big variables because it cost time, whatever logging
168 level is chosen (that is, even if these variables are not printed).
170 Accelerating numerical derivatives calculations by using a parallel mode
171 ------------------------------------------------------------------------
173 When setting an operator, as described in :ref:`section_reference`, the user can
174 choose a functional form "*ScriptWithOneFunction*". This form explicitly leads
175 to approximate the tangent and adjoint operators by a finite differences
176 calculation. It requires several calls to the direct operator (user defined
177 function), at least as many times as the dimension of the state vector. This are
178 these calls that can potentially be executed in parallel.
180 Under some conditions, it is then possible to accelerate the numerical
181 derivatives calculations by using a parallel mode for the finite differences
182 approximation. When setting up an ADAO case, it is done by adding the optional
183 sub-command "*EnableMultiProcessing*", set to "1", for the
184 "*SCRIPTWITHONEFUNCTION*" command in the operator definition. The parallel mode
185 will only use local resources (both multi-cores or multi-processors) of the
186 computer on which SALOME is running, requiring as many resources as available.
187 By default, this parallel mode is disabled ("*EnableMultiProcessing=0*").
189 The main conditions to perform parallel calculations come from the user defined
190 function, that represents the direct operator. This function has at least to be
191 "thread safe" to be executed in Python parallel environment (notions out of
192 scope of this paragraph). It is not obvious to give general rules, so it's
193 recommended, for the user who enable this internal parallelism, to carefully
194 verify his function and the obtained results.
196 From a user point of view, some conditions, that have to be met to set up
197 parallel calculations for tangent and the adjoint operators approximations, are
200 #. The dimension of the state vector is more than 2 or 3.
201 #. Unitary calculation of user defined direct function "last for long time", that is, more than few minutes.
202 #. The user defined direct function doesn't already use parallelism (or parallel execution is disabled in the user calculation).
203 #. The user defined direct function doesn't requires read/write access to common resources, mainly stored data or memory capacities.
205 If these conditions are satisfied, the user can choose to enable the internal
206 parallelism for the numerical derivative calculations. Despite the simplicity of
207 activating, by setting one variable only, the user is urged to verify the
208 results of its calculations. One must at least doing them one time with
209 parallelism enabled, and an another time with parallelism disabled, to compare
210 the results. If it does fail somewhere, you have to know that this parallel
211 scheme is working for complex codes, like *Code_Aster* in *SalomeMeca*
212 [SalomeMeca]_ for example. So check your operator function before and during
213 enabling parallelism...
215 **In case of doubt, it is recommended NOT TO ACTIVATE this parallelism.**
217 Switching from a version of ADAO to a newer one
218 -----------------------------------------------
220 The ADAO module and its ".comm" case files are identified by versions, with
221 "Major", "Minor" and "Revision" characteristics. A particular version is
222 numbered as "Major.Minor.Revision", with strong link with the numbering of the
225 Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
226 of the previous minor version "Major.Minor-1.*". In general, it can also read
227 ADAO case files of all the previous minor versions for one major branch, but it
228 is not guaranteed for all the commands or keywords. In general also, an ADAO
229 case file for one version can not be read by a previous minor or major version
232 Switching from 7.3 to 7.4
233 +++++++++++++++++++++++++
235 There is no known incompatibility for the ADAO case files. The upgrade procedure
236 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
240 Switching from 7.2 to 7.3
241 +++++++++++++++++++++++++
243 There is no known incompatibility for the ADAO case files. The upgrade procedure
244 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
247 Switching from 6.6 to 7.2
248 +++++++++++++++++++++++++
250 There is no known incompatibility for the ADAO case files. The upgrade procedure
251 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
254 There is one incompatibility introduced for the post-processing or observer
255 script files. The old syntax to call a result object, such as the "*Analysis*"
256 one (in a script provided through the "*UserPostAnalysis*" keyword), was for
259 Analysis = ADD.get("Analysis").valueserie(-1)
260 Analysis = ADD.get("Analysis").valueserie()
262 The new syntax is entirely similar to the (classical) one of a list or tuple
265 Analysis = ADD.get("Analysis")[-1]
266 Analysis = ADD.get("Analysis")[:]
268 The post-processing scripts has to be modified.
270 Switching from 6.5 to 6.6
271 +++++++++++++++++++++++++
273 There is no known incompatibility for the ADAO case file. The upgrade procedure
274 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
277 There is one incompatibility introduced for the naming of operators used to for
278 the observation operator. The new mandatory names are "*DirectOperator*",
279 "*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
280 of the chapter :ref:`section_reference`. The operator scripts has to be
283 Switching from 6.4 to 6.5
284 +++++++++++++++++++++++++
286 There is no known incompatibility for the ADAO case file or the accompanying
287 scripts. The upgrade procedure is to read the old ADAO case file with the new
288 SALOME/ADAO module, and save it with a new name.
290 Switching from 6.3 to 6.4
291 +++++++++++++++++++++++++
293 There is no known incompatibility for the ADAO case file or the accompanying
294 scripts. The upgrade procedure is to read the old ADAO case file with the new
295 SALOME/ADAO module, and save it with a new name.