SGE_PE(5)                  Grid Engine File Formats                  SGE_PE(5)



NNAAMMEE
       sge_pe - Grid Engine parallel environment configuration file format

DDEESSCCRRIIPPTTIIOONN
       Parallel environments are parallel programming and runtime environments
       allowing for the execution of shared memory or distributed memory  par-
       allelized applications. Parallel environments usually require some kind
       of setup to  be  operational  before  starting  parallel  applications.
       Examples  for  common  parallel environments are shared memory parallel
       operating systems and the distributed memory environments Parallel Vir-
       tual Machine (PVM) or Message Passing Interface (MPI).

       _s_g_e___p_e  allows  for  the definition of interfaces to arbitrary parallel
       environments.  Once a parallel environment is defined or modified  with
       the --aapp or --mmpp options to _q_c_o_n_f(1) the environment can be requested for
       a job via the --ppee switch to _q_s_u_b(1) together with a request of a  range
       for  the  number  of parallel process to be allocated by the job. Addi-
       tional --ll options may be used to specify the job requirement to further
       detail.

FFOORRMMAATT
       The format of a _s_g_e___p_e file is defined as follows:

   ppee__nnaammee
       The  name  of  the  parallel environment. To be used in the _q_s_u_b(1) --ppee
       switch.

   sslloottss
       The number of parallel processes being allowed to run  in  total  under
       the parallel environment concurrently.

   uusseerr__lliissttss
       A  comma separated list of user access list names (see _a_c_c_e_s_s___l_i_s_t(5)).
       Each user contained in at least one of the enlisted  access  lists  has
       access  to the parallel environment. If the uusseerr__lliissttss parameter is set
       to NONE (the default) any user has access being not explicitly excluded
       via  the xxuusseerr__lliissttss parameter described below.  If a user is contained
       both in an access list enlisted in xxuusseerr__lliissttss and uusseerr__lliissttss the  user
       is denied access to the parallel environment.

   xxuusseerr__lliissttss
       The  xxuusseerr__lliissttss parameter contains a comma separated list of so called
       user access lists as described in _a_c_c_e_s_s___l_i_s_t(5).  Each user  contained
       in  at  least one of the enlisted access lists is not allowed to access
       the parallel environment. If the xxuusseerr__lliissttss parameter is set  to  NONE
       (the  default)  any  user has access. If a user is contained both in an
       access list enlisted in xxuusseerr__lliissttss and uusseerr__lliissttss the user  is  denied
       access to the parallel environment.

   ssttaarrtt__pprroocc__aarrggss
       The  invocation  command  line of a start-up procedure for the parallel
       environment. The start-up procedure is invoked by _s_g_e___s_h_e_p_h_e_r_d(8) prior
       to executing the job script. Its purpose is to setup the parallel envi-
       ronment correspondingly to its needs.  An optional prefix "user@" spec-
       ifies  the user under which this procedure is to be started.  The stan-
       dard output of the start-up procedure is redirected to  the  file  _R_E_Q_-
       _N_A_M_E.po_J_I_D  in  the job's working directory (see _q_s_u_b(1)), with _R_E_Q_N_A_M_E
       being the name of the job as displayed by _q_s_t_a_t(1) and  _J_I_D  being  the
       job's  identification  number.   Likewise, the standard error output is
       redirected to _R_E_Q_N_A_M_E.pe_J_I_D
       The following special variables being expanded at runtime can  be  used
       (besides  any  other  strings which have to be interpreted by the start
       and stop procedures) to constitute a command line:

       _$_p_e___h_o_s_t_f_i_l_e
              The pathname of a file containing a detailed description of  the
              layout  of  the parallel environment to be setup by the start-up
              procedure. Each line of the file refers to a host on which  par-
              allel  processes  are  to  be  run. The first entry of each line
              denotes the hostname, the second entry the  number  of  parallel
              processes to be run on the host, the third entry the name of the
              queue, and the fourth entry a processor range to be used in case
              of a multiprocessor machines.

       _$_h_o_s_t  The  name  of  the host on which the start-up or stop procedures
              are started.

       _$_j_o_b___o_w_n_e_r
              The user name of the job owner.

       _$_j_o_b___i_d
              Grid Engine's unique job identification number.

       _$_j_o_b___n_a_m_e
              The name of the job.

       _$_p_e    The name of the parallel environment in use.

       _$_p_e___s_l_o_t_s
              Number of slots granted for the job.

       _$_p_r_o_c_e_s_s_o_r_s
              The pprroocceessssoorrss string as contained in  the  queue  configuration
              (see  _q_u_e_u_e___c_o_n_f(5)) of the master queue (the queue in which the
              start-up and stop procedures are started).

       _$_q_u_e_u_e The cluster queue of the master queue instance.

   ssttoopp__pprroocc__aarrggss
       The invocation command line of a shutdown procedure  for  the  parallel
       environment. The shutdown procedure is invoked by _s_g_e___s_h_e_p_h_e_r_d(8) after
       the job script has finished. Its purpose is to stop the parallel  envi-
       ronment  and  to remove it from all participating systems.  An optional
       prefix "user@" specifies the user under which this procedure is  to  be
       started.   The standard output of the stop procedure is also redirected
       to the file _R_E_Q_N_A_M_E.po_J_I_D in the job's working directory (see _q_s_u_b(1)),
       with _R_E_Q_N_A_M_E being the name of the job as displayed by _q_s_t_a_t(1) and _J_I_D
       being the job's identification number.  Likewise,  the  standard  error
       output is redirected to _R_E_Q_N_A_M_E.pe_J_I_D
       The  same  special variables as for ssttaarrtt__pprroocc__aarrggss can be used to con-
       stitute a command line.

   aallllooccaattiioonn__rruullee
       The allocation rule is  interpreted  by  _s_g_e___s_c_h_e_d_d(8)  and  helps  the
       scheduler  to  decide  how  to  distribute parallel processes among the
       available machines. If, for instance, a parallel environment  is  built
       for  shared memory applications only, all parallel processes have to be
       assigned to a single machine, no matter how much suitable machines  are
       available.   If, however, the parallel environment follows the distrib-
       uted memory paradigm, an even distribution of processes among  machines
       may be favorable.
       The  current  version  of  the scheduler only understands the following
       allocation rules:

       <<iinntt>>:    An integer number fixing the number of processes per host. If
                 the  number  is  1, all processes have to reside on different
                 hosts. If the special denominator $$ppee__sslloottss is used, the full
                 range  of  processes as specified with the _q_s_u_b(1) --ppee switch
                 has to be allocated on a single host (no matter  which  value
                 belonging  to  the  range is finally chosen for the job to be
                 allocated).

       $$ffiillll__uupp: Starting from the best  suitable  host/queue,  all  available
                 slots are allocated. Further hosts and queues are "filled up"
                 as long as a job still requires slots for parallel tasks.

       $$rroouunndd__rroobbiinn:
                 From all suitable hosts a single slot is allocated until  all
                 tasks  requested  by the parallel job are dispatched. If more
                 tasks are requested than suitable hosts are found, allocation
                 starts  again  from  the  first  host.  The allocation scheme
                 walks through suitable hosts in a best-suitable-first  order.

   ccoonnttrrooll__ssllaavveess
       This  parameter can be set to TRUE or FALSE (the default). It indicates
       whether Grid Engine is the creator of the slave  tasks  of  a  parallel
       application via _s_g_e___e_x_e_c_d(8) and _s_g_e___s_h_e_p_h_e_r_d(8) and thus has full con-
       trol over all processes in a parallel application, which enables  capa-
       bilities  such  as resource limitation and correct accounting. However,
       to gain control over the slave  tasks  of  a  parallel  application,  a
       sophisticated  PE  interface  is required, which works closely together
       with Grid Engine facilities. Such PE interfaces are  available  through
       your local Grid Engine support office.

       Please  set  the  control_slaves  parameter  to  false for all other PE
       interfaces.

   jjoobb__iiss__ffiirrsstt__ttaasskk
       This parameter is only checked if ccoonnttrrooll__ssllaavveess (see above) is set  to
       TRUE and thus Grid Engine is the creator of the slave tasks of a paral-
       lel application via _s_g_e___e_x_e_c_d(8) and _s_g_e___s_h_e_p_h_e_r_d(8).  In this case,  a
       sophisticated  PE  interface  is required closely coupling the parallel
       environment and Grid Engine. The  documentation  accompanying  such  PE
       interfaces will recommend the setting for jjoobb__iiss__ffiirrsstt__ttaasskk.

       The jjoobb__iiss__ffiirrsstt__ttaasskk parameter can be set to TRUE or FALSE. A value of
       TRUE indicates that the Grid Engine job script already contains one  of
       the tasks of the parallel application, while a value of FALSE indicates
       that the job script (and its child processes) is not part of the paral-
       lel program.


   uurrggeennccyy__sslloottss
       For  pending  jobs  with a slot range PE request the number of slots is
       not determined. This setting specifies the method to be  used  by  Grid
       Engine to assess the number of slots such jobs might finally get.

       The assumed slot allocation has a meaning when determining the resource
       request based priority contribution for numeric resources as  described
       in  _s_g_e___p_r_i_o_r_i_t_y(5)  and is displayed when _q_s_t_a_t(1) is run without --gg tt
       option.

       The following methods are supported:

       <<iinntt>>:    The specified integer number is directly used as  prospective
                 slot amount.

       mmiinn:      The slot range minimum is used as prospective slot amount. If
                 no lower bound is specified with the range 1 is assumed.

       mmaaxx:      The of the slot range maximum is  used  as  prospective  slot
                 amount.   If  no  upper bound is specified with the range the
                 absolute maximum possible due to the PE's  sslloottss  setting  is
                 assumed.

       aavvgg:      The average of all numbers occurring within the jobs PE range
                 request is assumed.

RREESSTTRRIICCTTIIOONNSS
       NNoottee, that the functionality of the start-up, shutdown  and  signalling
       procedures remains the full responsibility of the administrator config-
       uring the parallel environment.  Grid Engine  will  just  invoke  these
       procedures  and  evaluate  their  exit status. If the procedures do not
       perform their tasks properly or if the parallel environment or the par-
       allel  application  behave  unexpectedly,  Grid  Engine has no means to
       detect this.

SSEEEE AALLSSOO
       _s_g_e___i_n_t_r_o(1),  _q_c_o_n_f(1),  _q_d_e_l(1),  _q_m_o_d(1),  _q_s_u_b(1),  _a_c_c_e_s_s___l_i_s_t(5),
       _s_g_e___q_m_a_s_t_e_r(8), _s_g_e___s_c_h_e_d_d(8), _s_g_e___s_h_e_p_h_e_r_d(8).

CCOOPPYYRRIIGGHHTT
       See _s_g_e___i_n_t_r_o(1) for a full statement of rights and permissions.



GE 6.0                   $Date: 2005/11/23 21:49:49 $                SGE_PE(5)
