doc/batch.rst

   1
   2 .. _batch:
   3
   4 Starting a SALOME application in a batch manager
   5 ================================================================
   6
   7 This section explains how SALOME is used with batch managers used in the operation of clusters.
   8 The objective is to run a SALOME application with a command script on a cluster starting from a
   9 SALOME session running on the user's personal machine.  The script contains the task that the user
  10 wants SALOME to execute.  The most usual task is to start a YACS scheme.
  11
  12 Principles
  13 -----------
  14 The start principle is as follows:  starting from a first SALOME session, a SALOME application is started
  15 on a cluster using the batch manager.  Therefore there are two SALOME installations:  one on the user’s machine
  16 and the other on the cluster.  The user must have an account on the cluster, and must have a read/write access to it.
  17 He must also have correctly configured the connection protocol from his own station, regardless of whether he uses rsh or ssh.
  18
  19 The remainder of this chapter describes the different run steps.  Firstly, a SALOME application is run on
  20 the user’s machine using a CatalogResources.xml file containing the description of the target batch
  21 machine (see :ref:`catalogresources_batch`).  The user then calls the SALOME service to run it on the batch machine.
  22 The user does this by describing input and output files for the SALOME application running in batch
  23 and for the Python script to be run (see :ref:`service_launcher`).  This service then starts the SALOME
  24 application defined in the CatalogResources.xml file on the batch machine and executes the Python
  25 command file (see :ref:`salome_clusteur_batch`).
  26
  27 .. _catalogresources_batch:
  28
  29 Description of the cluster using the CatalogResource.xml file
  30 --------------------------------------------------------------------
  31
  32 The CatalogResources.xml file contains the description of the different distributed calculation
  33 resources (machines) that SALOME can use to launch its containers.  It can also contain the description
  34 of clusters administered by batch managers.
  35
  36 The following is an example of description of a cluster:
  37
  38 .. code-block:: xml
  39
  40   <machine hostname="clusteur1"
  41            alias="frontal.com"
  42            protocol="ssh"
  43            userName="user"
  44            mode="batch"
  45            batch="lsf"
  46            mpi="prun"
  47            appliPath="/home/user/applis/batch_exemples"
  48            batchQueue="mpi1G_5mn_4p"
  49            userCommands="ulimit -s 8192"
  50            preReqFilePath="/home/ribes/SALOME5/env-prerequis.sh"
  51            OS="LINUX"
  52            CPUFreqMHz="2800"
  53            memInMB="4096"
  54            nbOfNodes="101"
  55            nbOfProcPerNode="2"/>
  56
  57 The following is the description of the different fields used when launching a batch:
  58  - **hostname**:  names the cluster for SALOME commands.  Warning, this name is not used to identify the cluster front end.
  59  - **alias**:  names the cluster front end.  It must be possible to reach this machine name using the protocol
  60    defined in the file.  This is the machine that will be used to start the batch session.
  61  - **protocol**:  fixes the connection protocol between the user session and the cluster front end.
  62    The possible choices are rsh or ssh.
  63  - **userName**:  user name on the cluster.
  64  - **mode**:  identifies the description of the machine as a cluster managed by a batch.  The possible choices are
  65    interactive and batch.  The batch option must be chosen for the machine to be accepted as a cluster with a batch manager.
  66  - **batch**:  identifies the batch manager.  Possible choices are:  pbs, lsf or sge.
  67  - **mpi**:  SALOME uses mpi to Start the SALOME session and containers on different calculation nodes allocated
  68    by the batch manager.  Possible choices are lam, mpich1, mpich2, openmpi, slurm and prun.  Note that some
  69    batch managers replace the mpi launcher with their own launcher for management of resources, which is the
  70    reason for the slurm and prun options.
  71  - **appliPath**:  contains the path of the SALOME application previously installed on the cluster.
  72
  73 There are two optional fields that can be useful depending on the configuration of clusters.
  74  - **batchQueue**:  specifies the queue of the batch manager to be used
  75  - **userCommands**:  to insert the sh code when SALOME is started.  This code is executed on all nodes.
  76
  77 .. _service_launcher:
  78
  79
  80 Using the Launcher service
  81 -------------------------------
  82 The Launcher service is a CORBA server started by the SALOME kernel.  Its interface is described in the
  83 **SALOME_ContainerManager.idl** file of the kernel.
  84
  85 Its interface is as follows:
  86
  87 ::
  88
  89   interface SalomeLauncher
  90   {
  91     long submitJob( in string xmlExecuteFile,
  92                     in string clusterName ) raises (SALOME::SALOME_Exception);
  93     long submitSalomeJob( in string fileToExecute,
  94                           in FilesList filesToExport,
  95                           in FilesList filesToImport,
  96                           in BatchParameters batch_params,
  97                           in MachineParameters params )
  98                                             raises (SALOME::SALOME_Exception);
  99
 100     string queryJob ( in long jobId, in MachineParameters params )
 101                                             raises (SALOME::SALOME_Exception);
 102     void   deleteJob( in long jobId, in MachineParameters params )
 103                                             raises (SALOME::SALOME_Exception);
 104
 105     void getResultsJob( in string directory, in long jobId,
 106                         in MachineParameters params )
 107                                             raises (SALOME::SALOME_Exception);
 108
 109     boolean testBatch(in MachineParameters params)
 110                                             raises (SALOME::SALOME_Exception);
 111
 112     void Shutdown();
 113     long getPID();
 114   };
 115
 116 The **submitSalome.job** method launches a SALOME application on a batch manager.
 117 This method returns a **job** identifier that is used in the **query.Job**, **delete.Job** and **getResults.Job** methods.
 118
 119 The following is an example using this method:
 120
 121 ::
 122
 123   # Initialisation
 124   import os
 125   import Engines
 126   import orbmodule
 127   import SALOME
 128
 129   clt = orbmodule.client()
 130   cm  = clt.Resolve('SalomeLauncher')
 131
 132   # The python script that will be launched on the cluster
 133   script = '/home/user/Dev/Install/BATCH_EXEMPLES_INSTALL/tests/test_Ex_Basic.py'
 134
 135   # Preparation of arguments for submitSalomeJob
 136   filesToExport = []
 137   filesToImport = ['/home/user/applis/batch_exemples/filename']
 138   batch_params = Engines.BatchParameters('', '00:05:00', '', 4)
 139   params = Engines.MachineParameters('','clusteur1','','','','',[],'',0,0,1,1,0,
 140                                      'prun','lsf','','',4)
 141
 142   # Using submitSalomeJob
 143   jobId = cm.submitSalomeJob(script, filesToExport, filesToImport,
 144                              batch_params, params)
 145
 146 The following is a description of the different arguments of **submitSalomeJob**:
 147
 148 - **fileToExecute**:  this is the python script that will be executed in the SALOME application on the cluster.
 149   This argument contains the script path **on** the local machine and **not on** the cluster.
 150 - **filesToExport**:  this is a list of files that will be copied into the run directory on the cluster
 151 - **filesToImport**:  this is a list of files that will be copied from the cluster onto the user machine when the **getResultsJob** method is called.
 152 - **batch_params**:  this is a structure that contains information that will be given to the batch manager.  This structure is
 153   composed of four arguments.  The first argument will be used to give the name of the directory in which it is required that
 154   the files and SALOME application should be run (this function is not available at the moment).  The second argument
 155   is the requested time.  It is expressed in the form hh:min:se, for example 01:30:00.  The third argument is the required memory.
 156   It is expressed in the form of 32gb or 512mb.  Finally, the final argument describes the requested number of processors.
 157 - **params**:  contains the description of the required machine. In this case, the cluster on which the application is to be launched
 158   is clearly identified.
 159
 160 The **queryJob** method should be used to determine the state of the Job.  There are three possible states, namely **waiting**,
 161 **running** and **terminated**.
 162 The following is an example of how this method is used:
 163
 164 ::
 165
 166   status = cm.queryJob(jobId, params)
 167   print jobId,' ',status
 168   while(status != 'DONE'):
 169     os.system('sleep 10')
 170     status = cm.queryJob(jobId, params)
 171     print jobId,' ',status
 172
 173 The job identifier supplied by the **submitSalomeJob** method is used in this method together with the **params** structure.
 174
 175 Finally, the **getResultsJob** method must be used to retrieve application results.
 176 The following is an example of how to use this method:
 177 ::
 178
 179   cm.getResultsJob('/home/user/Results', jobId, params)
 180
 181 The first argument contains the directory in which the user wants to retrieve the results.  The user automatically receives
 182 logs from the SALOME application and the different containers that have been started, in addition to those defined in the **filesToImport** list.
 183
 184 .. _salome_clusteur_batch:
 185
 186 SALOME on the batch cluster
 187 ----------------------------------------------------
 188 SALOME does not provide a service for automatic installation of the platform from the user’s personal machine, for the moment.
 189 Therefore, SALOME (KERNEL + modules) and a SALOME application have to be installed beforehand on the cluster.
 190 In the example used in this documentation, the application is installed in the directory **/home/user/applis/batch_exemples**.
 191
 192 When the **submitSalomeJob** method is being used, SALOME creates a directory in $HOME/Batch/**run_date**.
 193 The various input files are copied into this directory.
 194
 195 SALOME constraints on batch managers
 196 ----------------------------------------------------
 197 SALOME needs some functions that the batch manager must authorise before SALOME applications can be run.
 198
 199 SALOME runs several processor **threads** for each CORBA server that is started.
 200 Some batch managers can limit the number of threads to a number that is too small, or the batch manager may configure the size
 201 of the thread stack so that it is too high.
 202 In our example, the user fixes the size of the thread stack in the **userCommands** field in the CatalogResources.xml file.
 203
 204 SALOME starts processes in the session on machines allocated by the batch manager.  Therefore, the batch manager must authorise this.
 205 Finally, SALOME is based on the use of dynamic libraries and the **dlopen** function.  The system must allow this.