doc/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 As an example, here is one very simple script used to print the value of one
 117 monitored variable::
 118
 119     print "    --->",info," Value =",var[-1]
 120
 121 Stored in a python file, this script can be associated to each variable
 122 available in the "*SELECTION*" keyword of the "*Observers*" command:
 123 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 124 variable will be printed at each step of the optimization or assimilation
 125 algorithm. The observers can embed plotting capabilities, storage, printing,
 126 etc.
 127
 128 Getting more information when running a calculation
 129 ---------------------------------------------------
 130
 131 When running, useful data and messages are logged. There are two ways to obtain
 132 theses information.
 133
 134 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 135 available in every ADAO case. It is available through the GUI of the module.
 136 Setting it to "*1*" will send messages in the log window of the YACS scheme
 137 execution.
 138
 139 The second one consist in using the "*logging*" native module of Python (see the
 140 Python documentation http://docs.python.org/library/logging.html for more
 141 information on this module). Everywhere in the YACS scheme, mainly through the
 142 scripts entries, the user can set the logging level in accordance to the needs
 143 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 144 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 145 certain level will be printed for whatever activated level above this particular
 146 one (included). The easiest way is to change the log level is to write the
 147 following Python lines::
 148
 149     import logging
 150     logging.getLogger().setLevel(logging.DEBUG)
 151
 152 The standard logging module default level is "*WARNING*", the default level in
 153 the ADAO module is "*INFO*".
 154
 155 It is also recommended to include in the simulation code some logging or debug
 156 mechanisms and use them in conjunction with the two previous methods. But be
 157 careful not to store too big variables because it cost time, whatever logging
 158 level is chosen.
 159
 160 Switching from a version of ADAO to a newer one
 161 -----------------------------------------------
 162
 163 The ADAO module and cases are identified as versions, with "Major", "Minor" and
 164 "Revision" characteristics. A particular version is numbered as
 165 "Major.Minor.Revision".
 166
 167 Each version of the ADAO module can read ADAO case files of the previous minor
 168 version. In general, it can also read ADAO case files of all the previous minor
 169 versions for one major branch. In general also, an ADAO case file for one
 170 version can not be read by a previous minor or major version.
 171
 172 Switching from 6.6 to 7.2
 173 +++++++++++++++++++++++++
 174
 175 There is no known incompatibility for the ADAO case file. The upgrade procedure
 176 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 177 with a new name.
 178
 179 There is one incompatibility introduced for the post-processing or observer
 180 script files. The old syntax to call a result object, such as the "*Analysis*"
 181 one in a script provided through the "*UserPostAnalysis*" keyword), was for
 182 example::
 183
 184     Analysis = ADD.get("Analysis").valueserie(-1)
 185     Analysis = ADD.get("Analysis").valueserie()
 186
 187 The new syntax is entirely similar to the classical one of a list/tuple object::
 188
 189     Analysis = ADD.get("Analysis")[-1]
 190     Analysis = ADD.get("Analysis")[:]
 191
 192 The post-processing scripts has to be modified.
 193
 194 Switching from 6.5 to 6.6
 195 +++++++++++++++++++++++++
 196
 197 There is no known incompatibility for the ADAO case file. The upgrade procedure
 198 is to read the old ADAO case file with the new SALOME/ADAO module, and save it
 199 with a new name.
 200
 201 There is one incompatibility introduced for the designation of operators used to
 202 for the observation operator. The new mandatory names are "*DirectOperator*",
 203 "*TangentOperator*" and "*AdjointOperator*", as described in the last subsection
 204 of the chapter :ref:`section_reference`.
 205
 206 Switching from 6.4 to 6.5
 207 +++++++++++++++++++++++++
 208
 209 There is no known incompatibility for the ADAO case file or the accompanying
 210 scripts. The upgrade procedure is to read the old ADAO case file with the new
 211 SALOME/ADAO module, and save it with a new name.
 212
 213 Switching from 6.3 to 6.4
 214 +++++++++++++++++++++++++
 215
 216 There is no known incompatibility for the ADAO case file or the accompanying
 217 scripts. The upgrade procedure is to read the old ADAO case file with the new
 218 SALOME/ADAO module, and save it with a new name.