subslice_placement_group#
- ray.util.tpu.subslice_placement_group(subslice_topology: str, accelerator_version: str, chips_per_vm: int | None = None, resources_per_bundle: Dict[str, float] | None = None, strategy: str = 'SPREAD', name: str = '', lifetime: str | None = None, head_reservation_timeout_s: float | None = 100.0, subslice_index: int | None = None) SubslicePlacementGroup[source]#
Asynchronously creates a PlacementGroup for a TPU subslice.
A subslice placement group reserves a contiguous subset of workers within a larger TPU slice, enabling multiple workloads to share a physical slice while maintaining ICI topology alignment.
On the first call for a given topology this function temporarily reserves a full parent slice to discover the physical chip layout, computes each worker’s physical position, and releases unused workers. Subsequent calls reuse the cached data.
A subslice claims whole hosts: a host that already runs one subslice is not considered for another, even if the first subslice uses only part of that host’s chips.
- Parameters:
subslice_topology (str) – Desired subslice topology (e.g.
"2x4").accelerator_version (str) – TPU accelerator generation (e.g.
"v6e").chips_per_vm (int | None) – Optional override for chips per VM. Useful for ambiguous topologies like v6e 2x4 which can be 1 VM (8 chips) or 2 VMs (4 chips each).
resources_per_bundle (Dict[str, float] | None) – Per-bundle resources. Defaults to one bundle per host with
CPU: 1and the subslice’s logical TPU devices on that host.strategy (str) – Placement group strategy (default
"SPREAD").name (str) – Optional placement group name.
lifetime (str | None) – Placement group lifetime (
Noneor"detached").head_reservation_timeout_s (float | None) – Maximum seconds to wait for TPU head placement groups. Defaults to
DEFAULT_TPU_HEAD_RESERVATION_TIMEOUT_S.subslice_index (int | None) – Optional index of the subslice to select. If specified, only the subslice at this index within the physical slice will be considered. If that subslice is busy, the request will fail even if other subslices are idle.
- Returns:
A
SubslicePlacementGrouphandle.- Raises:
ValueError – If the subslice topology is invalid for the accelerator, or if no suitable parent topology is found in the cluster.
RuntimeError – If all slices are occupied, or if TPU chip coordinate discovery fails (for example, JAX is not installed on the TPU workers).
- Return type:
Examples
>>> import ray >>> from ray.util.scheduling_strategies import PlacementGroupSchedulingStrategy >>> from ray.util.tpu import subslice_placement_group >>> sg = subslice_placement_group( ... subslice_topology="2x4", ... accelerator_version="v6e", ... ) >>> ray.get(sg.placement_group.ready()) >>> @ray.remote(num_cpus=0, resources={"TPU": 4}) ... def train(world, rank): ... ... >>> tasks = [ ... train.options( ... scheduling_strategy=PlacementGroupSchedulingStrategy( ... placement_group=sg.placement_group, ... placement_group_bundle_index=i, ... ), ... runtime_env={"env_vars": sg.get_jax_env_vars(worker_id=i)}, ... ).remote(world=sg.num_hosts, rank=i) ... for i in range(sg.num_hosts) ... ]
PublicAPI (alpha): This API is in alpha and may change before becoming stable.