> This page is for version Release 3.0 (default). > For other versions, use one of these documentation indexes: > - Release 3.0 (default): https://docs.nvidia.com/isaaclab/3.0/llms.txt > - Release 2.3: https://docs.nvidia.com/isaaclab/2.3/llms.txt > - Release 2.2: https://docs.nvidia.com/isaaclab/2.2/llms.txt > - Release 2.1: https://docs.nvidia.com/isaaclab/2.1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/isaaclab/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/isaaclab/_mcp/server. # Implicit MPM Newton's implicit Material Point Method (MPM) solver models particle materials such as sand, snow, and other granular media. Isaac Lab integrates it as a Newton solver configuration, a particle asset type, and an optional coupling with rigid-body solvers. MPM support and rigid--MPM coupling are experimental. This page explains how the integration works. For runnable scenes, see `Examples and tasks`\_. For resolution, convergence, and material studies, and the nearly rigid MPM limit, see [MPM Solver](/source/how-to/solver_tuning_mpm). ## How MPM fits into the Newton backend Selecting `~isaaclab_newton.physics.MPMSolverCfg` as the `solver_cfg` of `~isaaclab_newton.physics.NewtonCfg` installs `~isaaclab_newton.physics.NewtonMPMManager`, a specialization of the Newton manager that constructs Newton's `SolverImplicitMPM`. The solver represents material as particles and solves its rheology implicitly on a background voxel grid. The MPM manager configures the Newton manager as follows: * It advances particles in place on a single Newton state rather than double buffering state. * It resolves collider contact inside the implicit solve. It does not use Newton's collision pipeline. * It treats rigid geometry as colliders. It is not a rigid-body or articulation dynamics solver, and it does not accept external rigid-body forces. Kinematic bodies are given zero mass before the model is finalized, and convex meshes are passed to the solver as triangle meshes. ## Coupling with rigid bodies On its own, the MPM solver advances only particles. Rigid bodies act as colliders whose motion comes from elsewhere, such as kinematic pose writes, and the material does not push back on them. Two-way interaction uses the experimental coupler in `isaaclab_contrib.coupling`. A `~isaaclab_contrib.coupling.CouplerProxyCfg` partitions one Newton model into named entries: * a rigid entry, for example MJWarp, that owns the robot or object bodies; * an MPM entry that owns the particles and must set `in_place=True`; and * a proxy mapping that exposes selected rigid bodies as colliders in the MPM entry and feeds the resulting impulses back to the rigid entry. The `mpm-two-way-coupling` example, the `snowball-smash` demo, and the Franka Pour task all use this pattern. See [Coupled Solvers](/source/concepts/coupled_solvers) for proxy and ADMM coupling, exchange modes, and tuning. ## Data model ### Configuration and USD An MPM material is a scene asset. `~isaaclab_newton.assets.MPMObjectCfg` extends the deformable-object configuration and takes a particle spawner: * `~isaaclab_newton.sim.spawners.mpm.MPMGridCfg` fills an axis-aligned local box with a particle lattice whose resolution follows `voxel_size` and `particles_per_cell`. * `~isaaclab_newton.sim.spawners.mpm.MPMPointsCfg` places particles at explicit local positions, with optional velocities, masses, and radii. Both spawners author schema-valid `UsdGeom.Points` simulation geometry. Grid configurations still generate the lattice in Isaac Lab before authoring explicit points, widths, velocities, and masses. Per-particle material values come from `~isaaclab_newton.sim.spawners.mpm.MPMParticleMaterialCfg` and are authored with `NewtonMPMMaterialAPI`. Damping \[s] is authored as `damping * young_modulus` \[Pa·s]. Solver-wide settings, including `critical_fraction`, live on `MPMSolverCfg`; the schema-representable ones are authored with `NewtonMPMSceneAPI` on the physics scene prim. MPM objects are cloned through Newton replication. Grid jitter is generated once in asset-local coordinates with a fixed seed, so USD clones share the same local particle distribution. Use reset events or domain randomization when each environment needs an independent distribution. Use the same voxel size for the solver grid and particle generator. Add the generated object to an `~isaaclab.scene.InteractiveSceneCfg` like any other declarative asset: ```python import isaaclab.sim as sim_utils from isaaclab_newton.assets import MPMObjectCfg from isaaclab_newton.physics import MPMSolverCfg, NewtonCfg from isaaclab_newton.sim.spawners.mpm import MPMGridCfg voxel_size = 0.02 sim_cfg = sim_utils.SimulationCfg( dt=1.0 / 100.0, physics=NewtonCfg( solver_cfg=MPMSolverCfg( voxel_size=voxel_size, max_iterations=100, tolerance=1.0e-4, ), num_substeps=2, ), ) media = MPMObjectCfg( prim_path="{ENV_REGEX_NS}/Media", spawn=MPMGridCfg( lower=(-0.1, -0.1, 0.0), upper=(0.1, 0.1, 0.2), voxel_size=voxel_size, particles_per_cell=2.0, particle_placement="cell_center", ), ) ``` ### Runtime asset `~isaaclab_newton.assets.MPMObject` implements Isaac Lab's deformable-object interface, so scene reset, update, and state workflows treat it like other deformables. Each environment instance holds the same number of particles, reported by `particles_per_object`. `~isaaclab_newton.assets.MPMObjectData` exposes particle positions, velocities, and combined state in the simulation world frame through `particle_pos_w`, `particle_vel_w`, and `particle_state_w`. The deformable `nodal_*` properties are aliases of these. `root_pos_w` and `root_vel_w` are per-instance means over the particles. Position, velocity, and state writers apply immediately. Deformable kinematic targets are not supported. ## Configuration reference The generated `~isaaclab_newton.physics.MPMSolverCfg` reference is the source of truth for fields and defaults. The fields group as follows: | Group | Fields | Effect | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Resolution | `voxel_size`, and `particles_per_cell` on the spawner | Background-grid and particle resolution, which set accuracy, active cells, and memory use. | | Grid storage | `grid_type`, `grid_padding`, `max_active_cell_count`, the `max_*_node_count` limits, and `separate_worlds` | Sparse, dense, or fixed grid allocation, reserved capacity, and whether each world uses its own local grid. | | Rheology solve | `max_iterations`, `tolerance`, `solver`, and `warmstart_mode` | Iteration cap, convergence tolerance, the solver or warm-start sequence, and warm-start source. | | Discretization | `transfer_scheme`, `integration_scheme`, `velocity_basis`, `strain_basis`, and `collider_basis` | Particle-grid transfer, shape-function support, and the basis functions for each field. | | Material and background | `critical_fraction` and `air_drag` | Solver-global yield-surface collapse and numerical drag for empty space. | | Colliders | `collider_velocity_mode`, `collider_normal_from_sdf_gradient`, and `project_outside_colliders` | Collider velocity and normal computation, and an optional post-substep projection of particles out of colliders. | The implicit solve already resolves collider contact. `project_outside_colliders` adds a hard post-step correction for particles that remain inside colliders; use it only when that geometric correction is intentional, and not as a substitute for valid initial states, collision geometry, or a stable timestep. ### CUDA graph capture CUDA graph capture of the MPM step is available only when the grid has capture-stable storage: * a `"fixed"` grid with a positive `max_active_cell_count`; or * a `"sparse"` grid with a positive `max_active_cell_count`, `grid_padding=0`, and the `"Q1"` velocity basis. The strain basis must start with `"pic"` or be one of `"P0"`, `"P1d"`, `"Q1d"`, or `"Q1"`. The collider basis must start with `"pic"` or be one of `"Q1"`, `"S2"`, or `"S3"`. Dense grids and unbounded grids run without capture. ### Resets With the MPM solver alone, automatic asset resets leave solver history untouched, because worlds that share one grid cannot have their history reset individually. Under a coupler, automatic resets go through the coupled solver's reset, which passes the per-world reset mask to every entry, including the MPM entry. Tasks that need an exact history reset, such as Franka Pour, use independent MPM worlds (`separate_worlds=True`) and call `~isaaclab_newton.physics.NewtonMPMManager.reset_solver_state` after writing their complete state. In a coupled run, this also resets the coupled solver's history. Try the [interactive MPM demo](https://isaac-sim.github.io/IsaacLab/release/3.0.0/source/setup/interactive_demos.html) to compare material references and adjust stiffness, cohesion, friction, and hardening on a repeatable particle drop. ## Rendering a particle surface MPM simulation state remains a set of particles. Surface reconstruction is an optional visualization pass: it does not change particle motion, collisions, or material behavior. Run the teapot demo to compare the available modes: ```bash # Reconstructed surface uv run isaaclab demo teapot-fill \ --visualizer newton_gl --fluid_render_mode surface # Surface and source particles together uv run isaaclab demo teapot-fill \ --visualizer newton_gl --fluid_render_mode both # Path-traced translucent surface uv run --extra ovrtx isaaclab demo teapot-fill \ --visualizer newton_rtx --fluid_render_mode surface ``` The teapot demo defaults to the reconstructed surface. Select `particles` or `both` to inspect the source MPM state in Newton GL or Newton RTX. Surface rendering is available in the Newton GL and Newton RTX visualizers. The Kit visualizer continues to render the MPM particles directly. [Watch the embedded video](https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/mpm_surface_reconstruction.mp4) This recording demonstrates rendering appearance, not a different constitutive model. The teapot demo configures `newton.geometry.ParticleSurface` after `sim.reset()` and updates the mesh before `sim.render()`. Its renderer captures extraction on CUDA when enabled and stages the dynamic mesh inside the viewer's frame lifecycle. Tune reconstruction independently from the simulation: * `voxel_size` controls surface detail and memory use. It can be smaller than the MPM solver voxel size. * `kernel_radius` controls how far each particle contributes to the surface. Start near three times the particle spacing. * `max_grid_cells` provides fixed-capacity storage for CUDA graph capture. Increase it if the reconstructed domain outgrows the reserved grid. * Anisotropic kernels preserve sheets and stretched fluid features better, but cost more than isotropic kernels. To render a surface in your own scene, pass the configured `newton.geometry.ParticleSurface` to `ParticleSurfaceRenderer` after `sim.reset()`. Call `update()` before `sim.render()` to extract and stage the current mesh. The renderer handles CUDA graph capture, empty surfaces, inactive particles, and dynamic topology: ```python class ParticleSurfaceRenderer: """Extract one particle surface and stage its latest mesh for Newton viewers. Configure a Newton `ParticleSurface` and construct this renderer after resetting the simulation. Call `update` before rendering each frame to reconstruct the surface from the current particle state. """ def __init__( self, visualizers: Iterable[BaseVisualizer], surface: ParticleSurface, *, path: str, color: tuple[float, float, float], opacity: float, roughness: float = 0.1, use_cuda_graph: bool = True, ) -> None: """Allocate reusable extraction storage and optionally capture its CUDA graph. Args: visualizers: Active visualizers; non-Newton viewers are ignored. surface: Configured Newton surface extractor. path: Viewer mesh path. color: Surface RGB color in [0, 1]. opacity: Surface opacity in [0, 1]. roughness: Surface roughness in [0, 1]. use_cuda_graph: Capture extraction on CUDA when enabled. Raises: RuntimeError: If no Newton GL or RTX visualizer is active. """ self._visualizers = tuple( visualizer for visualizer in visualizers if isinstance(visualizer, (NewtonGLVisualizer, NewtonRTXVisualizer)) ) if not self._visualizers: raise RuntimeError("Particle surface rendering requires a Newton GL or RTX visualizer.") self._model = NewtonManager.get_model() self._state = NewtonManager.get_state_0() self._surface = surface self._path = path self._color = color self._opacity = opacity self._roughness = roughness self._empty_points = wp.empty(0, dtype=wp.vec3, device=self._model.device) self._empty_indices = wp.empty(0, dtype=wp.int32, device=self._model.device) self._empty_normals = wp.empty(0, dtype=wp.vec3, device=self._model.device) self._surface_mesh = None self._surface_graph = None if use_cuda_graph and self._model.device.is_cuda: self._surface_mesh = self._extract_surface() with wp.ScopedCapture(device=self._model.device) as capture: self._surface_mesh = self._extract_surface() self._surface_graph = capture.graph def update(self) -> int: """Stage the latest surface mesh and return its triangle count.""" if self._surface_graph is None: self._surface_mesh = self._extract_surface() else: wp.capture_launch(self._surface_graph) vertices, indices, normals = self._surface_mesh.to_arrays() hidden = vertices is None triangle_count = 0 if hidden else indices.shape[0] // 3 if hidden: vertices = self._empty_points indices = self._empty_indices normals = self._empty_normals for visualizer in self._visualizers: visualizer.log_mesh( self._path, vertices, indices, normals=normals, hidden=hidden, backface_culling=False, color=self._color, roughness=self._roughness, metallic=0.0, dynamic=True, opacity=self._opacity, ) return triangle_count def _extract_surface(self): """Extract the surface from the current Newton particle state.""" return self._surface.extract( self._state.particle_q, self._model.particle_radius, particle_flags=self._model.particle_flags, particle_world=self._model.particle_world if self._surface.world_count > 1 else None, ) ``` ## Examples and tasks These examples and demos introduce MPM construction and interaction. They default to Newton GL for interactive viewing. The launcher uses `cuda:0` by default. Pass `--device cuda:N` to select a different GPU. [Watch the embedded video](https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/mpm_granular.mp4) ```bash uv run isaaclab example mpm-granular ``` [Watch the embedded video](https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/mpm_two_way.mp4) ```bash uv run isaaclab example mpm-two-way-coupling ``` [Watch the embedded video](https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/mpm_snowball.mp4) ```bash uv run isaaclab demo snowball-smash ``` [Watch the embedded video](https://download.isaacsim.omniverse.nvidia.com/isaaclab/videos/mpm_teapot_particles.mp4) ```bash uv run isaaclab demo teapot-fill --fluid_render_mode particles ``` ### Franka Pour The `IsaacContrib-Franka-Pour` task restores episodes from a reset artifact containing the connected 14-phase reset distribution. The canonical 20,000-row artifact downloads from the standard Isaac Lab asset root on first use, so training needs no artifact setup: ```bash uv run isaaclab train --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ --num_envs 2048 ``` The checked-in generator remains the executable reference for reproducing or customizing the distribution. It takes about two minutes on an L40S-class GPU and writes a local artifact that can be selected explicitly: ```bash uv run python scripts/tools/generate_franka_pour_reset_dataset.py uv run isaaclab train --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ --num_envs 2048 \ env.reset_dataset_path=datasets/franka_pour/reset_dataset.pt ``` The task validates the payload's stored content digest automatically. Setting `ISAACSIM_ASSET_ROOT` redirects the canonical artifact to a compatible local or self-hosted asset tree. Digest pinning remains available for custom reproducible experiments. The source uses a non-colliding analytic fill volume whose height is controlled by `env.source_fill_level` in `(0, 1]`. The default `0.70` fills roughly 70% of the cup height; the particle count follows the requested fill level while voxel size and particle spacing stay fixed. `env.pour_target_frac` independently controls the fraction of that live payload that must reach the receiver. Play a checkpoint in Kit with the canonical task configuration; no external callback or particle override is required: ```bash uv run --extra isaacsim isaaclab play --rl_library rsl_rl --task IsaacContrib-Franka-Pour \ --checkpoint /path/to/model.pt --num_envs 1 --visualizer kit ``` ## Limitations * Coupled MPM entries must step in place and do not support `project_outside_colliders`.