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, or how to use it without the graphical user interface (GUI). It
   9 requires to know how to find files or commands included inside the whole SALOME
  10 installation. All the names to be replaced by user are indicated by the
  11 following 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"
  17 file, which resides in ``<ADAO JDC file directory>``) automatically by using a
  18 template script containing all the required steps. The user has to know where
  19 are the main SALOME scripts, and in particular the ``runAppli`` one. The
  20 directory in which this script resides is symbolically named ``<SALOME main
  21 installation dir>`` and has to be replaced by the good one in the template.
  22
  23 When an ADAO command file is build by the ADAO GUI editor and saved, if it is
  24 named for example "AdaoStudy1.comm", then a companion file named "AdaoStudy1.py"
  25 is automatically created in the same directory. It is named ``<ADAO Python
  26 file>`` in the template, and it is converted to YACS as an ``<ADAO YACS xml
  27 scheme>``. After that, it can be executed in console mode using the standard
  28 YACS console command (see YACS documentation for more information).
  29
  30 In the example, we choose to start and stop the SALOME application server in the
  31 same script, which is not necessary, but useful to avoid stalling SALOME
  32 sessions. We choose also to remove the ``<ADAO YACS xml scheme>`` because it is
  33 a generated one. You only need to replace the text between these symbols
  34 ``<...>`` to use it.
  35
  36 The template of the shell script is the following::
  37
  38     #!/bin/bash
  39     export USERDIR=<ADAO JDC file directory>
  40     export SALOMEDIR=<SALOME main installation directory>
  41     $SALOMEDIR/runAppli -k -t
  42     $SALOMEDIR/runSession python \
  43         $SALOMEDIR/bin/salome/AdaoYacsSchemaCreator.py \
  44         $USERDIR/<ADAO Python file> $USERDIR/<ADAO YACS xml scheme>
  45     $SALOMEDIR/runSession driver $USERDIR/<ADAO YACS xml scheme>
  46     $SALOMEDIR/runSession killSalome.py
  47     rm -f $USERDIR/<ADAO YACS xml scheme>
  48
  49 Standard output and errors come on console.
  50
  51 Running an ADAO calculation scheme in YACS using a TUI user mode
  52 ----------------------------------------------------------------
  53
  54 This section describes how to execute in TUI (Text User Interface) mode a YACS
  55 calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
  56 the standard YACS TUI mode, which is briefly recalled here (see YACS
  57 documentation for more information) through a simple example. As seen in
  58 documentation, a XML scheme can be loaded in a Python. We give here a whole
  59 sequence of command lines to test the validity of the scheme before executing
  60 it, adding some initial supplementary ones to explicitly load the types catalog
  61 to avoid weird difficulties::
  62
  63     import pilot
  64     import SALOMERuntime
  65     import loader
  66     SALOMERuntime.RuntimeSALOME_setRuntime()
  67
  68     r = pilot.getRuntime()
  69     xmlLoader = loader.YACSLoader()
  70     xmlLoader.registerProcCataLoader()
  71     try:
  72      catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
  73     except:
  74       pass
  75     r.addCatalog(catalogAd)
  76
  77     try:
  78         p = xmlLoader.load("<ADAO YACS xml scheme>")
  79     except IOError,ex:
  80         print "IO exception:",ex
  81
  82     logger = p.getLogger("parser")
  83     if not logger.isEmpty():
  84         print "The imported file has errors :"
  85         print logger.getStr()
  86
  87     if not p.isValid():
  88         print "The schema is not valid and can not be executed"
  89         print p.getErrorReport()
  90
  91     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
  92     p.checkConsistency(info)
  93     if info.areWarningsOrErrors():
  94         print "The schema is not consistent and can not be executed"
  95         print info.getGlobalRepr()
  96
  97     e = pilot.ExecutorSwig()
  98     e.RunW(p)
  99     if p.getEffectiveState() != pilot.DONE:
 100         print p.getErrorReport()
 101
 102 This method allows for example to edit the YACS XML scheme in TUI, or to gather
 103 results for further use.
 104
 105 Getting information on special variables during the ADAO calculation in YACS
 106 -----------------------------------------------------------------------------
 107
 108 Some special variables, used during calculations, can be monitored during the
 109 ADAO calculation in YACS. These variables can be printed, plotted, saved, etc.
 110 This can be done using "*observers*", that are scripts associated with one
 111 variable. In order to use this feature, one has to build scripts using as
 112 standard inputs (available in the namespace) the variables ``var`` and ``info``.
 113 The variable ``var`` is to be used in the same way as for the final ADD object,
 114 that is as a list/tuple object.
 115
 116 Some templates are available when editing the ADAO case in EFICAS editor. These
 117 simple scripts can be customized by the user, either at the EFICAS edition stage
 118 or at the YACS edition stage, to improve the tuning of the ADAO calculation in
 119 YACS.
 120
 121 As an example, here is one very simple script (similar to the "*ValuePrinter*"
 122 template) used to print the value of one monitored variable::
 123
 124     print "    --->",info," Value =",var[-1]
 125
 126 Stored in a python file, this script can be associated to each variable
 127 available in the "*SELECTION*" keyword of the "*Observers*" command:
 128 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 129 variable will be printed at each step of the optimization or assimilation
 130 algorithm. The observers can embed plotting capabilities, storage, printing,
 131 etc.
 132
 133 Getting more information when running a calculation
 134 ---------------------------------------------------
 135
 136 When running, useful data and messages are logged. There are two ways to obtain
 137 theses information.
 138
 139 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 140 available in every ADAO case. It is available through the GUI of the module.
 141 Setting it to "*1*" will send messages in the log window of the YACS scheme
 142 execution.
 143
 144 The second one consist in using the "*logging*" native module of Python (see the
 145 Python documentation http://docs.python.org/library/logging.html for more
 146 information on this module). Everywhere in the YACS scheme, mainly through the
 147 scripts entries, the user can set the logging level in accordance to the needs
 148 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 149 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 150 certain level will be printed for whatever activated level above this particular
 151 one (included). The easiest way is to change the log level is to write the
 152 following Python lines::
 153
 154     import logging
 155     logging.getLogger().setLevel(logging.DEBUG)
 156
 157 The standard logging module default level is "*WARNING*", the default level in
 158 the ADAO module is "*INFO*".
 159
 160 It is also recommended to include in the simulation code some logging or debug
 161 mechanisms and use them in conjunction with the two previous methods. But be
 162 careful not to store too big variables because it cost time, whatever logging
 163 level is chosen.
 164
 165 Switching from a version of ADAO to a newer one
 166 -----------------------------------------------
 167
 168 The ADAO module and cases are identified as versions, with "Major", "Minor" and
 169 "Revision" characteristics. A particular version is numbered as
 170 "Major.Minor.Revision".
 171
 172 Each version of the ADAO module can read ADAO case files of the previous minor
 173 version. In general, it can also read ADAO case files of all the previous minor
 174 versions for one major branch. In general also, an ADAO case file for one
 175 version can not be read by a previous minor or major version.
 176
 177 Switching from 6.6 to 7.2
 178 +++++++++++++++++++++++++
 179
 180 There is no known incompatibility for the ADAO case file. The upgrade procedure
 181 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 182 with a new name.
 183
 184 There is one incompatibility introduced for the post-processing or observer
 185 script files. The old syntax to call a result object, such as the "*Analysis*"
 186 one in a script provided through the "*UserPostAnalysis*" keyword), was for
 187 example::
 188
 189     Analysis = ADD.get("Analysis").valueserie(-1)
 190     Analysis = ADD.get("Analysis").valueserie()
 191
 192 The new syntax is entirely similar to the classical one of a list/tuple object::
 193
 194     Analysis = ADD.get("Analysis")[-1]
 195     Analysis = ADD.get("Analysis")[:]
 196
 197 The post-processing scripts has to be modified.
 198
 199 Switching from 6.5 to 6.6
 200 +++++++++++++++++++++++++
 201
 202 There is no known incompatibility for the ADAO case file. The upgrade procedure
 203 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 204 with a new name.
 205
 206 There is one incompatibility introduced for the designation of operators used to
 207 for the observation operator. The new mandatory names are "*DirectOperator*",
 208 "*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
 209 of the chapter :ref:`section_reference`.
 210
 211 Switching from 6.4 to 6.5
 212 +++++++++++++++++++++++++
 213
 214 There is no known incompatibility for the ADAO case file or the accompanying
 215 scripts. The upgrade procedure is to read the old ADAO case file with the new
 216 SALOME/ADAO module, and save it with a new name.
 217
 218 Switching from 6.3 to 6.4
 219 +++++++++++++++++++++++++
 220
 221 There is no known incompatibility for the ADAO case file or the accompanying
 222 scripts. The upgrade procedure is to read the old ADAO case file with the new
 223 SALOME/ADAO module, and save it with a new name.