Provided by: gridengine-common_8.1.9+dfsg-10build1_all bug

NAME

       complex - Grid Engine complexes configuration file format

DESCRIPTION

       Complex  reflects  the format of the Grid Engine complex configuration.  The definition of
       complex attributes 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 Grid Engine complex object defines all entries which  are  used  for  configuring  the
       global,  host,  and  queue objects. The system has a set of pre-defined entries, which are
       assigned to a host or queue by default.  In addition, the user can define new entries  and
       assign  them  to  one or more objects. Each load value has to have a corresponding complex
       entry object, which defines the type and the relational operator for it.

   Defining resource attributes
       The complex configuration should not be accessed directly.  In  order  to  add  or  modify
       complex  entries,  the qconf(1) options -Mc and -mc should be used instead.  While the -Mc
       option takes a complex configuration  file  as  an  argument  and  overrides  the  current
       configuration,  the  -mc  option  brings  up  an editor filled in with the current complex
       configuration.

       The provided list contains all definitions of resource attributes in the system. Adding  a
       new entry means to provide: name, shortcut, type, relop, requestable, consumable, default,
       and urgency. The fields are described below. Changing one is easily done by  updating  the
       field  to  change, and removing an entry by deleting its definition. An attribute can only
       be removed when it is not referenced in a host or queue object anymore.  Also  the  system
       has  a  set  of  default resource attributes which are always attached to a host or queue.
       They cannot be deleted, nor can the type of such an attribute be changed.

   Working with resource attributes
       Before a user can request a resource attribute it has to be attached to the global,  host,
       or  queue  object.  The  resource  attribute  exists  only for the objects to which it was
       attached.  If it is attached to the global object (qconf -me global),  it  exists  system-
       wide.   Attached  to  a  host  object  (qconf  -me host), it exists only on that host, and
       attached to queue object (qconf -mq queue), only on that queue.

       When an administrator attaches a resource attribute to an object, they also have to assign
       a value to it: the resource limit.  A load sensor may be run to adjust the value presented
       by a host down from that limit.  For instance, to support requests for free space  in  the
       /tmp  filesystem,  set  up  a  load  sensor to report the value (probably using df(1)) and
       attach a sufficiently high limit to each host, e.g.
       qconf -aattr exechost complex_values tmp_free=10T $(qconf -sel)

   Default queue resource attributes
       By default there is a selection of parameters in the queue  configuration  as  defined  in
       queue_conf(5).   The principal queue configuration parameters requestable for a job by the
       user are:

              qname
              hostname
              notify
              calendar
              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

   Default host resource attributes
       The standard set of host-related attributes consists of two categories. 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 configuration. It allows maintaining the corresponding resources on a
       host level, and at the same time on a queue level. Total virtual 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 is that  of  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
       parameter in the cluster  or  host  configuration  (see  sge_conf(5)  for  details).   The
       definition  of  characteristics  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  load_parameters(5) for detailed information on the standard set of load
       values.

   Overriding attributes
       An attribute can be assigned to the global object, host object, and queue  object  at  the
       same  time.  On the host level it might get its value from the user-defined resource limit
       and a load sensor. If the attribute is a consumable, we have, in addition to the  resource
       limit  and  its  load report at host level, also the internal usage which the system keeps
       track of. The merge is done as follows:

       In general an attribute can be overridden on a lower level
          - global by hosts and queues
          - hosts by queues and load values or resource limits on the same level.

       We have one limitation for overriding attributes based on their relational operator:

       != and == operators can only be overridden on the same level, not on a  lower  level.  The
       user-defined value always overrides the load value.

       >=,  >,  <=, and < operators can only be overridden when the new value is more restrictive
       than the old one.

       In the case of a consumable at host level which has also a load sensor, the system  checks
       for  the  current  usage, and if the internal accounting is more restrictive than the load
       sensor report, the internal value is kept; if the load sensor report is more  restrictive,
       that one is kept.

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 non-comment line defines one element
       of  the  complex.  Backslashes (\) be used to escape newline characters. The backslash and
       the newline are replaced with a space character before any interpretation.

       An element definition line consists of the following 8 column entries per line  (in  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. A complex attribute name (see complex_name in sge_types(5)) 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. A given shortcut may appear only once across all complexes,  so  as  to
       avoid the possibility of ambiguous complex attribute references.

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

       •  With INT only raw integers are allowed.

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

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

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

       •  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'.

       •  With  STRING  all  strings  are  allowed  and  are  used  for  wildcard regular boolean
          expression matching.  Please see the sge_types(5) man page for expression definition.

          Examples:
           -l arch="*x*|sol*"  :
                results in "arch=lx-x86" OR "arch=lx-amd64"
                   OR "arch=sol-amd64" OR ...
           -l arch="sol-x??"  :
                results in "arch=sol-x86" OR "arch=sol-x64" OR ...
           -l arch="lx2[246]-x86"  :
                results in "arch=lx22-x86" OR "arch=lx24-x86"
                   OR "arch=lx26-x86"
           -l arch="lx2[4-6]-x86"  :
                results in "arch=lx24-x86" OR "arch=lx25-x86"
                   OR "arch=lx26-x86"
           -l arch="lx2[24-6]-x86"  :
                results in "arch=lx22-x86" OR "arch=lx24-x86"
                   OR "arch=lx25-x86" OR "arch=lx26-x86"
           -l arch="!lx-x86&!sol-amd64"  :
                results in NEITHER "arch=lx-x86" NOR "arch=sol-amd64"
           -l arch="lx2[4|6]-amd64"  :
                results in "arch=lx24-amd64" OR "arch=lx26-amd64"

       •  CSTRING is like STRING except comparisons are case insensitive.

       •  RESTRING is the same as STRING for historical compatibility, but is deprecated and  may
          be removed in future..

       •  HOST is like CSTRING but the expression must match a valid host name.

   relop
       The  relation  operator is used when the value requested by the user for this parameter is
       compared 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
       operators are "==", "<", ">", "<=", ">=" and "EXCL". The only valid  operator  for  string
       type attributes is "==".

       The  "EXCL"  relation  operator  implements  exclusive  scheduling  and  is only valid for
       consumable boolean type attributes. Exclusive means the result of the comparison  is  only
       true  if  a job requests to be exclusive, and no other exclusive or non-exclusive job uses
       the complex. If the job does not request to be exclusive and no other exclusive  job  uses
       the complex the comparison is also true.

   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.

       To enable resource request enforcement the existence of the resource has  to  be  defined.
       This  can  be  done  on  a cluster global, per host and per queue basis. The definition of
       resource availability is performed with  the  complex_values  entry  in  host_conf(5)  and
       queue_conf(5).

   consumable
       The consumable parameter can be set to either 'yes' ('y' abbreviated), 'no' ('n') or 'JOB'
       ('j'). It can be set to 'yes' and 'JOB' only for numeric attributes (INT, DOUBLE,  MEMORY,
       TIME  -  see  type  above).  If set to 'yes' or 'JOB' 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
       as available memory, free space on a file system, network bandwidth or  floating  software
       licenses.

       A  consumable defined by 'y' is a per-slot consumable, which means the limit is multiplied
       by the number of slots being used by the job before being applied.  In  case  of  'j'  the
       consumable  is  a  per-job  consumable.  This  resource  is  debited as requested (without
       multiplication) from the allocated master queue. The resource need not  be  available  for
       the slave task queues.

       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 exceeds a given limit.

       To  enable  consumable resource management, the basic availability of a resource has to be
       defined. This can be done on a cluster global, per host and per  queue  basis,  and  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  definition  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 complex 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 a forced 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.

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

   urgency
       The urgency value allows influencing job priorities on a per-resource  base.  The  urgency
       value  effects  the addend for each resource when determining the resource request-related
       urgency contribution. For numeric type resource requests the addend is the product of  the
       urgency  value,  the  job's assumed slot allocation, and the per-slot request as specified
       via the -l option to qsub(1).  For string type requests the resource's  urgency  value  is
       directly used as addend. Urgency values are of type real. See under sge_priority(5) for an
       overview of job priorities.

SEE ALSO

       sge_intro(1),    sge_types(1),     qconf(1),     qsub(1),     uptime(1),     host_conf(5),
       load_parameters(5), queue_conf(5), sge_execd(8), sge_qmaster(8)

COPYRIGHT

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