🧶 IPC Coupler

Genesis provides Incremental Potential Contact (IPC) coupling for high-fidelity deformable-rigid interactions.

Requirements

Requires libuipc library (build from https://github.com/spiriMirror/libuipc).

Basic Setup

import genesis as gs

dt = 0.01
scene = gs.Scene(
    sim_options=gs.options.SimOptions(dt=dt, gravity=(0.0, 0.0, -9.8)),
    coupler_options=gs.options.IPCCouplerOptions(
        dt=dt,
        gravity=(0.0, 0.0, -9.8),
    ),
)

Key Parameters

Parameter	Default	Description
dt	0.001	Time step for IPC simulation
contact_d_hat	0.001	Contact barrier distance
contact_friction_mu	0.5	Friction coefficient
ipc_constraint_strength	(100, 100)	(translation, rotation) coupling strength
two_way_coupling	True	Forces from IPC affect rigid bodies
IPC_self_contact	False	Enable rigid-rigid self-collision
enable_ipc_gui	False	Polyscope visualization

Cloth Simulation

scene = gs.Scene(
    coupler_options=gs.options.IPCCouplerOptions(
        dt=2e-3,
        contact_d_hat=0.01,
        contact_friction_mu=0.3,
        enable_ipc_gui=True,
    ),
)

cloth = scene.add_entity(
    morph=gs.morphs.Mesh(file="cloth.obj"),
    material=gs.materials.FEM.Cloth(
        E=10e5,
        nu=0.499,
        rho=200,
        thickness=0.001,
        bending_stiffness=50.0,
    ),
)

Robot Grasping

scene = gs.Scene(
    coupler_options=gs.options.IPCCouplerOptions(
        dt=1e-2,
        ipc_constraint_strength=(100, 100),
        contact_friction_mu=0.8,
        two_way_coupling=True,
    ),
)

franka = scene.add_entity(gs.morphs.MJCF(file="panda.xml"))

# Filter which links participate in IPC
scene.sim.coupler.set_ipc_link_filter(
    entity=franka,
    link_names=["left_finger", "right_finger"],
)

cube = scene.add_entity(
    morph=gs.morphs.Box(size=(1.0, 1.0, 1.0)),
    material=gs.materials.FEM.Elastic(E=5e3, nu=0.45, rho=1000),
)

When to Use IPC

Use IPC for:

• Cloth/fabric simulation with collision

• FEM objects interacting with rigid bodies

• High-quality grasping simulation

• Stable constraint-based contact resolution

Use LegacyCoupler for:

• Simple rigid-MPM, rigid-SPH interactions

• Lower computational overhead

• When IPC library unavailable

Contact Handling

Interaction	IPC Behavior
FEM-FEM	Always enabled
FEM-Rigid	Always enabled
Rigid-Rigid	IPC_self_contact option
Cloth-Cloth	Always enabled (self-collision)

Performance Tips

• Match contact_d_hat to mesh resolution (0.5-2mm typical)

• Higher ipc_constraint_strength = stiffer but potentially unstable

• Use disable_genesis_ground_contact=True to avoid double-counting ground collision