Add MPM solver guide and packaged tuning examples

[maxkra15]

Description

Add a focused MPM solver guide and four controlled, packaged Newton MPM examples: material comparisons, nearly rigid MPM versus MJWarp, G1 particle coupling, and surface reconstruction. The guide separates constitutive tuning, numerical resolution, coupling, particle initialization, and visualization, with the reviewed recordings beside the relevant guidance.

Depends on #7944. This branch incorporates the current head of that PR and must land after it. The tuning programs live under examples/mpm/tuning/, are staged in the released wheel, and have stable isaaclab example names. The existing granular and two-way examples and the snowball and teapot demos use #7944's relocated paths and CLI commands. Refresh this branch on the final develop after #7944 merges, especially if it is squash-merged, so this PR's final diff contains only its own changes.

Organization and scope

• Run the material, rigid-equivalence, G1, and surface programs as isaaclab example mpm-material-tuning, mpm-rigid-equivalence, mpm-g1-coupling, and mpm-surface-reconstruction. The G1 example uses the existing rsl-rl extra for its published policy.
• Keep the methodology in docs/source/concepts/solver-tuning/tune_mpm.rst alongside the other solver guides, with core MPM scenes, G1 coupling, and surface reconstruction documented in their relevant concept pages.
• Add optional kinematic plate compression for the elastic-stiffness and compressibility comparisons and document deterministic jitter, particle density, observation time, and qualitative-comparison limits.
• Expose fixed/adaptive proxy-feedback relaxation through CouplerProxyMappingCfg and explain true one-way coupling.
• Keep capture tooling, encoded media, benchmark artifacts, and training changes out of Git.

Published media

The documentation embeds 18 reviewed MPM recordings from https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/. Encoded media remain outside Git.

Validation

• CLI and standalone-script tests: 84 passed, 348 opt-in simulator-launch cases skipped.
• Built the unified wheel and verified that all four tuning scripts are present under isaaclab/_examples/mpm/tuning/.
• Ran isaaclab example mpm-material-tuning for two headless Newton steps through the packaged CLI; isaaclab example list and example help also worked.
• Built the complete documentation with warnings treated as errors.
• All formatting hooks passed. The changelog check passes against Package demos and examples behind the Isaac Lab CLI #7944's head. A local all-files check against develop flags already-consumed fragments in the stacked history; the PR's GitHub changelog and pre-commit checks pass.

Type of change

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

Release backport

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

Screenshots

The documentation embeds the published MP4 comparisons directly from the Isaac Lab media host.

Checklist

• I have read and understood the contribution guidelines
• I have run the formatting hooks and checked changelog fragments against the dependency PR
• I have made corresponding changes to the documentation
• My changes generate no new documentation warnings
• I have added focused standalone-script and CLI coverage
• I have added a changelog fragment for the changed source package
• My name already exists in CONTRIBUTORS.md

[maxkra15]

run-ci

[maxkra15]

run-ci

[greptile-apps]

Confidence Score: 4/5

The PR is not yet safe to merge because the new G1 smoke case can fail or time out on cold or offline CI workers while retrieving its policy checkpoint.

Findings

1.  Network-Dependent Smoke Test ▶

Summary

This PR adds four controlled Newton MPM tuning demonstrations, a comprehensive solver-tuning guide, proxy-feedback relaxation configuration, and focused standalone-script coverage.

• Documents material, resolution, coupling, and surface-reconstruction tuning practices.
• Adds material, rigid-equivalence, G1 coupling, and reconstruction demos.
• Exposes fixed and adaptive proxy-feedback relaxation settings.
• Changes the teapot demo’s default rendering mode to particles.
• Adds smoke coverage, but the G1 case currently depends on downloading a policy before readiness.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    CLI[G1 tuning demo] --> CFG[Configure rigid and MPM solvers]
    CFG --> COUPLER[Proxy coupler]
    COUPLER --> RIGID[MJWarp G1 and runway]
    COUPLER --> MPM[Sand, snow, and clay particles]
    RIGID -->|proxy motion| MPM
    MPM -->|relaxed feedback in two-way mode| RIGID
    POLICY[Published G1 checkpoint] --> RUNNER[RSL-RL policy runner]
    RUNNER --> RIGID

Loading

_{Reviews (1) · Last reviewed commit: "Merge remote-tracking branch 'origin/dev..."}

[isaaclab-review-bot]

Isaac Lab Review Bot

Adds four Newton MPM tuning demos, integrated solver and coupling guidance, smoke registrations, and additive proxy-feedback relaxation settings. Two documentation/default issues should be corrected: the surface demo defaults to an optional RTX path, and the public relaxation docstring is ambiguous about staggered-mode behavior.

• Design and architecture: The self-contained tuning demos and dedicated solver-tuning guide fit the existing organization. However, surface_reconstruction.py defaults to newton_rtx, making its no-argument invocation depend on the optional ovrtx extra even though Newton GL supports the demo without that extra; default to newton_gl and retain RTX as an explicit choice.
• API: The four CouplerProxyMappingCfg fields are additive and covered by configuration plumbing tests and release documentation. The proxy_relaxation docstring incorrectly narrows its description to lagged feedback while the new G1 demo applies it with staggered mode and the guide describes it across both modes. The public API documentation should state explicitly which transfer modes honor relaxation, including whether zero suppresses staggered feedback.
• Implementation: The demo wiring, documentation integration, readiness markers, deterministic particle generation, and proxy configuration paths were traced. The actionable implementation concern is the surface reconstruction demo's optional-dependency default; otherwise the identified issue is API-contract clarity rather than a demonstrated solver implementation failure.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🔵 Suggestion · Implementation — Default visualizer requires optional ovrtx extra

This demo defaults to newton_rtx, whose own docstring shows it must be launched with --extra ovrtx, so a bare uv run python scripts/demos/mpm/tuning/surface_reconstruction.py depends on an optional extra. Sibling demos such as teapot_fill.py default to newton_gl and require the extra only for explicit RTX runs; defaulting to newton_gl would keep the no-argument invocation runnable in the base environment.

[isaaclab-review-bot]

🔵 Suggestion · Api — Clarify relaxation scope across proxy modes

The docstring scopes this factor to "lagged proxy-feedback forces", but g1_coupling.py defaults to --proxy_mode staggered and relies on proxy_relaxation=0.0 to realize one-way coupling, and coupled_solvers.rst states both transfer modes can return forces. Readers cannot tell whether zero relaxation suppresses feedback under staggered. State explicitly which modes the factor applies to.

[maxkra15]

run-ci