[Cloner] Represent worlds with reusable asset prototypes

[ooctipus]

Summary

Replace the asset-by-environment matrix with reusable asset definitions and explicit world compositions. Repeated memberships create distinct instances without importing the same geometry again.

plan = cloner.make_clone_plan(
    (banana_cfg, franka_cfg),
    ((0, 1), (0, 1, 1), (0, 0, 1), (1,)),
    16,
)
# Host declarations, kept once:
plan.asset_cfgs
# Naming and optional placement:
plan.env_template
plan.positions
# Numeric relationships, independent of cfgs and native resources:
plan.topology.world_prototypes        # [0,1, 0,1,1, 0,0,1, 1]
plan.topology.world_prototype_starts   # [0,0,2,5,8,9]; shared world -1 comes first
plan.topology.world_prototype_layout  # [0,0,0,0, 1,1,1,1, 2,2,2,2, 3,3,3,3]

• Newton imports each asset once, composes each selected world prototype once, and batches replication. Clone contexts consume world indices directly, without reconstructing dense masks.
• Consumers read the plan and compose cloner.path/cloner.query operations. They no longer read USD clone-context state. Clone contexts execute replication; they do not own naming, placement, or runtime resources.
• Path utilities return source/template tables and ancestry; each clone backend owns its copy selection. USD and both OVRTX paths preserve independent child overrides. OVRTX shares clone and partition orchestration between its two native APIs.
• NumPy handles planning and initialization queries. cloner.to_warp(plan.topology, device) explicitly materializes numeric arrays for batched, graph-capturable runtime queries. No implicit transfers or mirrored cfg objects.

Compared with develop d728f0335: 577 fewer package-production lines and 679 fewer test lines; 1,468 fewer lines overall, including documentation and release notes.

Migration

Normal InteractiveScene and clone_plan_from_env_0 signatures remain unchanged.

Direct plan callers use ClonePlan(topology, asset_cfgs, env_template=..., positions=...). ReplicateSession takes world_prototypes and weights instead of valid_set; sequential selection produces contiguous weighted groups.

path and query are stateless function namespaces in clone_plan.py, exported from isaaclab.cloner. Import the namespaces from the package; cloner.path.* and cloner.query.* calls remain unchanged.

Path filters live in cloner.path and take the host plan. Numeric queries take plan.topology and integer IDs, individually or in batches. All three numeric queries return flat world indices and boundaries shaped [num_queries, num_worlds + 2]. Warp callers supply resident IDs and preallocated outputs.

Custom clone contexts receive replicate(plan, asset_prototype_ids); context instances are constructed by the dispatcher from the simulation. Authored sources come from cloner.path.get_asset_prototype_paths(plan). get_world_prototype_asset_templates(plan) returns templates and prototype boundaries; include_world_indices=True additionally returns world IDs and their per-prototype boundaries. These tables replace get_instance_paths; the two boundary arrays group different relationships. Neither table depends on a USD context. Removed joined path mappings, iter_subtree_copies, and the under/relativize/split wrappers. Compose plan indexing with match, relative_to, rebase, and get_parent_indices; the API reference documents these primitives. Raw backend replication APIs retain their path-based inputs.

Performance check

Matched warm runs of 2c2c7bb55 against develop d728f0335 on RTX 5090 GPU 0: 4096 environments, seed 42, identical dependencies, no interactive visualizer. Newton uses MJWarp. Each checkout/workload had one excluded primer, then two fresh warm launches with the PR/develop order reversed for the second pair. Values are means of those two samples.

Workload	Physics → renderer	Startup PR / develop (s)	Runtime PR / develop (ms/step)	Aggregate FPS PR / develop
Cartpole	Newton → none	5.06 / 5.02	1.246 / 1.280	3,287,586 / 3,199,427
Humanoid	Newton → none	6.95 / 6.93	8.028 / 8.033	510,212 / 509,877
Franka Lift (varied objects)	Newton → none	9.16 / 11.71	15.465 / 15.902	264,855 / 257,581
Rough Anymal-D	Newton → none	10.66 / 10.73	29.491 / 29.346	138,889 / 139,577
Kuka Allegro (cube)	Newton → none	10.92 / 10.91	18.800 / 18.504	217,874 / 221,360
Kuka Allegro (varied objects)	Newton → none	11.38 / 15.04	18.100 / 17.828	226,292 / 229,748
Cartpole Camera	Newton → Newton	6.49 / 6.50	5.012 / 5.057	817,279 / 810,016
Kuka Camera (cube)	Newton → Newton	13.47 / 13.40	29.159 / 28.731	140,472 / 142,564
Kuka Camera (varied objects)	Newton → Newton	14.17 / 18.53	28.207 / 28.076	145,213 / 145,890
Cartpole	OVPhysX → none	11.06 / 10.89	3.693 / 3.796	1,108,994 / 1,078,998

• Heterogeneous manipulation startup improved by 21.8–24.3%. Scene creation accounts for approximately 2.6 s of the Franka saving, 3.5 s for Kuka, and 4.2 s for Kuka Camera. Newton composes each selected world prototype once and batches contiguous copies. Homogeneous scenes already had a batched path.
• Controls are approximately neutral, not universally faster. The largest startup cost was OVPhysX Cartpole: +0.17 s (+1.6%), with overlapping sample ranges. Runtime changes were small and mixed: 1.6% slower to 2.7% faster. This sweep does not establish a general runtime improvement.
• Sequential heterogeneous assignment now groups worlds contiguously by prototype rather than round-robin. Variant counts match, but per-world variant order and random-action contact trajectories can differ.
• Native body/shape counts matched; every Newton case used one backend. Camera output was finite and nonconstant. Process peak RSS differed by at most 15 MB (<1%). Savings persisted when including reset and the 20 warmup steps.

Startup includes imports, cfg resolution, application launch, and completed environment construction; it excludes explicit reset, warmup, and teardown. Runtime measures a GPU-synchronized 100-step random-action loop after 20 warmup steps. FPS is aggregate environment-steps/s, not policy-training throughput. These are warm-cache results, not cold startup measurements.

Validation

• Latest follow-up: 85 tests and 4 subtests passed across the core and Newton cloner suites. Extended existing tests reproduced the spawnless-child and root-transform regressions before the fix and passed afterward. A two-link Newton reproduction retained one intact revolute articulation.
• 338 tests and 4 subtests passed: core/Newton/OVPhysX/OVRTX cloning, NumPy/Warp queries and CUDA graph replay, material binding, deformable/MPM geometry, segmentation, frame views, scene lifecycle, and separate Kit core/PhysX cloner suites. OVPhysX CPU and GPU tests ran in separate processes.
• The existing material-initialization regression fails with the previous method and passes with the fix; its simulation fixture supplies only the plan, not clone contexts.
• Repository-wide ownership audit and an existing architecture test prevent consumer access to clone-context instances.
• uv run isaaclab -f, changelog validation, and git diff --check passed. Documentation builds in CI.

Type of change

• Breaking API change for direct plan callers and custom clone contexts.
• Documentation update.

Checklist

• Read the contribution guidelines
• Ran formatting and lint checks
• Updated documentation and migration notes
• Extended and consolidated existing tests
• Added a changelog fragment for each touched package
• Contributor already listed

Release backport

• Backport to the active release branch

[ooctipus]

run-ci

[greptile-apps]

Confidence Score: 3/5

[High risk] Restructures the clone plan data model across the codebase.

The PR should not merge until spawnless descendant replication and preservation of environment-root transforms are addressed.

Findings

1.  Spawnless descendants are replicated twice ▶
2.  Environment root transforms are discarded ▶

Summary

The PR changes ClonePlan to retain source configurations and per-environment variant selections, deriving path-based mappings for USD and physics backends. It also narrows cloning to declared subtrees and updates scene construction, queries, consumers, tests, and documentation.

• The direct homogeneous-plan helper can replicate spawnless descendants twice.
• USD asset-level replication can discard existing environment-root rotation or scale operations.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  C[Source configurations] --> P[ClonePlan: variant selections]
  P --> Q[replication_mapping]
  Q --> U[USD replication]
  Q --> N[Native physics replication]
  P --> R[Clone queries and scene consumers]

Loading

_{Reviews (1) · Last reviewed commit: "Preserve declared prim types when positi..."}

[isaaclab-review-bot]

Isaac Lab Review Bot

The cfg-backed ClonePlan consolidates variant selection and backend path derivation through replication_mapping, but two issues need correction: public cloner fields and arguments are removed without the required deprecation period, and clone_plan_from_env_0 treats spawnerless environment-scoped declarations as active prototypes, producing wildcard paths that low-level backends cannot consume.

• Design and architecture: Retaining source configurations and deriving backend mappings from one plan removes duplicated manifests and keeps declared subtree ownership explicit. However, the homogeneous planner must distinguish declarations used for querying from concrete prototype roots eligible for backend replication.
• API: The changes remove or redefine public ClonePlan fields and remove the global_paths parameters from make_clone_plan and ReplicateSession immediately. Migration documentation and a breaking changelog entry are present, but the repository requires prior deprecation; compatibility properties and transitional arguments are needed before removal.
• Implementation: clone_plan_from_env_0 marks every environment-scoped configuration as populated, including configurations without spawners. Consequently, _iter_prototypes can synthesize regex-containing paths such as /World/envs/env_0/Robot/[^/]*; the changed OVPhysX contact-sensor path then passes that non-prim source to ovphysx_replicate, which rejects it. Only declarations with concrete prototype paths should contribute replication mappings.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[ooctipus]

run-ci

[ooctipus]

run-ci

[StafaH]

Let's make sure that names are updated to reflect the new value, e.g. I caught scene_entities not being updated to scene even though its value is now InteractiveScene.

Also will need updated performance (especially for homogenous scenes under newton)

[ooctipus]

run-ci

[ooctipus]

Fixed the standalone Kit failure in 46821c6. With 2 environments and 16 declared layouts, weighted sequential selection chose layouts 4 and 12 rather than the full first bin. Some grocery cfgs then had no selected spawn path.

The demo now limits its layouts to the environment count, so the full first bin is always selected. Only examples/bin_packing.py changed (+6/-6); no generic cloner changes or additional tests.

Validated locally on GPU 1 with Isaac PhysX, no visualizer, and 10 simulation steps for both 1 and 2 environments. Checked layout coverage for 1, 2, 16, and 32 environments. Formatting and lint checks passed.

[ooctipus]

run-ci

[ooctipus]

run-ci

[ooctipus]

run-ci