Articulation Reordering Part 7/8: Cross-backend ordering interface tests by AntoineRichard · Pull Request #6340 · isaac-sim/IsaacLab

AntoineRichard · 2026-07-03T11:01:26Z

Description

Adds the shared interface test suite exercising ordering allocation, write parity, partial writes, and property reordering uniformly across PhysX, OVPhysX, and Newton through their mock views. Lands after all three backend parts because present-but-unwired backends error rather than skip.

Part 7/8 of the series splitting #6248 into independently reviewable units. #6248 remains open, untouched, as the reference implementation; this stack was cut from its final tree after a develop sync (Kamino Core, Newton bump, OVPhysX 0.5.1).

Stack

Part 1/8: Articulation Reordering Part 1/8: Extract rigid object interface test utilities #6334 — Extract rigid object interface test utilities
Part 2/8: Articulation Reordering Part 2/8: Core ordering foundation #6335 — Core ordering foundation
Part 3/8: Articulation Reordering Part 3/8: Newton backend #6336 — Newton backend
Part 4/8: Articulation Reordering Part 4/8: PhysX backend #6337 — PhysX backend
Part 5/8: Articulation Reordering Part 5/8: Extract articulation interface test utilities #6338 — Extract articulation interface test utilities
Part 6/8: Articulation Reordering Part 6/8: OVPhysX backend #6339 — OVPhysX backend
Part 7/8 (this PR): Articulation Reordering Part 7/8: Cross-backend ordering interface tests #6340 — Cross-backend ordering interface tests
Part 8/8: Articulation Reordering Part 8/8: Events, consumers, and documentation #6341 — Events, consumers, and documentation

Note

All parts target develop, so until the preceding parts merge this PR's diff includes them. The true delta of this part is this compare.

Type of change

Test/documentation/refactor change

Checklist

I have read and understood the contribution guidelines
I have run the pre-commit checks with ./isaaclab.sh --format
I have added tests that prove my fix is effective or that my feature works
I have added a changelog fragment under source/<pkg>/changelog.d/ for every touched package
My name exists in CONTRIBUTORS.md

Test Plan

./isaaclab.sh -p -m pytest source/isaaclab/test/assets/test_articulation_ordering_iface.py -> 233 passed
./isaaclab.sh -f -> all hooks pass

… utilities (#6334) # Description Moves the rigid object and rigid object collection interface test factories into shared underscore-prefixed utility modules so later parts can reuse them. Pure code movement with no behavior change and no ordering content. Part 1/8 of the series splitting #6248 into independently reviewable units. #6248 remains open, untouched, as the reference implementation; this stack was cut from its final tree after a `develop` sync (Kamino Core, Newton bump, OVPhysX 0.5.1). ## Stack - **Part 1/8 (this PR)**: #6334 — Extract rigid object interface test utilities - Part 2/8: #6335 — Core ordering foundation - Part 3/8: #6336 — Newton backend - Part 4/8: #6337 — PhysX backend - Part 5/8: #6338 — Extract articulation interface test utilities - Part 6/8: #6339 — OVPhysX backend - Part 7/8: #6340 — Cross-backend ordering interface tests - Part 8/8: #6341 — Events, consumers, and documentation ## Type of change - Test/documentation/refactor change ## Checklist - [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have added a changelog fragment under `source/<pkg>/changelog.d/` for every touched package - [x] My name exists in `CONTRIBUTORS.md` ## Test Plan - [x] `./isaaclab.sh -p -m pytest source/isaaclab/test/assets/test_rigid_object_iface.py` -> 1478 passed, 12 xfailed - [x] `./isaaclab.sh -p -m pytest source/isaaclab/test/assets/test_rigid_object_collection_iface.py` -> 1902 passed; the 7 failures + 636 errors are pre-existing on `develop` in the local environment (OVPhysX 0.4.13 wheel vs the 0.5.x binding API from #6314) — fail-set identical to the `develop` baseline - [x] `./isaaclab.sh -f` -> all hooks pass --------- Signed-off-by: Antoine RICHARD <antoiner@nvidia.com> Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

# Description Introduces the public joint/body ordering machinery in `isaaclab` core: the `ArticulationNameMap` type and builder, the ordering preset helper, the Warp reorder kernels with an explicit visibility contract, the symbolic convention resolvers (`physx`, `mjwarp`, `robot_schema`), the `ArticulationCfg.joint_ordering`/`body_ordering` fields, the `BaseArticulation`/`BaseArticulationData` plumbing that backends wire into, and the API reference entries. **Transitional semantics:** no backend consumes the machinery yet, so configuring an ordering in this intermediate state is a silent no-op until Parts 3/4/6 land. This is called out in the cfg field docstrings and resolves quickly as the stack merges. Part 2/8 of the series splitting #6248 into independently reviewable units. #6248 remains open, untouched, as the reference implementation; this stack was cut from its final tree after a `develop` sync (Kamino Core, Newton bump, OVPhysX 0.5.1). ## Stack - Part 1/8: #6334 — Extract rigid object interface test utilities - **Part 2/8 (this PR)**: #6335 — Core ordering foundation - Part 3/8: #6336 — Newton backend - Part 4/8: #6337 — PhysX backend - Part 5/8: #6338 — Extract articulation interface test utilities - Part 6/8: #6339 — OVPhysX backend - Part 7/8: #6340 — Cross-backend ordering interface tests - Part 8/8: #6341 — Events, consumers, and documentation > [!NOTE] > All parts target `develop`, so until the preceding parts merge this PR's diff includes them. The true delta of this part is [this compare](AntoineRichard/IsaacLab@antoiner/articulation-reordering-p1...antoiner/articulation-reordering-p2). ## Type of change - New feature (non-breaking change which adds functionality) ## Checklist - [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have added a changelog fragment under `source/<pkg>/changelog.d/` for every touched package - [x] My name exists in `CONTRIBUTORS.md` ## Test Plan - [x] `./isaaclab.sh -p -m pytest source/isaaclab/test/assets/test_articulation_ordering.py` -> 67 passed - [x] `./isaaclab.sh -p -m pytest source/isaaclab/test/assets/test_articulation_ordering_kernels.py` -> 24 passed - [x] `./isaaclab.sh -f` -> all hooks pass

# Description Wires ordering into the Newton backend read/write paths. Non-identity orderings register an unconditional post-step publish that reorders the core state buffers inside the stepped (and CUDA-graph-captured) region, keeping the documented Tier-1 capture-safety contract without Python read guards; `NewtonManager` gains the matching `register`/`unregister_post_step_callback` API. Actuator torque telemetry reads live backend state through the ordering map. Also carries the shared branching USD test fixture used by cross-backend convention tests here and in later parts. Part 3/8 of the series splitting #6248 into independently reviewable units. #6248 remains open, untouched, as the reference implementation; this stack was cut from its final tree after a `develop` sync (Kamino Core, Newton bump, OVPhysX 0.5.1). ## Stack - Part 1/8: #6334 — Extract rigid object interface test utilities - Part 2/8: #6335 — Core ordering foundation - **Part 3/8 (this PR)**: #6336 — Newton backend - Part 4/8: #6337 — PhysX backend - Part 5/8: #6338 — Extract articulation interface test utilities - Part 6/8: #6339 — OVPhysX backend - Part 7/8: #6340 — Cross-backend ordering interface tests - Part 8/8: #6341 — Events, consumers, and documentation > [!NOTE] > All parts target `develop`, so until the preceding parts merge this PR's diff includes them. The true delta of this part is [this compare](AntoineRichard/IsaacLab@antoiner/articulation-reordering-p2...antoiner/articulation-reordering-p3). ## Type of change - New feature (non-breaking change which adds functionality) ## Checklist - [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have added a changelog fragment under `source/<pkg>/changelog.d/` for every touched package - [x] My name exists in `CONTRIBUTORS.md` ## Test Plan - [x] `./isaaclab.sh -p -m pytest source/isaaclab_newton/test/assets/test_articulation_ordering_kernels.py` -> 2 passed - [x] `./isaaclab.sh -p -m pytest source/isaaclab_newton/test/assets/test_newton_actuators_newton.py` -> 76 passed - [x] `./isaaclab.sh -p -m pytest source/isaaclab_newton/test/assets/test_articulation.py` -> 257 passed, 8 skipped, 1 xfailed - [x] `./isaaclab.sh -f` -> all hooks pass

ooctipus · 2026-07-17T08:52:19Z

+                assert _ordering_shadow_shape(shadow)[:2] == (num_instances, item_count)
+
+    @pytest.mark.parametrize("ordering_mode", ["none", "identity", "reversed"])
+    def test_newton_allocates_shadows_only_for_nonidentity_ordering(self, ordering_mode: str) -> None:


Agent review: this Newton variant is a near-verbatim copy of the PhysX/OVPhysX allocation test above and the shadow tables already carry newton entries — the four allocation-shadow tests are one parametrized test. Relatedly, test_identity_ordering_matches_none_behavior and test_physx_none_ordering_allocates_no_external_wrench_staging_buffers are strict subsets of this family's identity/none cases and can fold in.

ooctipus · 2026-07-17T08:52:19Z

+        retained_field: str,
+    ) -> None:
+        """Allocate one staging destination for each ordered body read path."""
+        if backend not in BACKENDS:


Agent suggestion: 27 tests open with an in-body backend-availability pytest.skip(...) like this one, where the module already defines a marker convention for exactly this — sweeping them to the marker trims ~2 lines each and makes the skips visible at collection time.

ooctipus · 2026-07-17T08:52:19Z

+        _seed_backend_com_poses("ovphysx", art, raw_backend, backend_seed)
+        np.testing.assert_array_equal(_read_backend_com_poses("ovphysx", art, raw_backend), backend_seed)
+
+        art.data._body_com_pose_b.timestamp = -1.0


Agent review: this cache re-invalidation right after the seed helper is a no-op (the helper already leaves the cache invalidated), and the surrounding user_to_backend if/else is re-derived inline at 4 more sites past the file's own _ordering_user_to_backend helper.

ooctipus · 2026-07-17T08:52:19Z

+                return
+            env_ids = indices.numpy()
+            # PhysX writers pass global staging rows; the generic mock setter expects compact rows.
+            source_ids = env_ids if values.shape[0] == art.num_instances else np.arange(indices.shape[0])


Agent review: the PhysX partial-write tests validate against this test-local shape-sniffing setter instead of the shared mock's setter — and the two have already drifted. Validating against a private reimplementation is exactly the mock-drift failure mode this cross-backend file exists to catch; better to fix and use the shared mock setter.

ooctipus · 2026-07-17T08:52:19Z

+        real_import = builtins.__import__
+
+        def find_spec(name, package=None):
+            if name == "isaaclab_ovphysx":


Agent review: this subprocess scenario fakes find_spec only for isaaclab_ovphysx, but the utils gate the backend on two specs (isaaclab_ovphysx AND the external ovphysx SDK). On machines without that SDK — exactly where this file's other ovphysx tests politely skip — the guarded branch short-circuits and this test hard-fails instead of skipping. Faking both specs makes it hermetic.

ooctipus · 2026-07-17T08:52:19Z

+    @pytest.mark.parametrize("operation", ["position", "velocity", "state"])
+    @pytest.mark.parametrize(
+        "coverage",
+        ["one_env_one_item", "all_envs_one_item", "one_env_all_items"],


Agent review: 36 of the 108 cases in this joint-write cartesian run the coverage mode the block's own comment declares redundant — dropping that mode deletes a third of the matrix at no coverage cost.

# Description Wires ordering into the PhysX backend read/write paths using the shared kernels: fused user-and-backend target writes, lazily refreshed timestamped `body_mass`/`body_inertia` (see the changelog `Changed` entry for the semantics change vs develop), and ordering maps resolved at initialization. Part 4/8 of the series splitting #6248 into independently reviewable units. #6248 remains open, untouched, as the reference implementation; this stack was cut from its final tree after a `develop` sync (Kamino Core, Newton bump, OVPhysX 0.5.1). ## Stack - Part 1/8: #6334 — Extract rigid object interface test utilities - Part 2/8: #6335 — Core ordering foundation - Part 3/8: #6336 — Newton backend - **Part 4/8 (this PR)**: #6337 — PhysX backend - Part 5/8: #6338 — Extract articulation interface test utilities - Part 6/8: #6339 — OVPhysX backend - Part 7/8: #6340 — Cross-backend ordering interface tests - Part 8/8: #6341 — Events, consumers, and documentation > [!NOTE] > All parts target `develop`, so until the preceding parts merge this PR's diff includes them. The true delta of this part is [this compare](AntoineRichard/IsaacLab@antoiner/articulation-reordering-p3...antoiner/articulation-reordering-p4). ## Type of change - New feature (non-breaking change which adds functionality) ## Checklist - [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have added a changelog fragment under `source/<pkg>/changelog.d/` for every touched package - [x] My name exists in `CONTRIBUTORS.md` ## Test Plan - [x] `./isaaclab.sh -p -m pytest source/isaaclab_physx/test/assets/test_articulation.py` -> 239 passed - [x] `./isaaclab.sh -p -m pytest source/isaaclab_physx/test/assets/test_newton_actuators_physx.py` -> 44 passed - [x] `./isaaclab.sh -f` -> all hooks pass

Move the articulation interface test factories into a shared utility module mirroring the rigid object extraction, with ordering-aware construction hooks used by the later cross-backend ordering tests. Part 5 of the articulation reordering series.

The ordering core deleted the _cache_ordering_maps guard machinery; mock articulation factories now configure backend staging directly, matching the backend initialization paths.

Extract common test bootstrapping and ordering assertions so backend tests share one implementation. Guard optional PhysX setup and make unsupported mock ordering explicit.

Apply repository formatting and import ordering after the new helper files became tracked.

Cover the isaaclab_newton and isaaclab_physx test changes so the changelog gate recognizes every package touched by P5.

Match the established rigid-object test helper conventions for the mock backend label and private test access. Add a regression check that keeps the three interface utilities consistent.

Translate between public and backend order on the OVPhysX read and write paths: fused user-and-backend writes with persistent target staging separated from transient applied-torque scratch, forward kinematics aware body state refresh, and a fused ordered joint acceleration kernel. Part 6 of the articulation reordering series.

The ordering core rework single-homed the joint and body ordering maps on ArticulationData and removed the mirrored `_has_*` flags and `_*_user_to_backend` maps, the `_cache_ordering_maps` machinery, the `ArticulationNameMap` identity/name fields, and the dtype-suffixed write-kernel overloads. Repoint the OVPhysX articulation and data classes to the new contracts: - Read ordering presence via `data.joint_ordering` / `data.body_ordering` is-not-None checks; conditional sites dereference the map directly, while always-launch sites use the new `_*_user_to_backend_map()` helpers so publish, wrench, and telemetry gathers keep a valid map. - Configure backend staging through `_ordering_configure_backend_staging` and, now that `_install_ordering_flags` is gone, recover the previous per-axis ordering from the persistent backend staging buffers so a cleared ordering still releases its buffers on rebind. - Replace the dtype-suffixed overload launches with the `write_*_user_to_backend_*` launch wrappers, passing the dtype the old suffix implied and dropping the explicit launch dim. Adapt the OVPhysX asset tests to assert through the single-homed ordering maps, since a non-None map now always denotes a real permutation.

Add the shared interface test suite that exercises ordering allocation, write parity, partial writes, and property reordering uniformly across the PhysX, OVPhysX, and Newton backends through their mock views. Lands after all three backend parts because present-but-unwired backends error rather than skip. Part 7 of the articulation reordering series.

The ordering core now keeps a single source of truth for public ordering. Identity orderings resolve to None rather than an identity map, so a non-None map always denotes a real permutation. The mirror flags (_has_joint_ordering / _has_body_ordering on both the asset and data), the _cache_ordering_maps / _ordering_maps_cached guard, and the data _install_ordering_flags helper were all deleted; backends now stage through _ordering_configure_backend_staging(). Adapt the mocked cross-backend interface tests to match: - Re-stage installed orderings via _ordering_configure_backend_staging instead of the removed _cache_ordering_maps guard dance. - Delete the reinvocation-guard test; with one home there is no mirror state left to protect. - Assert ordering presence as (ordering is not None) against the single source instead of the removed mirror flags, keeping one dedicated assert that the asset property delegates to data. - Drop the now-redundant not-is_identity assert halves, since a non-None map already guarantees a permutation.

Keep the backend import-semantics regression with the shared interface utility tests introduced in P5.

github-actions Bot added documentation Improvements or additions to documentation isaac-lab Related to Isaac Lab team labels Jul 3, 2026

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch from d4cb2b5 to 8e788e4 Compare July 3, 2026 14:27

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch 7 times, most recently from 71acd4f to 8d3bae3 Compare July 13, 2026 16:13

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch 5 times, most recently from f086248 to ab412b6 Compare July 15, 2026 09:27

ooctipus reviewed Jul 17, 2026

View reviewed changes

AntoineRichard added 2 commits July 17, 2026 18:29

Adapt iface test utilities to reworked ordering core

389e66c

The ordering core deleted the _cache_ordering_maps guard machinery; mock articulation factories now configure backend staging directly, matching the backend initialization paths.

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch from ab412b6 to 9c65df4 Compare July 17, 2026 16:43

AntoineRichard added 2 commits July 17, 2026 19:08

Refine shared articulation test utilities

b1aa008

Extract common test bootstrapping and ordering assertions so backend tests share one implementation. Guard optional PhysX setup and make unsupported mock ordering explicit.

Format shared articulation test helpers

2dfb96e

Apply repository formatting and import ordering after the new helper files became tracked.

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch from 9c65df4 to eca40fc Compare July 17, 2026 17:12

Add missing test-only changelog fragments

240fca2

Cover the isaaclab_newton and isaaclab_physx test changes so the changelog gate recognizes every package touched by P5.

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch from eca40fc to 566b82a Compare July 20, 2026 07:43

AntoineRichard added 7 commits July 20, 2026 09:59

Align articulation interface test utility

044ae32

Match the established rigid-object test helper conventions for the mock backend label and private test access. Add a regression check that keeps the three interface utilities consistent.

Adapt OVPhysX backend to merged ordering buffer helper

5e2de0e

Remove duplicate backend discovery regression

fd00f58

Keep the backend import-semantics regression with the shared interface utility tests introduced in P5.

AntoineRichard force-pushed the antoiner/articulation-reordering-p7 branch from 566b82a to fd00f58 Compare July 20, 2026 08:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Articulation Reordering Part 7/8: Cross-backend ordering interface tests#6340

Articulation Reordering Part 7/8: Cross-backend ordering interface tests#6340
AntoineRichard wants to merge 12 commits into
isaac-sim:developfrom
AntoineRichard:antoiner/articulation-reordering-p7

AntoineRichard commented Jul 3, 2026 •

edited

Loading

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

ooctipus Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

AntoineRichard commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Stack

Type of change

Checklist

Test Plan

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ooctipus Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AntoineRichard commented Jul 3, 2026 •

edited

Loading