Request values¶
These frozen dataclasses describe requests. to_wire() returns their JSON form,
omitting None fields. Validation and destination defaults are applied by the
service when you call validate, preview, or submit.
JobSpec.argv([...]) constructs a single-command specification. Decorators
yield this value and receive a Job; plain lists or dictionaries are not requests.
Memory is a decimal string of bytes per node. MPI ranks, threads, and allocation task budgets are explicit. See submit jobs for complete examples.
Immutable client value constructors; no rendering or lifecycle logic.
JobSpec
dataclass
¶
Bases: Value
Orthogonal allocation, scheduling and execution request values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
execution
|
Execution
|
Allocation-internal commands and composition. |
required |
resources
|
Resources | None
|
Explicit allocation budget, if supplied. |
None
|
scheduling
|
Scheduling | None
|
Explicit native scheduling intent. |
None
|
Constructors do not validate native representation, scheduling resources or permissions. Use a cluster's validate or preview method before submission when representation validation is required.
argv
classmethod
¶
Construct a specification for one literal argument-vector command.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
argv
|
list[str]
|
Executable and its literal arguments, copied into the single execution unit. |
required |
resources
|
Resources | None
|
Optional allocation budget. |
None
|
scheduling
|
Scheduling | None
|
Optional queue placement intent. |
None
|
environment
|
Environment | None
|
Optional prepared environment for this command. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
JobSpec |
JobSpec
|
A single-unit request without validation or defaults merging. |
Resources
dataclass
¶
Resources(nodes=None, tasks=None, cpus_per_task=None, memory_bytes=None, time_limit_seconds=None, accelerators=None)
Bases: Value
Allocation budget; omitted fields are resolved by the runtime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nodes
|
int | None
|
Positive allocation node count. |
None
|
tasks
|
int | None
|
Positive total task budget. |
None
|
cpus_per_task
|
int | None
|
Positive CPU budget per task. |
None
|
memory_bytes
|
str | None
|
Positive per-node bytes as a decimal string. |
None
|
time_limit_seconds
|
int | None
|
Positive allocation time limit in seconds. |
None
|
accelerators
|
tuple[Accelerator, ...] | None
|
Explicit accelerator requests. |
None
|
Accelerator
dataclass
¶
Bases: Value
A formal allocation resource quantity, with explicit scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kind
|
str
|
"gpu" or "nvidia_mps"; no automatic resource fallback. |
required |
quantity
|
int
|
Positive resource quantity in the declared scope. |
required |
scope
|
str
|
"per_node" or "total". |
'per_node'
|
model
|
str | None
|
Exact native model selector, if specified. |
None
|
Scheduling
dataclass
¶
Scheduling(name=None, comment=None, partition=None, account=None, qos=None, reservation=None, priority=None, exclusive=None, dependencies=None, array=None, requeue=None)
Bases: Value
Scheduling intent, independent of execution content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str | None
|
Native allocation name. |
None
|
comment
|
str | None
|
Native allocation comment. |
None
|
partition
|
str | None
|
Exact native partition selector. |
None
|
account
|
str | None
|
Native billing account. |
None
|
qos
|
str | None
|
Native quality-of-service selector. |
None
|
reservation
|
str | None
|
Native reservation selector. |
None
|
priority
|
int | None
|
Nonnegative native priority request. |
None
|
exclusive
|
bool | None
|
Whether to request exclusive allocation. |
None
|
dependencies
|
tuple[dict[str, Any], ...] | None
|
Each dependency supplies a registry-qualified ref and an explicit condition: after, after_success, after_failure or after_started. |
None
|
array
|
JobArray | None
|
Optional native Slurm array. |
None
|
requeue
|
bool | None
|
Opt into Slurm native requeue policy. |
None
|
Execution
dataclass
¶
Bases: Value
One or more units with an optional compositional plan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
units
|
tuple[ExecutionUnit, ...]
|
Nonempty tuple of uniquely named units. |
required |
plan
|
UnitRef | Sequence | Parallel | None
|
Plan referencing every unit exactly once; required when more than one unit is supplied. |
None
|
env
|
dict[str, str] | None
|
Execution-wide environment additions. |
None
|
cwd
|
str | None
|
Execution-wide target working directory. |
None
|
ExecutionUnit
dataclass
¶
ExecutionUnit(id, command, env=None, cwd=None, stdout=None, stderr=None, launch=None, placement=None)
Bases: Value
One allocation-internal command and optional placement.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
Unique unit identifier referenced by the execution plan. |
required |
command
|
dict[str, Any]
|
Canonical argv, shell or script command value. |
required |
env
|
dict[str, str] | None
|
Unit environment additions or overrides. |
None
|
cwd
|
str | None
|
Target working directory for this unit. |
None
|
stdout
|
str | None
|
Explicit target stdout path. |
None
|
stderr
|
str | None
|
Explicit target stderr path. |
None
|
launch
|
Launch | None
|
Direct or MPI process launch request. |
None
|
placement
|
dict[str, int] | None
|
Explicit tasks/cpus_per_task budget within the allocation. |
None
|
argv
classmethod
¶
Construct a command without shell interpretation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
Unique unit identifier. |
required |
argv
|
list[str]
|
Executable and its literal argument vector. |
required |
environment
|
Environment | None
|
Optional prepared environment for this command. |
None
|
**kwargs
|
Any
|
Additional ExecutionUnit constructor fields. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
ExecutionUnit |
ExecutionUnit
|
An argv command holding a copy of the argument list. |
Raises:
| Type | Description |
|---|---|
TypeError
|
Additional fields do not match the constructor signature. |
shell
classmethod
¶
Construct explicit shell content, interpreted only on the target.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
Unique unit identifier. |
required |
command
|
str
|
Shell command text to run on the target. |
required |
**kwargs
|
Any
|
Additional ExecutionUnit constructor fields. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
ExecutionUnit |
ExecutionUnit
|
An explicitly requested shell command. |
Raises:
| Type | Description |
|---|---|
TypeError
|
Additional fields do not match the constructor signature. |
script
classmethod
¶
Construct inline payload script content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
Unique unit identifier. |
required |
text
|
str
|
Script payload rendered into the native submission. |
required |
**kwargs
|
Any
|
Additional ExecutionUnit constructor fields. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
ExecutionUnit |
ExecutionUnit
|
An inline script command. |
Raises:
| Type | Description |
|---|---|
TypeError
|
Additional fields do not match the constructor signature. |
Launch
dataclass
¶
Bases: Value
Direct or explicitly configured MPI launch intent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kind
|
str
|
"direct" or "mpi". |
'direct'
|
ranks
|
int | None
|
Positive MPI rank count when requested. |
None
|
threads
|
int | None
|
Positive thread count per launched process. |
None
|
UnitRef
dataclass
¶
Bases: Value
Reference one execution unit in a compositional plan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
str
|
Identifier of a unit in the execution's units tuple. |
required |
kind
|
str
|
Wire discriminator; must remain "unit". |
'unit'
|
Sequence
dataclass
¶
Bases: Value
Run child plans in order, stopping on failure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
children
|
tuple[Any, ...]
|
Nonempty sequence of UnitRef, Sequence, Parallel or equivalent wire plan dictionaries. |
required |
kind
|
str
|
Wire discriminator; must remain "sequence". |
'sequence'
|
Parallel
dataclass
¶
Bases: Value
Run child plans concurrently, awaiting all started children.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
children
|
tuple[Any, ...]
|
Nonempty sequence of UnitRef, Sequence, Parallel or equivalent wire plan dictionaries. |
required |
kind
|
str
|
Wire discriminator; must remain "parallel". |
'parallel'
|