newton.solvers.SolverImplicitMPM#

class newton.solvers.SolverImplicitMPM(model, options)[source]#

Bases: SolverBase

Implicit MPM solver.

This solver implements an implicit MPM algorithm for granular materials, roughly following [1] but with a GPU-friendly rheology solver.

This variant of MPM is mostly interesting for very stiff materials, especially in the fully inelastic limit, but is not as versatile as more traditional explicit approaches.

[1] https://doi.org/10.1145/2897824.2925877

Parameters:

  • model (Model) – The model to solve.

  • options (ImplicitMPMOptions) – The solver options.

Returns:

The solver.

Options#

alias of ImplicitMPMOptions

classmethod register_custom_attributes(builder)#

Register MPM-specific custom attributes in the ‘mpm’ namespace.

This method registers per-particle material parameters and state variables for the implicit MPM solver.

Attributes registered on Model (per-particle):

  • mpm:young_modulus: Young’s modulus in Pa

  • mpm:poisson_ratio: Poisson’s ratio for elasticity

  • mpm:damping: Viscous damping coefficient

  • mpm:hardening: Hardening factor for plasticity

  • mpm:friction: Friction coefficient

  • mpm:yield_pressure: Yield pressure in Pa

  • mpm:tensile_yield_ratio: Tensile yield ratio

  • mpm:yield_stress: Deviatoric yield stress in Pa

Attributes registered on State (per-particle):

  • mpm:particle_qd_grad: Velocity gradient for APIC transfer

  • mpm:particle_elastic_strain: Elastic deformation gradient

  • mpm:particle_Jp: Determinant of plastic deformation gradient

  • mpm:particle_transform: Overall deformation gradient for rendering

__init__(model, options)#
collect_collider_impulses(state)#

Collect current collider impulses and their application positions.

Returns a tuple of 3 arrays:

  • Impulse values in world units.

  • Collider positions in world units.

  • Collider id, that can be mapped back to the model’s body ids using the collider_body_index property.

notify_model_changed(flags)#
project_outside(state_in, state_out, dt, max_dist=None)#

Project particles outside of colliders, and adjust their velocity and velocity gradients

Parameters:

  • state_in (State) – The input state.

  • state_out (State) – The output state. Only particle_q, particle_qd, and particle_qd_grad are written.

  • dt (float) – The time step, for extrapolating the collider end-of-step positions from its current position and velocity.

  • max_dist (float | None) – Maximum distance for closest-point queries. If None, the default is the voxel size times sqrt(3).

sample_render_grains(state, grains_per_particle)#

Generate per-particle point samples used for high-resolution rendering.

Parameters:

  • state (State) – Current Newton state providing particle positions.

  • grains_per_particle (int) – Number of grains to sample per particle.

Returns:

A wp.array with shape (num_particles, grains_per_particle) of type wp.vec3 containing grain positions.

setup_collider(collider_meshes=None, collider_body_ids=None, collider_thicknesses=None, collider_friction=None, collider_adhesion=None, collider_projection_threshold=None, model=None, body_com=None, body_mass=None, body_inv_inertia=None, body_q=None)#

Configure collider geometry and material properties.

By default, collisions are set up against all shapes in the model with newton.ShapeFlags.COLLIDE_PARTICLES. Use this method to customize collider sources, materials, or to read colliders from a different model.

Parameters:

  • collider_meshes (list[Mesh] | None) – Warp triangular meshes used as colliders.

  • collider_body_ids (list[int] | None) – For dynamic colliders, per-mesh body ids.

  • collider_thicknesses (list[float] | None) – Per-mesh signed distance offsets (m).

  • collider_friction (list[float] | None) – Per-mesh Coulomb friction coefficients.

  • collider_adhesion (list[float] | None) – Per-mesh adhesion (Pa).

  • collider_projection_threshold (list[float] | None) – Per-mesh projection threshold (m).

  • model (Model | None) – The model to read collider properties from. Default to solver’s model.

  • body_com (array | None) – For dynamic colliders, per-body center of mass.

  • body_mass (array | None) – For dynamic colliders, per-body mass. Pass zeros for kinematic bodies.

  • body_inv_inertia (array | None) – For dynamic colliders, per-body inverse inertia.

  • body_q (array | None) – For dynamic colliders, per-body initial transform.

step(state_in, state_out, control, contacts, dt)#
update_particle_frames(state_prev, state, dt, min_stretch=0.25, max_stretch=2.0)#

Update per-particle deformation frames for rendering and projection.

Integrates the particle deformation gradient using the velocity gradient and clamps its principal stretches to the provided bounds for robustness.

update_render_grains(state_prev, state, grains, dt)#

Advect grain samples with the grid velocity and keep them inside the deformed particle.

Parameters:

  • state_prev (State) – Previous state (t_n).

  • state (State) – Current state (t_{n+1}).

  • grains (array) – 2D array of grain positions per particle to be updated in place. See sample_render_grains.

  • dt (float) – Time step duration.

property collider_body_index: array#

Array mapping collider indices to body indices.

Returns:

Per-collider body index array. Value is -1 for colliders that are not bodies.

property voxel_size: float#

Grid voxel size used by the solver.