Publish clone plans before scene construction

[ooctipus]

Description

This follows #7462 by making the simulation's ClonePlan available before cfg-owned scene construction.

ReplicateSession now builds and publishes the plan on entry, constructs every participant at its planned source path, and dispatches that same object on exit. SimulationContext remains the canonical owner of the plan pointer; no secondary lifecycle state, constructor ownership heuristic, stage discovery, fallback context, or second clone mapping is introduced.

InteractiveScene owns this lifecycle for cfg-declared scenes. An empty InteractiveScene authors only the env-0 prototype and leaves replication to direct task setup. That removes redundant environment-root authoring while preserving direct workflows with custom clone positions.

Migration

Custom cfg-owned composition roots should use the session around cfg construction:

with cloner.ReplicateSession(asset_cfgs, num_clones=num_envs, env_spacing=env_spacing):
    for cfg in asset_cfgs:
        cfg.class_type(cfg)

Homogeneous direct workflows construct env 0 first, then finish their one clone lifecycle explicitly:

plan = cloner.clone_plan_from_env_0(src, dest, num_envs, positions, global_paths=global_paths)
cloner.replicate(plan)

Size

Scope	Added	Deleted	Net
This PR	160	130	+30
Production	70	70	0
#7462 + this PR	1,393	1,800	-407

Performance

The earlier functional 3B head was performance-neutral in one matched warm sample on physical GPU 0 using Isaac-Lift-KukaAllegro, 4,096 environments, Newton MJWarp physics, and no visualizer:

Metric	This PR	merged develop
Total startup	42.58 s	43.11 s
Environment creation	39.76 s	39.24 s
First step	0.658 s	0.637 s

The cleanup commit removes redundant empty-scene root authoring and adds no startup work. A current-head sample will replace this table when the shared physical GPU 0 is idle.

Type of change

• Breaking change
• Documentation update

Release backport

• Backport this pull request to the active release branch after it merges into develop

Screenshots

Not applicable.

Validation

• 92 clone-plan and ReplicateSession tests passed
• 2 focused InteractiveScene lifecycle tests passed
• 2 clone-session failure-cleanup variants passed
• Former CI failures passed: visual-material scene (1), multi-mesh ray-caster camera (21), ray-caster integration (7), and Newton duplicate-body frame transforms (4)
• PhysX and Newton visual-color-randomization demos reached setup and continued through repeated resets
• Warning-free current documentation build passed
• Repository formatting, lint, changelog, and LFS checks passed
• git diff --check passed

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks
• I have made corresponding documentation changes
• My changes generate no new warnings
• I have added focused lifecycle tests
• I have added the required changelog fragment
• My name already exists in CONTRIBUTORS.md

[ooctipus]

run-ci

[greptile-apps]

Greptile Summary

The PR publishes clone plans before cfg-owned scene construction and enforces a single plan and backend dispatch per simulation.

• Moves plan publication into ReplicateSession entry and validates constructor registrations against the active plan.
• Makes InteractiveScene own the lifecycle only for cfg-declared scenes while leaving empty scenes available to direct workflows.
• Adds lifecycle, ownership, cleanup, and scene behavior tests and updates cloning documentation.

Confidence Score: 4/5

The PR should not merge until failed backend dispatch leaves the clone lifecycle recoverable rather than permanently consumed.

Backend replication remains fallible, but the new ordering marks the plan consumed before invoking any backend, leaving the simulation unable to clear or retry after a failure or partial dispatch.

Files Needing Attention: source/isaaclab/isaaclab/cloner/replicate_session.py and source/isaaclab/isaaclab/sim/simulation_context.py

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/cloner/replicate_session.py	Publishes plans on session entry and validates planned constructors, but consumes the lifecycle before fallible backend dispatch completes.
source/isaaclab/isaaclab/sim/simulation_context.py	Adds single-plan and single-dispatch enforcement whose consumed state cannot currently be rolled back after dispatch failure.
source/isaaclab/isaaclab/scene/interactive_scene.py	Moves cfg-owned construction into the published-plan lifecycle and leaves empty scenes to explicit direct-task cloning.
source/isaaclab/isaaclab/cloner/clone_plan.py	Routes global-only paths through the active physics clone context, including plans without populated cfg rows.

Sequence Diagram

sequenceDiagram
    participant Scene as InteractiveScene
    participant Session as ReplicateSession
    participant Sim as SimulationContext
    participant Backend as Clone backends
    Scene->>Session: enter with cfgs
    Session->>Session: make_clone_plan()
    Session->>Sim: set_clone_plan(plan)
    Scene->>Scene: construct planned entities
    Scene->>Session: exit
    Session->>Sim: consume plan
    loop Registered backends
        Session->>Backend: replicate(plan)
    end

Loading

_{Reviews (1): Last reviewed commit: "Clarify clone plan inspection" | Re-trigger Greptile}

[greptile-apps]

Dispatch failure locks clone lifecycle

When a registered backend raises during context.replicate(plan), _consume_clone_plan() has already marked the lifecycle consumed, so cleanup and subsequent replication attempts raise instead of recovering the active SimulationContext.

Knowledge Base Used: Scene and asset composition

[ooctipus]

Addressed in eca3cd2. The consumed flag and cross-module lifecycle mutation were removed entirely. A partial multi-backend dispatch is not safely retryable without transactional rollback, so retry state is no longer modeled here; ReplicateSession owns publication before construction and dispatches the same plan on exit.

[isaaclab-review-bot]

Isaac Lab Review Bot

The review traced the new cfg-first lifecycle from ReplicateSession.__enter__ through constructor ownership validation and single backend dispatch, including the separate empty-scene/direct-task path. The proposed documentation finding is not accepted because the changelog and cloning guide already instruct custom composition roots to include participants in a plan published before construction and dispatch that same plan once.

• Design and architecture: Plan publication before cfg-owned construction, single-plan ownership in SimulationContext, and caller-owned cloning for empty InteractiveScene instances form a coherent lifecycle split. The replacement scene_from_cfg gate preserves the prior distinction used for collision filtering.
• API: The changed compatibility surface is explicitly marked as breaking. The documentation and changelog provide migration guidance for custom composition roots: build and publish one plan covering participants before construction, then dispatch that plan once. Although they do not repeat the exact runtime error wording, they cover the ownership rule underlying it.
• Implementation: The reviewed paths validate backend registration before consuming the plan, route global-path-only plans to the physics context, clear failed sessions, and keep environment origins synchronized with a subsequently published direct-workflow plan. Focused tests cover pre-construction publication, ownership rejection, single dispatch, failure cleanup, and empty-scene behavior.

No blocking issues. No inline issue met the actionable-evidence threshold; the assessment above records the review feedback.

Automated review; human maintainers own approval decisions.

[ooctipus]

run-ci

[StafaH]

Do we need _env_origins to be torch tensor? Ideally we want to keep initialization python or numpy array only