From 9dd42a535e4679431abf141d132bf4e4a8580d08 Mon Sep 17 00:00:00 2001 From: Octi Zhang Date: Wed, 27 May 2026 15:17:49 -0700 Subject: [PATCH] Document Digit closed-loop articulation limitation on Newton The Newton ArticulationView walks model.joint_child without deduplicating, so closed-loop articulations like Agility Digit end up with link_count larger than the number of unique physical bodies (49 vs 43 on Digit). Downstream this breaks any code path that assumes one entry per logical body. Drop newton_mjwarp from the three Digit env rows in the supported environments tables and add a "Closed-loop articulations on Newton" entry under Known Issues describing the root cause and pointing users to the physx preset until the upstream fix lands. --- docs/source/overview/environments.rst | 15 +++++------- docs/source/refs/issues.rst | 24 +++++++++++++++++++ ...ti-docs-digit-newton-known-limitation.skip | 0 3 files changed, 30 insertions(+), 9 deletions(-) create mode 100644 source/isaaclab_newton/changelog.d/octi-docs-digit-newton-known-limitation.skip diff --git a/docs/source/overview/environments.rst b/docs/source/overview/environments.rst index 34cbb7a7624d..384062fd78c0 100644 --- a/docs/source/overview/environments.rst +++ b/docs/source/overview/environments.rst @@ -525,14 +525,11 @@ Environments based on legged locomotion tasks. | |velocity-rough-g1| | |velocity-rough-g1-link| | Track a velocity command on rough terrain with the Unitree G1 robot | **physics=** ``physx``, | | | | | ``newton_mjwarp`` | +------------------------------+----------------------------------------------+------------------------------------------------------------------------------+------------------------------+ - | |velocity-flat-digit| | |velocity-flat-digit-link| | Track a velocity command on flat terrain with the Agility Digit robot | **physics=** ``physx``, | - | | | | ``newton_mjwarp`` | + | |velocity-flat-digit| | |velocity-flat-digit-link| | Track a velocity command on flat terrain with the Agility Digit robot | **physics=** ``physx`` | +------------------------------+----------------------------------------------+------------------------------------------------------------------------------+------------------------------+ - | |velocity-rough-digit| | |velocity-rough-digit-link| | Track a velocity command on rough terrain with the Agility Digit robot | **physics=** ``physx``, | - | | | | ``newton_mjwarp`` | + | |velocity-rough-digit| | |velocity-rough-digit-link| | Track a velocity command on rough terrain with the Agility Digit robot | **physics=** ``physx`` | +------------------------------+----------------------------------------------+------------------------------------------------------------------------------+------------------------------+ - | |tracking-loco-manip-digit| | |tracking-loco-manip-digit-link| | Track a root velocity and hand pose command with the Agility Digit robot | **physics=** ``physx``, | - | | | | ``newton_mjwarp`` | + | |tracking-loco-manip-digit| | |tracking-loco-manip-digit-link| | Track a root velocity and hand pose command with the Agility Digit robot | **physics=** ``physx`` | +------------------------------+----------------------------------------------+------------------------------------------------------------------------------+------------------------------+ .. |velocity-flat-anymal-b-link| replace:: `Isaac-Velocity-Flat-Anymal-B-v0 <../../../source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/config/anymal_b/flat_env_cfg.py>`__ @@ -1118,7 +1115,7 @@ inferencing, including reading from an already trained checkpoint and disabling - Isaac-Tracking-LocoManip-Digit-Play-v0 - Manager Based - **rsl_rl** (PPO) - - **physics=** ``physx``, ``newton_mjwarp`` + - **physics=** ``physx`` * - Isaac-Navigation-Flat-Anymal-C-v0 - Isaac-Navigation-Flat-Anymal-C-Play-v0 - Manager Based @@ -1384,7 +1381,7 @@ inferencing, including reading from an already trained checkpoint and disabling - Isaac-Velocity-Flat-Digit-Play-v0 - Manager Based - **rsl_rl** (PPO) - - **physics=** ``physx``, ``newton_mjwarp`` + - **physics=** ``physx`` * - Isaac-Velocity-Flat-G1-v0 - Isaac-Velocity-Flat-G1-Play-v0 - Manager Based @@ -1444,7 +1441,7 @@ inferencing, including reading from an already trained checkpoint and disabling - Isaac-Velocity-Rough-Digit-Play-v0 - Manager Based - **rsl_rl** (PPO) - - **physics=** ``physx``, ``newton_mjwarp`` + - **physics=** ``physx`` * - Isaac-Velocity-Rough-G1-v0 - Isaac-Velocity-Rough-G1-Play-v0 - Manager Based diff --git a/docs/source/refs/issues.rst b/docs/source/refs/issues.rst index 42a78ec27ffb..1ab3d8671401 100644 --- a/docs/source/refs/issues.rst +++ b/docs/source/refs/issues.rst @@ -93,6 +93,30 @@ message and continue with terminating the process. On Windows systems, please us ``Ctrl+Break`` or ``Ctrl+fn+B`` to terminate the process. +Closed-loop articulations on Newton (e.g. Agility Digit) +-------------------------------------------------------- + +Robots whose USD encodes a closed kinematic loop -- such as the achilles rod and +toe push-rods on the Agility Digit -- do not currently run correctly on the +``newton_mjwarp`` physics preset, even though they work on ``physx``. This affects: + +* ``Isaac-Velocity-Flat-Digit-v0`` / ``Isaac-Velocity-Flat-Digit-Play-v0`` +* ``Isaac-Velocity-Rough-Digit-v0`` / ``Isaac-Velocity-Rough-Digit-Play-v0`` +* ``Isaac-Tracking-LocoManip-Digit-v0`` / ``Isaac-Tracking-LocoManip-Digit-Play-v0`` + +The root cause sits inside Newton's :class:`~newton.selection.ArticulationView`. When +it builds its per-link axis it walks each joint in the articulation's joint range and +appends ``model.joint_child[joint_id]`` without deduplicating. A body that is the +child of multiple joints (the standard closed-loop encoding) therefore occupies +multiple slots on that axis, so ``view.link_count`` is larger than the number of +unique physical bodies in the model. On Digit this is 49 link slots versus 43 actual +bodies (the four loop-closed bodies -- left/right ``tarsus`` and left/right +``toe_roll`` -- account for the six extra slots). + +Until the upstream fix lands in Newton, please use the ``physx`` preset for +Digit-based environments. + + URDF Importer: Unresolved references for fixed joints ----------------------------------------------------- diff --git a/source/isaaclab_newton/changelog.d/octi-docs-digit-newton-known-limitation.skip b/source/isaaclab_newton/changelog.d/octi-docs-digit-newton-known-limitation.skip new file mode 100644 index 000000000000..e69de29bb2d1