.. github display GitHub is NOT the preferred viewer for this file. Please visit https://flux-framework.rtfd.io/projects/flux-rfc/en/latest/spec_46.html 46/Command Line Job Specification Resources Shape ################################################# This specification describes a compact form for expressing an RFC 14 jobspec resources list that can be provided to several Flux commands by a user. .. list-table:: :widths: 25 75 * - **Name** - github.com/flux-framework/rfc/spec_46.rst * - **Editor** - Sam Maloney * - **State** - raw Language ******** .. include:: common/language.rst Related Standards ***************** - :doc:`spec_4` - :doc:`spec_14` - :doc:`spec_22` - :doc:`spec_25` - :doc:`spec_45` Goals ***** - Express a resource specification on the command line (a.k.a. a "shape") to expand into the resources list of a Canonical Job Specification. - The shape should make simple resource requests compact and easy to express, but without restricting complex requests from being fully specifiable. - Allow inclusion in several submission contexts, including submit, run, and batch. Overview ******** This RFC describes a "shape" string that can be expanded into the full YAML or JSON representation of the equivalent :doc:`RFC 14 ` Job Specification resources list. Description *********** A shape string is essentially a compacted form of the equivalent JSON array, according to the following rules: - Every level of the resource graph (including the outermost level) is a list of resource vertices which SHALL be separated by a semicolon ``;`` (to reduce ambiguity with commas in idsets for counts) and the entire list SHALL in general be surrounded by square brackets ``[...]`` except: - If a list contains only a single vertex then the brackets MAY be omitted. - A resource vertex is a dictionary which SHALL be represented by the general form ``={:}``, where ```` and ```` are the *values* of the corresponding mandatory keys, and the following apply: - Strings such as ````, ````, or a string type ```` do not need to be quoted unless they contain special characters (or would otherwise be parsed as a different ```` type). - ```` SHALL be one of a positive integer, an :doc:`RFC 22 ` idset, or an :doc:`RFC 45 ` compact range string (i.e. not a range dictionary). - If the ```` is integer ``1`` then it (and the ``=``) MAY be omitted. - If the ```` is ``slot`` then the first entry in the braces SHALL be the *value* (and only the value) of the mandatory ``label`` key, except: - If there is only a single ``slot`` vertex in the entire jobspec, then the label MAY be omitted; however, if there are any other ``:`` pairs then the label is REQUIRED and MUST be the first entry. - Additional ``:`` pairs SHALL be separated by a comma ``,``. - Boolean keys (e.g. ``exclusive``) MAY omit the ``:`` and instead: - Prepend either ``+`` or ``-`` to the key name to indicate ``true`` or ``false`` respectively, or: - Add nothing to indicate an implicit value of ``true``. - As a special case, the ``exclusive`` key may be shortened to simply ``x``. - The ```` should be a `valid JSON value `_, except: - Objects (sub-dictionaries) MAY be specified with the same syntax as the outer dict (i.e. using unquoted strings/keys and shortened booleans). - If there are no ``:`` pairs or slot ``