libuipc

A Cross-Platform Modern C++20 Library of Unified Incremental Potential Contact — both C++ and Python APIs.

Website ➡️ spirimirror.github.io/libuipc-web ・ Samples ➡️ github.com/spiriMirror/libuipc-samples

Libuipc is a GPU-accelerated simulation library built around a unified Incremental Potential Contact framework. It couples rigid bodies (affine body dynamics), soft bodies (FEM), cloth, and threads in one scene with accurate, penetration-free frictional contact, and is designed to be naturally differentiable for ML, inverse dynamics, and robotics workflows. The whole pipeline — collision detection, contact assembly, and a fused-PCG linear solver with CUDA-graph replay and an optional MAS preconditioner — runs on the GPU.

We are actively developing Libuipc. Feedback and contributions are welcome!

Table of Contents

• libuipc
  • Table of Contents
  • What is libuipc?
    • Why libuipc
  • Catalogue
    • Stiff-GIPC Benchmark Suite (88–93)
    • Robotics
    • FEM & Cloth
    • Rigid Bodies, Joints & Coupling
  • Installation
    • Python (PyPI)
    • From Source
  • Quick Start (Python)
  • Contributing & Support
  • News
  • License & Acknowledgments
  • Citation

What is libuipc?

libuipc is organized in three layers: a friendly scene API on top, a reusable simulation core in the middle, and a fully-parallel CUDA backend underneath.

• Simulation Interface — Python and C++ APIs for building scenes: geometry IO (OBJ/MSH/URDF/glTF), constitutions (SNK elasticity, Baraff-Witkin cloth, shell bending, ABD affine bodies, joint systems), contact tabulars, animation scripting, and a Polyscope-based GUI.
• Simulation Core — scene/world/engine abstractions with the incremental-potential Newton solver: implicit time integration, line search with continuous collision detection, frictional contact with scene-adaptive tolerances, and a scene-adaptive kappa corridor.
• CUDA Backend — GPU PCG linear solver with StiffGIPC MAS (Multi-Level Additive Schwarz) preconditioner, stackless-BVH collision detection, and per-constitution GPU kernels — all running without CPU round-trips in the solver loop.

Why libuipc

• Easy & Powerful: an intuitive, unified way to create and drive vivid simulation scenes; objects and constraints compose freely.
• Fast & Robust: fully GPU-parallel, with Stiff-GIPC-grade numerics and a contact model that stays penetration-free under stiff, frictional, coupled scenarios.
• High Flexibility: Python and C++ APIs, Linux and Windows, PyPI wheels and source builds.
• Fully Differentiable: differentiable simulation APIs for backward optimization (Diff-Sim, coming soon).

Catalogue

Runnable examples live in libuipc-samples/examples/ — each is a self-contained main.py with a GUI (run/stop) and most support --headless [N] benchmarking. Highlights:

Stiff-GIPC Benchmark Suite (88–93)

The reproducible headless cross-domain registry and current machine-specific reference are documented in Testing and Benchmarks.

• 88: set_case2
• 89: set_case7
• 90: set_case1
• 91: set_case4
• 92: set_case5
• 93: set_case6

Robotics

• 87: robot hand (URDF links + soft constraints + ABD cube)

FEM & Cloth

• 3: periodically pressed tetrahedron
• 11: bunny + cloth
• 23: Kirchhoff rod bending
• 24: sewing pattern
• 34: cloth stack
• 36: vertex stitch family

Rigid Bodies, Joints & Coupling

• 2: walking cube
• 6: wrecking balls
• 10: ramp sliding
• 12: soft transform constraint
• 17: revolute joint
• 18: pendulum joint

Installation

Python (PyPI)

pip install pyuipc

The release pipeline builds Windows / Linux, Python 3.10–3.14 wheels with CUDA 12.8. Wheels built from the current source carry the CUDA runtime code they use and require a compatible NVIDIA driver, not a locally installed CUDA Toolkit. For GPUs served by a packaged SASS image, the driver floor is 525.60.13 on Linux and 528.33 on Windows; newer CUDA 13 drivers remain backward compatible under NVIDIA's CUDA compatibility model. Those are the CUDA 12.x minor-compatibility floors when the GPU selects a packaged SASS image. A GPU that must JIT the packaged CUDA 12.8 PTX requires at least driver 570.124.06 on Linux or 572.61 on Windows.

The immutable 0.0.27 wheel still dynamically loads cublas64_12.dll. Install CUDA 12.8 side-by-side when using that release on a CUDA 13-only machine, or use a source build until the next wheel release removes the dependency.

New wheels contain native code for compute capabilities 7.5, 8.0, 8.6, 8.9, and 12.0, plus compute-8.9 PTX for forward JIT on other newer GPUs. The doctor distinguishes a selected native SASS image from the PTX path and applies the matching driver floor. Diagnose an installation before running a scene:

python -m uipc doctor
python -m uipc doctor --probe-cuda

From Source

Prerequisites: CMake ≥ 3.26, Python ≥ 3.11, CUDA ≥ 12.4, and vcpkg (XMake ≥ 3.0.5 if you prefer that build path).

# 1) vcpkg (once): clone + bootstrap, then point CMake at the toolchain
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg && ./bootstrap-vcpkg.bat   # Linux: ./bootstrap-vcpkg.sh
# set CMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake

# 2) clone (samples come along as a submodule)
git clone https://github.com/spiriMirror/libuipc.git --recurse-submodules
cd libuipc && mkdir build && cd build

# 3) configure + build (NVCC is slow — use all cores)
cmake -S .. -DUIPC_BUILD_PYBIND=1
cmake --build . --config Release -j8   # Linux: add -DCMAKE_BUILD_TYPE=Release

With UIPC_BUILD_PYBIND=ON, the Python binding is built and installed into the active Python environment. If the install step fails, finish it manually with cd build/python && pip install .; to target a specific venv, pass -DUIPC_PYTHON_EXECUTABLE_PATH=<python.exe>.

On Linux, a conda environment is recommended: conda env create -f conda/env.yaml && conda activate uipc_env, then conda env config vars set CMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake before the build commands above.

XMake alternative: xmake f -c && xmake build -j8 (Python binding: xmake f --pybind=true --python_system=true --python_version=3.11.x -c).

Check the install: cd python && python uipc_info.py.

Full guide (incl. Docker and CUDA/driver compatibility notes): Build & Install. For the samples' uv-based workflow, see the libuipc-samples README.

Quick Start (Python)

from uipc.core import Engine, World, Scene
from uipc.geometry import SimplicialComplexIO, ground, label_surface, label_triangle_orient, flip_inward_triangles
from uipc.constitution import StableNeoHookean, ElasticModuli

engine = Engine("cuda", "output")
world  = World(engine)
scene  = Scene(Scene.default_config())
scene.contact_tabular().default_model(0.2, 1e8)

mesh = SimplicialComplexIO().read("bunny.msh")
label_surface(mesh)
label_triangle_orient(mesh)
mesh = flip_inward_triangles(mesh)
StableNeoHookean().apply_to(mesh, ElasticModuli.youngs_poisson(1e6, 0.49), mass_density=1e3)

scene.objects().create("bunny").geometries().create(mesh)
scene.objects().create("ground").geometries().create(ground(-1.0))

world.init(scene)
for _ in range(100):
    world.advance()
    world.retrieve()

Optional: enable the MAS preconditioner for stiff FEM scenes with one config line — config["linear_system"]["fem_preconditioner"] = "mas".

Inspect the validated configuration contract (defaults, units, ranges, selectors, lifecycle, and backend consumers) with python -m uipc config-schema, or read the Scene Configuration Reference.

Contributing & Support

• Bugs & features: file an Issue; questions and ideas go to Discussions.
• Pull requests are welcome — CI runs the full simulation suite, please keep it green.
• For maintainers: .cursor/ holds AI-assisted build/test/commit/PR commands and style rules; agent_docs/ documents the architecture.

News

2026-8-24: We preliminarily optimized the CUDA backend, improving the framework's simulation performance across the board — and Libuipc v1.0 will be ready soon!

2026-3-29: Thanks Genesis AI for contributing AL-IPC (Augmented Lagrangian IPC) integration, a Minimal Coordinate Articulated Joint System (ExternalArticulationConstraint) for affine bodies, and the CIBuildWheel cross-platform PyPI packaging pipeline.

2026-2-13: Cursor AI-assisted development support — see .cursor/ for built-in commands and rules.

2026-2-7: pip install pyuipc on PyPI (Win/Linux, Python 3.10–3.13, CUDA 12.8).

2025-11-01: The prototype implementation of Libuipc was open-sourced (Stiff-GIPC) as our performance benchmark reference.

2025-5-23: StiffGIPC presented at SIGGRAPH 2025.

2024-11-25: Libuipc v0.9.0 (Alpha) published — feedback welcome via Issues and PRs!

License & Acknowledgments

libuipc is released under the Apache License 2.0 (see LICENSE).

This project is led by Kemeng Huang and Professor Taku Komura (The University of Hong Kong), in collaboration with Professor Minchen Li (Carnegie Mellon University), with comprehensive support from TransGP. It builds upon the GPU IPC project, originally developed and continuously optimized by Kemeng Huang. We also thank the many open-source contributors, with special thanks to Xinyu Lu, who initially worked with us at TransGP and helped a lot in this project.

Citation

If you use Libuipc in your project, please cite our works:

@article{stiffgipc2025,
      author = {Huang, Kemeng and Lu, Xinyu and Lin, Huancheng and Komura, Taku and Li, Minchen},
      title = {StiffGIPC: Advancing GPU IPC for Stiff Affine-Deformable Simulation},
      year = {2025},
      publisher = {Association for Computing Machinery},
      volume = {44},
      number = {3},
      issn = {0730-0301},
      doi = {10.1145/3735126},
      journal = {ACM Trans. Graph.},
      month = may,
      articleno = {31},
      numpages = {20}
}

@article{gipc2024,
      author = {Huang, Kemeng and Chitalu, Floyd M. and Lin, Huancheng and Komura, Taku},
      title = {GIPC: Fast and Stable Gauss-Newton Optimization of IPC Barrier Energy},
      year = {2024},
      publisher = {Association for Computing Machinery},
      volume = {43},
      number = {2},
      issn = {0730-0301},
      doi = {10.1145/3643028},
      journal = {ACM Trans. Graph.},
      month = {mar},
      articleno = {23},
      numpages = {18}
}