Simplify clone lifecycle ownership

Author: ooctipus

docs/source/how-to/cloning.rst

@@ -207,19 +207,15 @@ need every variant behind a template. Note that environment ids are not mask col
 column ``j`` stands for ``env_ids[j]``, and the queries speak ids throughout.
 
 A plan is the *what*. Putting one together and handing it to the backends is
-the *how*, and Isaac Lab exposes three idiomatic ways to do that. All three end
+the *how*, and Isaac Lab exposes two idiomatic ways to do that. Both end
 in the same ``cloner.replicate(plan)`` call, so the choice between
 them is purely about ergonomics:
 
 * The first wraps both phases in a context manager and is what
   :class:`~isaaclab.scene.InteractiveScene` runs under the hood. Reach for it
   when you want the lifecycle hidden and you are authoring assets through a
   scene config.
-* The second spells the same flow out as plain function calls, leaving a moment
-  between the build and the drain where you can inspect the plan.
-  Reach for it when you are assembling a scene outside
-  :class:`~isaaclab.scene.InteractiveScene` or want fine control over timing.
-* The third is a one-shot shortcut for the case where every env is just a copy
+* The second is a one-shot shortcut for the case where every env is just a copy
   of env_0. Reach for it in :class:`~isaaclab.envs.DirectRLEnv` and standalone
   scripts that hand-build the env-0 prototype prim by prim.
 
@@ -256,21 +252,6 @@ When envs need to differ across the population, use
 :class:`~isaaclab.sim.spawners.wrappers.MultiUsdFileCfg`; see
 :doc:`multi_asset_spawning`.
 
-``make_clone_plan`` + ``replicate``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The same lifecycle as the session, written as separate function calls. Publish the
-plan before construction so every participant observes the same layout, then
-dispatch it after the prototypes exist:
-
-.. code-block:: python
-
-    plan = cloner.make_clone_plan(cfgs, num_clones=N, env_spacing=2.0)
-    sim.set_clone_plan(plan)
-    for cfg in cfgs:
-        cfg.class_type(cfg)
-    cloner.replicate(plan)
-
 ``clone_plan_from_env_0`` + ``replicate``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -294,9 +275,10 @@ subclasses use — they author the env-0 prototype prim by prim in
         plan = cloner.clone_plan_from_env_0(src, dest, self.scene.num_envs, pos, global_paths=global_paths)
         cloner.replicate(plan)
 
-Every env receives the same prototype. When envs need to differ, use one of the
-other two. Hand-built scenes must pass every shared asset root in ``global_paths``;
-use ``()`` when there are none.
+Every env receives the same prototype. When envs need to differ, declare their
+assets on :class:`~isaaclab.scene.InteractiveSceneCfg` so the scene owns the
+session-backed lifecycle. Hand-built scenes must pass every shared asset root in
+``global_paths``; use ``()`` when there are none.
 
 
 Under the Hood
@@ -325,15 +307,14 @@ execution contract:
 
 .. code-block:: python
 
-    simulation.set_clone_plan(plan)
-    construct_prototypes()
+    plan = published_clone_plan
     for context_type in plan.context_rows:
         simulation_backends[context_type].replicate(plan)
 
 The cfg-first lifecycle publishes before ``construct_prototypes()``. The direct
 single-source workflow remains post-construction and is published by
 :func:`~isaaclab.cloner.replicate` immediately before dispatch. In either form,
-the simulation accepts one plan and each backend receives that exact object once.
+each maintained lifecycle passes that exact object to every backend.
 
 USD runs before native physics contexts so the destination topology exists when
 they consume it. No fallback context is constructed during dispatch.

source/isaaclab/changelog.d/ooctipus-single-clone-lifecycle.major.rst

@@ -1,7 +1,7 @@
 Changed
 ^^^^^^^
 
-* **Breaking:** Published cfg-owned clone plans before scene construction and limited each
-  :class:`~isaaclab.sim.SimulationContext` to one plan and one dispatch. Custom scene composition
-  roots should build and publish one plan before constructing its participants, then pass that same
-  plan once to :func:`~isaaclab.cloner.replicate`.
+* **Breaking:** Published :class:`~isaaclab.cloner.ReplicateSession` plans on entry and dispatched
+  them on exit. Empty :class:`~isaaclab.scene.InteractiveScene` configurations now author only
+  ``env_0``; direct workflows must finish setup with :func:`~isaaclab.cloner.clone_plan_from_env_0`
+  and :func:`~isaaclab.cloner.replicate`.

source/isaaclab/isaaclab/cloner/clone_plan.py

@@ -203,10 +203,7 @@ def make_valid_clone_combinations(
 
 
 def _context_rows(
-    cfgs: tuple[Any, ...],
-    cfg_rows: dict[int, tuple[int, ...]],
-    populated_rows: set[int],
-    global_paths: tuple[str, ...] = (),
+    cfgs: tuple[Any, ...], cfg_rows: dict[int, tuple[int, ...]], populated_rows: set[int]
 ) -> dict[type[object], tuple[int, ...]]:
     """Route plan rows to the clone contexts registered for this simulation."""
     sim = sim_utils.SimulationContext.instance()
@@ -216,9 +213,7 @@ def _context_rows(
     physics_context = sim.physics_manager.clone_context_type
     if physics_context is not None and not isinstance(physics_context, type):
         raise TypeError("PhysicsManager.clone_context_type must be a context class.")
-    rows_by_context: dict[type[object], set[int]] = (
-        {} if physics_context is None or not global_paths else {physics_context: set()}
-    )
+    rows_by_context: dict[type[object], set[int]] = {}
 
     for cfg in cfgs:
         rows = cfg_rows.get(id(cfg))
@@ -241,7 +236,7 @@ def _context_rows(
     return {
         context_type: tuple(sorted(rows & populated_rows))
         for context_type, rows in rows_by_context.items()
-        if rows & populated_rows or context_type is physics_context and bool(global_paths)
+        if rows & populated_rows
     }
 
 
@@ -318,7 +313,6 @@ def set_spawn_paths(spawn_cfg: Any, paths: list[str | None]) -> None:
             env_ids=env_ids,
             positions=positions,
             cfg_rows={},
-            context_rows=_context_rows(cfgs, {}, set(), global_paths),
             global_paths=global_paths,
         )
 
@@ -335,7 +329,7 @@ def set_spawn_paths(spawn_cfg: Any, paths: list[str | None]) -> None:
             env_ids=env_ids,
             positions=positions,
             cfg_rows=cfg_rows,
-            context_rows=_context_rows(cfgs, cfg_rows, {0}, global_paths),
+            context_rows=_context_rows(cfgs, cfg_rows, {0}),
             global_paths=global_paths,
         )
 
@@ -408,7 +402,7 @@ def validate_combinations(combos: np.ndarray, name: str, expected_rows: int | No
         env_ids=env_ids,
         positions=positions,
         cfg_rows=cfg_rows,
-        context_rows=_context_rows(cfgs, cfg_rows, populated_rows, global_paths),
+        context_rows=_context_rows(cfgs, cfg_rows, populated_rows),
         global_paths=global_paths,
     )
 
@@ -451,6 +445,6 @@ def clone_plan_from_env_0(
         env_ids=np.arange(num_clones, dtype=np.int64),
         positions=positions,
         cfg_rows=cfg_rows,
-        context_rows=_context_rows(queued, cfg_rows, {0}, global_paths),
+        context_rows=_context_rows(queued, cfg_rows, {0}),
         global_paths=global_paths,
     )

source/isaaclab/isaaclab/cloner/replicate_session.py

@@ -17,8 +17,6 @@
 from .clone_plan import make_clone_plan
 from .cloner_cfg import DEFAULT_ENV_TEMPLATE
 from .cloner_strategies import sequential
-from .path import under
-from .query import path_to_source
 from .usd import UsdReplicateContext
 
 if TYPE_CHECKING:
@@ -34,23 +32,13 @@
 
 
 def queue_replication(cfg: Any) -> None:
-    """Register a constructed cfg or verify that the active plan owns it.
+    """Register a constructed cfg when no clone plan is active.
 
     Args:
         cfg: Asset cfg with resolved ``prim_path``.
     """
-    sim = SimulationContext.instance()
-    plan = None if sim is None else sim.get_clone_plan()
-    if plan is None:
+    if (sim := SimulationContext.instance()) is None or sim.get_clone_plan() is None:
         REPLICATION_QUEUE.append(cfg)
-        return
-
-    global_owned = any(under(cfg.prim_path, root) for root in plan.global_paths)
-    if not sim._clone_plan_consumed and (id(cfg) in plan.cfg_rows or global_owned):
-        return
-    if cfg.spawn is None and (global_owned or path_to_source(plan, cfg.prim_path) is not None):
-        return
-    raise RuntimeError(f"{type(cfg).__name__} at {cfg.prim_path!r} is not owned by the active ClonePlan.")
 
 
 def replicate(plan: ClonePlan, *, replicate_physics: bool = True) -> None:
@@ -78,8 +66,12 @@ def replicate(plan: ClonePlan, *, replicate_physics: bool = True) -> None:
         names = ", ".join(f"{context_type.__module__}.{context_type.__qualname__}" for context_type in missing)
         raise RuntimeError(f"Clone contexts must be registered before plan dispatch: {names}.")
 
+    if (active_plan := sim.get_clone_plan()) is None:
+        sim.set_clone_plan(plan)
+    elif active_plan is not plan:
+        raise ValueError("replicate() requires the active SimulationContext's ClonePlan.")
+
     contexts = [sim._backend_registry[context_type] for context_type in context_types]
-    sim._consume_clone_plan(plan)
     for context in sorted(contexts, key=lambda item: item.replicate_priority):
         context.replicate(plan)
 
@@ -138,8 +130,7 @@ def __init__(
         self._plan: ClonePlan | None = None
 
     def __enter__(self) -> ReplicateSession:
-        sim = SimulationContext.instance()
-        if sim is None:
+        if (sim := SimulationContext.instance()) is None:
             raise RuntimeError("Clone planning requires an active SimulationContext.")
         if sim.get_clone_plan() is not None:
             raise RuntimeError("A SimulationContext owns exactly one clone lifecycle.")
@@ -154,8 +145,7 @@ def __exit__(self, exc_type, exc_value, traceback) -> None:
         else:
             # Drop cfgs registered before the failure so the next session is clean.
             REPLICATION_QUEUE.clear()
-            sim = SimulationContext.instance()
-            if sim is not None and sim.get_clone_plan() is self._plan:
+            if (sim := SimulationContext.instance()) is not None and sim.get_clone_plan() is self._plan:
                 sim.set_clone_plan(None)
 
     @property

source/isaaclab/isaaclab/scene/interactive_scene.py

@@ -168,29 +168,41 @@ def __init__(self, cfg: InteractiveSceneCfg):
         # the template is authoritative; the regex form is the same namespace spelled for matching
         self._env_fmt = self.cloner_cfg.clone_template
         self.env_prim_paths = [self._env_fmt.format(i) for i in range(self.cfg.num_envs)]
-        self._scene_asset_names: list[str] = []
-        self._clone_valid_set: np.ndarray | None = None
+        self._ALL_INDICES = torch.arange(self.cfg.num_envs, dtype=torch.long, device=self.device)
 
         self._global_prim_paths = list()
-        clone_cfgs, global_paths = self._collect_asset_cfgs()
-        scene_from_cfg = bool(self._scene_asset_names)
+        asset_cfgs, global_paths, valid_set = self._collect_asset_cfgs()
+        scene_from_cfg = any(
+            name not in InteractiveSceneCfg.__dataclass_fields__ and cfg is not None
+            for name, cfg in self.cfg.__dict__.items()
+        )
         if scene_from_cfg:
             with cloner.ReplicateSession(
-                clone_cfgs,
+                asset_cfgs,
                 num_clones=self.num_envs,
                 env_spacing=self.cfg.env_spacing,
                 global_paths=global_paths,
                 env_template=self._env_fmt,
                 clone_strategy=self.cloner_cfg.clone_strategy,
-                valid_set=self._clone_valid_set,
+                valid_set=valid_set,
                 replicate_physics=self.cloner_cfg.replicate_physics,
             ) as session:
-                self._author_envs(session.plan.env_ids, session.plan.positions)
+                self.stage.DefinePrim(self.env_prim_paths[0], "Xform")
+                with cloner.disabled_fabric_change_notifies(self.stage, restore=False):
+                    cloner.usd_replicate(
+                        self.stage,
+                        [self.env_prim_paths[0]],
+                        [self._env_fmt],
+                        session.plan.env_ids,
+                        positions=session.plan.positions,
+                    )
                 self._add_entities_from_cfg()
+            positions = session.plan.positions
         else:
-            env_ids = np.arange(self.num_envs, dtype=np.int64)
-            env_origins = cloner.grid_transforms(self.num_envs, self.cfg.env_spacing)[0]
-            self._author_envs(env_ids, env_origins)
+            self.stage.DefinePrim(self.env_prim_paths[0], "Xform")
+            positions = cloner.grid_transforms(self.num_envs, self.cfg.env_spacing)[0]
+        self._env_origins = torch.as_tensor(positions, device=self.device)
+        self._env_origins_plan = self.sim.get_clone_plan()
 
         # Every sensor exists by now, so all visualizer and camera-renderer requirements are visible.
         cam_types = [s.cfg.renderer_cfg.renderer_type for s in self._sensors.values() if isinstance(s.cfg, CameraCfg)]
@@ -203,17 +215,17 @@ def __init__(self, cfg: InteractiveSceneCfg):
         if self.cfg.filter_collisions and "physx" in self.physics_backend and scene_from_cfg:
             self.filter_collisions(self._global_prim_paths)
 
-    def _collect_asset_cfgs(self) -> tuple[list[Any], tuple[str, ...]]:
+    def _collect_asset_cfgs(self) -> tuple[list[Any], tuple[str, ...], np.ndarray | None]:
         """Flatten user-declared cfgs and declare shared prim roots for clone planning.
 
         Expands :class:`~isaaclab.assets.RigidObjectCollectionCfg` into its members,
         resolves ``{ENV_REGEX_NS}`` macros, lets an enclosing asset's row own nested materials,
-        and returns only env-scoped configs with a spawner. Global roots are returned separately.
+        and returns env-scoped configs with a spawner, global roots, and valid clone combinations.
         """
 
         cfg_fields = InteractiveSceneCfg.__dataclass_fields__
         items = [(name, cfg) for name, cfg in self.cfg.__dict__.items() if name not in cfg_fields and cfg is not None]
-        self._scene_asset_names = [name for name, _ in items]
+        scene_asset_names = [name for name, _ in items]
         flat_items: list[tuple[str, Any]] = []
         for asset_name, asset_cfg in items:
             children = (
@@ -239,7 +251,7 @@ def _collect_asset_cfgs(self) -> tuple[list[Any], tuple[str, ...]]:
             and any(cloner.path.relative_to(cfg.prim_path, owner) not in (None, "") for owner in owner_paths)
         }
         nested_material_names = {name for name, cfg in flat_items if id(cfg) in nested_visual_material_ids}
-        self._scene_asset_names = [name for name in self._scene_asset_names if name not in nested_material_names]
+        scene_asset_names = [name for name in scene_asset_names if name not in nested_material_names]
 
         cfgs: list[Any] = []
         global_paths: tuple[str, ...] = ()
@@ -259,15 +271,15 @@ def _collect_asset_cfgs(self) -> tuple[list[Any], tuple[str, ...]]:
                 variant_counts.append(cloner.num_spawn_variants(child.spawn))
 
         if self.cloner_cfg.clone_combinations and clone_asset_names:
-            self._clone_valid_set = cloner.make_valid_clone_combinations(
+            valid_set = cloner.make_valid_clone_combinations(
                 clone_asset_names,
                 variant_counts,
                 self.cloner_cfg.clone_combinations,
-                all_asset_names=self._scene_asset_names,
+                all_asset_names=scene_asset_names,
             )
         else:
-            self._clone_valid_set = None
-        return cfgs, global_paths
+            valid_set = None
+        return cfgs, global_paths, valid_set
 
     def filter_collisions(self, global_prim_paths: list[str] | None = None):
         """Filter environments collisions.
@@ -371,10 +383,9 @@ def env_origins(self) -> torch.Tensor:
         if self._terrain is not None:
             return self._terrain.env_origins
         plan = self.sim.get_clone_plan()
-        if plan is not self._env_origins_plan:
+        if plan is not None and plan is not self._env_origins_plan:
+            self._env_origins = torch.as_tensor(plan.positions, device=self.device)
             self._env_origins_plan = plan
-            if plan is not None and plan.positions is not None:
-                self._env_origins = torch.as_tensor(plan.positions, device=self.device)
         return self._env_origins
 
     @property
@@ -779,15 +790,6 @@ def __getitem__(self, key: str) -> Any:
     Internal methods.
     """
 
-    def _author_envs(self, env_ids: np.ndarray, positions: np.ndarray) -> None:
-        """Author environment roots from the active layout."""
-        self._ALL_INDICES = torch.as_tensor(env_ids, device=self.device)
-        self._env_origins = torch.as_tensor(positions, device=self.device)
-        self._env_origins_plan = self.sim.get_clone_plan()
-        self.stage.DefinePrim(self.env_prim_paths[0], "Xform")
-        with cloner.disabled_fabric_change_notifies(self.stage, restore=False):
-            cloner.usd_replicate(self.stage, [self.env_prim_paths[0]], [self._env_fmt], env_ids, positions=positions)
-
     def _add_entities_from_cfg(self):  # noqa: C901
         """Add scene entities from the config."""
         from isaaclab_physx.assets import SurfaceGripperCfg  # noqa: PLC0415

source/isaaclab/isaaclab/sim/simulation_context.py

@@ -196,7 +196,6 @@ def __init__(self, cfg: SimulationCfg | None = None):
         # Clone plan published before cfg-owned scene construction. Constructors and
         # backends therefore consume the same immutable layout through one lifecycle.
         self._clone_plan: ClonePlan | None = None
-        self._clone_plan_consumed: bool = False
         # Default visualization dt used before/without visualizer initialization.
         physics_dt = getattr(self.cfg.physics, "dt", None)
         self._viz_dt = (physics_dt if physics_dt is not None else self.cfg.dt) * self.cfg.render_interval
@@ -692,24 +691,8 @@ def get_clone_plan(self) -> ClonePlan | None:
         return self._clone_plan
 
     def set_clone_plan(self, plan: ClonePlan | None) -> None:
-        """Publish or clear this simulation's single clone plan.
-
-        Raises:
-            RuntimeError: If another plan is active or the current plan was consumed.
-        """
-        if self._clone_plan_consumed:
-            raise RuntimeError("A consumed clone lifecycle cannot be cleared or replaced.")
-        if plan is self._clone_plan:
-            return
-        if plan is not None and self._clone_plan is not None:
-            raise RuntimeError("A SimulationContext owns exactly one clone lifecycle.")
+        """Set the cloner's active clone plan."""
         self._clone_plan = plan
-        self._clone_plan_consumed = False
-
-    def _consume_clone_plan(self, plan: ClonePlan) -> None:
-        """Publish ``plan`` and atomically claim its single backend dispatch."""
-        self.set_clone_plan(plan)
-        self._clone_plan_consumed = True
 
     @property
     def visualizers(self) -> list[BaseVisualizer]: