COMPLEX(5)

💖 COMPLEX(5) — the Grid Engine complexes config file format, bestie 💖

Grid Engine File Formats · COMPLEX(5) · yeah it's a manual page but make it fashion ✨

---

🌸 NAME 🌸

complex — the Grid Engine complexes configuration file format. iykyk

---

🦋 DESCRIPTION 🦋

So complex is literally the format of the Grid Engine complex configuration. And the whole definition of complex attributes? It's giving everything you need to know about the resource attributes a user can request for a Grid Engine job through the qsub(1) -l option, plus how the Grid Engine system interprets all those parameters internally. no cap 💅

The Grid Engine complex object defines all the entries used for configuring the global, host, and queue objects. The system comes with a set of pre-defined entries that are assigned to a host or queue by default. On top of that, the user can define brand-new entries and assign them to one or more objects. Every single load value has to have a corresponding complex entry object, because that entry is what defines the type and the relational operator for it. periodt.

---

✨ Defining resource attributes ✨

DO NOT touch the complex configuration directly, bestie. I'm so serious. 🙈

To add or modify complex entries you use the qconf(1) options -Mc and -mc instead. Here's the vibe:

• -Mc takes a complex configuration file as an argument and overrides the current configuration.
• -mc brings up an editor filled in with the current complex configuration. cute, right? 🎀

The list you get there contains all the definitions of resource attributes in the system. Adding a new entry means you gotta provide: name, shortcut, type, relop, requestable, consumable, default, and urgency. All the fields are described below 👇

Changing an entry? Easy — just update the field you want to change. Removing an entry? Delete its definition. BUT 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. You cannot delete them, and you cannot change the type of such an attribute. not up for debate 💀

---

🌈 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. Like, it's exclusive 💅

• 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.
• Attached to a queue object (qconf -mq queue) → it exists 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 — say you wanna support requests for free space in the /tmp filesystem. You'd set up a load sensor to report the value (probably using df(1)) and attach a sufficiently high limit to each host, like:

qconf -aattr exechost complex_values tmp_free=10T $(qconf -sel)

obsessed with that one-liner honestly 🫶

---

🎀 Default queue resource attributes 🎀

By default there's a selection of parameters in the queue configuration as defined in queue_conf(5). The principal queue configuration parameters that are 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

there they are. all nineteen of them. iconic ✨

---

💜 Default host resource attributes 💜

The standard set of host-related attributes consists of two categories. bestie we're doing a two-parter.

Category one 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. lowkey genius ngl

Category two 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. And 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.

And in the case of a consumable at host level which also has 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.

vibe check passed ✅

---

okay that's part one bestie, there's more coming so don't go anywhere 💖

✨ FORMAT ✨

okay so bestie, the main vibe of a complex configuration is literally just a tabulated list. 💅 Each line that starts with a # is a comment line. No cap. Every non-comment line defines one element of the complex. And listen: backslashes (\) can be used to escape newline characters. The backslash and the newline get replaced with a space character before any interpretation. Periodt.

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. So like, this is the glow-up name you use in qsub -l to ask for this attribute. And bestie, it can only show up once across all complexes — uniqueness is the moment. 💖

✨ 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. So it's the nickname, but no duplicates allowed. 🎀

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

• INT — only raw integers are allowed. No decimals, no vibes. 💅
• DOUBLE — floating point numbers in double precision (decimal and scientific notation) can be specified. So like 3.14 or 1e-10, slay.
• TIME — time specifiers are allowed. Refer to sge_types(5) for a format description. ⏰
• MEMORY — memory size specifiers are allowed. Refer to sge_types(5) for a format description. 🧠
• 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'. So true = 1, false = 0, periodt.
• 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. This is giving pattern-matching realness. 🔍
  • 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. So HELLO and hello are the same vibe. 🙈
• RESTRING — is the same as STRING for historical compatibility, but is deprecated and may be removed in future.. ⚠️ So like, don't use it, bestie.
• HOST — is like CSTRING but the expression must match a valid host name. So it's picky about hostnames. 💅

✨ 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 "==". So like, no cap.

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. So it's giving VIP access only. 👑

✨ 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. So like, forced means you must ask for it, or you're not getting in. 🚫

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). So bestie, you gotta define it first.

✨ 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. So like, it's the budget manager of resources. 💸

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. So y multiplies, j doesn't. 💅

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. So it's double-checking, no cap.

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. So it's like a spreadsheet for resources. 📊

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. So it's the default snack amount, but you can bring your own. 🍓

✨ 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. So it's like a priority boost, main character energy. 👑

---

✨ SEE ALSO ✨

bestie, you gotta check out these too:

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

---

This iconic page is from SGE 8.1.3pre, dated 2011-12-04. Stay slay, bestie. 💖✨