Fix cable routing contact and replay semantics

Author: maxkra15

source/isaaclab_tasks/changelog.d/maximiliank-cable-routing-yam.minor.rst

@@ -25,8 +25,12 @@ Fixed
   represented gripper actions by their binary command state, and made terminal success and failure
   rewards independent of control frequency. Newton actuator graph capture and complete-episode PPO
   startup are now enabled for training.
-* Applied explicit Newton contact materials to YAM and fixture assets, proxied every collidable YAM
-  link into the cable solver, and declared the task's Newton and contrib runtime dependencies.
+* Applied explicit Newton contact materials to the fixtures and a task calibration layer that keeps
+  the Menagerie actuator dynamics while targeting high friction to YAM fingers. Limited the cable
+  solver proxy to each wrist/gripper subtree, and declared the task's Newton and contrib runtime
+  dependencies.
+* Prevented simultaneous success and invalid-state terminations from receiving successful reset
+  replay credit.
 * Avoided redundant or manager-order-dependent route evaluation and expensive ordinary cable
   generation when a full-scene replay reset will replace it.
 * Replaced legacy dense tangent-point optimization with a deterministic, fixed-sweep XPBD-style

source/isaaclab_tasks/isaaclab_tasks/contrib/cable_routing/assets/yam/README.md

@@ -1,8 +1,8 @@
 # I2RT YAM asset snapshot
 
 This directory contains the self-contained `i2rt_yam_default` USD package used
-by the cable-routing environment. It was copied on 2026-08-05 from NVIDIA's
-Robot Menagerie repository:
+by the cable-routing environment. The eight source USD files were copied on
+2026-08-05 from NVIDIA's Robot Menagerie repository:
 
 - repository: `https://gitlab-master.nvidia.com/isaac-applications-deployment/robot_menagerie`
 - `main` commit: `68ef1e0cc3e863a861b873893f038496e0dfe16b`
@@ -16,18 +16,22 @@ source to `google-deepmind/mujoco_menagerie` commit
 digest `5ae901629db944abd3e6cbb0eaf28ea78bbda3483c840d6db1167e999cc0348c`.
 That source is MIT licensed; the required notice is preserved in `LICENSE.md`.
 
-All eight USD files are included and all layer references are relative. OpenUSD
-dependency traversal resolves seven dependent layers with no unresolved paths,
-so runtime does not require GitLab, Git LFS, Nucleus, or credentials.
+All eight source USD files are included and all layer references are relative.
+The `i2rt_yam_cable_routing.usda` task layer composes that unmodified snapshot,
+retains its authored actuator dynamics, and targets the calibrated high-friction
+contact material to the finger collision subtrees. OpenUSD dependency traversal
+resolves every layer with no unresolved paths, so runtime does not require
+GitLab, Git LFS, Nucleus, or credentials.
 
 - entry-layer SHA-256: `c1bedf1d978d1147f82d1c2cb5e56da1b5003eb14ec78bd0be89258c021404bc`
 - eight-file package size: `1,887,475` bytes
 - deterministic package-manifest SHA-256: `7a1532b694a51f263a9e09b60d212d40104aee871bcfa6e8c6705fd566698d47`
 
-The manifest digest is produced from the pristine USD directory with:
+The manifest digest is produced from the pristine eight-file source package
+(and intentionally excludes the task layer) with:
 
 ```bash
-find . -type f -print0 | sort -z | xargs -0 sha256sum | sha256sum
+find i2rt_yam i2rt_yam_default.usda -type f -print0 | sort -z | xargs -0 sha256sum | sha256sum
 ```
 
 Set `ISAACLAB_CABLE_ROUTING_YAM_USD_PATH` to an alternate local YAM USD for an

source/isaaclab_tasks/isaaclab_tasks/contrib/cable_routing/assets/yam/i2rt_yam_cable_routing.usda

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ffcdbb1e477694e26cd58d1a1f605752327fae774cd5e6dd6f7f4433599f8d88
+size 2338

source/isaaclab_tasks/isaaclab_tasks/contrib/cable_routing/cable_routing_env_cfg.py

@@ -3,7 +3,7 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""Manager-based bimanual YAM cable routing with Newton MJWarp/VBD coupling."""
+"""Manager-based two-F1-peg cable-routing milestone with Newton MJWarp/VBD coupling."""
 
 from __future__ import annotations
 
@@ -37,11 +37,14 @@
 
 from . import mdp
 
+YAM_SOURCE_USD_PATH = str(Path(__file__).resolve().parent / "assets" / "yam" / "i2rt_yam_default.usda")
+"""Pinned, unmodified Robot Menagerie YAM source package."""
+
 YAM_USD_PATH = os.environ.get(
     "ISAACLAB_CABLE_ROUTING_YAM_USD_PATH",
-    str(Path(__file__).resolve().parent / "assets" / "yam" / "i2rt_yam_default.usda"),
+    str(Path(__file__).resolve().parent / "assets" / "yam" / "i2rt_yam_cable_routing.usda"),
 )
-"""Pinned Robot Menagerie YAM, optionally replaced by an explicit local asset path."""
+"""Task-calibrated YAM layer, optionally replaced by an explicit local asset path."""
 
 MANIPULATIONNET_ASSET_DIR = Path(__file__).resolve().parent / "assets" / "manipulationnet"
 BOARD_USD_PATH = str(MANIPULATIONNET_ASSET_DIR / "board.usdc")
@@ -63,11 +66,13 @@
 ROUTE_AXIAL_CUTOFF = 0.5 * PEG_HEIGHT + CABLE_RADIUS
 """Cable-center height range whose surface can overlap the finite peg [m]."""
 CABLE_CENTER_Z = BOARD_TOP_Z + CABLE_RADIUS + 0.002
-CABLE_CONTACT_FRICTION = 5.0
-YAM_CONTACT_FRICTION = 5.0
+CABLE_CONTACT_FRICTION = 60.0
 FIXTURE_CONTACT_FRICTION = 0.5
 CONTACT_STIFFNESS = 4.0e4
+# Rigid-contact damping is distinct from cable bend damping, which the current
+# CableMaterialCfg and Newton USD cable importer do not expose.
 CONTACT_DAMPING = 1.0e-5
+FAILURE_TERMINATION_NAMES = ("invalid_cable", "invalid_robot_or_action")
 YAM_BASE_COLLISION_DEPTH = 0.017
 YAM_BASE_Z = TABLE_TOP_Z + YAM_BASE_COLLISION_DEPTH
 YAM_VISUAL_BASE_DEPTH = 0.07
@@ -173,7 +178,6 @@ def _make_yam_cfg(prim_path: str, position: tuple[float, float, float], yaw: flo
         spawn=sim_utils.UsdFileCfg(
             usd_path=YAM_USD_PATH,
             copy_from_source=False,
-            physics_material=_make_rigid_contact_material(YAM_CONTACT_FRICTION),
             # The converted Menagerie package retains legacy
             # ``mjc:body:gravcomp`` metadata.  Author the current Newton schema
             # spelling explicitly and route compensation through each drive so
@@ -199,29 +203,20 @@ def _make_yam_cfg(prim_path: str, position: tuple[float, float, float], yaw: flo
         actuators={
             "arm": ImplicitActuatorCfg(
                 joint_names_expr=["joint[1-6]"],
-                effort_limit_sim=40.0,
-                velocity_limit_sim=2.0,
-                stiffness=400.0,
-                damping=40.0,
-                armature=0.02,
+                stiffness=None,
+                damping=None,
             ),
             "gripper_drive": ImplicitActuatorCfg(
                 joint_names_expr=["left_finger"],
-                effort_limit_sim=80.0,
-                velocity_limit_sim=0.2,
-                stiffness=2000.0,
-                damping=100.0,
-                armature=0.1,
+                stiffness=None,
+                damping=None,
             ),
             # Robot Menagerie authors right_finger as a -1 mimic of left_finger.
             # Keeping its drive passive avoids fighting the Newton equality constraint.
             "gripper_passive": ImplicitActuatorCfg(
                 joint_names_expr=["right_finger"],
-                effort_limit_sim=1.0,
-                velocity_limit_sim=0.2,
                 stiffness=0.0,
                 damping=0.0,
-                armature=0.1,
             ),
         },
         soft_joint_pos_limit_factor=0.95,
@@ -363,6 +358,7 @@ class CommandsCfg:
         board_origin_b=(0.0, 0.0, BOARD_TOP_Z),
         radial_cutoff=0.05,
         axial_cutoff=ROUTE_AXIAL_CUTOFF,
+        failure_termination_names=FAILURE_TERMINATION_NAMES,
     )
 
 
@@ -510,13 +506,13 @@ class RewardsCfg:
         weight=20.0,
         params={
             "command_name": "route",
-            "failure_termination_names": ("invalid_cable", "invalid_robot_or_action"),
+            "failure_termination_names": FAILURE_TERMINATION_NAMES,
         },
     )
     failure = RewTerm(
         func=mdp.route_failure,
         weight=-20.0,
-        params={"termination_names": ("invalid_cable", "invalid_robot_or_action")},
+        params={"termination_names": FAILURE_TERMINATION_NAMES},
     )
     stretch = RewTerm(
         func=mdp.cable_stretch,
@@ -563,7 +559,7 @@ class TerminationsCfg:
 
 @configclass
 class CableRoutingEnvCfg(ManagerBasedRLEnvCfg):
-    """Goal-conditioned bimanual cable-routing environment using Newton only."""
+    """Goal-conditioned one-meter, two-F1-peg cable-routing environment using Newton."""
 
     scene: CableRoutingSceneCfg = CableRoutingSceneCfg(
         num_envs=256,
@@ -621,7 +617,7 @@ class CableRoutingEnvCfg(ManagerBasedRLEnvCfg):
                         source="rigid",
                         destination="cable",
                         bodies=[
-                            r"/World/envs/env_.*/Yam(Left|Right)",
+                            r"/World/envs/env_.*/Yam(Left|Right)/Geometry/arm/link_1/link_2/link_3/link_4/link_5/link_6",
                             r"/World/envs/env_.*/(Table|Board)",
                             r"/World/envs/env_.*/Peg(0|1)",
                         ],

source/isaaclab_tasks/isaaclab_tasks/contrib/cable_routing/mdp/commands.py

@@ -267,6 +267,9 @@ class CableRoutingCommandCfg(CommandTermCfg):
     reset_replay: CableResetReplayCfg = CableResetReplayCfg()
     """Success-conditioned full-scene reset replay configuration."""
 
+    failure_termination_names: tuple[str, ...] = ()
+    """Failure terms that invalidate terminal success before replay crediting."""
+
     marker_z_offset: float = 0.040
     """Height of the first ordered-step marker above a peg center [m]."""
 
@@ -1354,6 +1357,13 @@ def _cable_rest_length(self) -> float:
         """Return the cached authored mean cable-control-point edge length [m]."""
         return self._cable_rest_length_m
 
+    def _terminal_success(self, env_ids: torch.Tensor) -> torch.Tensor:
+        """Return terminal success after failure terminations take precedence."""
+        succeeded = self.succeeded[env_ids].clone()
+        for term_name in self.cfg.failure_termination_names:
+            succeeded &= ~self._env.termination_manager.get_term(term_name)[env_ids]
+        return succeeded
+
     def reset(self, env_ids: Sequence[int] | None = None) -> dict[str, float]:
         """Credit finished episodes, then atomically restore state and route."""
         all_ids = torch.arange(self.num_envs, device=self.device, dtype=torch.long)
@@ -1364,7 +1374,7 @@ def reset(self, env_ids: Sequence[int] | None = None) -> dict[str, float]:
         else:
             ids = torch.as_tensor(env_ids, device=self.device, dtype=torch.long)
 
-        terminal_success = self.succeeded[ids].clone()
+        terminal_success = self._terminal_success(ids)
         terminal_route = self.route_id[ids].clone()
         source_before_reset: torch.Tensor | None = None
         if self.reset_replay is not None and self.reset_replay.built:

source/isaaclab_tasks/test/contrib/test_cable_routing_cfg.py

@@ -40,6 +40,7 @@
     BOARD_TOP_Z,
     BOARD_USD_PATH,
     CABLE_BEND_MODULUS,
+    CABLE_CONTACT_FRICTION,
     CABLE_LENGTH,
     CABLE_NUM_SEGMENTS,
     CABLE_SEGMENT_LENGTH,
@@ -55,6 +56,7 @@
     YAM_GRIPPER_CLOSED_POS,
     YAM_GRIPPER_OPEN_POS,
     YAM_LATERAL_OFFSET,
+    YAM_SOURCE_USD_PATH,
     YAM_USD_PATH,
     YAM_VISUAL_BASE_DEPTH,
     YAM_VISUAL_BASE_WIDTH,
@@ -210,6 +212,22 @@ def test_terminal_outcome_rewards_are_control_frequency_independent() -> None:
     torch.testing.assert_close(failure_return, torch.tensor((0.0, -20.0, -20.0)))
 
 
+def test_reset_replay_success_credit_excludes_invalid_terminal_states() -> None:
+    """A simultaneous route completion and invalid state is a failed replay outcome."""
+    term_values = {
+        "invalid_cable": torch.tensor((False, True, False)),
+        "invalid_robot_or_action": torch.tensor((False, False, True)),
+    }
+    command = CableRoutingCommand.__new__(CableRoutingCommand)
+    command.succeeded = torch.tensor((True, True, True))
+    command.cfg = SimpleNamespace(failure_termination_names=tuple(term_values))
+    command._env = SimpleNamespace(termination_manager=SimpleNamespace(get_term=lambda name: term_values[name]))
+
+    terminal_success = command._terminal_success(torch.arange(3))
+
+    torch.testing.assert_close(terminal_success, torch.tensor((True, False, False)))
+
+
 def test_cable_routing_ppo_starts_from_complete_1p2_second_rollouts() -> None:
     """The first SuccessMonitor outcomes come from complete episodes and sufficiently long rollouts."""
     env_cfg = CableRoutingEnvCfg()
@@ -246,6 +264,7 @@ def test_cable_routing_manager_terms_use_menagerie_joint_and_body_names() -> Non
         assert term.params["asset_cfg"].joint_names == ["joint[1-6]"]
 
     assert cfg.events.reset_cable.params["full_scene_replay_command_name"] == "route"
+    assert cfg.commands.route.failure_termination_names == cfg.rewards.success.params["failure_termination_names"]
 
 
 def test_cable_routing_rewards_are_sparse_success_with_penalties_only() -> None:
@@ -533,8 +552,14 @@ def test_cable_routing_table_board_and_yams_have_front_edge_reachable_placement(
         assert yam.spawn.joint_drive_props[0].actuatorgravcomp is True
         assert set(yam.actuators) == {"arm", "gripper_drive", "gripper_passive"}
         assert yam.actuators["arm"].joint_names_expr == ["joint[1-6]"]
+        assert yam.actuators["arm"].stiffness is None
+        assert yam.actuators["arm"].damping is None
+        assert yam.actuators["arm"].effort_limit_sim is None
+        assert yam.actuators["arm"].velocity_limit_sim is None
+        assert yam.actuators["arm"].armature is None
         assert yam.actuators["gripper_drive"].joint_names_expr == ["left_finger"]
-        assert yam.actuators["gripper_drive"].stiffness == 2000.0
+        assert yam.actuators["gripper_drive"].stiffness is None
+        assert yam.actuators["gripper_drive"].damping is None
         assert yam.actuators["gripper_passive"].joint_names_expr == ["right_finger"]
         assert yam.actuators["gripper_passive"].stiffness == 0.0
         assert yam.init_state.joint_pos["left_finger"] == YAM_GRIPPER_OPEN_POS
@@ -562,11 +587,13 @@ def test_cable_routing_table_board_and_yams_have_front_edge_reachable_placement(
 
 
 def test_cable_routing_uses_complete_credential_free_yam_snapshot() -> None:
-    """Test the default YAM is the pinned, dependency-complete Menagerie package."""
+    """Test the default YAM composes a calibration layer over the pinned Menagerie package."""
     yam_path = Path(YAM_USD_PATH)
+    source_path = Path(YAM_SOURCE_USD_PATH)
 
     assert yam_path.is_file()
-    assert yam_path.name == "i2rt_yam_default.usda"
+    assert yam_path.name == "i2rt_yam_cable_routing.usda"
+    assert source_path.name == "i2rt_yam_default.usda"
     expected_hashes = {
         "i2rt_yam_default.usda": "c1bedf1d978d1147f82d1c2cb5e56da1b5003eb14ec78bd0be89258c021404bc",
         "i2rt_yam/i2rt_yam.usda": "d51c03bf78f1724c09ce46ae4c95cf64269871af25450fbc075bc2eb7cf08b55",
@@ -577,12 +604,12 @@ def test_cable_routing_uses_complete_credential_free_yam_snapshot() -> None:
         "i2rt_yam/Payload/MaterialsLibrary.usdc": ("c20c4d119a844c7efbb74905589bef2bcab5eaeb0b5518f81d16f997d9da9adb"),
         "i2rt_yam/Payload/Physics.usda": "51f028b6a305fc788eb0286a7e67bf5d43cab54727ffcfeb20ef6502230b10c9",
     }
-    usd_files = {path.relative_to(yam_path.parent).as_posix(): path for path in yam_path.parent.rglob("*.usd*")}
-    assert usd_files.keys() == expected_hashes.keys()
+    usd_files = {path.relative_to(source_path.parent).as_posix(): path for path in source_path.parent.rglob("*.usd*")}
+    assert usd_files.keys() == expected_hashes.keys() | {"i2rt_yam_cable_routing.usda"}
     for relative_path, expected_hash in expected_hashes.items():
         assert hashlib.sha256(usd_files[relative_path].read_bytes()).hexdigest() == expected_hash
 
-    for usd_path in yam_path.parent.rglob("*.usd*"):
+    for usd_path in source_path.parent.rglob("*.usd*"):
         if usd_path.suffix == ".usda":
             contents = usd_path.read_text(encoding="utf-8")
             assert "omniverse://" not in contents
@@ -594,6 +621,7 @@ def test_cable_routing_uses_complete_credential_free_yam_snapshot() -> None:
     package_root = yam_path.parent.resolve()
     resolved_layers = {Path(layer.identifier).resolve().relative_to(package_root).as_posix() for layer in layers}
     assert resolved_layers == {
+        "i2rt_yam_cable_routing.usda",
         "i2rt_yam_default.usda",
         "i2rt_yam/Payload/Contents.usda",
         "i2rt_yam/Payload/Geometry.usda",
@@ -615,7 +643,7 @@ def test_cable_routing_uses_disjoint_newton_collision_ownership() -> None:
     assert physics.use_cuda_graph
     assert physics.default_shape_cfg.ke == 4.0e4
     assert physics.default_shape_cfg.gap == 0.001
-    assert physics.default_shape_cfg.mu == 5.0
+    assert physics.default_shape_cfg.mu == CABLE_CONTACT_FRICTION
 
     coupler = physics.solver_cfg
     assert isinstance(coupler, CouplerProxyCfg)
@@ -651,15 +679,15 @@ def test_cable_routing_uses_disjoint_newton_collision_ownership() -> None:
     assert proxy.collide_interval == 2
     assert physics.num_substeps % proxy.collide_interval == 0
     assert proxy.bodies == [
-        r"/World/envs/env_.*/Yam(Left|Right)",
+        r"/World/envs/env_.*/Yam(Left|Right)/Geometry/arm/link_1/link_2/link_3/link_4/link_5/link_6",
         r"/World/envs/env_.*/(Table|Board)",
         r"/World/envs/env_.*/Peg(0|1)",
     ]
     assert coupler.model_cfg is None
 
+    assert cfg.scene.yam_left.spawn.physics_material is None
+    assert cfg.scene.yam_right.spawn.physics_material is None
     for asset_cfg, expected_friction in (
-        (cfg.scene.yam_left, 5.0),
-        (cfg.scene.yam_right, 5.0),
         (cfg.scene.table, 0.5),
         (cfg.scene.board, 0.5),
         (cfg.scene.peg_0, 0.5),

source/isaaclab_tasks/test/contrib/test_cable_routing_collisions.py

@@ -9,12 +9,15 @@
 import math
 from pathlib import Path
 
-from pxr import Sdf, Usd, UsdGeom, UsdPhysics
+from pxr import Sdf, Usd, UsdGeom, UsdPhysics, UsdShade
 
 from isaaclab_tasks.contrib.cable_routing.cable_routing_env_cfg import (
     BOARD_SIZE,
     BOARD_THICKNESS,
     BOARD_USD_PATH,
+    CABLE_CONTACT_FRICTION,
+    CONTACT_DAMPING,
+    CONTACT_STIFFNESS,
     PEG_HEIGHT,
     PEG_RADIUS,
     PEG_SHAFT_RADIUS,
@@ -207,6 +210,22 @@ def test_yam_menagerie_asset_uses_native_newton_primitive_colliders() -> None:
     assert all(UsdPhysics.CollisionAPI(prim).GetCollisionEnabledAttr().Get() for prim in colliders)
     assert all(not prim.IsA(UsdGeom.Mesh) for prim in colliders)
 
+    finger_collider = next(prim for prim in colliders if "link_left_finger" in str(prim.GetPath()))
+    arm_collider = next(
+        prim
+        for prim in colliders
+        if "link_left_finger" not in str(prim.GetPath()) and "link_right_finger" not in str(prim.GetPath())
+    )
+    finger_material, _ = UsdShade.MaterialBindingAPI(finger_collider).ComputeBoundMaterial(materialPurpose="physics")
+    arm_material, _ = UsdShade.MaterialBindingAPI(arm_collider).ComputeBoundMaterial(materialPurpose="physics")
+    assert finger_material.GetPrim().GetAttribute("physics:dynamicFriction").Get() == CABLE_CONTACT_FRICTION
+    assert arm_material.GetPrim().GetAttribute("physics:dynamicFriction").Get() == 5.0
+    for material in (finger_material, arm_material):
+        assert material.GetPrim().GetAttribute("newton:contactStiffness").Get() == CONTACT_STIFFNESS
+        assert math.isclose(
+            material.GetPrim().GetAttribute("newton:contactDamping").Get(), CONTACT_DAMPING, rel_tol=1.0e-6
+        )
+
     # Each caging fingertip keeps a detailed open geometry instead of being filled by
     # a visual-mesh convex hull: three capsules, two boxes, and six small contact beads.
     for leaf_name in ("lf_down", "rf_down"):