[omniperf-agent] fix: PhysX KukaAllegro grasp via compliant contacts

[yts-nv]

Description

What & why

On Isaac-Lift-KukaAllegro, the PhysX backend never learns to grasp (success_rate ~ 0) while Newton converges. Root cause is a domain-randomization interaction, not a reward/sensor bug:

• The dexterous KukaAllegro hand needs PhysX compliant (soft) contacts to hold the object.
• But randomize_rigid_body_material writes the object's material through the rigid 3-tuple API — RigidBodyView.set_material_properties (static/dynamic friction + restitution) — which overwrites the compliant contact authored at spawn. -> rigid contacts -> the object is squirted out of the hand before a grasp forms -> good_finger_contact stays 0 -> the policy never converges.
• Newton is immune: its DR touches only friction bindings (shape_material_mu/restitution), leaving contact stiffness/damping alone, and its contacts are soft by default.

Fix (core/lift)

1. Give the object a PhysX compliant material — PhysxRigidBodyMaterialCfg(static_friction=0.5, compliant_contact_stiffness=300.0, compliant_contact_damping=30.0).
2. Add core/lift/mdp/compliant_events.py -> RandomizeFrictionKeepCompliant: a startup event that randomizes friction and writes it back through RigidBodyView.set_compliant_material_properties (the 4-tuple: friction + stiffness + damping), so compliant contact survives domain randomization.
3. Wire object_physics_material to it; robot_physics_material keeps the stock DR.

Keeps full domain randomization (object friction still randomized) and preserves compliant contact — no engine change needed; the compliant setter already exists in omni.physics.tensors.

Validation (PhysX, seed 42, 4096 envs)

Config	success_rate @2000	Passed
baseline (no fix)	0.055	0
compliant only, DR on	0.000	0
disable both DRs	0.40	1
this PR (keep DR + compliant)	0.637	1
Newton (reference)	0.827	1

Converges higher than disabling DR (0.637 vs 0.40) because retaining randomization yields a more robust grasp. Validated on develop 8c3bc5e; targets current develop.

Note for reviewers

Implemented task-scoped (a core/lift/mdp event). The same idea could be upstreamed into the core randomize_rigid_body_material (write compliant via set_compliant_material_properties when the material has compliant fields) so all tasks benefit.

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
List any dependencies that are required for this change.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Release backport

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

Screenshots

Please attach before and after screenshots of the change if applicable.

Checklist

Docker and GPU tests run on demand. Push the commits you want tested, then
comment run-ci on the pull request.

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• 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 (do not edit CHANGELOG.rst or bump extension.toml — CI handles that)
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

This PR fixes failed PhysX grasp learning in the KukaAllegro lift task by authoring compliant object contacts and preserving their stiffness and damping while friction is randomized.

• Adds a task-scoped compliant-contact friction-randomization event.
• Applies compliant PhysX materials to the lift object variants.
• Replaces object material randomization while retaining the existing robot randomization.
• The new event is currently installed for non-PhysX lift backends whose views do not share the required API.

Confidence Score: 4/5

The backend-specific compliant-material event must be limited to PhysX or given backend-compatible behavior before this PR is safe to merge.

The shared lift configuration invokes compliant-material methods during startup even for selectable backends such as OvPhysX whose root view does not implement those methods, preventing affected environments from initializing.

Files Needing Attention: source/isaaclab_tasks/isaaclab_tasks/core/lift/lift_env_cfg.py, source/isaaclab_tasks/isaaclab_tasks/core/lift/mdp/compliant_events.py

Important Files Changed

Filename	Overview
source/isaaclab_tasks/isaaclab_tasks/core/lift/lift_env_cfg.py	Authors compliant object materials and installs the new randomizer globally, unintentionally exposing non-PhysX lift presets to a PhysX-only API.
source/isaaclab_tasks/isaaclab_tasks/core/lift/mdp/compliant_events.py	Implements friction randomization through PhysX compliant-material tensors, but assumes every asset root view provides that backend-specific interface.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Lift EventCfg startup] --> B[RandomizeFrictionKeepCompliant]
  B --> C{Selected backend}
  C -->|PhysX| D[Compliant material tensor API]
  C -->|OvPhysX or Newton| E[Backend root view]
  E --> F[Unsupported compliant-material call]
  F --> G[Environment startup failure]

Loading

_{Reviews (1): Last reviewed commit: "[omniperf-agent] fix: PhysX KukaAllegro ..." | Re-trigger Greptile}

[greptile-apps]

Backend-specific startup event

When a lift environment uses the OvPhysX or default Newton backend, the shared startup event calls PhysX-specific compliant-material methods on that backend's root view, causing environment initialization to fail. Install this event only for the PhysX configuration or provide backend-compatible behavior.

Knowledge Base Used: Physics backend extensions

[isaaclab-review-bot]

Isaac Lab Review Bot

The compliant-contact fix is currently applied through backend-shared lift configuration, introducing PhysX-specific material and tensor APIs into Newton and OV startup paths. The new event also retains configuration parameters whose semantics it does not implement, and the new source is missing required repository metadata and includes experimental logging. A package changelog fragment is also required.

• Design and architecture: EventCfg and the shared object presets serve multiple physics backends, but now directly use RandomizeFrictionKeepCompliant and PhysxRigidBodyMaterialCfg. The compliant material and event should be scoped to the PhysX-specific configuration while shared paths retain backend-neutral materials and backend-dispatched randomization.
• API: The replacement event accepts the stock randomizer's parameters but ignores restitution_range, num_buckets, env_ids, and the call-time asset_cfg, causing configured behavior to be silently dropped. Its supported parameter contract should match its implementation, with callers updated accordingly, or the missing semantics should be implemented.
• Implementation: The compliant material write path is coherent, but the new module lacks the required BSD-3-Clause SPDX header and contains an experimental [TRUEFIX] stdout message that should not remain in production. Because this visibly changes isaaclab_tasks physics behavior, the required changelog fragment or .skip fragment must also be added.

Needs rework. Posted 5 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🔴 Critical · Design Architecture — PhysX-only event term in backend-shared EventCfg

EventCfg is documented as shared by all physics backends, yet RandomizeFrictionKeepCompliant calls root_view.max_shapes, get_compliant_material_properties() and set_compliant_material_properties(), which are PhysX RigidBodyView APIs. Newton and OV runs of this task now hit that startup term instead of the backend-dispatching mdp.randomize_rigid_body_material. Keep the shared config on the stock term and apply the compliant variant only in the PhysX-specific configuration.

[isaaclab-review-bot]

🟡 Warning · Design Architecture — PhysX material type in shared spawn presets

OBJECT_PHYSICS (and ObjectCfg.cube at line 85) now spawn with PhysxRigidBodyMaterialCfg instead of the backend-neutral RigidBodyMaterialCfg, but these presets feed default = shapes and ovphysx = cube for all backends. This changes the authored material type for non-PhysX spawners. Override the material in the PhysX configuration and leave the shared preset backend-neutral.

[isaaclab-review-bot]

🟡 Warning · Implementation — Missing SPDX header and leftover experiment artifacts

New source files must carry the repository SPDX header used by sibling modules such as lift_env_cfg.py; this file instead opens with an "experiment" note and ends with an unconditional [TRUEFIX] stdout print guarded by a _logged flag. Add the standard BSD-3-Clause header, remove the debug print, and rewrite the header comment to state the intent of preserving compliant contact.

[isaaclab-review-bot]

🟡 Warning · Api — Term silently ignores configured randomization parameters

__call__ accepts env_ids, restitution_range, num_buckets, and asset_cfg but uses none of them: every environment and shape is written, restitution is never applied, and the configured num_buckets=250 friction discretization is dropped. Callers editing these params in EventCfg will see no effect and different behavior from the term being replaced. Honor the parameters or remove them from both the signature and the config.

[isaaclab-review-bot]

🔵 Suggestion · Implementation — Missing changelog fragment for isaaclab_tasks

This changes user-visible lift task physics (compliant object material and a different startup randomization term) in the isaaclab_tasks package, but no fragment was added under source/isaaclab_tasks/changelog.d/. Repository rules require one past-tense fragment per touched source package, or a .skip fragment when no release note is needed.