Skip to content

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

JobSpec(execution, resources=None, scheduling=None)

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

argv(argv, *, resources=None, scheduling=None, environment=None)

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

Accelerator(kind, quantity, scope='per_node', model=None)

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

Execution(units, plan=None, env=None, cwd=None)

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

argv(id, argv, *, environment=None, **kwargs)

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

shell(id, command, **kwargs)

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

script(id, text, **kwargs)

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

Launch(kind='direct', ranks=None, threads=None)

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

UnitRef(ref, kind='unit')

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

Sequence(children, kind='sequence')

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

Parallel(children, kind='parallel')

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'