Allow usd-core 26.08 and adopt usd-exchange 3.x on aarch64 (#4022)

Co-authored-by: mzamoramora-nvidia <mzamoramora@nvidia.com>

Author: andrewkaufman

changelog/+usd-2608-deps-6496f7a7.changed.md

@@ -0,0 +1 @@
+Allow `usd-core` 26.08, and allow `usd-exchange` 3.x on aarch64 while keeping 2.3.0 installable, which extends USD support to Python 3.13 on aarch64.

changelog/+usd-thread-limit-61ecfa23.changed.md

@@ -0,0 +1 @@
+Stop forcing `PXR_WORK_THREAD_LIMIT=1` when running the test suite against OpenUSD 26.08 or newer, where the collider-parsing race it worked around is fixed.

docs/concepts/usd_parsing.rst

@@ -1387,16 +1387,20 @@ Limitations
 -----------
 
 Importing USD files where many (> 30) mesh colliders are under the same rigid body
-can result in a crash in ``UsdPhysics.LoadUsdPhysicsFromRange``.  This is a known
-thread-safety issue in OpenUSD and will be fixed in a future release of
-``usd-core``.  It can be worked around by setting the work concurrency limit to 1
-before ``pxr`` initializes its thread pool.
+can result in a crash in OpenUSD's native physics parser.  This is a known
+thread-safety issue in OpenUSD, **fixed in OpenUSD 26.08**: no workaround is needed
+when the USD runtime is 26.08 or newer, whether it comes from ``usd-core`` or from
+the OpenUSD build bundled in ``usd-exchange``.
+
+Newton still supports older ``usd-core`` releases, so the workaround below remains
+relevant when running against a USD runtime older than 26.08.  It can be applied by
+setting the work concurrency limit to 1 before ``pxr`` initializes its thread pool.
 
 .. note::
 
    Setting the concurrency limit to 1 disables multi-threaded USD processing
    globally and may degrade performance of other OpenUSD workloads in the same
-   process.
+   process.  Prefer upgrading to OpenUSD 26.08 or newer instead.
 
 Choose **one** of the two approaches below — do not combine them.
 ``PXR_WORK_THREAD_LIMIT`` is evaluated once when ``pxr`` is first imported and

newton/_src/solvers/kamino/_src/utils/io/usd.py

@@ -1782,12 +1782,12 @@ def import_from(
         ###
 
         # Initialize the ignore paths as an empty list if it is None
-        # NOTE: This is required by the LoadUsdPhysicsFromRange method
+        # NOTE: This is required by the native physics parser
         if ignore_paths is None:
             ignore_paths = []
 
         # Load the USD file into an object dictionary
-        ret_dict = self.UsdPhysics.LoadUsdPhysicsFromRange(stage, [root_path], excludePaths=ignore_paths)
+        ret_dict = usd_utils.load_physics_from_range(stage, [root_path], ignore_paths)
 
         # Create a new ModelBuilderKamino if not provided
         if builder is None:

newton/_src/usd/utils.py

@@ -2254,6 +2254,30 @@ def _get_surface_deformable_material(
     )
 
 
+def load_physics_from_range(stage, root_paths, exclude_paths=()):
+    """Parse a stage's native physics descriptors, across OpenUSD versions.
+
+    OpenUSD 26.08 renamed ``UsdPhysics.LoadUsdPhysicsFromRange`` to
+    ``UsdPhysics.UsdPhysicsLoadStageFromPrimRange`` and deprecated the old name, so calling
+    it emits a ``DeprecationWarning``. Both spellings take the same arguments and return the
+    same descriptor dict; prefer the new name where it exists.
+
+    Args:
+        stage: The USD stage to parse.
+        root_paths: Roots of the subtrees to parse.
+        exclude_paths: Prim paths whose subtrees should be excluded from the parse.
+
+    Returns:
+        The parser's object-type to descriptor mapping.
+    """
+    from pxr import UsdPhysics
+
+    load = getattr(UsdPhysics, "UsdPhysicsLoadStageFromPrimRange", None)
+    if load is None:
+        load = UsdPhysics.LoadUsdPhysicsFromRange
+    return load(stage, list(root_paths), excludePaths=list(exclude_paths))
+
+
 def _get_physics_material_density(material_prim) -> float | None:
     """Read a bound material's base ``UsdPhysicsMaterialAPI`` density.
 
@@ -2403,11 +2427,7 @@ def get_physics_scenes(
     Returns:
         Physics scenes in parser order.
     """
-    physics_results = UsdPhysics.LoadUsdPhysicsFromRange(
-        stage,
-        [root_path],
-        excludePaths=list(exclude_paths or ()),
-    )
+    physics_results = load_physics_from_range(stage, [root_path], exclude_paths or ())
     return _get_physics_scenes_from_results(stage, physics_results)
 
 

newton/_src/utils/import_usd.py

@@ -644,7 +644,7 @@ class PhysicsMaterial:
     has_nonunit_linear_units = not math.isclose(linear_unit, 1.0)
     has_nonunit_mass_units = not math.isclose(mass_unit, 1.0)
     non_regex_ignore_paths = [path for path in ignore_paths if ".*" not in path]
-    # LoadUsdPhysicsFromRange remains the native rigid/joint descriptor parser, so this
+    # The native rigid/joint descriptor parser remains authoritative, so this
     # pre-pass supplies its deformable exclusions before it runs. The same walk also
     # collects static visual leaves when requested, avoiding a third stage traversal.
     root_prim = stage.GetPrimAtPath(root_path)
@@ -658,7 +658,7 @@ class PhysicsMaterial:
     native_exclude_paths = list(
         dict.fromkeys([*non_regex_ignore_paths, *_deformable_prims.native_physics_exclude_paths])
     )
-    ret_dict = UsdPhysics.LoadUsdPhysicsFromRange(stage, [root_path], excludePaths=native_exclude_paths)
+    ret_dict = usd.load_physics_from_range(stage, [root_path], native_exclude_paths)
     physics_scenes = usd._get_physics_scenes_from_results(stage, ret_dict)
     physics_scene_prim = physics_scenes[0].GetPrim() if physics_scenes else None
 

newton/tests/test_import_usd.py

@@ -32,6 +32,7 @@
     SOLREF_MODE_RAW,
 )
 from newton._src.solvers.mujoco.utils import MjcEqualityTargetKind
+from newton._src.usd import utils as usd_utils
 from newton._src.utils.color import color_linear_to_srgb
 from newton._src.utils.import_usd import _is_uniform_scale
 from newton.math import quat_between_axes
@@ -47,7 +48,7 @@
 def _expect_jointless_articulation_warning(test):
     """Require the benign jointless-articulation warning on OpenUSD < 26.0.
 
-    ``UsdPhysics.LoadUsdPhysicsFromRange`` in OpenUSD < 26.0 (e.g. the
+    ``UsdPhysics``'s native physics parser in OpenUSD < 26.0 (e.g. the
     ``usd-exchange`` build resolved on ``aarch64``) reports an articulation root
     that has no joints as an invalid ``ArticulationDesc``, which
     :func:`~newton.utils.parse_usd` surfaces as a ``UserWarning``; usd-core
@@ -4897,7 +4898,7 @@ def verify_usdphysics_parser(test, file, model, compare_min_max_coords, floating
     from pxr import Gf, Sdf, Usd, UsdPhysics
 
     stage = Usd.Stage.Open(file)
-    parsed = UsdPhysics.LoadUsdPhysicsFromRange(stage, ["/"])
+    parsed = usd_utils.load_physics_from_range(stage, ["/"])
     # since the key is generated from USD paths we can assume that keys are unique
     body_key_to_idx = dict(zip(model.body_label, range(model.body_count), strict=False))
     shape_key_to_idx = dict(zip(model.shape_label, range(model.shape_count), strict=False))
@@ -10547,8 +10548,10 @@ def test_scene_path(self):
         scene = UsdPhysics.Scene.Define(stage, "/Scene")
         scene.CreateGravityMagnitudeAttr(2.0)
 
-        load_physics = UsdPhysics.LoadUsdPhysicsFromRange
-        with mock.patch.object(UsdPhysics, "LoadUsdPhysicsFromRange", wraps=load_physics) as load_physics_mock:
+        # Patch Newton's compat wrapper rather than the OpenUSD entry point, whose name
+        # differs across OpenUSD versions.
+        load_physics = usd_utils.load_physics_from_range
+        with mock.patch.object(usd_utils, "load_physics_from_range", wraps=load_physics) as load_physics_mock:
             result = newton.ModelBuilder().add_usd(stage)
 
         load_physics_mock.assert_called_once()
@@ -13197,8 +13200,8 @@ def test_scenes(self):
         first.CreateGravityMagnitudeAttr(2.0)
         second = UsdPhysics.Scene.Define(stage, "/World/SecondScene")
 
-        load_physics = UsdPhysics.LoadUsdPhysicsFromRange
-        with mock.patch.object(UsdPhysics, "LoadUsdPhysicsFromRange", wraps=load_physics) as load_physics_mock:
+        load_physics = usd_utils.load_physics_from_range
+        with mock.patch.object(usd_utils, "load_physics_from_range", wraps=load_physics) as load_physics_mock:
             scenes = usd.get_physics_scenes(stage)
 
         load_physics_mock.assert_called_once()

newton/tests/thirdparty/unittest_parallel.py

@@ -10,8 +10,10 @@
 
 import argparse
 import concurrent.futures  # NVIDIA Modification
+import importlib.metadata
 import multiprocessing
 import os
+import re
 import sys
 import tempfile
 import time
@@ -20,11 +22,34 @@
 from contextlib import contextmanager
 from io import StringIO
 
-# Work around a known OpenUSD thread-safety crash in
-# UsdPhysics.LoadUsdPhysicsFromRange for collider-dense assets. OpenUSD reads
-# this once when pxr initializes, so set it before test modules import pxr and
-# preserve any caller-provided override.
-os.environ.setdefault("PXR_WORK_THREAD_LIMIT", "1")
+# Work around a known OpenUSD thread-safety crash in the native physics parser for
+# collider-dense assets: concurrent descriptor appends could race when several colliders
+# shared one rigid body. Fixed in OpenUSD 26.08, so only older runtimes are constrained.
+#
+# OpenUSD reads this once when pxr initializes, so it must be set before test modules import
+# pxr. That rules out reading Usd.GetVersion(), and also rules out importing any newton USD
+# module, since newton_usd_schemas imports pxr at module scope. Distribution metadata gives
+# the runtime version without initializing OpenUSD: usd-core is versioned directly, while
+# usd-exchange bundles its own OpenUSD build and advertises it as a `usd<major><minor>` extra
+# (e.g. `usd2608`). A runtime that cannot be identified is treated as affected, and any
+# caller-provided override is preserved.
+try:
+    _USD_VERSION = tuple(int(part) for part in importlib.metadata.version("usd-core").split(".")[:2])
+except (importlib.metadata.PackageNotFoundError, ValueError):
+    try:
+        _USD_VERSION = next(
+            (int(match.group(1)), int(match.group(2)))
+            for match in (
+                re.fullmatch(r"usd(\d{2})(\d{2})", extra)
+                for extra in importlib.metadata.metadata("usd-exchange").get_all("Provides-Extra") or []
+            )
+            if match
+        )
+    except (importlib.metadata.PackageNotFoundError, StopIteration):
+        _USD_VERSION = (0, 0)
+
+if _USD_VERSION < (26, 8):
+    os.environ.setdefault("PXR_WORK_THREAD_LIMIT", "1")
 
 from newton.tests.unittest_utils import (  # NVIDIA modification
     AllocationCleanupTestResultMixin,

pyproject.toml

@@ -62,8 +62,8 @@ importers = [
     "open3d>=0.19.0; python_version < '3.13' and (sys_platform != 'linux' or platform_machine != 'aarch64')",
 
     # USD core libraries
-    "usd-core>=25.5,<26.5 ; platform_machine != 'aarch64' and python_version < '3.14'",
-    "usd-exchange>=2.2.0,<3 ; platform_machine == 'aarch64' and python_version < '3.13'",
+    "usd-core>=25.5,<26.9 ; platform_machine != 'aarch64' and python_version < '3.14'",
+    "usd-exchange>=2.3.0,<4 ; platform_machine == 'aarch64' and python_version < '3.14'",
 
     # Newton USD Schemas
     "newton-usd-schemas>=0.5.0",