doc/resource.rst

   1 Managing SALOME resources with the JOBMANAGER
   2 =============================================
   3
   4 The JOBMANAGER provides a GUI to manage SALOME resources.
   5 Later in the chapter, we use resource for SALOME resource.
   6
   7 Definition of a SALOME resource
   8 +++++++++++++++++++++++++++++++
   9
  10 A resource is the SALOME abstraction for computer.
  11 A resource contains three different kinds of information:
  12
  13 - A name.
  14 - A physical description of the computer.
  15 - A description of a SALOME installation in the computer.
  16
  17 A resource's name could be different from the computer name since
  18 different SALOME installation could coexist in the computer.
  19
  20 Types and usage of SALOME resources
  21 -----------------------------------
  22
  23 In SALOME, resources can be used in two different ways:
  24
  25 - Resources can be used to launch containers, either semi-automatically with
  26   YACS or directly by calling the method GiveContainer of the Container
  27   Manager (service provided by the KERNEL).
  28 - Resources can be used to launch jobs, either with the JOBMANAGER module or
  29   with the underlying Launcher service (provided by the KERNEL).
  30
  31 Those two kinds of resources are both managed by the Resource Manager (KERNEL
  32 service). They can both be created and edited with the resource management
  33 interface of the JOBMANAGER. This is why some informations describing the
  34 resources (e.g. CPU clock) are in fact not used at all by the JOBMANAGER to
  35 launch jobs. If you just want to create a resource to launch jobs, you can
  36 safely ignore those parameters.
  37
  38 Physical description of the computer
  39 ------------------------------------
  40
  41 A resource contains a physical description of the computer.
  42 These informations are used by the Resource Manager to choose and use a
  43 resource when a container (in YACS) or a job (in JOBMANAGER) has to be
  44 launched.
  45
  46 The description of each attribute is given in the table below.
  47
  48 **Warning:** The *mandatory* part is for using the resource with the JOBMANAGER.
  49
  50 ========================== ================ =============================================================
  51 **Attribute**              **Mandatory**    **Description**
  52 ========================== ================ =============================================================
  53 **hostname**               Yes              Network name of the computer. If the computer is a cluster,
  54                                             you have to give the head node name.
  55 **protocol**               Yes              Network protocol to use for creating connections
  56                                             (ssh or rsh).
  57 **username**               Yes              User login on the computer.
  58 **Batch Manager**          No               Type of batch manager installed in the resource. Use *None*
  59                                             if the resource is a single computer. Some batch managers are
  60                                             indicated with "limited support". This means that their
  61                                             support in JOBMANAGER is either new and experimental or
  62                                             old and obsolete. In both cases, they have not been fully
  63                                             validated in this version and thus can be buggy or even not
  64                                             work at all.
  65 **iprotocol**              Yes              Internal protocol to use on a cluster (i.e. the command used
  66                                             to launch processes on other nodes of the cluster).
  67 **mpiImpl**                No               MPI implementation to use.
  68 **OS**                     No               Operating system name, e.g.: Linux, Windows (not used by
  69                                             JOBMANAGER)
  70 **nb_node**                No               Number of nodes in the computer (not used by JOBMANAGER)
  71 **nb_proc_per_node**       No               Number of processors or cores in each node (only used with
  72                                             PBS batch manager)
  73 **mem_mb**                 No               Memory per node in megabytes (not used by JOBMANAGER)
  74 **cpu_clock**              No               Clock rate in gigahertz of the computer's processor(s) (not
  75                                             used by JOBMANAGER)
  76 **Can launch batch jobs**  Yes              Indicate if the resource can be used to launch batch jobs
  77                                             (mandatory to use the resource with JOBMANAGER)
  78 **Can run containers**     No               Indicate if the resource can be used to run containers
  79                                             interactively (from a YACS schema running on the local
  80                                             machine for instance)
  81 **Working Directory**      No               Base working directory for the resource. The working
  82                                             directories for the jobs will by default be created as
  83                                             subdirectories of this directory.
  84 ========================== ================ =============================================================
  85
  86 SALOME installation description
  87 -------------------------------
  88
  89 A resource could contain a SALOME installation description.
  90 The description of each attribute is given in the table below.
  91
  92 **Warning:** Attribute **applipath** is *mandatory* with JOBMANAGER SALOME related type of job.
  93
  94 ========================== =============================================================
  95 **Attribute**              **Description**
  96 ========================== =============================================================
  97 **applipath**              Directory of the SALOME application to use on the resource
  98 **componentList**          List of the SALOME components available in the SALOME
  99                            application (not used by JOBMANAGER)
 100 ========================== =============================================================
 101
 102 Where is the resource file?
 103 ---------------------------
 104
 105 Resources are located into a XML resource file. SALOME tries to find this file
 106 in three different locations:
 107
 108 1. If **USER_CATALOG_RESOURCES_FILE** env file is defined, SALOME uses this file.
 109 2. If not, in the SALOME application directory: $APPLIPATH/CatalogResources.xml.
 110 3. If not, in the directory of the installation of SALOME KERNEL:
 111    $KERNEL_ROOT_DIR/share/salome/resources/kernel/CatalogResources.xml.
 112
 113 By default, the resource manager creates a resource named "localhost" with the hostname
 114 of the local computer.
 115
 116 JOBMANAGER resource management GUI
 117 ++++++++++++++++++++++++++++++++++
 118
 119 The JOBMANAGER provides a panel to manage user's resources. This panel is shown in the
 120 figure :ref:`figure_jobmanager_resource_1`. The panel provides some buttons and a list
 121 that shows the available resources. You have to select one resource to enable some buttons.
 122
 123 .. _figure_jobmanager_resource_1:
 124
 125 .. figure:: images/jobmanager_resource_1.png
 126   :align: center
 127
 128   **JOBMANAGER resource management panel**
 129
 130 The description of each button is given in the table below.
 131
 132 ========================== =============================================================
 133 **Button**                  **Description**
 134 ========================== =============================================================
 135 **Refresh Resource List**  Resource file is read to refresh the list.
 136 **Show**                   Show the selected resource.
 137 **Edit**                   Edit the selected resource. The resource is saved is **Ok**
 138                            is clicked. If the resource name is changed, a new resource
 139                            is added.
 140 **Add**                    Add a new resource.
 141 **Remove**                 Remove the selected resource.
 142 ========================== =============================================================
 143
 144 The figure :ref:`figure_jobmanager_resource_2` shows the panel of a resource. This panel
 145 shows all the information of a resource.
 146
 147 .. _figure_jobmanager_resource_2:
 148
 149 .. figure:: images/jobmanager_resource_2.png
 150   :align: center
 151
 152   **JOBMANAGER resource panel**
 153
 154 Two usage scenarios of SALOME's resource with the JOBMANAGER
 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 156
 157 This section describes to common scenarios for understanding how to describe
 158 a resource for the JOBMANAGER.
 159
 160 Using a single machine
 161 ----------------------
 162
 163 In this scenario, you need to launch a job on your computer or another single computer
 164 available in your network.
 165
 166 To launch a **command** job you need to fill the following attributes:
 167
 168 - **hostname**
 169 - **protocol** = *ssh*
 170 - **username**
 171 - **Batch Manager** = *None*
 172 - **Can launch batch jobs** = *yes*
 173
 174 **Warning:** You have to configure ssh for allowing ssh commands without asking
 175 interactive password (RSA or DSA keys).
 176
 177 To launch a **SALOME** type of job, you also need to fill the following attributes:
 178
 179 - **applipath**
 180
 181 Using a cluster managed by a batch system
 182 -----------------------------------------
 183
 184 In this scenario, you need to launch a job into a cluster managed by a batch system.
 185
 186 To launch a **command** job you need to fill the following attributes:
 187
 188 - **hostname**
 189 - **protocol**
 190 - **username**
 191 - **Batch Manager**
 192 - **iprotocol**
 193 - **nb_proc_per_node** (only with PBS batch manager)
 194 - **Can launch batch jobs** = *yes*
 195
 196 **Warning:** You have to configure ssh for allowing ssh commands without asking
 197 interactive password (RSA or DSA keys) between your computer and the cluster and
 198 eventually between the cluster's nodes.
 199
 200 To launch a **SALOME** command job you also need to fill the following attributes:
 201
 202 - **applipath**