Articulation Reordering Part 6/8: OVPhysX backend

[AntoineRichard]

Description

Wires ordering into the OVPhysX backend read/write paths: fused user-and-backend writes with persistent target staging separated from transient applied-torque scratch, FK-aware body state refresh, and a fused ordered joint acceleration kernel.

Part 6/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 (this PR): Articulation Reordering Part 6/8: OVPhysX backend #6339 — OVPhysX backend
• Part 7/8: 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

• New feature (non-breaking change which adds functionality)

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

• Mock-based coverage lands in Part 7 (233 passed there). The live suite is blocked in the local environment: all 105 failures share the single PhysX.set_cpu_mode AttributeError from the OVPhysX 0.4.13 wheel vs Fetch OVPhysX wheelhouse CI through NGC + 0.5.1 bump #6314's manager code (develop shows the identical signature on its 99 pre-existing live tests); the same tests passed on the pre-sync monolithic branch
• CI with the 0.5.1 wheelhouse is the authoritative gate for this part
• ./isaaclab.sh -f -> all hooks pass

[ooctipus]

Agent review: this backend's new code replicates six patterns flagged on Part 4 (#6337) — listing them once here instead of re-raising each inline, so both backends can change together:

1. Unreachable staging None-guards — 16 sites across the two files here (PhysX had 6); staging is installed at init whenever ordering resolves, same argument as the #6337 thread.
2. The dead had_* release/reseed lifecycle (~60 lines in _configure_ordering_buffers) — the #6337 thread already noted "same on OVPhysX"; whichever resolution lands (wire a real re-resolve lifecycle in core, or drop the plumbing) should be chain-wide.
3. articulation_data.py:69 — repeats the factually wrong claim that Newton's ordered shadows are "refreshed lazily on first access"; they're published every step by a post-step callback (see the #6337 comment on the same sentence).
4. articulation_data.py:845 — root_com_pose_w's ternary re-derives the identity branch _backend_body_com_pose_b already takes internally; the base property can be used unconditionally.
5. ~13 boolean gates re-derive data.has_joint_ordering/has_body_ordering — you already agreed to sweep these on #6337.
6. The joint-axis gate-and-gather / write-buffer template is hand-written as near-twin variants here (e.g. _refresh_joint_pos/_refresh_joint_vel and their write-buffer getters are verbatim twins), where the PhysX file already parameterized the same pattern (_refresh_joint_state_user, _get_joint_state_write_buffer).

[ooctipus]

Agent review: this deprecated shim previously delegated in two lines to the _index sub-writers; it now carries its own 36-line hand-optimized fused launch that near-verbatim copies write_joint_state_to_sim_mask's body. A compatibility shim whose own docstring tells users to migrate doesn't need a private optimized implementation — restoring the delegation deletes the copy.

[ooctipus]

Agent review: after this rewiring, _effort_write_view/_pos_target_write_view/_vel_target_write_view are never dereferenced as arrays — their only remaining use is is not None in write_data_to_sim. Constructing pointer-aliased wp.array(ptr=...) wrappers (and _make_write_view) purely as availability sentinels can collapse to three booleans.

[ooctipus]

Agent review: these docstrings cite numbered findings from a private review document ("finding [27]" etc.) that future readers can't resolve — worth inlining the one-line rationale instead of the reference.

[ooctipus]

Agent suggestion: third hand-copied set of the ordering test fixtures (ANYmal/Panda name tuples, branching-fixture path helper + ground-truth orders) after the Newton and PhysX test files. Same home question as raised on #6338 — an installable shared location would let Parts 4/6 keep one copy.

[greptile-apps]

Greptile Summary

This PR wires articulation joint/body ordering into the OVPhysX backend's read and write paths — covering joint-target reordering in write_data_to_sim, ordering-aware wrench rotation in body-wrench composition, a fused finite-difference joint acceleration kernel (_fd_joint_acc_ordered) that avoids a separate reorder launch, and FK-aware body state refresh via _ensure_fk_fresh.

• write_data_to_sim now uses reorder_joint_targets_user_to_backend (with the correct backend_to_user map) and _body_wrench_to_world_ordered to rotate wrenches in one pass using backend-order poses, avoiding a per-substep public-order pose shadow.
• write_joint_state_to_sim_mask was correctly upgraded to use ordering_kernels.write_joint_state_user_to_backend_with_mask, but write_joint_state_to_sim_index was not updated: it still sends user-order _joint_pos_buf.data / _joint_vel_buf.data directly to set_attribute, which silently corrupts joint state in OVPhysX when a non-identity ordering is active.
• The _fd_joint_acc_ordered kernel logic (reading backend-order velocity through user_to_backend while keeping _previous_joint_vel in user order) is consistent with the velocity write paths that reset the FD baseline in public order.

Confidence Score: 3/5

There is an ordering asymmetry: write_joint_state_to_sim_mask was upgraded to reorder joint state before writing to OVPhysX, but write_joint_state_to_sim_index was not, so any reset or initialisation call that routes through the index path with a non-identity joint ordering will silently inject joint positions and velocities in the wrong order into the physics engine.

The core ordering kernels (_fd_joint_acc_ordered, _body_wrench_to_world_ordered, reorder_joint_targets_user_to_backend) are logically sound and the FK-aware refresh mechanism is correct. The gap is the incomplete update to write_joint_state_to_sim_index, which is a write path that callers (including reset logic) use frequently. Under a non-identity ordering, this produces silently wrong physics state from the very first step.

source/isaaclab_ovphysx/isaaclab_ovphysx/assets/articulation/articulation.py — write_joint_state_to_sim_index needs the same ordering treatment applied to write_joint_state_to_sim_mask in this PR.

Important Files Changed

Filename	Overview
source/isaaclab_ovphysx/isaaclab_ovphysx/assets/articulation/articulation.py	Wires joint/body ordering into write_data_to_sim (reorder_joint_targets_user_to_backend) and wrench composition (_body_wrench_to_world_ordered), but write_joint_state_to_sim_index was not updated to handle ordering, unlike write_joint_state_to_sim_mask.
source/isaaclab_ovphysx/isaaclab_ovphysx/assets/articulation/articulation_data.py	Adds FK-aware body state refresh (_ensure_fk_fresh), fused ordered joint acceleration kernel (_fd_joint_acc_ordered), and backend-order staging buffers for body ordering; logic appears correct.
source/isaaclab_ovphysx/isaaclab_ovphysx/assets/kernels.py	Adds _fd_joint_acc_ordered (fused backend-to-public reorder for FD acceleration), _body_wrench_to_world_ordered (ordering-aware wrench rotation), and a set of mask-based scatter kernels; kernel logic is correct.
source/isaaclab/test/assets/_articulation_iface_test_utils.py	New shared mock-backend factory for articulation interface tests; kitless detection logic and mock stubbing approach are reasonable.
source/isaaclab/test/assets/test_articulation_iface.py	Interface tests for ordering-related data properties; coverage looks appropriate for the mock layer.
source/isaaclab_ovphysx/test/assets/test_articulation.py	OVPhysX-specific articulation tests; relies on CI with 0.5.1 wheel for live coverage as noted in the PR description.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User as User Code
    participant Art as Articulation
    participant Data as ArticulationData
    participant Kern as kernels
    participant OVP as OVPhysX

    Note over Art,OVP: write_data_to_sim() — ordering-aware write path

    User->>Art: write_data_to_sim()
    Art->>Data: _backend_body_link_pose_w (backend order)
    Data-->>Art: poses (backend order)
    Art->>Kern: _body_wrench_to_world_ordered(force_b[user], torque_b[user], poses[backend], user_to_backend)
    Kern-->>Art: wrench_buf (backend order)
    Art->>OVP: set_attribute(LINK_WRENCH, wrench_buf)

    alt joint_ordering is not None
        Art->>Kern: reorder_joint_targets_user_to_backend(applied_torque, pos_target, vel_target, backend_to_user)
        Kern-->>Art: effort_backend, pos_target_backend, vel_target_backend
    end
    Art->>OVP: set_attribute(DOF_ACTUATION_FORCE / POSITION_TARGET / VELOCITY_TARGET)

    Note over Art,OVP: update() — FD joint acceleration

    User->>Art: update(dt)
    Art->>Data: update(dt)
    Data->>Data: "_sim_timestamp += dt"
    Data->>Data: joint_acc (lazy FD refresh)
    alt joint_ordering is not None
        Data->>OVP: read DOF_VELOCITY → _joint_vel_backend (backend order)
        Data->>Kern: _fd_joint_acc_ordered(cur_vel_backend, user_to_backend, prev_vel_user, inv_dt)
        Kern-->>Data: out_user (joint acc in public order)
    else
        Data->>OVP: read DOF_VELOCITY → _joint_vel_buf (user order)
        Data->>Kern: _fd_joint_acc(joint_vel, prev_vel, inv_dt)
        Kern-->>Data: joint_acc
    end

    Note over Art,OVP: body state read — FK-aware

    User->>Data: body_link_pose_w
    Data->>Data: _ensure_fk_fresh()
    alt "_fk_timestamp < _sim_timestamp"
        Data->>OVP: update_articulations_kinematic()
    end
    Data->>OVP: read LINK_POSE → backend buffer
    alt body_ordering is not None
        Data->>Kern: reorder_2d_backend_to_user
        Kern-->>Data: body_link_pose_w (public order)
    end
    Data-->>User: body_link_pose_w

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User as User Code
    participant Art as Articulation
    participant Data as ArticulationData
    participant Kern as kernels
    participant OVP as OVPhysX

    Note over Art,OVP: write_data_to_sim() — ordering-aware write path

    User->>Art: write_data_to_sim()
    Art->>Data: _backend_body_link_pose_w (backend order)
    Data-->>Art: poses (backend order)
    Art->>Kern: _body_wrench_to_world_ordered(force_b[user], torque_b[user], poses[backend], user_to_backend)
    Kern-->>Art: wrench_buf (backend order)
    Art->>OVP: set_attribute(LINK_WRENCH, wrench_buf)

    alt joint_ordering is not None
        Art->>Kern: reorder_joint_targets_user_to_backend(applied_torque, pos_target, vel_target, backend_to_user)
        Kern-->>Art: effort_backend, pos_target_backend, vel_target_backend
    end
    Art->>OVP: set_attribute(DOF_ACTUATION_FORCE / POSITION_TARGET / VELOCITY_TARGET)

    Note over Art,OVP: update() — FD joint acceleration

    User->>Art: update(dt)
    Art->>Data: update(dt)
    Data->>Data: "_sim_timestamp += dt"
    Data->>Data: joint_acc (lazy FD refresh)
    alt joint_ordering is not None
        Data->>OVP: read DOF_VELOCITY → _joint_vel_backend (backend order)
        Data->>Kern: _fd_joint_acc_ordered(cur_vel_backend, user_to_backend, prev_vel_user, inv_dt)
        Kern-->>Data: out_user (joint acc in public order)
    else
        Data->>OVP: read DOF_VELOCITY → _joint_vel_buf (user order)
        Data->>Kern: _fd_joint_acc(joint_vel, prev_vel, inv_dt)
        Kern-->>Data: joint_acc
    end

    Note over Art,OVP: body state read — FK-aware

    User->>Data: body_link_pose_w
    Data->>Data: _ensure_fk_fresh()
    alt "_fk_timestamp < _sim_timestamp"
        Data->>OVP: update_articulations_kinematic()
    end
    Data->>OVP: read LINK_POSE → backend buffer
    alt body_ordering is not None
        Data->>Kern: reorder_2d_backend_to_user
        Kern-->>Data: body_link_pose_w (public order)
    end
    Data-->>User: body_link_pose_w

Loading

Comments Outside Diff (1)

1. source/isaaclab_ovphysx/isaaclab_ovphysx/assets/articulation/articulation.py, line 906-923 (link)

   write_joint_state_to_sim_index skips joint reordering

   This method was not updated for joint ordering even though write_joint_state_to_sim_mask was (it now uses ordering_kernels.write_joint_state_user_to_backend_with_mask). As written, when joint_ordering is set the method writes user-order _joint_pos_buf.data / _joint_vel_buf.data directly to OVPhysX via set_attribute, which puts the joint positions and velocities into the backend in the wrong order. Any call to this method during reset or initialisation with a non-identity ordering will silently corrupt the physics state — joints will be driven to the wrong angle/rate targets from the very first step.

_{Reviews (1): Last reviewed commit: "Adapt OVPhysX backend to merged ordering..." | Re-trigger Greptile}