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) automatically by using a template script containing all the required
  18 steps. The user has to know where are the main SALOME scripts, and in particular
  19 the ``runAppli`` one. The directory in which this script resides is symbolicaly
  20 named ``<SALOME MAIN INSTALLATION DIR>`` and has to be replaced by the good one
  21 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 compagnon 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 also to start and stop the SALOME application server
  31 in the same script, which is not necessary, but useful to avoid stalling SALOME
  32 sessions.
  33
  34 The template of the shell script is the following::
  35
  36     #!/bin/bash
  37     <SALOME MAIN INSTALLATION DIR>/runAppli -k -t
  38     <SALOME MAIN INSTALLATION DIR>/runSession python \
  39         ${ADAO_ROOT_DIR}/bin/salome/AdaoYacsSchemaCreator.py \
  40         <ADAO Python file> <ADAO YACS xml scheme>
  41     <SALOME MAIN INSTALLATION DIR>/runSession driver \
  42         <ADAO YACS xml scheme>
  43     <SALOME MAIN INSTALLATION DIR>/runSession killSalome.py
  44
  45 Standard output and errors come on console, successive executions can be done if
  46 the SALOME server is already running.
  47
  48 Running an ADAO calculation scheme in YACS using a TUI user mode
  49 ----------------------------------------------------------------
  50
  51 This section describes how to execute in TUI (Text User Interface) mode a YACS
  52 calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
  53 the standard YACS TUI mode, which is briefly recalled here (see YACS
  54 documentation for more information) through a simple example. As seen in
  55 documentation, a XML scheme can be loaded in a Python. We give here a whole
  56 sequence of command lines to test the validity of the scheme before executing
  57 it, adding some initial supplementary ones to explicitly load the types catalog
  58 to avoid weird difficulties::
  59
  60     import pilot
  61     import SALOMERuntime
  62     import loader
  63     SALOMERuntime.RuntimeSALOME_setRuntime()
  64
  65     r = pilot.getRuntime()
  66     xmlLoader = loader.YACSLoader()
  67     xmlLoader.registerProcCataLoader()
  68     try:
  69      catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
  70     except:
  71       pass
  72     r.addCatalog(catalogAd)
  73
  74     try:
  75         p = xmlLoader.load("<ADAO YACS xml scheme>")
  76     except IOError,ex:
  77         print "IO exception:",ex
  78
  79     logger = p.getLogger("parser")
  80     if not logger.isEmpty():
  81         print "The imported file has errors :"
  82         print logger.getStr()
  83
  84     if not p.isValid():
  85         print "The schema is not valid and can not be executed"
  86         print p.getErrorReport()
  87
  88     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
  89     p.checkConsistency(info)
  90     if info.areWarningsOrErrors():
  91         print "The schema is not consistent and can not be executed"
  92         print info.getGlobalRepr()
  93
  94     e = pilot.ExecutorSwig()
  95     e.RunW(p)
  96     if p.getEffectiveState() != pilot.DONE:
  97         print p.getErrorReport()
  98
  99 This method allows for example to edit the YACS XML scheme in TUI, or to gather
 100 results for futher use.
 101
 102 Getting informations on special variables during the ADAO calculation in YACS
 103 -----------------------------------------------------------------------------
 104
 105 Some special variables, used during calculations, can be monitored during the
 106 ADAO calculation in YACS. These variables can be printed, plotted, saved, etc.
 107 This can be done using "*observers*", that are scripts associated with one
 108 variable. In order to use this feature, one has to build scripts using as
 109 standard inputs (available in the namespace) the variable ``var``. This variable
 110 is to be used in the same way as for the final ADD object.
 111
 112 As an example, here is one very simple script used to print the value of one
 113 monitored variable::
 114
 115     print "    ---> Value =",var.valueserie(-1)
 116
 117 Stored in a python file, this script can be associated to each variable
 118 available in the "*SELECTION*" keyword of the "*Observers*" command:
 119 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 120 variable will be printed at each step of the optimization or assimilation
 121 algorithm.
 122
 123 Getting more information when running a calculation
 124 ---------------------------------------------------
 125
 126 When running, useful data and messages are logged. There are two ways to obtain
 127 theses informations.
 128
 129 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 130 available in every ADAO case. It is available through the GUI of the module.
 131 Setting it to "*1*" will send messages in the log window of the YACS scheme
 132 execution.
 133
 134 The second one consist in using the "*logging*" native module of Python (see the
 135 Python documentation http://docs.python.org/library/logging.html for more
 136 information on this module). Everywhere in the YACS scheme, mainly through the
 137 scripts entries, the user can set the logging level in accordance to the needs
 138 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 139 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 140 certain level will be printed for whatever activated level above this particular
 141 one (included). The easiest way is to change the log level is to write the
 142 following Python lines::
 143
 144     import logging
 145     logging.getLogger().setLevel(logging.DEBUG)
 146
 147 The standard logging module default level is "*WARNING*", the default level in
 148 the ADAO module is "*INFO*".
 149
 150 It is also recommended to include in the simulation code some logging or debug
 151 mechanisms and use them in conjunction with the two previous methods. But be
 152 careful not to store too big variables because it cost time, whatever logging
 153 level is chosen.