[Newton] Delegate homogeneous world prefix generation to ModelBuilder.replicate()

[camevor]

Description

This depends on newton-physics/newton#4012 and pins the Newton 1.6 development build that first provides ModelBuilder.replicate(..., label_prefixes=...).

The homogeneous Newton cloning path previously replicated the model and then walked every replicated entity label to replace the prototype environment with its destination environment. It now rebases only the retained prototype labels, restores them after the call, and lets ModelBuilder.replicate() assign each copy's destination prefix while it is created. String-valued custom attributes still use the existing targeted rewrite because Newton cannot identify which strings are entity paths.

The destination itself is the source of identity: prefixes are derived from the queued source/destination mapping. No clone-plan environment metadata, scene discovery, fallback clone path, or retained prototype mutation is introduced. Labels exactly at a directly cloned asset root, including Newton's _free_joint and _articulation companion labels, are expressed relative to the nearest templated destination ancestor and remain on the same fast path.

The Newton commit pin is mirrored in workspace and wheel installation inputs so every supported install receives the API this path requires.

The final PR is +195/-218, net -23 LOC.

Performance

GPU 0, 4096 worlds, two samples per PR head. The targeted measurement uses one 48-body/48-shape Newton prototype and times replication plus all required label publication:

Head	Targeted path median	Versus develop
develop base (3a31389a9)	1.428 s	—
original PR (cbb17ab6e)	1.160 s	-18.8%
cleaned PR (844f4c4db)	1.171 s	-18.0%

The cleanup is within 1.0% (11 ms) of the original PR result and preserves the removed-pass gain. The 257 ms reduction from develop is consistent with the original 215 ms observation on Isaac-Velocity-Flat-G1.

Whole-workload check used:

CUDA_VISIBLE_DEVICES=0 uv run --no-sync isaaclab zero_agent \
  --task Isaac-Lift-KukaAllegro --num_envs 4096 --max_steps 1 \
  --device cuda:0 --visualizer none physics=newton_mjwarp

Head	Warm wall median	Scene creation median
original PR	21.30 s	6.324 s
cleaned PR	21.39 s	6.345 s

That end-to-end difference is within startup noise; the cleanup introduces no measured workload regression.

Type of change

• Startup performance enhancement

Validation

• 81 focused clone, Newton, visualization-state, wheel-metadata, and install tests passed.
• Ruff formatting and lint checks passed.
• Exact-root, sparse-environment, hook-authored-label, custom-attribute, and retained-prototype cases are covered.
• The changelog fragment is present for the changed Newton package.

Checklist

• I have read and understood the contribution guidelines
• My changes generate no new warnings
• I have added tests that prove the fix is effective
• I have added the required changelog fragment
• My name already exists in CONTRIBUTORS.md

[greptile-apps]

Greptile Summary

The PR propagates the clone plan’s environment template into backend replication and delegates homogeneous Newton entity naming to ModelBuilder.replicate(). It also qualifies per-world site labels with their destination environment and updates Newton to the required pinned 1.6 development commit.

• Stores env_template on ClonePlan and passes it to replication contexts.
• Rebases homogeneous prototype labels once and supplies per-environment label prefixes during Newton replication.
• Carries destination templates through site registration so bodyless per-world sites receive environment-qualified labels.
• Preserves the existing rewrite path when labels cannot be represented by a per-world prefix.
• Updates tests, changelog fragments, and the Newton dependency lock entry.

Confidence Score: 5/5

The PR appears safe to merge, with no actionable changed-code defect identified.

The new template and label-prefix data are propagated consistently through clone planning, backend construction, site registration, replication, and fallback rewriting, while body bindings and custom-attribute rewriting remain intact.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/cloner/clone_plan.py	Persists the environment destination template in every clone-plan construction path.
source/isaaclab/isaaclab/cloner/replicate_session.py	Propagates the clone plan’s environment template to each backend replication context.
source/isaaclab_newton/isaaclab_newton/cloner/newton_clone_utils.py	Adds prototype-label rebasing, delegated per-environment naming, and environment-qualified site-label generation while retaining fallback rewriting.
source/isaaclab_newton/isaaclab_newton/cloner/replicate.py	Threads the environment template through Newton model construction and skips redundant entity rewriting only when replication already named the copies.
source/isaaclab_newton/isaaclab_newton/physics/newton_manager.py	Extends pending site registrations with destination-template identity and carries it into injected per-world sites.
source/isaaclab_newton/isaaclab_newton/sim/views/newton_site_frame_view.py	Includes destination templates in resolved bodyless-site specifications and registration.
pyproject.toml	Pins Newton to the development commit providing label-prefix replication support.
uv.lock	Updates only Newton’s source and version while preserving its resolved dependency set.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[ClonePlan with env_template] --> B[Backend replication context]
    B --> C[Build Newton source prototypes]
    C --> D{Homogeneous and labels rebase cleanly?}
    D -- Yes --> E[ModelBuilder.replicate with per-env prefixes]
    D -- No --> F[Replicate then rewrite labels]
    E --> G[Rewrite string custom attributes]
    F --> G
    B --> H[Register per-world sites with destination template]
    H --> I[Environment-qualified site labels]
    G --> J[Final Newton model]
    I --> J

Loading

_{Reviews (1): Last reviewed commit: "Update newton pin" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The replication-prefix optimization is well scoped, but two compatibility issues need correction: the fast path mutates retained prototype labels, and NewtonReplicateContext.__init__ silently rebinds existing positional arguments by inserting env_template before device.

• Design and architecture: Delegating homogeneous label prefixing to ModelBuilder.replicate() with a guarded fallback is sound, but rebasing the source builder in place makes retained prototype state depend on the replication path. Rebase a copy or restore labels after replication.
• API: ClonePlan.env_template is defaulted and propagated consistently to in-tree contexts. However, inserting env_template before existing positional parameters in NewtonReplicateContext.__init__ breaks positional-call compatibility and the new argument is omitted from the docstring. Preserve the existing parameter order or make the new argument keyword-only.
• Implementation: The batched and per-world site paths and three-value replication result are wired through their consumers and tests. The remaining implementation defect is that _rebase_to_env permanently changes builders later retained in NewtonManager._cl_protos, exposing environment-relative labels to single-model consumers.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Implementation — Rebase mutates retained prototype builders

_rebase_to_env rewrites source_builder labels in place, and that same object is returned in source_builders, stored as NewtonManager._cl_protos, and handed out by copy_newton_clone_source for single-model consumers. On the delegated path the retained prototype now carries env-relative labels (Robot/base) instead of the clone-plan source path, so prototype label state differs between the two cloning paths. Rebase a copy, or restore the labels after replicate().

[isaaclab-review-bot]

🟡 Warning · Api — New parameter inserted before existing positional arguments

env_template is inserted between global_paths and device in NewtonReplicateContext.__init__, so an existing positional call such as NewtonReplicateContext(stage, paths, "cuda:0") silently binds the device string to the template and falls back to device="cpu". The USD and OvPhysX contexts append the parameter last. Append it after the existing parameters (or make it keyword-only) and document it in the Args block, which currently omits it.

[StafaH]

Since this is moving the newton pin, we won't be able to backport this to our release branch, it'll have to stay in develop until GA. Is that okay?

[StafaH]

Please use absolute imports here and elsewhere (feel free to change other imports in the file to match)

[StafaH]

The wording here is a bit confusing "every world is the shape replication can name itself:"

[ooctipus]

Nice finding chris , there is soem duplication is stored attribute I will help to make this pr leaner

[ooctipus]

run-ci

[ooctipus]

run-ci

[ooctipus]

run-ci

[kellyguo11]

run-ci

[ooctipus]

run-ci

[ooctipus]

run-ci

[kellyguo11]

run-ci

[kellyguo11]

run-ci