[FEATURE] IPC Coupler Basic Logic

[ACMLCZH]

Summary

Add IPC (Incremental Potential Contact) as a coupler option in Genesis, sitting alongside the existing SAP/Legacy couplers. Wraps libuipc's C++ ABD + FEM solver and orchestrates a per-step Rigid↔FEM↔IPC handshake so that Genesis's rigid-body dynamics and FEM dynamics share a single contact-resolution pass.

Coupling modes (per gs.materials.Rigid(coup_type=...))

coup_type	Who owns the body's dynamics	Who applies contact forces	Used for
two_way_soft_constraint	Genesis rigid solver (full integration)	IPC ABD body tracks Genesis pose via SoftTransformConstraint; back-coupling force returned to Genesis	Any rigid bodies that controlled in RigidSolver and coupled with FEM (not recommended to be used in articulations because it ignores constraints)
external_articulation	Genesis rigid solver (joint-level)	IPC's ExternalArticulationConstraint corrects each joint's delta_theta after contact	Articulated robots ( fixed-base only )
ipc_only	libuipc ABD (free body)	libuipc directly	Free-floating rigid objects that don't need PD/joint control — base joint gets FREE→FIXED conversion at build

FEM entities (tet meshes via gs.materials.FEM.*) and Cloth entities (thin-shell via gs.materials.FEM.Cloth) are always owned by libuipc and contact-coupled with all ABD bodies above.

Per-step flow

For each scene.step() substep, the order is:

substep_pre_coupling:
    rigid_solver.substep_pre_coupling(f)
        kernel_compute_qacc(...)                                  # Genesis-side forward dynamics
        if IPC:
            kernel_predict_integrate(update_qpos=True)            # vel_prev=vel; vel+=acc*dt; qpos_prev=qpos; qpos+=vel*dt
            kernel_forward_kinematics_links_geoms(...)            # FK on predicted qpos
        elif SAP:
            kernel_predict_integrate(update_qpos=False)           # only vel prediction
        else:
            constraint_force()                                    # legacy / no-coupler path

coupler.couple(f):                                                # IPC step (this PR's core)
    1. _store_gs_rigid_states()                                   # snapshot Genesis mass_mat, links_state
    2. cache_pre_prediction_transforms()                          # write any teleport (set_qpos) into IPC ABD bodies
    3. _pre_advance_write_ipc_attributes()
         two_way:  aim_transform[link]   = Genesis predicted T    # what STC tracks
         ext_art:  ref_dof_prev[entity]  = Genesis delta_theta    # what ExternalArticulationConstraint constrains
         ipc_only: aim_transform[link]   = Genesis predicted T (animator path)
    4. _ipc_world.advance()                                       # libuipc Newton solve (contact + dynamics)
    5. _ipc_world.retrieve()
    6. _retrieve_ipc_fem_states()                                 # copy IPC vertex positions  -> FEM solver
    7. _retrieve_ipc_rigid_states()                               # copy IPC ABD transforms    -> abd_data.ipc_transforms
    8. _post_advance_write_qpos()
         Step 1a: ipc_only  base links   -> links_state.pos/quat  (direct write)
         Step 1b: non-fixed base links   -> qpos[0:7]              (FREE-base translation+rotation)
         Step 2a: two_way   child links  -> qpos[q_idx]            (back-compute joint angle from IPC transform)
         Step 2b: ext_art   entities     -> qpos[joints]           (apply IPC's delta_theta)

substep_post_coupling:
    rigid_solver.substep_post_coupling(f)
        if IPC:
            kernel_restore_integrate(restore_qpos=True)           # vel = (qpos_ipc - qpos_prev)/dt; qpos = qpos_prev; acc back-fill
        elif SAP:
            kernel_restore_integrate(restore_qpos=False)          # only acc back-fill
        kernel_step_2(...)                                         # final FK + collision update

Key invariant: for two_way_soft_constraint and external_articulation, Genesis remains the authority for qpos; IPC only adjusts qpos in response to contact. For ipc_only, libuipc is fully authoritative for the body's pose — Genesis just reads the result.

Velocity back-compute (BDF1 assumption)

After IPC writes corrected qpos, kernel_restore_integrate derives velocity as vel = (qpos − qpos_prev) / dt — BDF1. The libuipc integrator is pinned to bdf1 in build_ipc_scene_config so this stays consistent. Switching to BDF2 would require also resetting q_{n−1} / v_{n−1} on teleport, which libuipc doesn't currently expose. Pin + FIXME tracked in utils.py.

Self-collision filtering

IPC's contact tabular respects the same self-collision policy as the rigid solver:

• enable_self_collision — disable all same-entity pairs
• enable_adjacent_collision — disable parent↔child link pairs in the same articulation
• enable_neutral_collision — disable pairs whose merged meshes already overlap at qpos₀ (auto-detect via 99.9%-shrunk trimesh intersection)

coup_links on the material limits which links participate in IPC at all; coup_collision_links further limits which links get contact-active (vs no-collision).

ABD body construction

• Mesh ABD bodies: built via apply_to(mesh, kappa=100 MPa, mass_density=material.rho) — libuipc derives mass/COM/inertia from mesh volumetric integration. Caveat: Genesis-side link.inertial_mass may follow the URDF's explicit <mass>, which can differ from material.rho × mesh_volume. The two solvers can silently disagree for URDFs that author non-default <inertial> blocks. Tracked as a FIXME in coupler.py; principled fix (overload-2 with explicit 12×12 ABD matrix) is verified mechanically correct against libuipc tests but requires test re-calibration before shipping.
• Proxy ABD bodies (no collision mesh): built via create_proxy(mass, mass_center, inertia, volume) using Genesis URDF inertials directly — no mass disagreement in this path.

Fixed-link merging

find_target_link_for_fixed_merge walks up the kinematic tree across FIXED joints, merging child geometry into the first non-fixed ancestor's ABD body. E.g., Franka's hand (FIXED joint to link7) merges into link7's ABD body. Reduces ABD body count and avoids the merged children's collision-detection ambiguity.

Scope

Area	Files	Notes
IPC coupler	genesis/engine/couplers/ipc_coupler/{coupler,data,utils}.py	core implementation
Coupler options	genesis/options/solvers.py (IPCCouplerOptions)	Newton/line-search/contact knobs + Genesis-side toggles
Materials	genesis/engine/materials/rigid.py	coup_type, coup_links, coup_collision_links, soft_constraint_strength, contact_resistance
Rigid kernels	rigid_solver.py, abd/forward_dynamics.py	kernel_predict_integrate, kernel_restore_integrate
Collider filter	solvers/rigid/collider/collider.py	self-collision filter + IPC-vs-rigid delegation
Tests	tests/test_ipc.py	54 tests covering all three coup_types, contact pairs, set_qpos sync, ext_art merge, cloth coupling

Excludes (separate PRs): FEM Paper/Rope materials, plastic discrete-shell bending, per-entity contact_d_hat override, COM/inertia pass-through to libuipc (the principled fix for the mass-disagreement caveat above).

Test plan

• pytest tests/test_ipc.py — 54/54 pass on RTX 5090 Linux
• pytest tests/test_fem.py — 9 pass + 1 pre-existing upstream xfail unrelated to IPC
• pytest tests/test_rigid_physics.py — passes with the IPC delegation/filter changes (re-run with the post-review cleanups recommended)
• Examples under examples/IPC_Solver/ (4 scripts) ported to the new API

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: acdb7b2d05

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Handle scalar qpos indices when marking IPC state dirty

When using IPCCoupler, a direct RigidSolver.set_qpos(..., qs_idx=3) call reaches this branch with qs_idx still as an int; iterating it raises TypeError: 'int' object is not iterable before the ABD state can be marked dirty. The link index branch below already normalizes scalar integers, so scalar qpos/dof indices need the same treatment to keep single-DOF updates working under IPC.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Implement the advertised restitution option

This new option is documented and tests explicitly set it to 0.0, but a repo-wide search shows no read of options.restitution/self.options.restitution, so any nonzero value is silently ignored. Users enabling IPC restitution for bounces or impact experiments will still get the inelastic IPC result, contrary to the API contract added here.

Useful? React with 👍 / 👎.

[alanray-tech]

Bug: exist_ok=False will crash on re-run or after unclean shutdown

The workspace path is deterministic (genesis_ipc_{scene_uid}). If a previous run crashed without cleaning the temp directory, or if the user re-creates a scene with the same UID, this line raises FileExistsError and the coupler cannot initialize.

Questions:

1. Was exist_ok=False intentional here (e.g. to detect stale state)? If so, should there be a try/except with a clear error message guiding the user to clean up?
2. Would shutil.rmtree + os.makedirs be preferable to exist_ok=True, to ensure stale IPC output files from a previous session don't corrupt the new one?
3. There is also no cleanup at shutdown -- the workspace directory accumulates on disk across runs. Would it make sense to register an atexit handler or add a close() method that calls shutil.rmtree(self._ipc_workspace)?

[alanray-tech]

Bug: Operator precedence -- and binds tighter than or

This expression parses as:

(frame_pos is not None and np.any(frame_pos)) or np.any(frame_quat[1:])

rather than the likely intended:

frame_pos is not None and (np.any(frame_pos) or np.any(frame_quat[1:]))

Additionally, frame_pos is initialized on line 452 as a numpy array -- it is never None here, so the is not None check is dead code.

The current expression happens to produce correct results because when frame_pos is all-zero, np.any(frame_pos) is False, so the or falls through to np.any(frame_quat[1:]), which matches the correct logic. But this is a fragile coincidence.

Questions:

1. Can you confirm the intended semantics? I believe this should simply be:

   if np.any(frame_pos) or np.any(frame_quat[1:]):

2. Is there any code path where frame_pos could actually be None at this point? If not, the is not None guard should be removed to avoid misleading future readers.

[alanray-tech]

Question: Division by dt without zero-guard + interaction with func_implicit_damping

Two related concerns about kernel_restore_integrate:

1. No zero-guard on dt division
Lines 99, 107, 129, 139-140, and 179 all divide by substep_dt without any floor/clamp. A zero or near-zero dt would produce inf/NaN that silently propagates through acc, vel, and into kernel_step_2. The existing func_implicit_damping in this same file uses EPS-clamped denominators as a defensive pattern. Should the same guard be applied here, e.g. dt = qd.max(rigid_global_info.substep_dt[None], EPS)?

2. func_implicit_damping can overwrite IPC-derived acceleration
After kernel_restore_integrate, dofs_state.acc holds the IPC-derived value (vel_ipc - vel_prev) / dt. However, kernel_step_2 subsequently calls func_implicit_damping, which -- for entities with non-zero dofs_info.damping -- solves acc = M_damped^{-1} * force, overwriting the IPC correction. This means if a user's IPC entity has joint damping enabled, IPC's contact resolution is silently discarded.

I understand this is low-risk in practice (IPC scenes typically use free-floating bodies without joint damping), but there is no validation or documentation of this constraint.

Questions:

1. Is substep_dt == 0 considered unreachable in all configurations? If so, is it worth adding a build-time assertion?
2. Would it be appropriate to add an assertion or warning (either in the coupler's _setup_coupling_config or at the kernel_restore_integrate call site) that damped DOFs are not used with IPC coupling?