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 symbolically
  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 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 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 further use.
 101
 102 Getting information 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 variables ``var`` and ``info``.
 110 The variable ``var`` is to be used in the same way as for the final ADD object,
 111 that is as a list object through its "*valueserie*" method.
 112
 113 As an example, here is one very simple script used to print the value of one
 114 monitored variable::
 115
 116     print "    --->",info," Value =",var.valueserie(-1)
 117
 118 Stored in a python file, this script can be associated to each variable
 119 available in the "*SELECTION*" keyword of the "*Observers*" command:
 120 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 121 variable will be printed at each step of the optimization or assimilation
 122 algorithm. The observers can embed plotting capabilities, storage, printing,
 123 etc.
 124
 125 Getting more information when running a calculation
 126 ---------------------------------------------------
 127
 128 When running, useful data and messages are logged. There are two ways to obtain
 129 theses information.
 130
 131 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 132 available in every ADAO case. It is available through the GUI of the module.
 133 Setting it to "*1*" will send messages in the log window of the YACS scheme
 134 execution.
 135
 136 The second one consist in using the "*logging*" native module of Python (see the
 137 Python documentation http://docs.python.org/library/logging.html for more
 138 information on this module). Everywhere in the YACS scheme, mainly through the
 139 scripts entries, the user can set the logging level in accordance to the needs
 140 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 141 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 142 certain level will be printed for whatever activated level above this particular
 143 one (included). The easiest way is to change the log level is to write the
 144 following Python lines::
 145
 146     import logging
 147     logging.getLogger().setLevel(logging.DEBUG)
 148
 149 The standard logging module default level is "*WARNING*", the default level in
 150 the ADAO module is "*INFO*".
 151
 152 It is also recommended to include in the simulation code some logging or debug
 153 mechanisms and use them in conjunction with the two previous methods. But be
 154 careful not to store too big variables because it cost time, whatever logging
 155 level is chosen.