Support OvPhysX 0.6 while retaining public 0.5.11 compatibility

[AntoineRichard]

Description

Support OvPhysX 0.6 without changing the public 0.5.11 default or CI dependency sources. OvPhysX 0.6 already fixes reversed-joint Jacobians and mass matrices; applying Isaac Lab's legacy sign correction again produces incorrect dynamics. Gate that correction by the installed runtime's release line, including 0.6 development builds.

Gravity compensation forces already use the public joint basis in both tested versions. Remove their extra sign correction while retaining joint ordering. Register the wheel's physics schemas with OVStage's independent registry when that API exists, including when host USD already supplies the schemas.

Keep installation documentation limited to publicly available packages. The compatibility path is selected automatically when OvPhysX 0.6 is already installed; no internal-build installation support is added. Public package pins and CI workflows remain unchanged. The schema fix is adapted from integration/ovphysx-next and overlaps #7626.

Type of change

• Bug fix
• Documentation update

Release backport

• Backport this pull request to the active release branch after it merges into develop

Validation

• Public OV backend CI: 1,021 passing cases, 28 skipped, including all eight CPU/CUDA dynamics regressions and all six version-boundary cases. The full package CI run, x86/ARM installation checks, wheel build, documentation, formatting, and changelog/link checks all passed. Both multi-GPU checks also passed. These CI results cover commit 1ac23b8fafa; CI is being rerun for the review follow-up.
• 16 native dynamics cases passed: 0.5.11 and 0.6.2 on CPU and CUDA, with/without gravity and custom joint/body ordering. Checks compare Jacobian-predicted velocity with measured body velocity, generalized kinetic energy with body kinetic energy, and gravity compensation with summed body weights through the Jacobian.
• Reproduced the 0.6 Jacobian failure before the version gate and the 0.5 gravity-force failure before removing its extra correction.
• 76 tests passed: shared ordering kernels, version boundaries, schema registration, and manager lifecycle; legacy resolver/cache tests also passed.
• Review follow-up: 36 lifecycle and compatibility tests passed on each runtime (0.5.11 and 0.6.2). The added missing-OVStage regression failed before the fix and passed afterward.
• Full Sphinx HTML build passed with warnings treated as errors (15-second external inventory fetch timeout). Formatting and changelog checks passed. Full local suite intentionally not run; broader validation uses CI.

The internally tested OVRTX 0.5/OVStage renderer still differs from existing Cartpole RGB goldens (2.02% pixels versus 1.50% allowed). Unchanged develop code with the same native stack reproduces it; the public renderer stack passes. Golden images and thresholds are unchanged.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with uv run isaaclab -f
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective
• I have added a changelog fragment for every touched source package
• My name already exists in CONTRIBUTORS.md

[AntoineRichard]

run-ci

[AntoineRichard]

run-ci

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable correctness, security, or repository-rule violations remain.

Summary

• Gates the legacy reversed-joint Jacobian and mass-matrix correction by the installed OvPhysX release line.
• Reorders gravity-compensation forces without applying an unnecessary direction-sign correction.
• Registers codeless schemas with OVStage’s independent registry when that API is available.
• Adds CPU/CUDA, ordering, version-boundary, schema-registration, and lifecycle coverage.
• Documents an isolated opt-in command for the matching internal OvPhysX 0.6.2 stack.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Detect installed OvPhysX version] --> B{Version before 0.6?}
    B -->|Yes| C[Resolve reversed-joint signs]
    B -->|No| D[Use runtime-corrected dynamics basis]
    C --> E[Reorder Jacobians and mass matrices with signs]
    D --> F[Reorder Jacobians and mass matrices without legacy correction]
    C --> G[Reorder gravity forces without signs]
    D --> G
    H[Manager initialization] --> I{OVStage schema API available?}
    I -->|Yes| J[Register OvPhysX schema root with OVStage]
    I -->|No| K[Skip OVStage-specific registration]
    J --> L[Register missing schemas with host USD registry]
    K --> L

Loading

_{Reviews (1) · Last reviewed commit: "Support OvPhysX 0.6 while retaining the ..."}

[isaaclab-review-bot]

Isaac Lab Review Bot

The release-aware reversed-joint correction, gravity-force basis handling, and OVStage schema registration are coherently integrated. One schema-registration regression should be fixed: failure to import OVStage now prevents the existing host USD schema registration path from running.

• Design and architecture: The OvPhysX release policy remains backend-local in ovphysx_compat, while the shared generalized-force kernel supports backends whose forces already use the public joint basis. However, optional OVStage registration is currently coupled to host USD registration, so the independent registration paths are not properly isolated.
• API: The generalized-force ordering kernel preserves behavior for callers supplying sign arrays, and the keyword-only correct_joint_signs parameter retains the previous default. Public gravity-compensation shapes and return types remain unchanged, with changelog coverage for both affected packages.
• Implementation: The version gate and dynamics-buffer paths preserve legacy 0.5.11 behavior while disabling redundant corrections for 0.6. In _ensure_physx_schemas_registered, adding import ovstage to the existing guarded import block causes any OVStage import failure to return before Plug.Registry().RegisterPlugins(...); OVStage probing should be isolated so host schema registration still occurs.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Implementation — OVStage import can skip host schema registration

import ovstage was added to the same try guarded by except ImportError: return, so an absent or renamed ovstage now makes _ensure_physx_schemas_registered return before Plug.Registry().RegisterPlugins(...), skipping the host USD registration of the wheel's codeless schemas that previously ran with only ovphysx and pxr installed, and leaving _physx_schemas_registered False. The OVStage API is already probed defensively with getattr; import it in its own guarded block so host registration remains unconditional.

[AntoineRichard]

Fixed in c8f8b4e by guarding the optional OVStage import separately. Extended the existing schema-registration test to cover an unavailable OVStage import; it failed before the fix and now passes. All 36 lifecycle/compatibility cases pass on both 0.5.11 and 0.6.2.

[kellyguo11]

maybe we leave this out from the docs

[kellyguo11]

we can just leave what's available for users

[AntoineRichard]

Removed the internal-build section in c8f8b4e. Installation docs now cover only publicly available packages.

[kellyguo11]

I don't think we need to provide installation support for internal builds. we can just automatically switch to the code path that uses this if the code detects 0.6 is installed in the environment

[AntoineRichard]

Removed the internal installation instructions in c8f8b4e. Public pins remain unchanged, and the existing runtime version detection automatically selects the 0.6 compatibility path when that version is installed.

[AntoineRichard]

run-ci

[marcodiiga]

run-ci

[marcodiiga]

Reviewed c8f8b4e. The dynamics-sign and schema-registration changes look correct; one non-blocking installation-documentation issue is noted inline.

On ovphysx 0.5.11, 77 compatibility, lifecycle, and ordering tests passed, plus all eight reversed-joint dynamics cases on CPU and CUDA. The gravity assertions also detect the base implementation's sign error. Changed Python files and documentation examples passed syntax checks. CI is still running.

[marcodiiga]

[P2] Preserve installed extras when adding ovphysx

This is an exact sync: in an environment already synced with --extra test, it removes pytest, pytest-mock, and the other test-only dependencies. Packages belonging only to other unselected extras, such as isaacsim, are also removed. Please use uv sync --inexact --extra ovphysx so adding this backend preserves those dependencies, consistent with the tetrahedralization instructions. The dry run retains them with --inexact; see uv's sync behavior.