Physics Based Animation Toolkit

A flexible C++20 library for physics-based simulation

logo

Quick Start • Documentation • Examples • Installation • Contributing

</div>

entei

🚧 Development Notice

⚠️ This library is currently under active development

While the core functionality is working and the library is usable, we are actively working towards a stable release with comprehensive documentation. Expect the following improvements in the coming months:

📚 Much better documentation with detailed examples and tutorials

🔧 API stabilization and improved user experience

We appreciate your patience as we work to deliver a polished, well-documented library!

🎯 What is PBAT?

PBAT (Physics Based Animation Toolkit) is a flexible, cross-platform C++20 library that exposes the fundamental building blocks of physically-based simulation. Rather than hiding implementation details behind black-box APIs, PBAT gives researchers and developers direct access to core algorithms, enabling rapid prototyping of new techniques while maintaining the flexibility to customize and extend simulation frameworks.

Why PBAT?

🧩 Modular Building Blocks: Direct access to core algorithms without abstraction layers enabling interoperability with existing ecosystem
🔬 Research Expressivity: Expose implementation details to enable novel research directions
🐍 Rapid Prototyping: Python integration for quick iteration and experimentation

✨ Features

🧮 Finite Element Method

Multi-dimensional support: 1D, 2D, 3D simulations
Lagrange shape functions of order 1-3
Element types: Lines, triangles, quads, tetrahedra, hexahedra
Polynomial quadrature rules for accurate integration

🔷 Geometry Processing

Mesh repair, refinement, simplification, remeshing, boundary extraction, cage generation, partitioning, tetrahedralization, file format conversion
SDF editing, querying and root-finding and optimization.

</td> <td width="50%">

🚀 GPU Acceleration

Vertex Block Descent (VBD) for real-time dynamics
eXtended Position Based Dynamics (XPBD) solver
Broad-phase collision detection with Sweep and Prune
Linear BVH for spatial queries

🔍 Spatial Acceleration

Bounding Volume Hierarchies (BVH)
(Hierarchical) Hash Grids
Nearest Neighbor search
Overlap querying

</td> </tr> </table>

🔧 Additional Features

🐍 Python bindings with NumPy integration
📊 Tracy profiler integration for performance analysis
🏗️ Cross-platform support (Windows, Linux, macOS)
⚙️ Template-based design for algorithmic flexibility and specialization

Currently, the master branch may contain breaking changes at any point in time. We recommend users to use specific git tags, i.e. via git checkout v<major>.<minor>.<patch>, where the version <major>.<minor>.<patch> matches the installed pbatoolkit's version downloaded from PyPI (i.e. from pip install pbatoolkit).

📋 Table of Contents

🎯 What is PBAT?
✨ Features
🚀 Quick Start
📦 Installation
- From PyPI (Recommended)
- Building from Source
🎨 Gallery
📚 Documentation
🛠️ Advanced Topics
🤝 Contributing
📄 License
📖 Citation

🚀 Quick Start

💡 Pro Tip: Install the Tracy profiler to analyze performance and visualize algorithm execution in real-time!

Python

pip install pbatoolkit

Try this simple example to verify your installation:

from pbatoolkit import pbat
import numpy as np

# Create a simple tetrahedral mesh
V = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0], 
    [0.0, 1.0, 0.0],
    [0.0, 0.0, 1.0]
])
C = np.array([[0, 1, 2, 3]])

# Create a finite element mesh
element = pbat.fem.Element.Tetrahedron
order = 1
mesh = pbat.fem.mesh(V.T, C.T, element=element, order=order)

# Explore available modules
help(pbat)

C++

Check out our unit tests!

📦 Installation

From PyPI (Recommended)

The easiest way to get started is via pip:

# CPU-only version (lighter, good for getting started)
pip install pbatoolkit

# GPU-accelerated version (requires CUDA, see CUDA Setup below)
pip install pbatoolkit-gpu

Building from Source

For the latest features or custom configurations:

# Clone the repository
git clone https://github.com/Q-Minh/PhysicsBasedAnimationToolkit.git
cd PhysicsBasedAnimationToolkit

# TODO: Install dependencies ...

# Build and install
pip install . --config-settings=cmake.args="--preset=pip" --config-settings=build.tool-args="-j 4" --config-settings=cmake.build-type="Release" -v

Refer to scikit-build-core and CMake for more fine-grained build customization.

📚 Documentation

Full online documentation hosted at q-minh.com/PhysicsBasedAnimationToolkit.

📁 Python Demos: Ready-to-run scripts with detailed documentation
📖 Tutorials: Step-by-step guides for physics-based animation
🧪 Unit Tests: Check out unit tests in source files for C++ usage patterns

Running Examples

# Install example dependencies
pip install -r python/examples/requirements.txt

# Display help menu of one of the examples
python -m python.examples.vbd -h

# See all available examples
ls python/examples/

Mesh Resources

Need test meshes? Here are some great sources:

🔺 Thingi10K: Large collection of 3D models
🎨 TurboSquid Free: High-quality free models
🛠️ Blender: Create your own meshes

Convert surface meshes to volumes using:

TetWild: Robust tetrahedral meshing
fTetWild: Fast TetWild variant
TetGen: Classic tetrahedral mesh generator

🛠️ Advanced Topics

Dependencies

See vcpkg.json for a complete list of external dependencies. We recommend using vcpkg for dependency management, though any dependency discoverable by CMake's find_package will work.

CUDA Setup

For PyPI Installation

pbatoolkit-gpu (downloaded from PyPI) requires dynamically linking to an instance of the

CUDA 12 Runtime library, and your
CUDA Driver.

Recall that the CUDA Runtime is ABI compatible up to major version.

On 64-bit Windows, these are cudart64_12.dll and nvcuda.dll. Ensure that they are discoverable via Windows' DLL search order. We recommend adding <drive>:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.<minor>\bin (i.e. the binary folder of your CUDA Toolkit installation) to the PATH environment variable. The driver should already be on the search path by default after installation.

On Linux, they are libcudart.so.12 and libcuda.so.1. Ensure that they are discoverable via Linux's dynamic linker/loader. If they are not already in a default search path, we re

PhysicsBasedAnimationToolkit

Install / Use

README