'\" t
.\"___INFO__MARK_BEGIN__
.\"
.\" Copyright: 2004 by Sun Microsystems, Inc.
.\"
.\"___INFO__MARK_END__
.\"
.\" Some handy macro definitions [from Tom Christensen's man(1) manual page].
.\"
.de SB		\" small and bold
.if !"\\$1"" \\s-2\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
..
.\" For Emacs: "
.de T		\" switch to typewriter font
.ft CW		\" probably want CW if you don't have TA font
..
.\"
.de TY		\" put $1 in typewriter font
.if t .T
.if n ``\c
\\$1\c
.if t .ft P
.if n \&''\c
\\$2
..
.\"
.de M		\" man page reference
\\fI\\$1\\fR\\|(\\$2)\\$3
..
.de MO		\" other man page reference
\\fI\\$1\\fR\\|(\\$2)\\$3
..
.TH COMPLEX 5 2011-12-04 "xxRELxx" "xxQS_NAMExx File Formats"
.\"
.SH NAME
complex \- xxQS_NAMExx complexes configuration file format
.\"
.\"
.SH DESCRIPTION
.I Complex
reflects the format of the xxQS_NAMExx complex configuration.  The
definition of complex attributes provides all pertinent information
concerning the resource attributes a user may request for a xxQS_NAMExx
job via the
.M qsub 1
\fB\-l\fP option,
and for the interpretation of these parameters within the xxQS_NAMExx
system.
.PP
The xxQS_NAMExx 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.
.\"
.SS "\fBDefining resource attributes\fP"
The complex configuration should not be accessed directly.
In order to add or modify complex entries, the
.M qconf 1
options \-Mc and \-mc should be used instead.
While the \-Mc option takes a
.I complex
configuration file as an argument and overrides the current configuration, 
the \-mc option brings up an editor filled in with the current
.I complex
configuration.
.sp 1
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.
.PP
.\"
.SS "\fBWorking with resource attributes\fP"
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 \fIhost\fP), it exists
only on that host, and attached to queue object (qconf \-mq \fIqueue\fP),
only on that queue.
.sp 1
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
.M df 1 )
and attach a sufficiently high limit to each host, e.g.
.nf
qconf -aattr exechost complex_values tmp_free=10T $(qconf -sel)
.fi
.PP
.\"
.SS "\fBDefault queue resource attributes\fP"
By default there is a selection of parameters in the
queue configuration as defined in
.M queue_conf 5 .
The principal queue configuration parameters requestable for a job
by the user are:
.sp 1
.nf
.RS
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
.RE
.\"
.SS "\fBDefault host resource attributes\fP"
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:
.sp 1
.nf
.RS
slots
s_vmem
h_vmem
s_fsize
h_fsize
.RE
.fi
.sp 1
(Please refer to
.M queue_conf 5
for details.)
.sp 1
.B 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.
.sp 1
The second attribute category in the standard host complex is that of
the default load values every
.M xxqs_name_sxx_execd 8
periodically reports load to
.M xxqs_name_sxx_qmaster 8 .
The reported load values are either the standard xxQS_NAMExx load values,
such as the CPU load average (see
.MO uptime 1 ),
or load values defined by the xxQS_NAMExx administration (see the
.B load_sensor
parameter in the cluster or host configuration (see
.M xxqs_name_sxx_conf 5
.\" and the
.\" .I xxQS_NAMExx Installation and Administration Guide
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
.M load_parameters 5
for detailed information on the
standard set of load values.
.\"
.SS "\fBOverriding attributes\fP"
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:
.sp 1
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.
.sp 1
We have one limitation for overriding attributes based on their relational 
operator:
.sp 1
\fB!=\fP and \fB==\fP operators can only be overridden on the same level, not on a
lower level. The user-defined value always overrides the load value.
.sp 1
.BR >= ,
.BR > ,
.BR <= ,
and
.B <
operators can only be overridden when the new value is more
restrictive than the old one.
.sp 1
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.
.\"
.\"
.PP
.SH FORMAT
The principal format of a 
.I 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.
.PP
An element definition line
consists of the following 8 column entries per line (in order
of appearance):
.SS "\fBname\fP"
The name of the complex element to be used to request this attribute
for a job in the
.M qsub 1
\fB\-l\fP option. A complex attribute
name (see \fIcomplex_name\fP in 
.M sge_types 5 )
may appear only once across all 
complexes, i.e. the complex attribute definition is unique.
.SS "\fBshortcut\fP"
A shortcut for \fBname\fP which may also be used to request this
attribute for a job in the
.M qsub 1
\fB\-l\fP option. A given shortcut
may appear only once across 
all complexes, so as to avoid the possibility of ambiguous complex attribute 
references.
.\"
.SS "\fBtype\fP"
This setting determines how the corresponding values are to be treated by
xxQS_NAMExx internally in comparisons or in load scaling for 
the load complex entries:
.IP "\(bu" 3n
With \fBINT\fP only raw integers are allowed.
.IP "\(bu" 3n
With \fBDOUBLE\fP floating point numbers in double precision (decimal and
scientific notation) can be specified.
.IP "\(bu" 3n
With \fBTIME\fP time specifiers are allowed. Refer to 
.M sge_types 5
for a format description.
.IP "\(bu" 3n
With \fBMEMORY\fP memory size specifiers are allowed. Refer to 
.M sge_types 5
for a format description.
.IP "\(bu" 3n
With \fBBOOL\fP the strings TRUE and FALSE are allowed. When used in a 
load formula (refer to 
.M sched_conf 5 ),
TRUE and FALSE get mapped into '1' and '0'.
.IP "\(bu" 3n
With \fBSTRING\fP all strings are allowed and are used for 
wildcard regular boolean expression matching. 
Please see the
.M sge_types 5
man page for \fBexpression\fP definition.
.sp 1
.nf
.RS
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"
.RE
.fi
.IP "\(bu" 3n
\fBCSTRING\fP is like \fBSTRING\fP except comparisons are case insensitive. 
.IP "\(bu" 3n
\fBRESTRING\fP is the same as \fBSTRING\fP for historical
compatibility, but is deprecated and may be removed in future..
.IP "\(bu" 3n
\fBHOST\fP is like \fBCSTRING\fP but the expression must match a valid host name.
.\"
.SS "\fBrelop\fP"
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 "==".
.sp
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.
.\"
.SS "\fBrequestable\fP"
The entry can be used in a
.M 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.
.sp
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
.M host_conf 5
and
.M queue_conf 5 .
.\"
.SS "\fBconsumable\fP"
The
.B 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
.B type
above). If set to 'yes' or 'JOB' the 
consumption of the corresponding resource can be managed by 
xxQS_NAMExx internal bookkeeping. In this case xxQS_NAMExx accounts 
for the consumption of this resource for all running jobs and ensures that jobs 
are only dispatched if the xxQS_NAMExx 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.
.sp 1
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.
.sp 1
Consumables can be combined with default or user-defined load parameters 
(see
.M xxqs_name_sxx_conf 5
and
.M host_conf 5 ),
i.e. load values can be reported 
for consumable attributes, or the consumable flag can be set for load 
attributes. The xxQS_NAMExx 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.
.sp 1
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
.B complex_values
entry in
.M host_conf 5
and
.M queue_conf 5 . 
The
.B complex_values
definition of the "global" host specifies cluster global 
consumable settings. To each consumable complex attribute in a 
.B 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.
.sp 1
.B Note:
Jobs can be forced to request a resource and thus to specify their 
assumed consumption via a
.B forced
value of the
.B requestable 
parameter (see above).
.sp 1
.B 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
.B default
parameter below). This is meaningful only if 
requesting the attribute is not enforced as explained above.
.\" .sp 1
.\" See the
.\" .I xxQS_NAMExx Installation and Administration Guide
.\" for examples
.\" of the usage of the consumable resources facility.
.\"
.SS "\fBdefault\fP"
Meaningful only for consumable complex attributes (see
.B consumable
parameter above) and must be specified as 0 otherwise.
xxQS_NAMExx assumes the resource amount denoted in the
.B 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 \fB\-l\fP option to
.M qsub 1
override this default value.
.\"
.SS "\fBurgency\fP"
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 \fB\-l\fP option to
.M qsub 1 .
For string type requests the resource's urgency value is directly 
used as addend. Urgency values are of type real. See under 
.M sge_priority 5 
for an overview of job priorities.
.\"
.\"
.SH "SEE ALSO"
.M xxqs_name_sxx_intro 1 ,
.M xxqs_name_sxx_types 1 ,
.M qconf 1 ,
.M qsub 1 ,
.M uptime 1 ,
.M host_conf 5 ,
.M load_parameters 5 ,
.M queue_conf 5 ,
.M xxqs_name_sxx_execd 8 ,
.M xxqs_name_sxx_qmaster 8 
.\" .br
.\" .I xxQS_NAMExx Installation and Administration Guide.
.\"
.SH "COPYRIGHT"
See
.M xxqs_name_sxx_intro 1
for a full statement of rights and permissions.