Author Newton MPM particles through USD

[maxkra15]

Description

This PR migrates Isaac Lab's Newton MPM spawners from direct ModelBuilder particle emission to schema-valid USD authoring and Newton's standard USD import path.

MPMGridCfg and MPMPointsCfg remain the user-facing convenience APIs. They now author:

• a real UsdGeom.Points prim with positions, velocities, widths = 2 * radius, and explicit physics:masses;
• Newton deformable/simulation schemas and a relationship to the owning MPM scene;
• a physics-purpose bound material carrying NewtonMPMMaterialAPI;
• all supported material values, including the new hardening_rate and softening_rate fields; and
• solver-global MPM settings, including critical_fraction, on NewtonMPMSceneAPI.

Newton imports the authored particles through ModelBuilder.add_usd(). Isaac Lab consumes the returned path_particle_map to retain each MPMObject particle range across both homogeneous batched replication and heterogeneous builder merges.

Behavior preserved

• Explicit particle masses are retained instead of being reconstructed from density and particle width.
• Existing particle ordering, initial velocities, and initial transforms are preserved.
• Grid generation remains deterministic with the existing fixed jitter seed.
• Isaac Lab's relaxation-time damping is converted to schema viscosity with elastic_damping = damping * young_modulus.
• The existing independently mutable <MPM asset>/Particles visualization prim and synchronization path remain in place for GL, Newton RTX, and Kit rendering.
• MPMGridCfg continues generating explicit points procedurally in Isaac Lab because the USD schema represents explicit particles rather than a procedural grid.

The four MPM demos and the Franka Pour and UR10 Particle Push tasks use the new authoring path. Their manually added MPM ground colliders were removed in favor of the standard scene ground-plane workflow.

Dependencies

• Uses the Newton 1.6.0rc1 release already pinned on develop.
• Requires newton-usd-schemas >= 0.5.0.

Breaking changes

• Removes the direct emit_mpm_particles() helper. Use MPMGridCfg or MPMPointsCfg through the standard spawner workflow.
• Grid jitter is authored once in asset-local space and shared by USD clones. Independent per-environment distributions should use reset events or domain randomization.

Per-point multi-material authoring through UsdGeomSubset remains intentionally out of scope until Isaac Lab has a user-facing subset configuration API.

Type of change

• Breaking change
• Documentation update

Release backport

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

Screenshots

Not applicable; existing runtime visualization behavior is retained.

Validation

• 216 passed across the focused MPM spawner, MPM object, Newton cloning, and Newton manager suites.
• CUDA smoke-tested all four MPM demos: granular, two-way coupling, snowball smash, and teapot fill.
• CUDA smoke-tested IsaacContrib-UR10-Particle-Push and IsaacContrib-Franka-Pour.
• Built the complete documentation with warnings treated as errors.
• Ran all formatting and pre-commit checks successfully.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have updated focused tests for the feature
• I have added changelog fragments for every touched source package
• My name already exists in CONTRIBUTORS.md

[maxkra15]

run-ci

[greptile-apps]

Greptile Summary

This PR migrates Newton MPM particle creation from direct ModelBuilder emission to schema-valid USD authoring and Newton's standard USD import path.

• Authors explicit particle positions, velocities, widths, masses, materials, and solver-global MPM settings in USD.
• Preserves particle ranges and transforms across homogeneous and heterogeneous replication.
• Adds hardening and softening material parameters and requires newton-usd-schemas>=0.5.0.
• Updates MPM demos and tasks to use the standard scene ground-plane workflow.
• No changes were made after the previous review SHA.

Confidence Score: 5/5

The PR appears safe to merge because no new issues were introduced after the previous review and both prior findings were resolved after Greptile conceded them.

The current changes consistently author and import MPM particles through USD, preserve particle ranges across replication paths, and expose the required schema revision. The two previous findings are not outstanding: both threads were resolved after the implementation details showed the reported failures were unreachable.

Important Files Changed

Filename	Overview
source/isaaclab_newton/isaaclab_newton/sim/spawners/mpm/mpm.py	Authors validated MPM particles and materials as schema-backed USD geometry instead of emitting particles directly into Newton.
source/isaaclab_newton/isaaclab_newton/assets/mpm_object/mpm_object.py	Registers imported particle ranges and restores clone transforms so each MPM object retains its corresponding Newton particle slice.
source/isaaclab_newton/isaaclab_newton/cloner/newton_clone_utils.py	Propagates USD import results and particle offsets through homogeneous replication and heterogeneous builder merges.
source/isaaclab_newton/isaaclab_newton/physics/mpm_manager.py	Authors solver settings on NewtonMPMSceneAPI and constructs the runtime solver configuration from the validated schema.
source/isaaclab_newton/isaaclab_newton/cloner/replicate.py	Connects source import particle maps to MPM range registration during mapped replication.
source/isaaclab_newton/isaaclab_newton/physics/newton_manager.py	Records imported MPM particle ranges in the standard Newton scene-building paths.
pyproject.toml	Raises the Newton USD schema requirement to the revision needed for MPM USD authoring.
uv.lock	Resolves newton-usd-schemas 0.5.0 and refreshes workspace package versions.

Sequence Diagram

sequenceDiagram
    participant C as MPMGridCfg / MPMPointsCfg
    participant U as USD Stage
    participant N as Newton ModelBuilder
    participant R as Clone Replication
    participant O as MPMObject

    C->>U: Author UsdGeom.Points, masses, velocities, widths
    C->>U: Bind NewtonMPMMaterialAPI material
    C->>U: Relate particles to NewtonMPMSceneAPI
    U->>N: add_usd()
    N-->>R: path_particle_map and source builder
    R->>R: Replicate or merge builders
    R->>O: Record destination particle ranges
    O->>O: Synchronize simulation and visualization state

Loading

_{Reviews (2): Last reviewed commit: "Merge remote-tracking branch 'origin/dev..." | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The USD-based Newton MPM authoring and import pipeline is coherent, including explicit points, materials, solver schemas, and particle-range tracking across replication. One API compatibility issue remains: the exported emit_mpm_particles helper is removed without the deprecation period required by repository policy.

• Design and architecture: The spawner-to-USD-to-path_particle_map flow consistently connects authored particles to MPMObject registry ranges across homogeneous replication and heterogeneous builder merges. No actionable architecture defect was established.
• API: The new material fields, schema dependency, documentation, and changelog updates are aligned. However, removing the publicly exported emit_mpm_particles symbol outright violates the repository requirement for prior deprecation and migration; retain a deprecated compatibility wrapper for the required transition period.
• Implementation: The particle generation, explicit mass and width authoring, transform restoration, and range-recording paths were traced without finding another concrete implementation defect. Importing the shared private suffix constant keeps the producer and consumer path synchronized, so that candidate concern does not warrant a separate change.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[maxkra15]

run-ci

[maxkra15]

run-ci