Integrate articulation ordering caches and selectors

docs/source/testing/micro_benchmarks.rst

@@ -146,10 +146,10 @@ Python environment must contain the backend being measured.
      - Asset benchmarks
      - Sensor benchmarks
    * - PhysX
-     - Launch Isaac Sim and use mocked PhysX views
+     - Run kitless with mocked PhysX views
      - Launch Isaac Sim and build a live PhysX scene
    * - Newton
-     - Launch Isaac Sim and use mocked Newton views
+     - Run kitless with mocked Newton views
      - Run kitless with the installed Newton runtime
    * - OVPhysX
      - Run kitless; require the optional ``ovphysx`` runtime wheel
@@ -185,6 +185,13 @@ Use the top-level component command with an exact physics selector:
    ./isaaclab.sh microbenchmark --component articulation physics=ovphysx \
        --num_instances 4096 --warmup_steps 10 --num_iterations 1000
 
+To isolate one item-selector representation, select its mode explicitly:
+
+.. code-block:: bash
+
+   ./isaaclab.sh microbenchmark --component articulation physics=physx \
+       --mode torch_tensor_int64
+
 Replace ``articulation`` with ``rigid_object`` or
 ``rigid_object_collection``. Each command measures both API surfaces and emits
 separate method and data artifacts. The three retained scripts under each
@@ -228,21 +235,51 @@ Defaults differ by file; use ``--help`` before creating a comparison command.
 Asset Input Modes
 ~~~~~~~~~~~~~~~~~
 
+Methods indexed only by ``env_ids`` support five selector modes:
+
 ``torch_list``
-   Pass selection IDs as Python lists. This includes list-to-tensor conversion
-   and represents common convenience-API usage.
+   Pass environment IDs as Python lists. This includes list-to-tensor
+   conversion and represents common convenience-API usage.
+
+``torch_tensor_int32`` and ``torch_tensor_int64``
+   Pass pre-allocated Torch tensors using the corresponding signed index width.
 
-``torch_tensor``
-   Pass pre-allocated Torch tensors. This removes repeated list conversion and
-   represents the optimized Torch path.
+``warp_int32`` and ``warp_int64``
+   Pass pre-allocated Warp arrays using the corresponding signed index width.
 
-``warp_mask``
-   Pass pre-allocated Warp boolean masks. This mode is available for supported
-   Newton and OVPhysX mask APIs.
+Writers with ``joint_ids`` or ``body_ids`` support the same-type modes above
+plus four mixed-width modes:
+
+``torch_tensor_int32_int64`` and ``torch_tensor_int64_int32``
+   Pass Torch environment and item selectors with the widths named in order.
+
+``warp_int32_int64`` and ``warp_int64_int32``
+   Pass Warp environment and item selectors with the widths named in order.
+
+Supported Newton and OVPhysX mask APIs are benchmarked separately with
+pre-allocated Warp boolean masks.
 
 Not every backend or method supports every mode. Compare a mode only when it has
 the same meaning on both sides.
 
+Articulation Finder Phases
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Articulation method artifacts also contain actual ``find_bodies`` and
+``find_joints`` workloads:
+
+* ``default`` measures the legacy list return.
+* ``proxy_cold`` clears the asset-local selector cache before each call, outside
+  the timer, so the measured finder call includes creation of the device-local
+  proxy selector.
+* ``proxy_cached`` warms the cache during preflight and measures repeated lookup
+  of the same proxy selector.
+
+Run timing comparisons only while the selected GPU is idle. Another process
+using the device can dominate microsecond-scale differences; correctness-only
+CPU runs and results collected on a busy GPU must not be presented as speed
+comparisons.
+
 Running Sensor Benchmarks
 -------------------------
 
@@ -359,12 +396,13 @@ Asset Output
 ~~~~~~~~~~~~
 
 Asset scripts print mean and standard deviation for every method/mode pair in
-microseconds, followed by mode comparisons when applicable:
+microseconds. Articulation method artifacts additionally contain the finder and
+raw index-kernel phases described above:
 
 .. code-block:: text
 
-   [1/24] [TORCH_LIST] write_root_state_to_sim... 132.02 +/- 6.79 us
-   [1/24] [TORCH_TENSOR] write_root_state_to_sim... 65.44 +/- 3.06 us
+   [1/30] [TORCH_LIST] write_root_state_to_sim... 132.02 +/- 6.79 us
+   [1/30] [TORCH_TENSOR_INT64] write_root_state_to_sim... 65.44 +/- 3.06 us
 
 They also write a timestamped JSON file to ``--output_dir`` by default. It
 contains benchmark configuration, hardware/software metadata, phase names, and
@@ -561,7 +599,7 @@ Import or Backend Errors
 
 Confirm the backend is installed in the Python environment selected by
 ``./isaaclab.sh -p``. OVPhysX requires its optional runtime wheel. PhysX
-benchmarks require Isaac Sim.
+sensor benchmarks require Isaac Sim.
 
 CUDA Out of Memory
 ~~~~~~~~~~~~~~~~~~

source/isaaclab/changelog.d/antoiner-articulation-reordering-integration.rst

@@ -0,0 +1,21 @@
+Added
+^^^^^
+
+* Added the ``as_proxy`` return-mode option to asset finder methods.
+  ``as_proxy=False`` is the default and returns the legacy selector
+  representation, while ``as_proxy=True`` opts into cached
+  :class:`~isaaclab.utils.warp.ProxyArray` selectors with zero-copy ``.torch``
+  and ``.warp`` index views. Pass those explicit views to downstream APIs.
+* Added a shared asset micro-benchmark grid for Torch and Warp item selectors,
+  cold and cached finder calls, and signed 32-bit versus signed 64-bit
+  articulation index-kernel timings.
+
+Fixed
+^^^^^
+
+* Fixed shared articulation ordering and external wrench paths to accept signed
+  32-bit and signed 64-bit selectors without allocating Torch conversion tensors.
+* Fixed manager entity resolution for sensors with legacy body finder signatures.
+* Fixed external wrench composition to consume explicit Warp views of cached
+  body selectors without materializing Torch tensors.
+* Fixed articulation dynamics reads for reversed USD joint relationships.

source/isaaclab/isaaclab/actuators/actuator_base.py

@@ -227,7 +227,7 @@ def __str__(self) -> str:
         """Returns: A string representation of the actuator group."""
         # resolve joint indices for printing
         joint_indices = self.joint_indices
-        if joint_indices == slice(None):
+        if isinstance(joint_indices, slice):
             joint_indices = list(range(self.num_joints))
         # resolve model type (implicit or explicit)
         model_type = "implicit" if self.is_implicit_model else "explicit"

source/isaaclab/isaaclab/actuators/actuator_pd.py

@@ -381,7 +381,7 @@ def __init__(
         self,
         cfg: RemotizedPDActuatorCfg,
         joint_names: list[str],
-        joint_ids: Sequence[int],
+        joint_ids: slice | torch.Tensor,
         num_envs: int,
         device: str,
         stiffness: torch.Tensor | float = 0.0,

source/isaaclab/isaaclab/assets/articulation/base_articulation.py

@@ -20,6 +20,7 @@
 from ...sim import SimulationContext
 from ...utils.buffers import TimestampedBufferWarp
 from ...utils.leapp.leapp_semantics import OutputKindEnum, joint_names_resolver, leapp_tensor_semantics
+from ...utils.warp import ProxyArray
 from ..asset_base import AssetBase
 from . import ordering_kernels
 from .ordering import ArticulationNameMap, ArticulationOrderingConvention, build_articulation_name_map
@@ -508,25 +509,38 @@ def update(self, dt: float) -> None:
     """
 
     @abstractmethod
-    def find_bodies(self, name_keys: str | Sequence[str], preserve_order: bool = False) -> tuple[list[int], list[str]]:
+    def find_bodies(
+        self,
+        name_keys: str | Sequence[str],
+        preserve_order: bool = False,
+        *,
+        as_proxy: bool = False,
+    ) -> tuple[list[int] | ProxyArray, list[str]]:
         """Find bodies in the articulation based on the name keys.
 
-        Please check the :meth:`isaaclab.utils.string_utils.resolve_matching_names` function for more
+        Please check the :func:`isaaclab.utils.string.resolve_matching_names` function for more
         information on the name matching.
 
         Args:
             name_keys: A regular expression or a list of regular expressions to match the body names.
             preserve_order: Whether to preserve the order of the name keys in the output. Defaults to False.
+            as_proxy: Whether to return cached, immutable :class:`ProxyArray` indices. Use ``.warp`` or
+                ``.torch`` and reacquire after invalidation. Defaults to False.
 
         Returns:
-            A tuple of lists containing the body indices and names.
+            Matched body indices and names. Indices are a list by default or a cached proxy when requested.
         """
         raise NotImplementedError()
 
     @abstractmethod
     def find_joints(
-        self, name_keys: str | Sequence[str], joint_subset: list[str] | None = None, preserve_order: bool = False
-    ) -> tuple[list[int], list[str]]:
+        self,
+        name_keys: str | Sequence[str],
+        joint_subset: list[str] | None = None,
+        preserve_order: bool = False,
+        *,
+        as_proxy: bool = False,
+    ) -> tuple[list[int] | ProxyArray, list[str]]:
         """Find joints in the articulation based on the name keys.
 
         Please see the :func:`isaaclab.utils.string.resolve_matching_names` function for more information
@@ -537,16 +551,23 @@ def find_joints(
             joint_subset: A subset of joints to search for. Defaults to None, which means all joints
                 in the articulation are searched.
             preserve_order: Whether to preserve the order of the name keys in the output. Defaults to False.
+            as_proxy: Whether to return proxy indices. See :meth:`find_bodies`. Subsets use asset-global
+                proxy indices.
 
         Returns:
-            A tuple of lists containing the joint indices, names.
+            Matched joint indices and names. Indices are a list by default or a cached proxy when requested.
         """
         raise NotImplementedError()
 
     @abstractmethod
     def find_fixed_tendons(
-        self, name_keys: str | Sequence[str], tendon_subsets: list[str] | None = None, preserve_order: bool = False
-    ) -> tuple[list[int], list[str]]:
+        self,
+        name_keys: str | Sequence[str],
+        tendon_subsets: list[str] | None = None,
+        preserve_order: bool = False,
+        *,
+        as_proxy: bool = False,
+    ) -> tuple[list[int] | ProxyArray, list[str]]:
         """Find fixed tendons in the articulation based on the name keys.
 
         Please see the :func:`isaaclab.utils.string.resolve_matching_names` function for more information
@@ -558,16 +579,23 @@ def find_fixed_tendons(
             tendon_subsets: A subset of joints with fixed tendons to search for. Defaults to None, which means
                 all joints in the articulation are searched.
             preserve_order: Whether to preserve the order of the name keys in the output. Defaults to False.
+            as_proxy: Whether to return proxy indices. See :meth:`find_bodies`. Subsets use asset-global
+                proxy indices.
 
         Returns:
-            A tuple of lists containing the tendon indices, names.
+            Matched fixed-tendon indices and names. Indices are a list by default or a cached proxy when requested.
         """
         raise NotImplementedError()
 
     @abstractmethod
     def find_spatial_tendons(
-        self, name_keys: str | Sequence[str], tendon_subsets: list[str] | None = None, preserve_order: bool = False
-    ) -> tuple[list[int], list[str]]:
+        self,
+        name_keys: str | Sequence[str],
+        tendon_subsets: list[str] | None = None,
+        preserve_order: bool = False,
+        *,
+        as_proxy: bool = False,
+    ) -> tuple[list[int] | ProxyArray, list[str]]:
         """Find spatial tendons in the articulation based on the name keys.
 
         Please see the :func:`isaaclab.utils.string.resolve_matching_names` function for more information
@@ -578,9 +606,11 @@ def find_spatial_tendons(
             tendon_subsets: A subset of tendons to search for. Defaults to None, which means all tendons
                 in the articulation are searched.
             preserve_order: Whether to preserve the order of the name keys in the output. Defaults to False.
+            as_proxy: Whether to return proxy indices. See :meth:`find_bodies`. Subsets use asset-global
+                proxy indices.
 
         Returns:
-            A tuple of lists containing the tendon indices, names.
+            Matched spatial-tendon indices and names. Indices are a list by default or a cached proxy when requested.
         """
         raise NotImplementedError()
 
@@ -2575,10 +2605,6 @@ def _get_backend_ordered_joint_buffer(
             )
         return backend_data
 
-    """
-    Internal helpers -- Actuators.
-    """
-
     @abstractmethod
     def _process_actuators_cfg(self) -> None:
         """Process and apply articulation joint properties."""