[BUG FIX] Fix IPC coupler auto-detecting wrong coup_type for Plane entities.

[liminchen]

Description

A Plane entity added to a scene with IPCCouplerOptions(two_way_coupling=True) crashed at scene.build() with:

GenesisException: Plane entity (solver idx=0) has coup_type='1', but only 'ipc_only' is supported for plane geoms.

Root Cause

Primitive morphs (Plane, Box, Sphere, etc.) always create one joint in the rigid entity tree, even when that joint is FIXED (zero DOFs). The auto-detection logic in _setup_coupling_config used entity.n_joints > 0 to identify articulated entities, which incorrectly classified a Plane (1 FIXED joint, 0 DOFs) as external_articulation (enum value 1). PLANE geoms only support ipc_only, triggering the exception.

Fix

Changed entity.n_joints > 0 → entity.n_dofs > 0 in _setup_coupling_config. This correctly distinguishes:

• Fixed entities with no DOFs (Plane, fixed Box, etc.) → ipc_only
• Fixed-base articulated robots (joints with DOFs) → external_articulation
• Free-floating rigid bodies → two_way_soft_constraint

To Reproduce

python examples/IPC_Solver/ipc_objects_falling.py

Crashes before the fix, runs successfully after.

[alanray-tech]

LGTM now, but need an deep investigation into the whole structure

[alanray-tech]

Took a deeper look at the whole coup_type detection path as discussed, and pushed a follow-up commit (2d3bbc6) that keeps the original fix but removes the remaining inconsistency and adds a regression test.

Analysis

The bug is real and the original one-line fix (n_joints > 0 -> n_dofs > 0) is the correct direction. The root cause is not in the coupler semantics but in how the rigid entity tree represents joints:

• Primitive morphs (Plane, Box, Sphere, ...) always keep exactly one base joint: FIXED (n_dofs=0) when fixed=True, otherwise FREE (n_dofs=6). See RigidEntity._load_primitive.
• MJCF/URDF entities instead drop zero-DOF joints from the tree (to align with MuJoCo), see rigid_entity.py:912.

So a Plane ends up with n_joints=1 but n_dofs=0. n_joints therefore cannot express "is articulated", while n_dofs can. I verified this empirically by building a scene with all four entity kinds and printing the raw values before/after build:

entity	n_joints	n_dofs	is_fixed	resolved coup_type
Plane	1	0	True	ipc_only
fixed Box	1	0	True	ipc_only
free Box	1	6	False	two_way_soft_constraint
fixed-base robot	1	1	True	external_articulation

Remaining inconsistency this addresses

Auto-detect and the external_articulation validation both answer the same question ("does this entity have dynamic DOFs?"), but after the original fix they used two different predicates: auto-detect used n_dofs > 0, while the guard a few lines below still used n_joints == 0. That guard has the exact same blind spot: an explicit coup_type="external_articulation" on a fixed primitive (n_joints=1, n_dofs=0) passed the check and then silently built an empty articulation (all its FIXED joints are skipped later).

Changes

• Add has_articulation_dofs(entity) and default_coup_type(entity) to ipc_coupler/utils.py, so the "articulated?" discriminator lives in exactly one place. The "why n_dofs and not n_joints" rationale is documented once, on the util.
• Route auto-detect through default_coup_type and the external_articulation guard through has_articulation_dofs. This also fixes the guard so a fixed primitive explicitly marked external_articulation is now rejected up front instead of building an empty articulation.
• Add test_auto_coup_type_from_dofs: one scene with Plane / fixed Box / free Box / fixed-base robot, asserting the resolved coup_type for each and the underlying n_joints/n_dofs/is_fixed invariants. This fails on main (Plane crashes at build) and passes here.

Verification

Ran on an RTX 5090 (CUDA backend, pyuipc 0.0.25):

• tests/ipc/test_api.py::test_auto_coup_type_from_dofs -> passed
• full tests/ipc/test_api.py -> 12 passed (covers explicit ipc_only / two_way_soft_constraint / external_articulation paths as well)

No new heuristic or workaround was introduced; this only unifies the existing decision into a single predicate.

[alanray-tech]

Approving. After reviewing the whole coup_type detection path, this is a real bug with the correct fix, not a workaround: primitive morphs always keep one FIXED base joint, so n_joints cannot express "is articulated" while n_dofs can. The follow-up unifies the discriminator into a single has_articulation_dofs util (also fixing the sibling n_joints == 0 guard) and adds a regression test covering Plane / fixed Box / free Box / fixed-base robot. Verified locally: full tests/ipc/test_api.py passes (12 tests).