NAME
     complex - Grid Engine complexes configuration file format

DESCRIPTION
     Complex reflects the format of  the  Grid  Engine  complexes
     configuration.   The  definition  of  complexes provides all
     pertinent information concerning the resource  attributes  a
     user  may  request  for a Grid Engine job via the qsub(1) -l
     option and for the interpretation of these parameters within
     the Grid Engine system.

     The complexes configuration files  should  not  be  accessed
     directly.  In order to add or modify complexes, the qconf(1)
     options -Ac, -ac, -Mc and -mc should be used instead.  While
     the -Ac and -Mc options take a complex configuration file as
     an argument, the -ac and -mc  options  bring  up  an  editor
     filled  in with a template complex configuration or the con-
     figuration of an existing complex.

     The Grid Engine  complexes  object  integrates  4  different
     types of complexes:

  The Queue Complex
     It is referenced by the special name "queue".

     In its default form it contains a selection of parameters in
     the  queue  configuration  as defined in queue_conf(5).  The
     queue configuration parameters being requestable for  a  job
     by the user in principal are:

          qname
          hostname
          priority
          notify
          calendar
          max_migr_time
          max_no_migr
          min_cpu_interval
          tmpdir
          seq_no
          s_rt
          h_rt
          s_cpu
          h_cpu
          s_data
          h_data
          s_stack
          h_stack
          s_core
          h_core
          s_rss
          h_rss

     The queue complex can be extended if further attributes  are
     intended  to  be available for each queue. The queue complex
     defines the characteristics (such as the data type)  of  the
     attributes  it  contains. A value setting for the queue com-
     plex attributes is defined by the  queue  configuration  for
     each  queue  in  case  of  the  standard parameters enlisted
     above, or by the complex_values entry in  the  queue  confi-
     guration  (see queue_conf(5) for details) if a parameter has
     been added to the default queue complex.  If  no  definition
     for  the value in the complex_values entry of the queue con-
     figuration is given in the latter case, the value is set  as
     defined by the value field described below.

  The Host Complex
     It is referenced by the special name "host" and contains the
     characteristics  definition  of  all  attributes  which  are
     intended to be managed on a host basis. The standard set  of
     host  related  attributes consists of two categories, but it
     may be enhanced like the queue complex as  described  above.
     The  first  category is built by several queue configuration
     attributes which are particularly suitable to be managed  on
     a host basis. These attributes are:

          slots
          s_vmem
          h_vmem
          s_fsize
          h_fsize
     (please refer to queue_conf(5) for details).

     Note: Defining these attributes in the host  complex  is  no
     contradiction  to  having  them also in the queue configura-
     tion. It allows maintaining the corresponding resources on a
     host level and at the same time on a queue level. Total vir-
     tual free memory (h_vmem) can be managed  for  a  host,  for
     example,  and a subset of the total amount can be associated
     with a queue on that host.

     The second attribute category in the standard  host  complex
     are  the default load values Every sge_execd(8) periodically
     reports load to sge_qmaster(8).  The  reported  load  values
     are  either the standard Grid Engine load values such as the
     CPU load average (see uptime(1)) or load values  defined  by
     the  Grid Engine administration (see the load_sensor parame-
     ter in the cluster configuration sge_conf(5)  and  the  Grid
     Engine  Installation  and Administration Guide for details).
     The characteristics definition for the standard load  values
     is  part  of  the  default host complex, while administrator
     defined load values require extension of the  host  complex.
     Please  refer to the file <sge_root>/doc/load_parameters.asc
     for detailed information on the standard set of load values.

     The host complex commonly is not only  extended  to  include
     non-standard  load  parameters,  but  also  to  manage  host
     related resources such as the number  of  software  licenses
     being  assigned  to  a host or the available disk space on a
     host local filesystem.

     A concrete value for a particular host complex attribute  is
     determined  by  either  an associated queue configuration in
     the case of the queue configuration  derived  attributes,  a
     reported load value or the explicit definition of a value in
     the complex_values entry of the  corresponding  host  confi-
     guration (see host_conf(5)).  If none of the above is avail-
     able (e.g. the value is supposed to be a load parameter, but
     sge_execd(8) does not report a load value for it), the value
     field described below is used.

  The Global Complex
     It is referenced by the special name "global".

     The entries configured in the global complex refer to  clus-
     ter  wide  resource attributes, such as the number of avail-
     able "floating" licenses of a  particular  software  or  the
     free disk space on a network wide available filesystem. Glo-
     bal resource attributes can also  be  associated  with  load
     reports, if the corresponding load report contains the "GLO-
     BAL" identifier (see the corresponding section in  the  Grid
     Engine  Installation  and Administration Guide for details).
     Global load values can be reported  from  any  host  in  the
     cluster.  There  are  no global load values reported by Grid
     Engine by default and hence there is no default global  com-
     plex configuration.

     Concrete values for global  complex  attributes  are  either
     determined  by global load reports or by explicit definition
     in the complex_values parameter of the "global" host  confi-
     guration  (see  host_conf(5)).   If  none of both is present
     (e.g. a load value has not  yet  been  reported)  the  value
     field described below is used.

  User Defined Complexes
     By  setting  up  user  defined  complexes  the  Grid  Engine
     administration  has  the ability to extend the set of attri-
     butes managed by Grid Engine while restricting the influence
     of  those  attributes  to  particular queues and/or hosts. A
     user complex is just a named collection  of  attributes  and
     the  corresponding definition as to how these attributes are
     to be handled by Grid Engine. One  or  more  of  these  user
     defined  complexes  can  be attached to a queue and/ or host
     via the complex_list queue and host configuration  parameter
     (see   queue_conf(5)   and  host_conf(5)).   The  attributes
     defined in all assigned complexes become  available  to  the
     queue  and  the host respectively in addition to the default
     complex attributes.

     Concrete values for user defined complexes have to be set by
     the  complex_values  parameter  in the queue and host confi-
     guration or otherwise the value  field  described  below  is
     used.

FORMAT
     The principal format of a complex configuration is that of a
     tabulated list. Each line starting with a '#' character is a
     comment line. Each line despite  comment  lines  define  one
     element  of  the complex. A element definition line consists
     of the following 6 column entries per line (in the order  of
     appearance):

  name
     The name of the complex element to be used to  request  this
     attribute  for  a job in the qsub(1) -l option. An attribute
     name may appear only once across  all  complexes,  i.e.  the
     complex attribute definition is unique.

  shortcut
     A shortcut for name which may also be used to  request  this
     attribute  for  a job in the qsub(1) -l option. An attribute
     shortcut may appear only once across all complexes, so as to
     avoid  the possibility of ambiguous complex attribute refer-
     ences.

  type
     This setting determines how the corresponding values are  to
     be  treated Grid Engine internally in case of comparisons or
     in case of load scaling for the load complex entries:

     o  With INT only raw integers are allowed.

     o  With DOUBLE floating point numbers  in  double  precision
        (decimal and scientific notation) can be specified.

     o  With  TIME  time  specifiers  are   allowed.   Refer   to
        queue_conf(5) for a format description.

     o  With MEMORY memory size specifiers are allowed. Refer  to
        queue_conf(5) for a format description.

     o  With BOOL the strings TRUE and FALSE  are  allowed.  When
        used in a load formula (refer to sched_conf(5) ) TRUE and
        FALSE get mapped into '1' and '0'.

     o  With STRING all strings are allowed and strcmp(3) is used
        for comparisons.

     o  CSTRING  is  like  STRING  except  comparisons  are  case
        insensitive.


     o  HOST is like CSTRING but the string must be a valid host-
        name.

  value
     The value field is a pre-defined value setting for an attri-
     bute,  which  only  has  an  effect if it is not overwritten
     while attempting to  determine  a  concrete  value  for  the
     attribute with respect to a queue, a host or the Grid Engine
     cluster. The value field can be overwritten by

     o  the queue configuration values of a referenced queue.

     o  host specific and cluster related load values.

     o  explicit specification of a value via the  complex_values
        parameter   in  the  queue  or  host  configuration  (see
        queue_conf(5) and host_conf(5) for details.

     If none of above is applicable, value is set for the  attri-
     bute.

  relop
     The relation operator. The relation operator  is  used  when
     the  value  requested by the user for this parameter is com-
     pared against the corresponding  value  configured  for  the
     considered queues. If the result of the comparison is false,
     the job cannot run in this queue. Possible  relation  opera-
     tors  are  "==",  "<",  ">",  "<="  and ">=". The only valid
     operator for string type attributes is "==".

  requestable
     The entry can be used in a qsub(1) resource request if  this
     field  is  set  to 'y' or 'yes'.  If set to 'n' or 'no' this
     entry cannot be used by a user in order to request  a  queue
     or  a  class  of queues.  If the entry is set to 'forced' or
     'f' the attribute has to be requested by  a  job  or  it  is
     rejected.

  consumable
     The consumable parameter can be set  to  either  'yes'  ('y'
     abbreviated)  or 'no' ('n'). It can be set to 'yes' only for
     numeric attributes (INT, MEMORY, TIME - see type above).  If
     set  to  'yes' the consumption of the corresponding resource
     can be managed by Grid Engine internal bookkeeping. In  this
     case  Grid  Engine  accounts  for  the  consumption  of this
     resource for all running jobs and ensures that jobs are only
     dispatched if the Grid Engine internal bookkeeping indicates
     enough available consumable resources.  Consumables  are  an
     efficient means to manage limited resources such a available
     memory, free space on a file system,  network  bandwidth  or
     floating software licenses.

     Consumables can be combined with  default  or  user  defined
     load  parameters  (see  sge_conf(5)  and host_conf(5)), i.e.
     load values can be reported for consumable attributes or the
     consumable  flag  can  be  set for load attributes. The Grid
     Engine consumable resource management takes  both  the  load
     (measuring  availability  of  the resource) and the internal
     bookkeeping into account in this case, and makes  sure  that
     neither of both exceeds a given limit.

     To enable consumable resource management the  basic  availa-
     bility  of a resource has to be defined. This can be done on
     a cluster global, per host and per queue basis  while  these
     categories may supersede each other in the given order (i.e.
     a host can restrict availability of a cluster resource and a
     queue  can restrict host and cluster resources). The defini-
     tion  of  resource  availability  is  performed   with   the
     complex_values entry in host_conf(5) and queue_conf(5).  The
     complex_values definition of  the  "global"  host  specifies
     cluster  global consumable settings. To each consumable com-
     plex attribute in a complex_values list a value is  assigned
     which   denotes   the  maximum  available  amount  for  that
     resource. The internal bookkeeping will subtract  from  this
     total  the  assumed resource consumption by all running jobs
     as expressed through the jobs' resource requests.

     Note: Jobs can be forced to request a resource and  thus  to
     specify  their  assumed consumption via the 'force' value of
     the requestable parameter (see above).

     Note also: A default resource consumption value can be  pre-
     defined  by  the administrator for consumable attributes not
     explicitly requested by the job (see the  default  parameter
     below).  This is meaningful only if requesting the attribute
     is not enforced as explained above.

     See the Grid Engine Installation  and  Administration  Guide
     for examples on the usage of the consumable resources facil-
     ity.

  default
     Meaningful only for consumable complex attributes (see  con-
     sumable  parameter  above). Grid Engine assumes the resource
     amount denoted in the default  parameter  implicitly  to  be
     consumed  by jobs being dispatched to a host or queue manag-
     ing the consumable attribute. Jobs explicitly requesting the
     attribute via the -l option to qsub(1) override this default
     value.


SEE ALSO
     sge_intro(1), qconf(1),  qsub(1),  uptime(1),  host_conf(5),
     queue_conf(5), sge_execd(8), sge_qmaster(8), sge_schedd(8),
     Grid Engine Installation and Administration Guide.

COPYRIGHT
     See sge_intro(1) for a full statement of rights and  permis-
     sions.













































Man(1) output converted with man2html