complex - Grid Engine complexes configuration file format


       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

       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:


   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:


       (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

       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.


       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):

       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.

       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.

       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:

       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 sge_types(5) for a
          format description.

       o  With MEMORY memory size specifiers are allowed. Refer to
          sge_types(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 are used for wildcard
          regular boolean expression matching.  Please see the sge_types(5)
          man page for expression definition.

           -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"

       o  CSTRING is like STRING except comparisons are case insensitive.

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

       o  HOST is like CSTRING but the expression must match a valid host

       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.

       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).

       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.

       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.

       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


       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)


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

SGE 8.1.3pre                      2011-12-04                        COMPLEX(5)

Man(1) output converted with man2html