[FEATURE] Adds support for attaching MPM particles to rigid links.

[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.

[duburcqa]

You should flag this test as slow if it is (>200s). Beware that it means that it will only run on production CI, so only do this if necessary.

[YilingQiao]

it's not slow on my machine, but I'm happy to add the tag to make our generic CI not too slow

[duburcqa]

it's not slow on my machine, but I'm happy to add the tag to make our generic CI not too slow

The speed must be benched on the generic CI runners. Not your machine. So you need to run the entire CI pipeline without "slow" mark at least once, otherwise you will never know since it will be skipped.

[github-actions]

⚠️ Abnormal Benchmark Result Detected ➡️ Report

[YilingQiao]

Comments are addressed

[duburcqa]

Note that you are still not using zero-copy but I will let that slip in I don't think it is a bottleneck.