RunPolicy

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class RunPolicy(workers: int = 1, backend: str = 'serial', subject_timeout_sec: float | None = 900.0, subject_spawn_timeout_sec: float | None = 120.0, graceful_shutdown_sec: float = 15.0, on_subject_failure: str = 'continue', oom_backoff: bool = True, oom_reduce_workers_by: int = 1, cap_workers_to_gpu_pool: bool = False, resume: bool = True, checkpoint_dir: str | None = None, parallel_mode: str = 'persistent', auto_retry_rounds: int = 2, retry_failed_subjects: bool = False, force_rerun_subjects: ~typing.Tuple[str, ...] = <factory>, clear_checkpoint_on_success: bool = False, strict_checkpoint_hash: bool = False, persistent_worker_max_consecutive_failures: int = 1, persistent_worker_recycle_after_tasks: int = 0)

Bases: object

Execution policy for a study run.

workers

Parallel worker processes; 1 means serial execution.

Type:

int

backend

Execution backend name; "serial" or "process".

Type:

str

subject_timeout_sec

Wall-clock seconds allowed per subject before it is marked failed; None disables the per-subject timeout.

Type:

float | None

subject_spawn_timeout_sec

Wall-clock seconds allowed for a worker process to start; None disables the spawn timeout.

Type:

float | None

graceful_shutdown_sec

Seconds to wait after terminate() before kill() when a subject exceeds its timeout.

Type:

float

on_subject_failure

"continue" isolates a subject failure in its result slot; "fail_fast" aborts the run on the first failure.

Type:

str

oom_backoff

Reduce workers after a fatal memory error so pending subjects can still run.

Type:

bool

oom_reduce_workers_by

Workers subtracted per OOM backoff step; the effective worker count never drops below one.

Type:

int

cap_workers_to_gpu_pool

Clamp worker count to the usable GPU pool for steps whose components require a GPU.

Type:

bool

resume

Reuse checkpointed subject results when a checkpoint directory is available.

Type:

bool

checkpoint_dir

Directory for resumable subject results; None lets the runner pick its default location.

Type:

str | None

parallel_mode

"persistent" keeps one long-lived worker per slot; "isolated" spawns one child process per subject.

Type:

str

auto_retry_rounds

Extra dispatch rounds for checkpoint-failed subjects within one run; 0 disables.

Type:

int

retry_failed_subjects

Re-queue checkpoint-failed subjects on the next resumed run.

Type:

bool

force_rerun_subjects

Subject IDs reprocessed even when a checkpoint exists.

Type:

Tuple[str, …]

clear_checkpoint_on_success

Remove the checkpoint directory after a successful run.

Type:

bool

strict_checkpoint_hash

Raise instead of discarding checkpoints when the recorded run fingerprint is incompatible.

Type:

bool

persistent_worker_max_consecutive_failures

Restart a persistent worker slot after this many consecutive fatal-class failures (1 matches v0.1; ignored in isolated mode).

Type:

int

persistent_worker_recycle_after_tasks

Restart a persistent worker after this many successful tasks (0 disables; ignored in isolated mode).

Type:

int

__post_init__() → None

Validate policy values at the boundary.

to_dict() → Dict[str, Any]

Serialise to a plain dict (YAML isomorphic).

classmethod from_dict(payload: Mapping[str, Any]) → RunPolicy

Rebuild a run policy from its dict form, tolerating omissions.

Unknown keys are rejected so a misspelled field surfaces at load time instead of being silently dropped.

Parameters:

payload – Mapping as produced by to_dict(); every key is optional.

Returns:

The reconstructed policy.

Raises:

HABITAPIError – On unknown keys or invalid values.

__init__(workers: int = 1, backend: str = 'serial', subject_timeout_sec: float | None = 900.0, subject_spawn_timeout_sec: float | None = 120.0, graceful_shutdown_sec: float = 15.0, on_subject_failure: str = 'continue', oom_backoff: bool = True, oom_reduce_workers_by: int = 1, cap_workers_to_gpu_pool: bool = False, resume: bool = True, checkpoint_dir: str | None = None, parallel_mode: str = 'persistent', auto_retry_rounds: int = 2, retry_failed_subjects: bool = False, force_rerun_subjects: ~typing.Tuple[str, ...] = <factory>, clear_checkpoint_on_success: bool = False, strict_checkpoint_hash: bool = False, persistent_worker_max_consecutive_failures: int = 1, persistent_worker_recycle_after_tasks: int = 0) → None

Examples using habit.spec.RunPolicy

Running the same study on each backend

Running the same study on each backend