[FEATURE] MPM rigid attachment

[YilingQiao]

Adds support for attaching MPM particles to rigid links using soft constraints, similar to the existing FEM vertex constraint system.

mpm_attachment.mp4

Changes

genesis/options/solvers.py

• Add enable_particle_constraints option to MPMOptions (default: False)

genesis/engine/solvers/mpm_solver.py

• Add particle_constraint_info struct for constraint data
• Add init_constraints() for lazy field initialization
• Add _kernel_set_particle_constraints() and _kernel_remove_particle_constraints() kernels
• Add apply_particle_constraints() kernel with ti.static branching for zero overhead when disabled
• Call constraint kernel in substep_post_coupling() after G2P

genesis/engine/entities/mpm_entity.py

• Add get_particles_in_bbox() helper to find particles in a region
• Add set_particle_constraints() to attach particles to a rigid link
• Add remove_particle_constraints() to detach particles

Usage

scene = gs.Scene(
    mpm_options=gs.options.MPMOptions(
        enable_particle_constraints=True,
        ...
    )
)

# Find particles in attachment region
particles = mpm_entity.get_particles_in_bbox(bbox_min, bbox_max)

# Attach to rigid link with spring stiffness
mpm_entity.set_particle_constraints(particles, link=robot.links[0], stiffness=1e5)

Tests

• tests/test_mpm.py: Unit tests for constraint API and behavior

Example

• examples/coupling/rigid_mpm_attachment.py: Demo of MPM cube attached to oscillating rigid box

Screenshots (if appropriate):

Checklist:

• I read the CONTRIBUTING document.
• I followed the Submitting Code Changes section of CONTRIBUTING document.
• I tagged the title correctly (including BUG FIX/FEATURE/MISC/BREAKING)
• I updated the documentation accordingly or no change is needed.
• I tested my changes and added instructions on how to test it for reviewers.

• I have added tests to cover my changes.
• All new and existing tests passed.