Skip to content

[FEATURE] IPC Robot-Cloth Coupling #2352

Merged
duburcqa merged 4 commits intoGenesis-Embodied-AI:mainfrom
Roushelfy:ipc-coupling-pr1
Feb 18, 2026
Merged

[FEATURE] IPC Robot-Cloth Coupling #2352
duburcqa merged 4 commits intoGenesis-Embodied-AI:mainfrom
Roushelfy:ipc-coupling-pr1

Conversation

@alanray-tech
Copy link
Copy Markdown
Contributor

@alanray-tech alanray-tech commented Feb 3, 2026 •
edited
Loading

Description

This PR refactors the IPC (Incremental Potential Contact) coupler implementation from a monolithic single-file structure into a modular package architecture. The main changes include:

  • Code organization: Split genesis/engine/couplers/ipc_coupler.py into a well-organized package structure:

    • genesis/engine/couplers/ipc_coupler/coupler.py: Main IPCCoupler class with core coupling logic
    • genesis/engine/couplers/ipc_coupler/data.py: Data-oriented classes for Taichi field management (IPCTransformData, IPCCouplingData)
    • genesis/engine/couplers/ipc_coupler/utils.py: Stateless utility functions for transform computation, entity categorization, and scene configuration
    • genesis/engine/couplers/ipc_coupler/__init__.py: Module exports

  • Example updates: Updated all IPC examples to work with the new package structure:

    • examples/IPC_Solver/ipc_cloth.py
    • examples/IPC_Solver/ipc_grasp.py
    • examples/IPC_Solver/ipc_arm_cloth.py
    • examples/IPC_Solver/genesis_ipc_motion_test.py
    • Removed examples/IPC_Solver/ipc_twist_cloth_band.py (deprecated example)

  • Asset additions: Added genesis/assets/xml/franka_emika_panda/panda_non_overlap.xml for improved robot model support

  • Configuration updates: Enhanced IPCCouplerOptions in genesis/options/solvers.py with additional configuration parameters

  • Test compatibility: Updated tests/test_ipc.py to work with the new package structure

Motivation and Context

The original IPC coupler implementation was contained in a single thousand-line file, making it difficult to:

  • Navigate and understand the codebase
  • Maintain and debug specific functionality
  • Test individual components in isolation
  • Extend with new features

By organizing the code into a modular package structure with clear separation of concerns:

  • Data management (data.py): Isolated Taichi field definitions and data structures
  • Core logic (coupler.py): Main coupling algorithms and state management
  • Utilities (utils.py): Reusable helper functions that can be tested independently

How Has This Been / Can This Be Tested?

Testing approach:

  1. Unit tests: Run the existing IPC test suite:

    uv run pytest tests/test_ipc.py -v

  2. Example verification: Test all IPC examples to ensure they work with the refactored code:

    # Basic cloth simulation
python examples/IPC_Solver/ipc_cloth.py -v

# Robotic grasping
python examples/IPC_Solver/ipc_grasp.py -v --ipc

# Interactive cloth manipulation
python examples/IPC_Solver/ipc_arm_cloth.py -v --ipc

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.

alanray-tech
alanray-tech commented Feb 3, 2026
View reviewed changes
Comment thread tests/test_ipc.py
Copy link
Copy Markdown
Contributor Author

@alanray-tech alanray-tech Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a test assertion:

The cloth is free falling, so every vertex can be predicted manually.

$$ dx^{n+1} = v^{n} \cdot dt + g \cdot dt^2 $$

and

$$ v^{n+1} = \frac{x^{n+1} - x^{n}}{dt} $$

Check it with proper tolerance.

ACMLCZH
ACMLCZH reviewed Feb 17, 2026
View reviewed changes
Comment thread genesis/engine/couplers/ipc_coupler/coupler.py
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
60bbca2 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
b25ebfd 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
4262298 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
3687400 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
11d0c75 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
83a5375 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
7f763cf 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 17, 2026
@duburcqa @claude
[FEATURE] Integrate IPC coupler via libuipc.
8a94c98 
Add IPCCoupler as a new coupler plugin for Incremental Potential Contact
simulation using libuipc. This enables cloth, FEM, and rigid body contact
resolution through the UIPC engine.

- Add FEM.Cloth thin shell material with thickness and bending_stiffness
- Add IPCCouplerOptions to configure IPC solver parameters
- Add IPCCoupler with zero-copy data transfer to/from UIPC
- Extend rigid solver to use SAP-like velocity/position split for IPC
- Skip FEM solver physics when IPC is active (IPC handles it)
- Add 5 IPC examples: cloth draping, grasping, arm+cloth, cloth band
  twisting, and rigid-FEM contact
- Add IPC unit tests preserving original PR Genesis-Embodied-AI#2352 test scenarios
- Register IPC examples in test_examples.py with uipc dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ACMLCZH
ACMLCZH reviewed Feb 18, 2026
View reviewed changes
Comment thread genesis/options/solvers.py
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 18, 2026
@duburcqa @claude
[WIP] IPC coupler unit tests.
c457a62 
Adapts the original PR Genesis-Embodied-AI#2352 tests to the refactored API plus one additional test:

1. test_ipc_cloth (n_envs=[0, 2]): cloth + rigid (two_way) + FEM ball.
   Per-step kinematic validation (10 steps, 1% tolerance).

2. test_ipc_cloth_gravity_freefall (n_envs=[0]): cloth free-fall, no ground.
   Displacement = 0.5 * g * t^2 over 50 steps (1% tolerance).

3. test_ipc_two_way_revolute (n_envs=[0]): revolute URDF robot, 100 steps,
   sinusoidal joint target. Checks Genesis ↔ IPC transform consistency
   when coupler exposes abd_data_by_link (< 1 mm pos, < 0.1 rad rot).

4. test_ipc_two_way_prismatic (n_envs=[0]): same as above for prismatic joint.

5. test_ipc_rigid_fem_contact (n_envs=[0, 2]): needs_coup=False exclusion
   (box falls through ground) + FEM ball ground contact (no penetration).

API changes applied vs original PR:
- Removed from IPCCouplerOptions: dt, gravity, contact_friction_mu,
  IPC_self_contact, two_way_coupling, disable_genesis_contact, enable_ipc_gui.
- Added enable_abd_self_contact=False where IPC_self_contact=False was used.
- Replaced set_entity_coupling_type() calls with coupling_mode="two_way"
  on Rigid material.
- Replaced _ipc_scene with _scene (coupler attribute name).
- Module-level uipc import via pytest.importorskip.

Code quality: top-level numpy import, shared helpers (_get_cloth_vertex_positions,
_rotmat_to_euler) extracted as module-level functions, fixed f-string print bugs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
duburcqa added a commit to duburcqa/Genesis that referenced this pull request Feb 18, 2026
@duburcqa @claude
[WIP] IPC coupler unit tests.
af25c61 
Adapts the original PR Genesis-Embodied-AI#2352 tests to the refactored API plus one additional test:

1. test_ipc_cloth (n_envs=[0, 2]): cloth + rigid (two_way) + FEM ball.
   Per-step kinematic validation (10 steps, 1% tolerance).

2. test_ipc_cloth_gravity_freefall (n_envs=[0]): cloth free-fall, no ground.
   Displacement = 0.5 * g * t^2 over 50 steps (1% tolerance).

3. test_ipc_two_way_revolute (n_envs=[0]): revolute URDF robot, 100 steps,
   sinusoidal joint target. Checks Genesis ↔ IPC transform consistency
   when coupler exposes abd_data_by_link (< 1 mm pos, < 0.1 rad rot).

4. test_ipc_two_way_prismatic (n_envs=[0]): same as above for prismatic joint.

5. test_ipc_rigid_fem_contact (n_envs=[0, 2]): needs_coup=False exclusion
   (box falls through ground) + FEM ball ground contact (no penetration).

API changes applied vs original PR:
- Removed from IPCCouplerOptions: dt, gravity, contact_friction_mu,
  IPC_self_contact, two_way_coupling, disable_genesis_contact, enable_ipc_gui.
- Added enable_abd_self_contact=False where IPC_self_contact=False was used.
- Replaced set_entity_coupling_type() calls with coupling_mode="two_way"
  on Rigid material.
- Replaced _ipc_scene with _scene (coupler attribute name).
- Module-level uipc import via pytest.importorskip.

Code quality: top-level numpy import, shared helpers (_get_cloth_vertex_positions,
_rotmat_to_euler) extracted as module-level functions, fixed f-string print bugs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Feb 18, 2026

🔴 Benchmark Regression Detected ➡️ Report

@duburcqa duburcqa merged commit 0812e83 into Genesis-Embodied-AI:main Feb 18, 2026
4 checks passed
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Feb 18, 2026

⚠️ Abnormal Benchmark Result Detected ➡️ Report

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ACMLCZH ACMLCZH ACMLCZH left review comments

@YilingQiao YilingQiao Awaiting requested review from YilingQiao YilingQiao is a code owner

@duburcqa duburcqa Awaiting requested review from duburcqa duburcqa is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@alanray-tech @ACMLCZH @duburcqa @Roushelfy