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.

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 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:

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:

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 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:

# 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 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:

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

uv run isaaclab example mpm-granular

Watch the embedded video

uv run isaaclab example mpm-two-way-coupling

Watch the embedded video

uv run isaaclab demo snowball-smash

Watch the embedded video

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:

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:

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:

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.