doc/en/advanced.rst

   1 .. _section_advanced:
   2
   3 ================================================================================
   4 Advanced usage of the ADAO module
   5 ================================================================================
   6
   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 ``<...>``.
  12
  13 Converting and executing an ADAO command file (JDC) using a shell script
  14 ------------------------------------------------------------------------
  15
  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.
  23
  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).
  30
  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 ``<...>``.
  36
  37 The template of the shell script is the following::
  38
  39     #!/bin/bash
  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>
  49
  50 Standard output and errors come on console.
  51
  52 Running an ADAO calculation scheme in YACS using a TUI user mode
  53 ----------------------------------------------------------------
  54
  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::
  63
  64     import pilot
  65     import SALOMERuntime
  66     import loader
  67     SALOMERuntime.RuntimeSALOME_setRuntime()
  68
  69     r = pilot.getRuntime()
  70     xmlLoader = loader.YACSLoader()
  71     xmlLoader.registerProcCataLoader()
  72     try:
  73      catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
  74     except:
  75       pass
  76     r.addCatalog(catalogAd)
  77
  78     try:
  79         p = xmlLoader.load("<ADAO YACS xml scheme>")
  80     except IOError,ex:
  81         print "IO exception:",ex
  82
  83     logger = p.getLogger("parser")
  84     if not logger.isEmpty():
  85         print "The imported file has errors :"
  86         print logger.getStr()
  87
  88     if not p.isValid():
  89         print "The schema is not valid and can not be executed"
  90         print p.getErrorReport()
  91
  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()
  97
  98     e = pilot.ExecutorSwig()
  99     e.RunW(p)
 100     if p.getEffectiveState() != pilot.DONE:
 101         print p.getErrorReport()
 102
 103 This method allows for example to edit the YACS XML scheme in TUI, or to gather
 104 results for further use.
 105
 106 Getting information on special variables during the ADAO calculation in YACS
 107 -----------------------------------------------------------------------------
 108
 109 Some special internal optimization variables, used during calculations, can be
 110 monitored during the ADAO calculation in YACS. These variables can be printed,
 111 plotted, saved, etc. This can be done using "*observers*", that are scripts,
 112 each associated with one variable. In order to use this feature, the user has to
 113 build scripts using as standard inputs (e.g. available in the namespace) the
 114 variables ``var`` and ``info``. The variable ``var`` is to be used in the same
 115 way as for the final ADD object, that is as a list/tuple object.
 116
 117 Some templates are available when editing the ADAO case in EFICAS editor. These
 118 simple scripts can be customized by the user, either at the EFICAS edition
 119 stage, or at the YACS edition stage, to improve the tuning of the ADAO
 120 calculation in YACS.
 121
 122 As an example, here is one very simple script (similar to the "*ValuePrinter*"
 123 template) used to print the value of one monitored variable::
 124
 125     print "    --->",info," Value =",var[-1]
 126
 127 Stored in a Python file, this script can be associated to each variable
 128 available in the "*SELECTION*" keyword of the "*Observers*" command:
 129 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 130 variable will be printed at each step of the optimization or assimilation
 131 algorithm. The observers can embed plotting capabilities, storage, complex
 132 printing, statistical treatment, etc.
 133
 134 Getting more information when running a calculation
 135 ---------------------------------------------------
 136
 137 When running a calculation, useful data and messages are logged. There are two
 138 ways to obtain theses information.
 139
 140 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 141 available in every ADAO case. It is available through the edition GUI of the
 142 module. Setting it to "*1*" will send messages in the log window of the YACS
 143 scheme execution.
 144
 145 The second one consist in using the "*logging*" native module of Python (see the
 146 Python documentation http://docs.python.org/library/logging.html for more
 147 information on this module). Everywhere in the YACS scheme, mainly through the
 148 scripts entries, the user can set the logging level in accordance to the needs
 149 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 150 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 151 certain level will be printed for whatever activated level above this particular
 152 one (included). The easiest way is to change the log level by using the
 153 following Python lines::
 154
 155     import logging
 156     logging.getLogger().setLevel(logging.DEBUG)
 157
 158 The standard logging module default level is "*WARNING*", the default level in
 159 the ADAO module is "*INFO*".
 160
 161 It is also recommended to include some logging or debug mechanisms in the
 162 simulation code, and use them in conjunction with the two previous methods. But
 163 be careful not to store too big variables because it cost time, whatever logging
 164 level is chosen (that is, even if these variables are not printed).
 165
 166 Switching from a version of ADAO to a newer one
 167 -----------------------------------------------
 168
 169 The ADAO module and its ".comm" case files are identified by versions, with
 170 "Major", "Minor" and "Revision" characteristics. A particular version is
 171 numbered as "Major.Minor.Revision", with strong link with the numbering of the
 172 SALOME platform.
 173
 174 Each version "Major.Minor.Revision" of the ADAO module can read ADAO case files
 175 of the previous minor version "Major.Minor-1.*". In general, it can also read
 176 ADAO case files of all the previous minor versions for one major branch, but it
 177 is not guaranteed for all the commands or keywords. In general also, an ADAO
 178 case file for one version can not be read by a previous minor or major version
 179 of the ADAO module.
 180
 181 Switching from 7.2 to 7.3
 182 +++++++++++++++++++++++++
 183
 184 There is no known incompatibility for the ADAO case files. The upgrade procedure
 185 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 186 with a new name.
 187
 188 Switching from 6.6 to 7.2
 189 +++++++++++++++++++++++++
 190
 191 There is no known incompatibility for the ADAO case files. The upgrade procedure
 192 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 193 with a new name.
 194
 195 There is one incompatibility introduced for the post-processing or observer
 196 script files. The old syntax to call a result object, such as the "*Analysis*"
 197 one (in a script provided through the "*UserPostAnalysis*" keyword), was for
 198 example::
 199
 200     Analysis = ADD.get("Analysis").valueserie(-1)
 201     Analysis = ADD.get("Analysis").valueserie()
 202
 203 The new syntax is entirely similar to the (classical) one of a list or tuple
 204 object::
 205
 206     Analysis = ADD.get("Analysis")[-1]
 207     Analysis = ADD.get("Analysis")[:]
 208
 209 The post-processing scripts has to be modified.
 210
 211 Switching from 6.5 to 6.6
 212 +++++++++++++++++++++++++
 213
 214 There is no known incompatibility for the ADAO case file. The upgrade procedure
 215 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 216 with a new name.
 217
 218 There is one incompatibility introduced for the naming of operators used to for
 219 the observation operator. The new mandatory names are "*DirectOperator*",
 220 "*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
 221 of the chapter :ref:`section_reference`. The operator scripts has to be
 222 modified.
 223
 224 Switching from 6.4 to 6.5
 225 +++++++++++++++++++++++++
 226
 227 There is no known incompatibility for the ADAO case file or the accompanying
 228 scripts. The upgrade procedure is to read the old ADAO case file with the new
 229 SALOME/ADAO module, and save it with a new name.
 230
 231 Switching from 6.3 to 6.4
 232 +++++++++++++++++++++++++
 233
 234 There is no known incompatibility for the ADAO case file or the accompanying
 235 scripts. The upgrade procedure is to read the old ADAO case file with the new
 236 SALOME/ADAO module, and save it with a new name.