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).
   9
  10 Exporting an ADAO command file (JDC) to YACS using a console user mode
  11 ----------------------------------------------------------------------
  12
  13 An export command can use the Python file generated by the editor used to build
  14 the ADAO command file (JDC). If the ADAO command file is named "Study1.comm",
  15 then a file named "Study1.py" can be found in the same directory. The complete
  16 procedure is the following:
  17
  18 #.      using the SALOME application including ADAO module, launch SALOME with ``./runAppli -k``
  19 #.      initialise the command line session with: ``./runSession``
  20 #.      change to the YACS calculation scheme directory to be executed
  21 #.      execute the export command: ``python ${ADAO_ROOT_DIR}/bin/salome/AdaoYacsSchemaCreator.py <input Python file> <output YACS xml scheme>``
  22 #.      standard output comes on console, successive executions can be done
  23 #.      stop SALOME:  ``killSalome.py``
  24 #.      exit from the session: ``CTRL+D``
  25
  26 Be careful, if the output YACS xml scheme file already exists, this command
  27 replace it without asking the user. The command accepts files with or without
  28 path specifications.
  29
  30 It is not necessary to launch and shut down SALOME each time if the application
  31 is already running.
  32
  33 Running an ADAO calculation scheme in YACS using a console user mode
  34 --------------------------------------------------------------------
  35
  36 This section describes how to execute in console mode a YACS calculation scheme,
  37 obtained using the ADAO "Export to YACS" function. It uses the standard YACS
  38 console mode, which is briefly recalled here (see YACS documentation for more
  39 information) through a simple example.
  40
  41 The way to do that is as follows:
  42
  43 #.      using the SALOME application including ADAO module, launch SALOME with ``./runAppli -k``
  44 #.      initialise the command line session with: ``./runSession``
  45 #.      change to the YACS calculation scheme directory to be executed
  46 #.      execute the YACS supervisor:  ``driver <ADAO YACS xml scheme>``
  47 #.      standard output comes on console, successive executions can be done
  48 #.      stop SALOME:  ``killSalome.py``
  49 #.      exit from the session: ``CTRL+D``
  50
  51 It is not necessary to launch and shut down SALOME each time if the application
  52 is already running.
  53
  54 Running an ADAO calculation scheme in YACS using a TUI user mode
  55 ----------------------------------------------------------------
  56
  57 This section describes how to execute in TUI (Text User Interface) mode a YACS
  58 calculation scheme, obtained using the ADAO "Export to YACS" function. It uses
  59 the standard YACS TUI mode, which is briefly recalled here (see YACS
  60 documentation for more information) through a simple example. As seen in
  61 documentation, a XML scheme can be loaded in a Python. We give here a whole
  62 sequence of command lines to test the validity of the scheme before executing
  63 it, adding some initial supplementary ones to explicitly load the types catalog
  64 to avoid weird difficulties::
  65
  66     import pilot
  67     import SALOMERuntime
  68     import loader
  69     SALOMERuntime.RuntimeSALOME_setRuntime()
  70
  71     r = pilot.getRuntime()
  72     xmlLoader = loader.YACSLoader()
  73     xmlLoader.registerProcCataLoader()
  74     try:
  75      catalogAd = r.loadCatalog("proc", "<ADAO YACS xml scheme>")
  76     except:
  77       pass
  78     r.addCatalog(catalogAd)
  79
  80     try:
  81         p = xmlLoader.load("<ADAO YACS xml scheme>")
  82     except IOError,ex:
  83         print "IO exception:",ex
  84
  85     logger = p.getLogger("parser")
  86     if not logger.isEmpty():
  87         print "The imported file has errors :"
  88         print logger.getStr()
  89
  90     if not p.isValid():
  91         print "The schema is not valid and can not be executed"
  92         print p.getErrorReport()
  93
  94     info=pilot.LinkInfo(pilot.LinkInfo.ALL_DONT_STOP)
  95     p.checkConsistency(info)
  96     if info.areWarningsOrErrors():
  97         print "The schema is not consistent and can not be executed"
  98         print info.getGlobalRepr()
  99
 100     e = pilot.ExecutorSwig()
 101     e.RunW(p)
 102     if p.getEffectiveState() != pilot.DONE:
 103         print p.getErrorReport()
 104
 105 This method allows for example to edit the YACS XML scheme in TUI, or to gather
 106 results for futher use.
 107
 108 Getting informations on special variables during the ADAO calculation in YACS
 109 -----------------------------------------------------------------------------
 110
 111 Some special variables, used during calculations, can be monitored during the
 112 ADAO calculation in YACS. These variables can be printed, plotted, saved, etc.
 113 This can be done using "*observers*", that are scripts associated with one
 114 variable. In order to use this feature, one has to build scripts using as
 115 standard inputs (available in the namespace) the variable ``var``. This variable
 116 is to be used in the same way as for the final ADD object.
 117
 118 As an example, here is one very simple script used to print the value of one
 119 monitored variable::
 120
 121     print "    ---> Value =",var.valueserie(-1)
 122
 123 Stored in a python file, this script can be associated to each variable
 124 available in the "*SELECTION*" keyword of the "*Observers*" command:
 125 "*Analysis*", "*CurrentState*", "*CostFunction*"... The current value of the
 126 variable will be printed at each step of the optimization or assimilation
 127 algorithm.
 128
 129 Getting more information when running a calculation
 130 ---------------------------------------------------
 131
 132 When running, the ADAO module is logging useful data and messages. There are two
 133 ways to obtain theses informations.
 134
 135 The first one, and the preferred way, is to use the built-in variable "*Debug*"
 136 integrated in every "*ASSIMILATION_STUDY*". It is available through the GUI of
 137 the module. Setting it to "*1*" will send a lot of messages in the log window of
 138 the YACS scheme execution.
 139
 140 The second one consist in using the "*logging*" native module of Python (see the
 141 Python documentation http://docs.python.org/library/logging.html for more
 142 informations on this module). Everywhere in the YACS scheme, mainly through the
 143 scripts entries, the user can set the logging level in accordance to the needs
 144 of detailed informations. The different logging levels are: "*DEBUG*", "*INFO*",
 145 "*WARNING*", "*ERROR*", "*CRITICAL*". All the informations flagged with a
 146 certain level will be printed for whatever activated level above this particular
 147 one (included). The easiest way is to change the log level is to write the
 148 following Python lines::
 149
 150     import logging
 151     logging.getLogger().setLevel(logging.DEBUG)
 152
 153 The standard logging module default level is "*WARNING*", the default level in
 154 the ADAO module is "*INFO*".