Fix MuJoCo tendon duplication in Newton physics replication

Horde · Horde · commit ea456bcafd59 · 2026-04-28T23:40:36.000Z
add_builder is called once per environment in _build_newton_builder_from_mapping.
Each call appends T tendon custom-attribute entries (from the prototype), so after
N environments the builder has N×T entries instead of the T entries that
Newton's SolverMuJoCo expects (it only reads tendons from world 0 and replicates
them internally).

Introduce _deduplicate_tendon_attributes, which trims all mujoco:tendon*,
mujoco:tendon_joint*, and mujoco:tendon_wrap* custom attribute lists back to the
template-world (world-0) count after the build loop completes.  The trim boundary
is captured from _custom_frequency_counts after the first world is processed.

Add 8 unit tests in test/cloner/test_tendon_deduplication.py that exercise
the helper directly using Newton's ModelBuilder API without requiring Isaac Sim
or MJCF XML parsing.

Bump version to 0.5.16.
diff --git a/source/isaaclab_newton/config/extension.toml b/source/isaaclab_newton/config/extension.toml
@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.5.15"
+version = "0.5.16"
 
 # Description
 title = "Newton simulation interfaces for IsaacLab core package"
diff --git a/source/isaaclab_newton/docs/CHANGELOG.rst b/source/isaaclab_newton/docs/CHANGELOG.rst
@@ -1,6 +1,21 @@
 Changelog
 ---------
 
+0.5.16 (2026-04-28)
+~~~~~~~~~~~~~~~~~~~
+
+Fixed
+^^^^^
+
+* Fixed MuJoCo tendon duplication in Newton physics replication.
+  :func:`~isaaclab_newton.cloner.newton_replicate._build_newton_builder_from_mapping`
+  called ``add_builder`` once per environment, which appended T tendon custom-attribute
+  entries each time and produced N×T entries after N environments instead of the T
+  template-world entries that Newton's SolverMuJoCo expects.  A new
+  ``_deduplicate_tendon_attributes`` helper now trims all ``mujoco:tendon*``
+  custom-attribute lists back to the world-0 (template) count after the build loop.
+
+
 0.5.15 (2026-04-28)
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/isaaclab_newton/isaaclab_newton/cloner/newton_replicate.py b/source/isaaclab_newton/isaaclab_newton/cloner/newton_replicate.py
@@ -19,6 +19,81 @@
 from isaaclab_newton.physics import NewtonManager
 
 
+def _deduplicate_tendon_attributes(
+    builder: ModelBuilder,
+    tendon_count: int,
+    tendon_joint_count: int,
+    tendon_wrap_count: int,
+) -> None:
+    """Trim replicated MuJoCo tendon custom attributes to the template-world entries only.
+
+    Newton's SolverMuJoCo only reads tendons from the template world (world 0) and
+    replicates them across all worlds internally.  Because the cloner calls
+    ``add_builder`` once per environment, each call appends T tendon entries, yielding
+    N×T total after N environments.  This function restores the correct T count so the
+    solver receives exactly the template entries.
+
+    Args:
+        builder: Newton model builder to update in-place.
+        tendon_count: Number of ``mujoco:tendon``-frequency entries to keep
+            (global entries + template-world entries).
+        tendon_joint_count: Number of ``mujoco:tendon_joint``-frequency entries to keep.
+        tendon_wrap_count: Number of ``mujoco:tendon_wrap``-frequency entries to keep.
+    """
+    _TENDON_ATTRS = [
+        "mujoco:tendon_world",
+        "mujoco:tendon_stiffness",
+        "mujoco:tendon_damping",
+        "mujoco:tendon_frictionloss",
+        "mujoco:tendon_limited",
+        "mujoco:tendon_range",
+        "mujoco:tendon_margin",
+        "mujoco:tendon_solref_limit",
+        "mujoco:tendon_solimp_limit",
+        "mujoco:tendon_solref_friction",
+        "mujoco:tendon_solimp_friction",
+        "mujoco:tendon_armature",
+        "mujoco:tendon_springlength",
+        "mujoco:tendon_joint_adr",
+        "mujoco:tendon_joint_num",
+        "mujoco:tendon_actuator_force_range",
+        "mujoco:tendon_actuator_force_limited",
+        "mujoco:tendon_label",
+        "mujoco:tendon_type",
+        "mujoco:tendon_wrap_adr",
+        "mujoco:tendon_wrap_num",
+    ]
+    _TENDON_JOINT_ATTRS = ["mujoco:tendon_joint", "mujoco:tendon_coef"]
+    _TENDON_WRAP_ATTRS = [
+        "mujoco:tendon_wrap_type",
+        "mujoco:tendon_wrap_shape",
+        "mujoco:tendon_wrap_sidesite",
+        "mujoco:tendon_wrap_prm",
+    ]
+
+    for key in _TENDON_ATTRS:
+        attr = builder.custom_attributes.get(key)
+        if attr is not None and isinstance(attr.values, list):
+            attr.values = attr.values[:tendon_count]
+
+    for key in _TENDON_JOINT_ATTRS:
+        attr = builder.custom_attributes.get(key)
+        if attr is not None and isinstance(attr.values, list):
+            attr.values = attr.values[:tendon_joint_count]
+
+    for key in _TENDON_WRAP_ATTRS:
+        attr = builder.custom_attributes.get(key)
+        if attr is not None and isinstance(attr.values, list):
+            attr.values = attr.values[:tendon_wrap_count]
+
+    if "mujoco:tendon" in builder._custom_frequency_counts:
+        builder._custom_frequency_counts["mujoco:tendon"] = tendon_count
+    if "mujoco:tendon_joint" in builder._custom_frequency_counts:
+        builder._custom_frequency_counts["mujoco:tendon_joint"] = tendon_joint_count
+    if "mujoco:tendon_wrap" in builder._custom_frequency_counts:
+        builder._custom_frequency_counts["mujoco:tendon_wrap"] = tendon_wrap_count
+
+
 def _build_newton_builder_from_mapping(
     stage: Usd.Stage,
     sources: list[str],
@@ -92,6 +167,13 @@ def _build_newton_builder_from_mapping(
     num_worlds = mapping.size(1)
     local_site_map: dict[str, list[list[int]]] = {}
 
+    # Snapshot tendon counts before the world loop.  add_builder appends T tendon
+    # entries per environment, yielding N×T after N worlds.  We capture the counts
+    # after world 0 (the template) and deduplicate once the loop is done.
+    _template_tendon_count: int = -1
+    _template_tendon_joint_count: int = 0
+    _template_tendon_wrap_count: int = 0
+
     # create a separate world for each environment (heterogeneous spawning)
     # Newton assigns sequential world IDs (0, 1, 2, ...), so we need to track the mapping
     for col, _ in enumerate(env_ids.tolist()):
@@ -115,6 +197,21 @@ def _build_newton_builder_from_mapping(
         # end the world context
         builder.end_world()
 
+        # Capture counts after world 0 — these are the template (global + env-0) entries.
+        if col == 0:
+            _template_tendon_count = builder._custom_frequency_counts.get("mujoco:tendon", 0)
+            _template_tendon_joint_count = builder._custom_frequency_counts.get("mujoco:tendon_joint", 0)
+            _template_tendon_wrap_count = builder._custom_frequency_counts.get("mujoco:tendon_wrap", 0)
+
+    # Remove duplicate tendon entries appended by subsequent add_builder calls.
+    # Newton's SolverMuJoCo only reads world-0 tendons and replicates them internally.
+    if _template_tendon_count >= 0 and (
+        builder._custom_frequency_counts.get("mujoco:tendon", 0) > _template_tendon_count
+    ):
+        _deduplicate_tendon_attributes(
+            builder, _template_tendon_count, _template_tendon_joint_count, _template_tendon_wrap_count
+        )
+
     site_index_map = {
         **global_site_map,
         **{label: (None, per_world) for label, per_world in local_site_map.items()},
diff --git a/source/isaaclab_newton/test/cloner/test_tendon_deduplication.py b/source/isaaclab_newton/test/cloner/test_tendon_deduplication.py
@@ -0,0 +1,218 @@
+# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Unit tests for MuJoCo tendon deduplication in the Newton cloner.
+
+:func:`_deduplicate_tendon_attributes` corrects the N×T tendon-entry duplication
+that arises when IsaacLab's Newton cloner calls ``add_builder`` once per environment
+(N times) with a prototype that carries T tendon entries.  Newton's SolverMuJoCo
+expects only the template-world (world 0) entries and replicates them internally.
+
+Tests construct builder state directly via Newton's ``ModelBuilder`` API so that
+no Isaac Sim or MJCF XML parsing is required.
+"""
+
+import unittest
+
+import newton
+from isaaclab_newton.cloner.newton_replicate import _deduplicate_tendon_attributes
+from newton.solvers import SolverMuJoCo
+
+# ─── helpers ────────────────────────────────────────────────────────────────
+
+_TENDON_FREQ = "mujoco:tendon"
+_TENDON_JOINT_FREQ = "mujoco:tendon_joint"
+_TENDON_WRAP_FREQ = "mujoco:tendon_wrap"
+
+
+def _registered_builder() -> newton.ModelBuilder:
+    """Return a ModelBuilder with MuJoCo custom attributes registered."""
+    b = newton.ModelBuilder()
+    SolverMuJoCo.register_custom_attributes(b)
+    return b
+
+
+def _inject_tendon_entries(
+    builder: newton.ModelBuilder,
+    world: int,
+    names: list[str],
+    stiffnesses: list[float],
+    joint_entries_per_tendon: int,
+) -> None:
+    """Append synthetic tendon entries to *builder* for the given *world*.
+
+    Directly manipulates custom attribute lists and frequency counts, mimicking
+    what ``add_builder`` does when copying a prototype with tendon data.
+    """
+    t = len(names)
+    j = t * joint_entries_per_tendon
+    world_attr = builder.custom_attributes.get("mujoco:tendon_world")
+    label_attr = builder.custom_attributes.get("mujoco:tendon_label")
+    stiff_attr = builder.custom_attributes.get("mujoco:tendon_stiffness")
+    joint_adr_attr = builder.custom_attributes.get("mujoco:tendon_joint_adr")
+    joint_num_attr = builder.custom_attributes.get("mujoco:tendon_joint_num")
+    joint_attr = builder.custom_attributes.get("mujoco:tendon_joint")
+    coef_attr = builder.custom_attributes.get("mujoco:tendon_coef")
+
+    for attr in (world_attr, label_attr, stiff_attr, joint_adr_attr, joint_num_attr):
+        if attr is not None and attr.values is None:
+            attr.values = []
+    for attr in (joint_attr, coef_attr):
+        if attr is not None and attr.values is None:
+            attr.values = []
+
+    current_joint_offset = builder._custom_frequency_counts.get(_TENDON_JOINT_FREQ, 0)
+    for i, (name, stiff) in enumerate(zip(names, stiffnesses)):
+        if world_attr is not None:
+            world_attr.values.append(world)
+        if label_attr is not None:
+            label_attr.values.append(name)
+        if stiff_attr is not None:
+            stiff_attr.values.append(stiff)
+        if joint_adr_attr is not None:
+            joint_adr_attr.values.append(current_joint_offset + i * joint_entries_per_tendon)
+        if joint_num_attr is not None:
+            joint_num_attr.values.append(joint_entries_per_tendon)
+    for _ in range(j):
+        if joint_attr is not None:
+            joint_attr.values.append(0)
+        if coef_attr is not None:
+            coef_attr.values.append(1.0)
+
+    builder._custom_frequency_counts[_TENDON_FREQ] = builder._custom_frequency_counts.get(_TENDON_FREQ, 0) + t
+    builder._custom_frequency_counts[_TENDON_JOINT_FREQ] = (
+        builder._custom_frequency_counts.get(_TENDON_JOINT_FREQ, 0) + j
+    )
+
+
+def _tendon_count(b: newton.ModelBuilder) -> int:
+    return b._custom_frequency_counts.get(_TENDON_FREQ, 0)
+
+
+def _tendon_joint_count(b: newton.ModelBuilder) -> int:
+    return b._custom_frequency_counts.get(_TENDON_JOINT_FREQ, 0)
+
+
+def _world_values(b: newton.ModelBuilder) -> list[int]:
+    attr = b.custom_attributes.get("mujoco:tendon_world")
+    if attr is None or not isinstance(attr.values, list):
+        return []
+    return [int(v) for v in attr.values]
+
+
+def _label_values(b: newton.ModelBuilder) -> list[str]:
+    attr = b.custom_attributes.get("mujoco:tendon_label")
+    if attr is None or not isinstance(attr.values, list):
+        return []
+    return list(attr.values)
+
+
+# ─── test cases ─────────────────────────────────────────────────────────────
+
+
+class TestTendonDeduplication(unittest.TestCase):
+    """Verifies that _deduplicate_tendon_attributes trims N×T entries to T."""
+
+    # Test parameters: 2 tendons, 2 joint entries each → 4 joint entries total per world.
+    NAMES = ["tendon_coupling", "tendon_sum"]
+    STIFFNESSES = [2.0, 1.0]
+    JOINT_ENTRIES_PER_TENDON = 2
+    T = len(NAMES)
+    T_JOINT = T * JOINT_ENTRIES_PER_TENDON
+
+    def _build_duplicated(self, n_envs: int) -> tuple[newton.ModelBuilder, int, int]:
+        """Return a builder with N×T entries and the template counts (T, T_joint)."""
+        main = _registered_builder()
+        template_tendon = 0
+        template_joint = 0
+        for world in range(n_envs):
+            _inject_tendon_entries(main, world, self.NAMES, self.STIFFNESSES, self.JOINT_ENTRIES_PER_TENDON)
+            if world == 0:
+                template_tendon = _tendon_count(main)
+                template_joint = _tendon_joint_count(main)
+        return main, template_tendon, template_joint
+
+    def test_duplication_exists_before_fix(self):
+        """Without fix, N add_builder calls produce N×T tendon entries."""
+        n = 4
+        main, _, _ = self._build_duplicated(n)
+        self.assertEqual(_tendon_count(main), n * self.T)
+        self.assertEqual(_tendon_joint_count(main), n * self.T_JOINT)
+
+    def test_deduplication_restores_template_count(self):
+        """After fix, exactly T tendon entries remain."""
+        n = 4
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        self.assertEqual(_tendon_count(main), self.T)
+        self.assertEqual(_tendon_joint_count(main), self.T_JOINT)
+
+    def test_deduplication_all_entries_are_world_0(self):
+        """After fix, every remaining tendon_world entry equals 0."""
+        n = 5
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        worlds = _world_values(main)
+        self.assertEqual(len(worlds), self.T)
+        self.assertTrue(all(w == 0 for w in worlds), f"Expected world=0, got {worlds}")
+
+    def test_deduplication_preserves_template_labels(self):
+        """After fix, the surviving labels are the template world's names."""
+        n = 3
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        labels = _label_values(main)
+        self.assertEqual(sorted(labels), sorted(self.NAMES))
+
+    def test_deduplication_frequency_counts_match_list_lengths(self):
+        """_custom_frequency_counts must stay consistent with attribute list lengths."""
+        n = 6
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+
+        reported_t = main._custom_frequency_counts.get(_TENDON_FREQ, 0)
+        actual_t = len(main.custom_attributes["mujoco:tendon_world"].values)
+        self.assertEqual(reported_t, actual_t)
+
+        reported_j = main._custom_frequency_counts.get(_TENDON_JOINT_FREQ, 0)
+        actual_j = len(main.custom_attributes["mujoco:tendon_joint"].values)
+        self.assertEqual(reported_j, actual_j)
+
+    def test_no_change_for_single_env(self):
+        """For N=1 no duplication occurs; counts must stay T after a no-op trim."""
+        main, tmpl_t, tmpl_j = self._build_duplicated(1)
+        self.assertEqual(_tendon_count(main), self.T)
+        # No trimming needed (caller guards on count > template), but the function
+        # should be safe to call anyway.
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        self.assertEqual(_tendon_count(main), self.T)
+        self.assertEqual(_tendon_joint_count(main), self.T_JOINT)
+
+    def test_deduplication_is_idempotent(self):
+        """Calling _deduplicate_tendon_attributes twice must not trim further."""
+        n = 4
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+        self.assertEqual(_tendon_count(main), self.T)
+        self.assertEqual(_tendon_joint_count(main), self.T_JOINT)
+
+    def test_regression_bug_n_times_t_entries(self):
+        """Regression: verify the reported bug (N×T instead of T) is fixed."""
+        n = 8
+        main, tmpl_t, tmpl_j = self._build_duplicated(n)
+
+        # BUG: before fix, count == n * T
+        self.assertEqual(_tendon_count(main), n * self.T, "pre-condition: duplication present")
+
+        _deduplicate_tendon_attributes(main, tmpl_t, tmpl_j, 0)
+
+        # FIX: after deduplication, count == T
+        self.assertEqual(_tendon_count(main), self.T, "post-condition: deduplication applied")
+        self.assertNotEqual(_tendon_count(main), n * self.T, "count must not be N×T after fix")
+
+
+if __name__ == "__main__":
+    unittest.main()
