isaaclab.cloner

Function namespaces

path	Stateless prim-path operations for clone plans.
query	Batched numeric topology queries.

Classes

ClonePlan	Prototype topology and placement used to instantiate a scene.
PrototypeWorldTopology	Numeric asset-prototype and world relationships.
CloneCfg	Configuration for environment replication.
InclusionSet	Legal clone combination defined by explicitly listing active assets.
ReplicateContext	Prepare routes before construction, then apply a clone plan to one representation.
ReplicateSession	Author prototypes before dispatching one shared world topology.
UsdReplicateContext	Apply routed clone-plan sources to one USD stage.

Functions

clone_plan_from_env_0(clone_cfg, asset_cfgs, ...)	Prepare one homogeneous topology, placement, and its USD authoring inputs.
make_clone_plan(asset_cfgs, ...[, weights, ...])	Select world compositions and retain their optional placement without creating native resources.
to_warp(topology, device)	Materialize numeric topology on an explicitly selected device.
make_valid_clone_combinations(asset_names, ...)	Expand named combinations into world memberships and relative weights.
num_spawn_variants(spawn_cfg)	Return the number of concrete prototypes declared by a spawner configuration.
grid_transforms(N[, spacing, up_axis])	Create centered grid transforms as host arrays.
replicate(plan, *[, replicate_physics])	Execute one topology through its declared clone contexts.
usd_replicate(stage, sources, destinations, ...)	Replicate USD prims from a raw source-to-environment mapping.
filter_collisions(stage, physicsscene_path, ...)	Create inverted collision groups for clones (PhysX only).

Clone plan

class isaaclab.cloner.ClonePlan

Prototype topology and placement used to instantiate a scene.

Attributes:

topology	Numeric asset-prototype and world membership, independent of naming and placement.
asset_cfgs	Host declarations indexed by asset-prototype ID, retained once by reference.
env_template	Destination-world path template, with one {} slot for the world ID.
positions	Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

Methods:

__init__(topology, asset_cfgs[, ...])

topology: PrototypeWorldTopology

Numeric asset-prototype and world membership, independent of naming and placement.

asset_cfgs: tuple[Any, ...]

Host declarations indexed by asset-prototype ID, retained once by reference.

env_template: str = '/World/envs/env_{}'

Destination-world path template, with one {} slot for the world ID.

positions: ndarray | None = None

Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

__init__(topology: PrototypeWorldTopology, asset_cfgs: tuple[Any, ...], env_template: str = '/World/envs/env_{}', positions: ndarray | None = None) → None

class isaaclab.cloner.PrototypeWorldTopology

Numeric asset-prototype and world relationships.

Arrays use NumPy storage for planning or Warp storage on one device for runtime queries. Treat the topology as read-only after planning; to_warp() explicitly materializes its numeric arrays on a device. Host declarations and naming belong to ClonePlan.

Attributes:

num_asset_prototypes	Number of asset definitions, including unused prototypes.
world_prototypes	Flat int32 asset-prototype indices.
world_prototype_starts	Offsets into world_prototypes, starting with the shared world -1.
world_prototype_layout	Int32 world-prototype index per world, indexed by world ID; shared assets are not sampled.

Methods:

__init__(num_asset_prototypes, ...)

num_asset_prototypes: int

Number of asset definitions, including unused prototypes.

world_prototypes: np.ndarray | wp.array

Flat int32 asset-prototype indices. Repeated indices represent distinct instances.

world_prototype_starts: np.ndarray | wp.array

Offsets into world_prototypes, starting with the shared world -1.

Shared assets occupy world_prototypes[world_prototype_starts[0]:world_prototype_starts[1]]. World prototype i occupies world_prototypes[world_prototype_starts[i + 1]:world_prototype_starts[i + 2]]. An empty shared world starts with [0, 0]. Offsets have dtype int64.

world_prototype_layout: np.ndarray | wp.array

Int32 world-prototype index per world, indexed by world ID; shared assets are not sampled.

__init__(num_asset_prototypes: int, world_prototypes: np.ndarray | wp.array, world_prototype_starts: np.ndarray | wp.array, world_prototype_layout: np.ndarray | wp.array) → None

class isaaclab.cloner.clone_plan.TemplateMatch

The "{}" text a template captured ("3", or a wildcard ".*"), and the path below it.

Attributes:

instance	Alias for field number 0
suffix	Alias for field number 1

Methods:

__new__(_cls, instance, suffix)

Create new instance of TemplateMatch(instance, suffix)

instance: str

Alias for field number 0

suffix: str

Alias for field number 1

static __new__(_cls, instance: str, suffix: str)

Create new instance of TemplateMatch(instance, suffix)

isaaclab.cloner.make_clone_plan(asset_cfgs: ~collections.abc.Sequence[~typing.Any], world_prototypes: ~collections.abc.Sequence[~collections.abc.Sequence[int]], num_worlds: int, *, weights: ~collections.abc.Sequence[float] | None = None, shared_assets: ~collections.abc.Sequence[int] = (), clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <function sequential>, env_template: str = '/World/envs/env_{}', positions: ~numpy.ndarray | None = None) → ClonePlan

Select world compositions and retain their optional placement without creating native resources.

Parameters:

• asset_cfgs – Asset prototype definitions, retained by reference.

• world_prototypes – Asset indices in each world prototype, including repeated instances.

• num_worlds – Number of destination worlds.

• weights – Relative world-prototype weights; None gives every prototype equal weight.

• shared_assets – Asset indices instantiated once in the shared world -1.

• clone_strategy – Function selecting world-prototype indices from weights.

• env_template – Destination-world path template with one {} slot for the world ID.

• positions – Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

Returns:

A plan holding the topology and placement. Topology starts with a shared-world slice.

isaaclab.cloner.grid_transforms(N: int, spacing: float = 1.0, up_axis: str = 'z') → tuple[ndarray, ndarray]

Create centered grid transforms as host arrays.

Parameters:

• N – Number of instances.

• spacing – Distance between neighboring grid positions [m].

• up_axis – Up axis for positions ("z", "y", or "x").

Returns:

Positions [m], shape [N, 3], and identity xyzw orientations, shape [N, 4].

isaaclab.cloner.to_warp(topology: PrototypeWorldTopology, device: str) → PrototypeWorldTopology

Materialize numeric topology on an explicitly selected device.

Parameters:

• topology – Host topology. Contiguous arrays with matching dtypes are borrowed on CPU and copied on CUDA.

• device – Warp device, such as "cpu" or "cuda:0".

Returns:

A new topology holding its arrays alive independently of the host topology. Call once during initialization and share the result; this function does not cache, synchronize later host edits, or transfer cfgs. Queries never call it implicitly.

Path

class isaaclab.cloner.path

Stateless prim-path operations for clone plans.

Concrete roots are matched on segment boundaries; templates carry one "{}" instance slot. Call these functions through cloner.path without constructing an instance.

Methods:

get_asset_prototypes(plan[, path_expr])	Select asset-prototype IDs by their declared cfg paths, without expanding instances.
get_world_prototypes(plan[, path_expr])	Select world-prototype IDs containing assets matched by their declared cfg paths.
get_asset_prototype_paths(plan)	Return authored source paths indexed by asset-prototype ID, without reading a stage.
get_world_prototype_asset_templates(plan, *)	Name every asset occurrence in each world prototype.
get_parent_indices(paths)	Return the nearest strict ancestor in a path collection, independent of input order.
match(path_expr, template)	Match path_expr against a destination template, capturing the instance slot.
relative_to(path, root)	Strip a concrete root prefix off path on a segment boundary.
rebase(path, src_root, dst_root)	Rebase path from one concrete root prefix onto another on a segment boundary.

static get_asset_prototypes(plan: ClonePlan, path_expr: str | None = None) → ndarray

Select asset-prototype IDs by their declared cfg paths, without expanding instances.

Parameters:

• plan – Host asset declarations and their numeric topology.

• path_expr – Exact cfg prim_path or a regular expression matching the complete declared path string. None selects all definitions, including unused prototypes.

Returns:

Ascending asset-prototype IDs, shape [num_matches], dtype int32, each included once. Generated native paths are not matched.

static get_world_prototypes(plan: ClonePlan, path_expr: str | None = None) → ndarray

Select world-prototype IDs containing assets matched by their declared cfg paths.

Parameters:

• plan – Host asset declarations and their numeric topology.

• path_expr – Asset-path filter interpreted by path.get_asset_prototypes(). None selects all world definitions, including empty and unused prototypes and shared world -1.

Returns:

Ascending world-prototype IDs, shape [num_matches], dtype int32, not destination world IDs. Filtering selects complete compositions; repeated asset memberships remain in the topology.

static get_asset_prototype_paths(plan: ClonePlan) → tuple[str | None, ...]

Return authored source paths indexed by asset-prototype ID, without reading a stage.

Parameters:

plan – Host declarations, topology, and naming template.

Returns:

One source path per asset definition, or None for an unused definition. Explicit spawner paths take precedence; otherwise the first participating prototype/world supplies the source. Shared world -1 precedes replicated worlds.

static get_world_prototype_asset_templates(plan: ClonePlan, *, include_world_indices: bool = False) → tuple[tuple[str, ...], ndarray] | tuple[tuple[str, ...], ndarray, ndarray, ndarray]

Name every asset occurrence in each world prototype.

Parameters:

• plan – Host declarations, topology, and naming template.

• include_world_indices – Also return destination world IDs and their per-prototype starts.

Returns:

Flat templates aligned with topology.world_prototypes, and the existing world_prototype_starts array by reference. Shared templates have no instance slot; repeated memberships receive distinct sibling names. Unused prototypes retain templates.

When requested, two additional arrays group destination world IDs by world prototype, including shared world -1 first. For group g (prototype g-1), template starts select its members and world-index starts select its destinations. These are different boundaries; world IDs are not duplicated for every member. Both starts arrays include the final end.

static get_parent_indices(paths: Sequence[str]) → ndarray

Return the nearest strict ancestor in a path collection, independent of input order.

Parameters:

paths – Concrete paths or templates. Equal paths are peers, not parents.

Returns:

Parent index per input, dtype int32; -1 when no ancestor occurs in the collection. For duplicate ancestors the first occurrence is used. No stage is read.

static match(path_expr: str, template: str) → TemplateMatch | None

Match path_expr against a destination template, capturing the instance slot.

The "{}" slot matches one path segment’s worth of text: a concrete id (3) or a wildcard standing for one segment (.*, [^/]+). The captured text identifies the instance without slicing the path by hand.

Parameters:

• path_expr – Path or path expression on the clone (destination) side.

• template – Destination path template with "{}" for the instance id.

Returns:

A TemplateMatch with the captured instance text and the asset-relative suffix, or None when path_expr is not under the template’s instance root.

Example

>>> path.match("/World/envs/env_3/Robot/base", "/World/envs/env_{}/Robot")
TemplateMatch(instance='3', suffix='/base')

static relative_to(path: str, root: str) → str | None

Strip a concrete root prefix off path on a segment boundary.

Unlike slicing or str.removeprefix(), this returns None rather than a mid-segment remainder when path is not under root.

Parameters:

• path – Path to make relative.

• root – Concrete subtree root. A trailing slash is insignificant, and "/" is the root of every path.

Returns:

The suffix below root (starting with /, or "" when path equals root), or None when path is not under root.

classmethod rebase(path: str, src_root: str, dst_root: str) → str

Rebase path from one concrete root prefix onto another on a segment boundary.

Unlike str.replace(), this swaps only a boundary-aligned prefix and touches only the leading occurrence.

Parameters:

• path – Path to rebase.

• src_root – Concrete source root prefix.

• dst_root – Concrete destination root prefix.

Returns:

The rebased path, or path unchanged when it is not under src_root.

Query

class isaaclab.cloner.query

Batched numeric topology queries. Resolve declared paths separately with path.

All queries return (world_indices, world_starts). Indices are flat int32 values; starts are int64 offsets with shape [num_queries, num_worlds + 2], including shared world -1. For query q and world w, world_starts[q, w + 1 : w + 3] bounds its selected instances. Each row’s first/last offset bounds the entire query. Repeated IDs retain separate results.

NumPy queries allocate exact-sized results. Warp queries require resident int32 query IDs and preallocated out arrays on the topology’s device; no upload or readback is implicit. Warm up before CUDA graph capture. For nonempty batches, the valid prefix ends at world_starts[-1, -1]. If that required size exceeds capacity, starts are still reported but indices are left untouched: the caller must provide enough capacity for its selection domain, not consume a partial result.

Methods:

get_asset_prototype_world_index(topology, ...)	Return one world index per asset instance, retaining repeated memberships.
get_asset_prototype_unique_world_index(...)	Return each world containing an asset once, independently for every requested asset.
get_world_prototype_world_index(topology, ...)	Return the destination worlds using each requested world prototype.

static get_asset_prototype_world_index(topology: PrototypeWorldTopology, asset_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return one world index per asset instance, retaining repeated memberships.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• asset_prototype – One integer (NumPy only), or a 1-D integer array of asset-prototype IDs.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries. A scalar is a batch of length one. Missing or unused asset IDs produce empty slices; shared instances use world -1.

static get_asset_prototype_unique_world_index(topology: PrototypeWorldTopology, asset_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return each world containing an asset once, independently for every requested asset.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• asset_prototype – One integer (NumPy only), or a 1-D integer array of asset-prototype IDs.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries, as in query.get_asset_prototype_world_index(). Every world slice has length zero or one. Separate queries are not deduplicated together.

static get_world_prototype_world_index(topology: PrototypeWorldTopology, world_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return the destination worlds using each requested world prototype.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• world_prototype – One integer (NumPy only), or a 1-D integer array of world-prototype IDs. Index -1 selects the shared world, even when empty.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries, as in query.get_asset_prototype_world_index(). Unused world prototypes produce empty slices.

Additional Public Classes

class isaaclab.cloner.CloneCfg

Bases: object

Configuration for environment replication.

Holds the knobs InteractiveScene forwards to make_clone_plan() when building per-env layouts.

Methods:

__new__(*args, **kwargs)
__init__([clone_strategy, ...])

classmethod __new__(*args, **kwargs)

__init__(clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <factory>, clone_combinations: list[~isaaclab.cloner.cloner_cfg.InclusionSet] = <factory>, clone_template: str = <factory>, replicate_physics: bool | None = <factory>) → None

class isaaclab.cloner.InclusionSet

Bases: object

Legal clone combination defined by explicitly listing active assets.

Methods:

__new__(*args, **kwargs)
__init__([assets, weight])

classmethod __new__(*args, **kwargs)

__init__(assets: list[str] = <factory>, weight: float = <factory>) → None

class isaaclab.cloner.ReplicateContext

Prepare routes before construction, then apply a clone plan to one representation.

Native resources belong to the simulation registry. Contexts borrow them during dispatch.

Attributes:

replicate_priority

Dispatch order; lower values run first.

Methods:

__init__(sim_context)	Retain the simulation that owns this representation's resources.
prepare(sim, routing)	Resolve routes and acquire resources before constructing or dispatching contexts.
replicate(plan, asset_prototype_ids)	Apply this representation's routed prototypes to its simulation-owned resources.

replicate_priority: ClassVar[int] = 0

Dispatch order; lower values run first.

__init__(sim_context: SimulationContext)

Retain the simulation that owns this representation’s resources.

Parameters:

sim_context – Simulation owning the clone plan and backend registry.

static prepare(sim: SimulationContext, routing: dict[type[ReplicateContext], set[int]]) → None

Resolve routes and acquire resources before constructing or dispatching contexts.

The default keeps the declared routes. Overrides may replace routes with a shared context.

Parameters:

• sim – Simulation owning the consumers and native resources.

• routing – Mutable mapping of context classes to routed asset prototype indices.

abstractmethod replicate(plan: ClonePlan, asset_prototype_ids: tuple[int, ...]) → object

Apply this representation’s routed prototypes to its simulation-owned resources.

Parameters:

• plan – Replication layout shared by every clone backend.

• asset_prototype_ids – Asset definitions routed to this context.

Returns:

A backend-specific result, if any. Dispatch does not consume it.

class isaaclab.cloner.ReplicateSession

Bases: object

Author prototypes before dispatching one shared world topology.

Methods:

__init__(cfgs, num_clones, env_spacing, *[, ...])	Capture prototype declarations, composition choices, and USD authoring inputs.
__new__(*args, **kwargs)

__init__(cfgs: ~collections.abc.Iterable[~typing.Any], num_clones: int, env_spacing: float, *, clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <function sequential>, world_prototypes: ~collections.abc.Sequence[~collections.abc.Sequence[int]] | None = None, weights: ~collections.abc.Sequence[float] | None = None, replicate_physics: bool | None = None, env_template: str = '/World/envs/env_{}')

Capture prototype declarations, composition choices, and USD authoring inputs.

classmethod __new__(*args, **kwargs)

class isaaclab.cloner.UsdReplicateContext

Bases: ReplicateContext

Apply routed clone-plan sources to one USD stage.

Methods:

__new__(*args, **kwargs)
__init__(sim_context)	Retain the simulation that owns this representation's resources.

classmethod __new__(*args, **kwargs)

__init__(sim_context: SimulationContext)

Retain the simulation that owns this representation’s resources.

Parameters:

sim_context – Simulation owning the clone plan and backend registry.