doc/execpy.rst

   1
   2 .. _execpy:
   3
   4 Execution of a calculation scheme with the Python programming interface
   5 ==========================================================================
   6 The first step is to have a Python calculation scheme object that will be called p.
   7 It is obtained using :ref:`schemapy`.
   8
   9 If it has not already been done, YACS modules have to be imported and YACS needs to be initialised
  10 for SALOME.  An Executor object will then have to be created that will execute the calculation scheme.
  11
  12 Create the Executor object::
  13
  14    e = pilot.ExecutorSwig()
  15
  16 There are two modes by which a scheme may be executed:
  17
  18 - standard mode that executes the scheme in block, waiting until the execution is completely finished
  19 - step by step mode, to partially execute the scheme and make pauses and restarts.
  20
  21 Executing the scheme in standard mode
  22 ----------------------------------------
  23 The Executor RunW method is used for this type of execution.  This method has three arguments.
  24 The first is the calculation scheme (or even a composite node under some conditions).  The second indicates
  25 the verbosity for execution in debug mode (0 is the level without debug, 1, 2 or 3 for debug).
  26 The third is a boolean that is equal to True if execution starts from zero (all nodes are calculated) or False if
  27 execution starts from a backed up state of the scheme.
  28 The default values of the latter two arguments are equal to 0 and True.
  29
  30 Execution of the scheme by the Executor object starting from zero, without debug::
  31
  32    e.RunW(p)
  33    if p.getEffectiveState() != pilot.DONE:
  34      print p.getErrorReport()
  35      sys.exit(1)
  36
  37 If the execution took place correctly, the state of the scheme obtained by ``p.getEffectiveState()`` is equal to DONE.
  38 If this is not the case, the scheme is in error.  An error report (see :ref:`errorreport`) is given by ``p.getErrorReport()``.
  39
  40 In all cases, the values contained in the input and output ports can then be retrieved.
  41
  42 Saving the state of a scheme
  43 ------------------------------------
  44 The state of a scheme after it has been executed can be saved in an XML file for a later restart if required.
  45 This save is done using the saveState method for the calculation scheme.  It uses an argument that is the name of
  46 the file in which the state will be saved.
  47
  48 This call is in the following format::
  49
  50   p.saveState("state.xml")
  51
  52 Loading the state of a scheme
  53 ------------------------------------
  54 A calculation scheme can be initialised with a state saved in a file.  Obviously, the calculation scheme must exist.
  55 Then, the loadState function of the loader module must be used.  It takes two arguments:  the calculation scheme and
  56 the name of the file containing the saved state.
  57
  58 For example, proceed as follows to initialise scheme p with the previously saved state::
  59
  60   import loader
  61   loader.loadState(p,"state.xml")
  62
  63 This initialisation is only possible if the structures of the scheme and the saved state are identical.
  64
  65 After initialisation, execution is started by transferring False as a third argument of RunW::
  66
  67   e.RunW(p,0,False)
  68
  69 Executing the scheme in step by step mode
  70 -----------------------------------------------
  71 This type of execution is for advanced users because it requires the use of thread programming in Python.
  72 Do not forget to import the threading module::
  73
  74   import threading
  75
  76 If it is required to use step by step mode or to add breakpoints, the scheme will have to be executed in a
  77 separate thread and execution control operations will have to be done in the main thread.
  78
  79 Execution with stop on breakpoints
  80 +++++++++++++++++++++++++++++++++++++++
  81 Before execution with breakpoints is possible, it is necessary to define the list of breakpoints, to set
  82 execution mode to execution with breakpoints, and then to start execution in a separate thread.
  83
  84 The list of breakpoints is defined by transferring a list of node names to the executor setListOfBreakPoints method.
  85 The mode is defined using the executor setExecMode method with a parameter equal to 2.
  86 Possible values are:
  87
  88 - 0, for standard execution mode (CONTINUOUS mode)
  89 - 1, for execution mode with pause at each execution step (STEPBYSTEP mode)
  90 - 2, for execution mode with breakpoints (STOPBEFORENODES mode).
  91
  92 Execution is started using the executor RunB method instead of RunW for a standard execution.
  93 The three arguments are the same:
  94
  95 - the calculation scheme
  96 - the display level (0,1,2,3)
  97 - execution start from zero (True,  False)
  98
  99 For example, the following will be written to stop before node “node1”::
 100
 101   e.setListOfBreakPoints(['node1'])
 102   e.setExecMode(2)
 103   mythread=threading.Thread(target=e.RunB, args=(p,1))
 104   mythread.start()
 105
 106 The state of nodes in the scheme can be displayed by calling the displayDot method during a pause::
 107
 108   e.displayDot(p)
 109
 110 It is then necessary to wait until the execution changes to pause:  an execution changes to pause when
 111 all possible tasks before execution of node “node1” are terminated.  The waitPause method is used to
 112 control this wait.  The next step will be to stop execution by calling the stopExecution method and the
 113 thread will then be released.  It is recommended that there should be a short wait before waiting for the pause.
 114 In total, the following sequence will be added::
 115
 116   time.sleep(0.1)
 117   e.waitPause()
 118   e.stopExecution()
 119   mythread.join()
 120
 121 A stop on breakpoint followed by resuming until the end of the scheme
 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 123 After a stop on breakpoint, an execution is resumed by changing to CONTINUE mode and then restarting
 124 the execution by calling the resumeCurrentBreakPoint method.
 125 The wait for the end of scheme execution is controlled by calling waitPause.
 126
 127 The call sequence to resume on breakpoint is as follows::
 128
 129   e.setExecMode(0)
 130   e.resumeCurrentBreakPoint()
 131   time.sleep(0.1)
 132   e.waitPause()
 133   mythread.join()
 134
 135 Execution in step by step mode
 136 +++++++++++++++++++++++++++++++++++++
 137 When executing in step by step mode, the calculation scheme executor pauses at each execution step.
 138 An execution step corresponds to execution of a group of calculation nodes.  This group may contain
 139 more than one calculation node if the calculation scheme contains parallel execution branches.
 140
 141 This mode is selected by calling the setExecMode method using the value 1 (STEPBYSTEP mode), and the executor
 142 is then started in a thread in the same way as above.  The waitPause method is used to wait until the end of
 143 the execution step.  The list of nodes in the next step is obtained using the getTasksToLoad method.
 144 The list of nodes to be executed is defined using the setStepsToExecute method and the execution is
 145 resumed using the resumeCurrentBreakPoint method.
 146 Everything must be placed in a loop that is exited at the end of the execution when there are no longer any nodes to be executed.
 147
 148 The complete sequence is as follows::
 149
 150   e.setExecMode(1)
 151   mythread=threading.Thread(target=e.RunB, args=(p,0))
 152   mythread.start()
 153   time.sleep(0.1)
 154
 155   tocont = True
 156   while tocont:
 157     e.waitPause()
 158     bp=e.getTasksToLoad()
 159     if bp:
 160       e.setStepsToExecute(bp)
 161     else:
 162       tocont=False
 163     e.resumeCurrentBreakPoint()
 164
 165   time.sleep(0.1)
 166   mythread.join()
 167
 168