Merge branch 'develop' into fix/avoid-duplicate-mujoco-schema-registration

Author: kellyguo11

.github/actions/run-tests/action.yml

@@ -182,6 +182,17 @@ runs:
         retention-days: 7
         compression-level: 9
 
+    # The reports carry the dump truncated to 10 000 chars; the whole thing per test file is here.
+    - name: Upload hang stack dumps
+      if: always()
+      id: upload-hang-dumps
+      uses: actions/upload-artifact@v7
+      with:
+        name: hang-dumps-${{ inputs.container-name }}
+        path: ${{ inputs.reports-dir }}/hang-dumps/
+        if-no-files-found: ignore
+        retention-days: 7
+
     - name: Upload JUnit XML report
       if: always()
       id: upload-junit-report

.github/actions/run-tests/run_tests.sh

@@ -470,6 +470,17 @@ run_tests() {
   elif docker cp "$container_name:/workspace/isaaclab/tests/ovrtx-logs" "$ovrtx_dir" 2>/dev/null; then
     echo "🟢 OVRTX renderer logs copied from container to $ovrtx_dir"
   fi
+
+  # Copy per-file thread stack dumps (written by tools/hang_dump.py when the runner kills a hung test).
+  # The reports carry these truncated to 10 000 chars; the whole dump is only here. Absent unless
+  # something hung, which is the normal case.
+  local hang_dir="$reports_dir/hang-dumps"
+  if [ -n "$volume_mount_source" ] && [ -d "${volume_mount_source}/tests/hang-dumps" ]; then
+    cp -r "${volume_mount_source}/tests/hang-dumps" "$hang_dir"
+    echo "🟢 Hang stack dumps copied to $hang_dir"
+  elif docker cp "$container_name:/workspace/isaaclab/tests/hang-dumps" "$hang_dir" 2>/dev/null; then
+    echo "🟢 Hang stack dumps copied from container to $hang_dir"
+  fi
   echo "::endgroup::"
 
   echo "::group::Cleanup"

.github/actions/warp-cache-key/collection_id.py

@@ -47,20 +47,25 @@ def main() -> int:
         warp = re.search(r'^version = "(.*)"$', packages["warp-lang"], flags=re.MULTILINE).group(1)
         mjwarp = re.search(r'^version = "(.*)"$', packages["mujoco-warp"], flags=re.MULTILINE).group(1)
         newton = packages["newton"]
+        newton_version = re.search(r'^version = "(.*)"$', newton, flags=re.MULTILINE).group(1)
     except (AttributeError, KeyError) as exc:
         print(f"::error::{LOCKFILE} has no version entry for {exc}", file=sys.stderr)
         return 1
 
-    # Newton is a git dependency, so its resolved version is a placeholder like
-    # 1.5.0.dev0 that does not move between revisions. Use the pinned revision.
+    # Git builds can share a placeholder version across revisions, so identify
+    # them by commit. Registry releases are immutable and use their version.
     source = re.search(r"^source = (.*)$", newton, flags=re.MULTILINE)
     source = source.group(1) if source else ""
     match = re.search(r"(?:rev=|#)([0-9a-f]{7,40})", source)
-    if not match:
-        print(f"::error::Could not read the pinned newton revision from {source!r}", file=sys.stderr)
+    if match:
+        newton_id = match.group(1)[:8]
+    elif "registry" in source:
+        newton_id = newton_version
+    else:
+        print(f"::error::Could not identify the newton package from {source!r}", file=sys.stderr)
         return 1
 
-    print(f"wp{warp}-newton{match.group(1)[:8]}-mjwarp{mjwarp}")
+    print(f"wp{warp}-newton{newton_id}-mjwarp{mjwarp}")
     return 0
 
 

.github/workflows/check-links.yml

@@ -85,6 +85,7 @@ jobs:
           --exclude '^file://'
           --exclude '^mailto:'
           --exclude 'localhost'
+          --exclude 'www\.tensorflow\.org/tensorboard'
           --exclude '127\.0\.0\.1'
           --exclude 'example\.com'
           --exclude 'your-organization'

.github/workflows/config.yaml

@@ -10,6 +10,6 @@
 # which the CI credential can reach.
 isaacsim_image_name: nvcr.io/0947644777160149/internal/isaac-sim
 # Isaac Sim 6.1.0-alpha.50 (b86cf6ce) includes Kit 110.3.0-360924's fix for NVBug 6566677.
-isaacsim_image_tag: latest-develop@sha256:1bbd249c2ef8b522bc901d5321a627c750e2e7b609262c56d01b516a60bd7072
+isaacsim_image_tag: latest-develop@sha256:769450b03a4c634d709a0f5d4bf96e47bfaf025444b6e4728045b42733575e71
 isaaclab_image_name: nvcr.io/0947644777160149/internal/isaac-lab
 ovphysx_wheelhouse_image: ""

conftest.py

@@ -19,7 +19,8 @@
 e.g. ``pytest -m unit source/isaaclab/test`` or ``pytest -m "not unit" source/isaaclab/test``.
 
 Also loads ``tools/ovrtx_log.py``, which replays the OVRTX renderer log per test, so every suite that
-builds a renderer reports what it logged the same way.
+builds a renderer reports what it logged the same way, and ``tools/hang_dump.py``, which lets the CI
+runner ask this process for a stack dump before it kills it for hanging.
 """
 
 from __future__ import annotations
@@ -35,7 +36,7 @@
 else:
     wp.config.enable_backward = False
 
-pytest_plugins = ["tools.ovrtx_log"]
+pytest_plugins = ["tools.ovrtx_log", "tools.hang_dump"]
 
 JOURNAL_ENV_VAR = "ISAACLAB_TEST_JOURNAL"
 """Environment variable naming the crash-journal file. Unset (the default) disables journaling."""

docs/index.rst

@@ -101,6 +101,7 @@ Table of Contents
 
    source/concepts/backends_and_presets
    source/concepts/actuators
+   source/concepts/coupled_solvers
 
 
 .. toctree::

docs/source/api/lab_contrib/isaaclab_contrib.coupling.rst

@@ -3,49 +3,51 @@ isaaclab_contrib.coupling
 
 .. automodule:: isaaclab_contrib.coupling
 
-  .. rubric:: Classes
+.. currentmodule:: isaaclab_contrib.coupling
 
-  .. autosummary::
+.. rubric:: Classes
 
-    coupler_cfg.CouplerEntryCfg
-    coupler_cfg.CouplerCfg
-    coupler_cfg.CouplerProxyMappingCfg
-    coupler_cfg.CouplerProxyCfg
-    coupler_cfg.CouplerAdmmCfg
-    coupler.NewtonCouplerManager
+.. autosummary::
+
+  CouplerEntryCfg
+  CouplerCfg
+  CouplerProxyMappingCfg
+  CouplerProxyCfg
+  CouplerAdmmCfg
+  NewtonCouplerManager
 
 Coupler Configurations
 ----------------------
 
-.. autoclass:: isaaclab_contrib.coupling.coupler_cfg.CouplerEntryCfg
+.. autoclass:: CouplerEntryCfg
   :members:
   :show-inheritance:
   :exclude-members: __init__
 
-.. autoclass:: isaaclab_contrib.coupling.coupler_cfg.CouplerCfg
+.. autoclass:: CouplerCfg
   :members:
   :show-inheritance:
   :exclude-members: __init__
 
-.. autoclass:: isaaclab_contrib.coupling.coupler_cfg.CouplerProxyMappingCfg
+.. autoclass:: CouplerProxyMappingCfg
   :members:
   :show-inheritance:
   :exclude-members: __init__
 
-.. autoclass:: isaaclab_contrib.coupling.coupler_cfg.CouplerProxyCfg
+.. autoclass:: CouplerProxyCfg
   :members:
   :show-inheritance:
   :exclude-members: __init__
 
-.. autoclass:: isaaclab_contrib.coupling.coupler_cfg.CouplerAdmmCfg
+.. autoclass:: CouplerAdmmCfg
   :members:
   :show-inheritance:
   :exclude-members: __init__
 
 Newton Coupler
 --------------
 
-.. autoclass:: isaaclab_contrib.coupling.coupler.NewtonCouplerManager
+.. autoclass:: NewtonCouplerManager
   :members:
   :inherited-members:
   :show-inheritance:

docs/source/concepts/coupled_solvers.rst

@@ -0,0 +1,217 @@
+.. Copyright (c) 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
+
+.. _newton-coupled-solvers:
+
+Coupled Solvers
+===============
+
+.. warning::
+
+   Coupled solvers are experimental and exposed through
+   :mod:`isaaclab_contrib.coupling`. Their API, behavior, feature support,
+   performance, and implementation may change.
+
+Newton can partition one model between multiple solvers and exchange state and
+forces between them during each simulation step. This lets a task combine
+solver families that target different physics, such as an MJWarp rigid robot
+interacting with VBD cloth or an MPM material.
+
+Isaac Lab exposes this framework through
+:mod:`isaaclab_contrib.coupling`. The adapter turns configuration selectors
+into named Newton solver entries, constructs the selected coupling algorithm,
+and integrates it with :class:`~isaaclab_newton.physics.NewtonCfg`. For the
+shared-model architecture, iteration algorithms, supported constraint rows,
+and solver-specific implementation details, see Newton's
+`Coupled Solvers concept page
+<https://newton-physics.github.io/newton/stable/concepts/coupling.html>`_.
+
+
+The coupling model
+------------------
+
+A coupled simulation starts from one Newton model. Instead of giving the whole
+model to one solver, Isaac Lab partitions it into named entries. Each entry
+selects a solver and owns a disjoint part of the model:
+
+.. code-block:: text
+
+   Shared Newton model
+   ├── "rigid" entry → MJWarp owns robot bodies, joints, and shapes
+   ├── "soft" entry  → VBD owns deformable particles and static shapes
+   └── interface     → proxy or ADMM coupling connects the entries
+
+Each solver receives a view of the shared model and advances only the elements
+owned by its entry. An element can belong to at most one entry; unassigned
+elements remain outside the nested solvers. Keep each articulation in a single
+entry.
+
+Isaac Lab resolves ownership selectors, constructs the Newton entry views, and
+runs the coupled solver through the normal Newton backend lifecycle. Newton
+owns the coupling algorithms and the exchange of poses, forces, and constraint
+information between entries.
+
+
+Choose Proxy or ADMM Coupling
+-----------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Approach
+     - How it works
+     - When to use it
+   * - Proxy
+     - A source-owned body or particle appears as a virtual endpoint in a
+       destination solver. The destination returns feedback on a later pass or
+       iteration.
+     - Use when the interaction is naturally directional, such as a rigid
+       collider inside a deformable or particle solve. Proxy coupling can
+       reuse the destination solver's contact path and is the established path
+       for Isaac Lab's coupled MJWarp--VBD and rigid--MPM tasks.
+   * - ADMM
+     - The coupler creates interface constraints between entries, iterates the
+       sub-solvers, and applies equal and opposite interface forces.
+     - Use when the interface should be symmetric, especially for supported
+       cross-entry joints, body--particle attachments, or frictional contacts.
+       ADMM has more tuning parameters and supports a narrower set of
+       constraint rows.
+
+Proxy coupling is usually the simpler starting point for collider-style
+rigid--deformable interaction. Use ``mode="lagged"`` first; the
+``"staggered"`` mode uses a newer source state but is more sensitive to the
+timestep and ordering. Increase coupling iterations only after each entry is
+stable on its own.
+
+ADMM is a better fit when assigning a source and destination would make the
+physical interface artificially one-way. Its fixed iteration count and
+penalty, proximal, and stabilization parameters are part of the coupled
+constraint solve, so tune them together with the timestep and the participating
+solvers. Newton's concept page is the source of truth for the currently
+supported joints, contacts, and limitations.
+
+Proxy coupling can have lower coupling overhead because it reuses the
+destination solver's contact path and may work with one pass, but its
+directional exchange is timestep- and ordering-sensitive. ADMM represents a
+symmetric interface, but every coupling iteration advances the participating
+solvers again. Additional passes or iterations can improve coupled response and
+interface convergence at a higher runtime cost. Neither approach is uniformly
+more accurate; compare them on task-relevant physical metrics.
+
+
+Configure a coupled solver
+--------------------------
+
+In Isaac Lab, :class:`~isaaclab_contrib.coupling.CouplerEntryCfg` defines each
+entry's solver and ownership. Use
+:class:`~isaaclab_contrib.coupling.CouplerProxyCfg` or
+:class:`~isaaclab_contrib.coupling.CouplerAdmmCfg` as the
+:class:`~isaaclab_newton.physics.NewtonCfg` solver configuration.
+
+The following configuration mirrors the maintained Franka rigid--deformable tasks. It
+assigns the complete robot to MJWarp, particles and static collision geometry
+to VBD, and exposes only the hand and fingers as VBD proxy colliders:
+
+.. code-block:: python
+
+   from isaaclab_contrib.coupling import (
+       CouplerEntryCfg,
+       CouplerProxyCfg,
+       CouplerProxyMappingCfg,
+   )
+   from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg, VBDSolverCfg
+
+   entries = [
+       CouplerEntryCfg(
+           name="rigid",
+           solver_cfg=MJWarpSolverCfg(),
+           bodies=[r"/World/envs/env_[^/]+/Robot"],
+       ),
+       CouplerEntryCfg(
+           name="soft",
+           solver_cfg=VBDSolverCfg(),
+           all_particles=True,
+           include_static_shapes=True,
+       ),
+   ]
+
+   physics = NewtonCfg(
+       solver_cfg=CouplerProxyCfg(
+           entries=entries,
+           proxies=[
+               CouplerProxyMappingCfg(
+                   source="rigid",
+                   destination="soft",
+                   bodies=[
+                       r"/World/envs/env_[^/]+/Robot/Geometry/.*panda_hand",
+                       r"/World/envs/env_[^/]+/Robot/Geometry/.*panda_(left|right)finger",
+                   ],
+                   mode="lagged",
+               )
+           ],
+           iterations=1,
+       ),
+       num_substeps=2,
+   )
+
+For ADMM, keep the ownership entries and replace the proxy mapping with the
+symmetric interfaces that should be coupled:
+
+.. code-block:: python
+
+   from isaaclab_contrib.coupling import CouplerAdmmCfg
+
+   physics = NewtonCfg(
+       solver_cfg=CouplerAdmmCfg(
+           entries=entries,
+           contact_pairs=[("rigid", "soft")],
+           iterations=5,
+           rho=1.0,
+       ),
+       num_substeps=2,
+   )
+
+Set ``contact_pairs=None`` to generate every distinct entry pair, or use an
+empty list to disable ADMM contact coupling while retaining supported
+cross-entry joints and attachments.
+
+
+Tune Coupling
+-------------
+
+Stabilize each entry independently before changing coupling controls.
+
+* ``CouplerEntryCfg.substeps`` changes the time resolution for one entry; more
+  substeps add solver work.
+* For proxy coupling, ``mode`` controls exchange ordering, ``iterations``
+  controls relaxation passes, ``mass_scale`` changes proxy effective inertia in
+  the destination, and ``collide_interval`` controls contact refresh frequency.
+* For ADMM, ``iterations`` controls interface passes, ``rho`` sets the penalty
+  weight, ``gamma`` adds proximal inertia and velocity weighting, and
+  ``baumgarte`` adds positional-error correction.
+
+More substeps or iterations can improve stability or convergence, but cost
+runtime and cannot repair an unstable entry. The generated
+:doc:`coupling configuration API
+</source/api/lab_contrib/isaaclab_contrib.coupling>` lists every field and
+default; Newton's concept page explains the underlying algorithms.
+
+
+Start from a maintained task
+----------------------------
+
+The :ref:`newton-vbd-proxy-coupling` guide contains the complete configuration
+and runnable commands for the Franka soft-body tasks. Start from that example
+when building a proxy-coupled rigid--deformable environment, then narrow entry
+ownership and proxy selectors to the bodies that participate in the
+interaction.
+
+Current Isaac Lab limitations include no support for nested couplers or Newton
+contact sensors, and proxy coupling supports at most two entries. Some solver
+modes require manager-specific lifecycle work and cannot be nested in a
+coupler. Validate each entry independently before tuning the coupled result,
+and consult the Newton concept page for current algorithm-level support and
+limitations.