API Reference¶
EnsembleLauncher¶
from ensemble_launcher import EnsembleLauncher
EnsembleLauncher(
ensemble_file: Union[str, Dict[str, Dict]],
system_config: SystemConfig = SystemConfig(name="local"),
launcher_config: Optional[LauncherConfig] = None,
Nodes: Optional[List[str]] = None,
)
| Parameter | Description |
|---|---|
ensemble_file |
Path to JSON config or dict of task definitions |
system_config |
System resource configuration |
launcher_config |
Launcher behavior configuration (auto-configured if None) |
Nodes |
List of compute nodes (auto-detected from PBS_NODEFILE if None) |
Methods¶
| Method | Description |
|---|---|
run() |
Execute ensemble synchronously and return results. Raises RuntimeError in cluster mode. |
start() |
Start the orchestrator in a background process (cluster mode). |
stop() |
Send SIGTERM to background process; force-kill after 30s if needed. |
__enter__ / __exit__ |
Context manager -- calls start() on entry, stop() on exit. |
ClusterClient¶
from ensemble_launcher.orchestrator import ClusterClient
ClusterClient(
checkpoint_dir: str,
node_id: str = "global",
client_id: Optional[str] = None,
)
| Parameter | Description |
|---|---|
checkpoint_dir |
Directory containing orchestrator checkpoint files |
node_id |
Node to connect to. "global" resolves to root master. |
client_id |
Optional identity string; auto-generated if omitted |
Methods¶
| Method | Description |
|---|---|
start() |
Connect transport and start receive thread |
teardown() |
Disconnect and stop receive thread |
submit(task) |
Send a Task and return a concurrent.futures.Future |
__enter__ / __exit__ |
Context manager |
PolicyClient¶
Reads and updates a node's scheduling-policy state while the run is in flight. Requires
checkpoint_dir, plus cluster=True or enable_policy_client=True.
from ensemble_launcher.orchestrator import PolicyClient
PolicyClient(
checkpoint_dir: str,
node_id: str = "global",
policy_kind: Literal["auto", "children", "task"] = "auto",
client_id: Optional[str] = None,
log_level: int = logging.INFO,
checkpoint_timeout: float = 60.0,
request_timeout: float = 30.0,
)
| Parameter | Description |
|---|---|
checkpoint_dir |
Directory containing orchestrator checkpoint files |
node_id |
Node to connect to. "global" resolves to root master. |
policy_kind |
Which policy to target. "auto" picks the node's only policy: "task" on a worker, "children" on a master. A mismatch is an error. |
client_id |
Optional identity string; auto-generated if omitted |
checkpoint_timeout |
How long to wait for the node to publish its endpoint |
request_timeout |
Default per-request timeout |
Methods¶
| Method | Description |
|---|---|
start() / teardown() |
Connect / disconnect; also available as a context manager |
get_state(keys=None, timeout=None) |
Deep copy of the state. keys filters; absent keys are omitted. |
set_state(state, merge=True, rescore=False, timeout=None) |
Update and return the resulting state. merge=False replaces it wholesale. |
get_state_async / set_state_async |
Same, returning a concurrent.futures.Future |
node_id / policy_name |
Resolved node and the policy class name serving it |
PolicyClient.discover_nodes(ckpt) |
(static) List every node serving a policy endpoint |
rescore=True re-scores the worker's already-pending tasks against the new state; it is
off by default, so a plain set_state only affects tasks submitted afterwards. Failures
raise PolicyStateError and leave both the state and the pending queue unchanged.
PolicyGroupClient¶
Fan-out wrapper over several PolicyClients. Not atomic across nodes.
from ensemble_launcher.orchestrator import PolicyGroupClient
PolicyGroupClient(
checkpoint_dir: str,
node_ids: Optional[List[str]] = None, # None -> every discovered node
**policy_client_kwargs,
)
get_state and set_state take the same arguments as PolicyClient and return
{node_id: state}.
Task¶
from ensemble_launcher.ensemble import Task
Task(
task_id: str,
nnodes: int = 1,
ppn: int = 1,
executable: Union[Callable, str] = None,
args: tuple = (),
kwargs: dict = {},
)
AsyncTask¶
from ensemble_launcher.ensemble import AsyncTask
AsyncTask(
task_id: str,
nnodes: int = 1,
ppn: int = 1,
executable: Union[Callable, str] = None,
args: tuple = (),
kwargs: dict = {},
)
For use with async callables. Automatically used when registering async def functions via MCP tools.
SystemConfig¶
from ensemble_launcher.config import SystemConfig
SystemConfig(
name: str,
ncpus: int = cpu_count(),
ngpus: int = 0,
cpus: List[int] = [],
gpus: List[Union[str, int]] = [],
)
LauncherConfig¶
from ensemble_launcher.config import LauncherConfig
LauncherConfig(
child_executor_name: str = "async_processpool",
task_executor_name: Union[str, List[str]] = "async_processpool",
comm_name: Literal["async_zmq"] = "async_zmq",
report_interval: float = 10.0,
return_stdout: bool = False,
worker_logs: bool = False,
master_logs: bool = False,
gpu_selector: str = "ZE_AFFINITY_MASK",
cluster: bool = False,
checkpoint_dir: Optional[str] = None,
enable_workstealing: bool = False,
enable_policy_client: bool = False,
children_scheduler_policy: str = "simple_split_children_policy",
task_scheduler_policy: str = "fifo_policy",
policy_config: PolicyConfig = PolicyConfig(),
)
enable_policy_client serves each node's policy state for PolicyClient without requiring
full cluster mode; cluster=True implies it. Either way checkpoint_dir must be set,
since clients discover the endpoint from disk.
PolicyConfig¶
from ensemble_launcher.config import PolicyConfig
PolicyConfig(
nlevels: int = 1,
nchildren: int = 1,
leaf_nodes: int = 1,
strict_priority: bool = False,
initial_state: Dict[str, Any] = {},
)
initial_state seeds the policy's self.state dict -- the state PolicyClient reads and
updates at runtime. See Custom Scheduling.