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_Case.xml
  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.