Skip to content

Articulation Reordering Part 8/8: Events, consumers, and documentation#6341

Draft
AntoineRichard wants to merge 23 commits into
isaac-sim:developfrom
AntoineRichard:antoiner/articulation-reordering-p8
Draft

Articulation Reordering Part 8/8: Events, consumers, and documentation#6341
AntoineRichard wants to merge 23 commits into
isaac-sim:developfrom
AntoineRichard:antoiner/articulation-reordering-p8

Conversation

@AntoineRichard

@AntoineRichard AntoineRichard commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Description

Routes event terms through the asset's public index mapping (map_body_ids_to_backend), fixes consumers that mixed public-order indices with backend-order view arrays (Forge force sensor, Lee controller inertia pairing), applies the factory/automate armature inertia offsets through the asset API, and adds the sim-to-sim transfer guide.

Part 8/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

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/envs/test_articulation_ordering_events.py -> 12 passed
  • ./isaaclab.sh -f -> all hooks pass

@github-actions github-actions Bot added documentation Improvements or additions to documentation isaac-lab Related to Isaac Lab team labels Jul 3, 2026
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from 77e1782 to f5300be Compare July 3, 2026 14:28
AntoineRichard added a commit that referenced this pull request Jul 7, 2026
… 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>
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch 2 times, most recently from 54512fc to 100886d Compare July 10, 2026 10:01
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from 100886d to 1607ec3 Compare July 13, 2026 16:13
AntoineRichard added a commit that referenced this pull request Jul 14, 2026
# 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
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch 5 times, most recently from 3ffe93c to 5619196 Compare July 15, 2026 09:27
AntoineRichard added a commit that referenced this pull request Jul 15, 2026
# 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
else:
joint_target_backend = joint_target_public[:, list(ordering.backend_to_user_indices)]

Use ``robot.body_ordering`` in the same way for body-indexed axes. Keep the

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: "Keep the None and identity guards" contradicts the contract this page establishes above — identity orderings are represented as None, never as an identity map, so an identity guard can't trigger.

supported escape hatch for custom Warp code. For example, this kernel gathers
one ``(environment, joint)`` array from backend order into public order:

.. code-block:: python

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent suggestion: this section teaches a hand-written conversion kernel that the very next paragraph supersedes with the built-in — starting from the built-in halves the section.

``isaaclab.assets.articulation.ordering_kernels`` are public for exactly this
task: translating a raw-view array between backend and public order. Rather than
hand-writing the gather above, launch ``reorder_2d_backend_to_user`` with the
asset's ``user_to_backend`` map (``backend_data`` and ``user_to_backend`` are

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: the parenthetical cites parameter names the kernel doesn't have — reorder_2d_backend_to_user aliases gather_2d(src, dst_to_src, dst). Reword against the real names or drop it; the code block below already shows the usage.

These kernels are retained for backward compatibility and will be removed in a future release. Prefer the
public-order asset write APIs (:meth:`~isaaclab.assets.Articulation.write_joint_position_to_sim_index` and its
siblings), which apply the ordering conversion internally, or the public-order reorder kernels from
``isaaclab.assets.articulation.ordering_kernels``. Because Warp kernels cannot emit a runtime deprecation warning

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: "Warp kernels cannot emit a runtime deprecation warning without breaking warp.launch" (stated here and at 3 more sites incl. both changelog fragments) isn't accurate — the repo's module-level __getattr__ shim convention emits a one-time DeprecationWarning and returns the object unchanged, without touching what's handed to wp.launch. Either adopt the shim for the restored kernels or soften the claim.

_NONIDENTITY_BODY_ORDERING = SimpleNamespace(
user_to_backend_indices=(0, 2, 1),
backend_to_user_indices=(0, 2, 1),
is_identity=False,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: is_identity=False fakes an attribute ArticulationNameMap doesn't have (identity is represented as None, never a map) — same phantom field as flagged on #6337's actuator tests. A test fake modeling non-existent API misleads the next reader about the production contract.

monkeypatch, deterministic_material_sampling, body_ordering, expected_shape_slice
):
"""Newton automatically converts public body selections to backend shape ranges."""
import isaaclab_newton.assets as newton_assets_module

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: when isaaclab_newton isn't installed this import makes the test error rather than skip — worth the same availability guard/skip the other backend-conditional tests use.

@@ -42,11 +42,11 @@ def set_friction(asset, value, num_envs):

def set_body_inertias(robot, num_envs):

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent review: after this migration num_envs is dead in set_body_inertias — the parameter (and its call-site argument) can go.

AntoineRichard added a commit that referenced this pull request Jul 17, 2026
# 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.
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from 5619196 to 86bbebc Compare July 17, 2026 16:43
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.
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from 86bbebc to 9ef0471 Compare July 17, 2026 17:12
Cover the isaaclab_newton and isaaclab_physx test changes so the changelog gate recognizes every package touched by P5.
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from 9ef0471 to f6c73bd Compare July 20, 2026 07:43
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.
Route event terms through the asset's public index mapping, fix
consumers that mixed public-order indices with backend-order view
arrays, apply the factory inertia offsets through the asset API, and
document the feature: the sim-to-sim transfer guide, the API reference
entries, and the changelog fragments for the touched task packages.
Part 8 of the articulation reordering series.
A 10-seed paired benchmark measured the feature at 1.06-1.55% lower
native training FPS than develop, attributed to write_data_to_sim
launching the joint-target gather unconditionally with an identity
map. This reverses the unification from 470b4b7 on the strength
of that measurement: both actuator branches now branch once in Python
and take develop's exact direct-assign path when no joint ordering is
configured, and the external-wrench path selects the reorder-free
shared kernel when body ordering is identity instead of threading a
flag through the ordered kernel every step.

Also fuse the post-step publish hook from four reorder launches into
two: one kernel gathers joint position and velocity together, one
gathers body pose and velocity together.
The ordering rework removed six public kernels without a prior
deprecation release: write_joint_state_data and write_joint_vel_data
on PhysX, and the four write_joint_state_data and write_joint_vel_data
index/mask variants on Newton. No ordering-aware replacement is
signature compatible, so each is restored verbatim from develop as a
deprecated shim for one release, with the replacement APIs named in
the docstrings and changelog. Raw warp kernels cannot emit a runtime
warning without breaking wp.launch, so the deprecation is documented
rather than raised.
Resolution errors told users to configure env.scene.robot, which is
wrong for direct-workflow tasks. Point at the ArticulationCfg fields
instead, which are layout independent.
Drop the two map micro-tests that duplicate the gather-branch coverage
of the permutation tests in the same file and the name-map construction
coverage in the core ordering suite. The four remaining map tests are
the only coverage of the public map_body_ids_to_backend and
map_joint_ids_to_backend application paths and stay.
Replace the 108-case partial-write cartesian with a deterministic
12-row all-pairs covering array, verified to cover every parameter
pair and seeded on all backend, ordering, and selector triples so
each backend still drives both writer kinds under both orderings.
Drop the identity value from the shadow-allocation axes, covered by
the per-backend identity-matches-none tests, and remove the internal
buffer-shape assertions whose behavioral observables are covered by
the shared-backend-read and allocation tests. 233 collected cases
become 131 with no loss of distinct-branch coverage.
Application coverage of map_body_ids_to_backend and
map_joint_ids_to_backend now lives beside the name-map construction
tests in the core ordering suite.
In the ordered Lab-actuator branch of write_data_to_sim, the fused target
reorder passed the effort buffer as both the effort output (index 0) and the
unused joint-act output (index 3). Because write_joint_act is off, index 3 is
never written, but the alias creates a false output dependency on the effort
buffer under CUDA graph capture. Point index 3 at the dedicated
_sim_bind_joint_act buffer, matching the newton-actuator branch.
sync_torque_telemetry mixed the user-space loop index j with the
backend-space backend_j. Rename the user-space index to user_j so each
index only subscripts arrays of its own order: user-order targets, gains,
limits, and outputs at [i, user_j]; backend-order live state and sim-bound
effort buffers at [i, backend_j]. The kernel signature is unchanged, so
call sites are unaffected.
Document that register_post_step_callback's hook fires exactly once per
step() call, reflecting state after all decimation iterations and their
solver substeps complete -- not once per substep or per decimation iteration.
The remaining public-order presence re-derivations in write_data_to_sim
tested the raw ordering map (self.data.joint_ordering is None). Replace
them with the has_joint_ordering property so presence checks read
uniformly across the ordering paths. Genuine map-object uses and
articulation-level ordering reads are left untouched. No behavior change.
@AntoineRichard
AntoineRichard force-pushed the antoiner/articulation-reordering-p8 branch from f6c73bd to d7cae3b Compare July 20, 2026 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation isaac-lab Related to Isaac Lab team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants