[BUG FIX] Refine IPC Coupling Logic

examples/IPC_Solver/ipc_objects_falling.py

@@ -36,7 +36,12 @@ def main():
     )
 
     # Ground plane
-    scene.add_entity(gs.morphs.Plane())
+    scene.add_entity(
+        gs.morphs.Plane(),
+        material=gs.materials.Rigid(
+            coup_type="ipc_only",
+        ),
+    )
 
     # Cloth using Cloth material
     # Note: Using coarse grid mesh to avoid IPC thickness violations

examples/IPC_Solver/ipc_robot_cloth_teleop.py

@@ -39,6 +39,7 @@ def main():
         default="two_way_soft_constraint",
         choices=["two_way_soft_constraint", "external_articulation"],
     )
+    parser.add_argument("--vis_ipc", action="store_true", default=False, help="Show IPC GUI")
     args = parser.parse_args()
 
     scene = gs.Scene(
@@ -58,6 +59,7 @@ def main():
             enable_rigid_rigid_contact=True,
             contact_d_hat=0.001,
             contact_resistance=1e7,
+            _show_ipc_gui=args.vis_ipc,
         ),
         viewer_options=gs.options.ViewerOptions(
             camera_pos=(2.0, -1.0, 1.5),
@@ -68,7 +70,12 @@ def main():
     )
 
     # Add flat floor
-    scene.add_entity(gs.morphs.Plane())
+    scene.add_entity(
+        gs.morphs.Plane(),
+        material=gs.materials.Rigid(
+            coup_type="ipc_only",
+        ),
+    )
 
     # Add Franka robot
     franka_material_kwargs = dict(

examples/IPC_Solver/ipc_robot_grasp_cube.py

@@ -40,7 +40,12 @@ def main():
         show_viewer=args.vis,
     )
 
-    scene.add_entity(gs.morphs.Plane())
+    scene.add_entity(
+        gs.morphs.Plane(),
+        material=gs.materials.Rigid(
+            coup_type="ipc_only",
+        ),
+    )
 
     franka_material_kwargs = dict(
         coup_friction=0.8,
@@ -85,9 +90,9 @@ def main():
     franka.set_dofs_kp([4500.0, 4500.0, 3500.0, 3500.0, 2000.0, 2000.0, 2000.0, 500.0, 500.0])
 
     qpos = franka.inverse_kinematics(link=end_effector, pos=[0.65, 0.0, 0.4], quat=[0.0, 1.0, 0.0, 0.0])
+    qpos[fingers_dof] = 0.04
     if not args.no_ipc or args.coup_type == "external_articulation":
-        franka.control_dofs_position(qpos[motors_dof], dofs_idx_local=motors_dof)
-        franka.control_dofs_position(0.04, dofs_idx_local=fingers_dof)
+        franka.control_dofs_position(qpos)
         for _ in range(200 if "PYTEST_VERSION" not in os.environ else 1):
             scene.step()
     else:

genesis/engine/couplers/ipc_coupler/data.py

@@ -39,14 +39,13 @@ class ArticulatedEntityData:
 
     articulation_slots: list[GeometrySlot]
 
-    ref_dof_prev: np.ndarray
     qpos_stored: np.ndarray
     qpos_current: np.ndarray
     qpos_new: np.ndarray
     delta_theta_tilde: np.ndarray
     delta_theta_ipc: np.ndarray
 
-    # Previous timestep link transforms for ref_dof_prev computation {(joint, env_idx): transform_matrix_4x4}
+    # Previous timestep link transforms for IPC ABD ref_dof_prev sync {(joint, env_idx): transform_matrix_4x4}
     prev_links_transform: list[list[np.ndarray | None]]
 
 

genesis/engine/couplers/ipc_coupler/utils.py

@@ -34,9 +34,8 @@ def find_target_link_for_fixed_merge(link):
         if link.parent_idx < 0:
             break
 
-        # Check if there is any non-fixed joint
+        # Stop if the link has any non-fixed joint (non-fixed joints define separate bodies)
         if any(joint.type != gs.JOINT_TYPE.FIXED for joint in link.joints):
-            # Found a link with non-FIXED joint, this is our target
             break
 
         # All joints are FIXED, move up to parent

genesis/engine/entities/rigid_entity/rigid_entity.py

@@ -3321,10 +3321,11 @@ def set_qpos(self, qpos, qs_idx_local=None, envs_idx=None, *, zero_velocity=True
         """
         from genesis.engine.couplers import IPCCoupler
 
-        if isinstance(self.sim.coupler, IPCCoupler) and self.material.coup_type == "external_articulation":
-            gs.raise_exception("This method is not supported by `RigidMaterial.coup_type='external_articulation'`.")
         super().set_qpos(qpos, qs_idx_local, envs_idx, zero_velocity=zero_velocity, skip_forward=skip_forward)
 
+        if isinstance(self.sim.coupler, IPCCoupler):
+            self.sim.coupler.set_qpos_changed(self)
+
     @gs.assert_built
     def set_dofs_kp(self, kp, dofs_idx_local=None, envs_idx=None):
         """
@@ -3446,10 +3447,11 @@ def set_dofs_position(self, position, dofs_idx_local=None, envs_idx=None, *, zer
         """
         from genesis.engine.couplers import IPCCoupler
 
-        if isinstance(self.sim.coupler, IPCCoupler) and self.material.coup_type == "external_articulation":
-            gs.raise_exception("This method is not supported by `RigidMaterial.coup_type='external_articulation'`.")
         super().set_dofs_position(position, dofs_idx_local, envs_idx, zero_velocity=zero_velocity)
 
+        if isinstance(self.sim.coupler, IPCCoupler):
+            self.sim.coupler.set_qpos_changed(self)
+
     # ------------------------------------------------------------------------------------
     # ---------------------------------- PD control --------------------------------------
     # ------------------------------------------------------------------------------------

genesis/engine/materials/rigid.py

@@ -36,14 +36,12 @@ class Rigid(Kinematic):
             Compensation factor for gravity. 1.0 cancels gravity. Default is 0.
         coup_type : str or None, optional
             Coupling mode for this entity. Only used by the IPC coupler. Requires ``needs_coup=True``.
-            If None, auto-selected based on entity type: ``'external_articulation'`` for fixed-base
-            articulated robots, ``'two_way_soft_constraint'`` for floating-base robots, and
-            ``'ipc_only'`` for non-articulated objects. Valid values:
+            Must be explicitly set when ``needs_coup=True``. Valid values:
               - 'two_way_soft_constraint': Two-way soft coupling.
               - 'external_articulation': Joint-level coupling for articulated bodies. Joint positions will be coupled at
                 the DOF level.
-              - 'ipc_only': IPC controls entity, transforms copied to Genesis (one-way). Only supported by rigid
-                non-articulated objects.
+              - 'ipc_only': IPC controls entity, transforms copied to Genesis (one-way). Not supported for
+                entities with constrained joints (revolute, prismatic, etc.).
             Default is None.
         coup_links : tuple of str or None, optional
             Tuple of link names to include in coupling. When set, only the named links participate