Articulation Reordering Part 8/8: Events, consumers, and documentation#6341
Articulation Reordering Part 8/8: Events, consumers, and documentation#6341AntoineRichard wants to merge 23 commits into
Conversation
77e1782 to
f5300be
Compare
… 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>
54512fc to
100886d
Compare
100886d to
1607ec3
Compare
# 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
3ffe93c to
5619196
Compare
# 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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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): | |||
There was a problem hiding this comment.
Agent review: after this migration num_envs is dead in set_body_inertias — the parameter (and its call-site argument) can go.
# 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.
5619196 to
86bbebc
Compare
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.
86bbebc to
9ef0471
Compare
Cover the isaaclab_newton and isaaclab_physx test changes so the changelog gate recognizes every package touched by P5.
9ef0471 to
f6c73bd
Compare
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.
f6c73bd to
d7cae3b
Compare
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
developsync (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
Checklist
pre-commitchecks with./isaaclab.sh --formatsource/<pkg>/changelog.d/for every touched packageCONTRIBUTORS.mdTest Plan
./isaaclab.sh -p -m pytest source/isaaclab/test/envs/test_articulation_ordering_events.py-> 12 passed./isaaclab.sh -f-> all hooks pass