Physics Based Animation Toolkit

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

Quick Start • Documentation • Examples • Installation • Contributing

---

🚧 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.

🚀 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

🔧 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
  • Python Installation
  • First Steps
  • C++ Usage
• 📦 Installation
  • From PyPI (Recommended)
  • Building from Source
• 🎨 Gallery
• 📚 Documentation
• 🛠️ Advanced Topics
  • Dependencies
  • CUDA Setup
  • Configuration Options
• 🤝 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 recommend simply updating the library search path, i.e. export LD_LIBRARY_PATH="path/to/driver/folder;path/to/runtime/folder;$LD_LIBRARY_PATH".

MacOS does not support CUDA GPUs.

Our pbatoolkit-gpu prebuilt binaries include PTX, such that program load times will be delayed by JIT compilation on first use. Verify that your NVIDIA GPU supports compute capability at least 7.0. For example, only RTX 2060 up to 4090 chips are supported in the GeForce series. Runtime GPU performance may be constrained by the targeted compute capability.

Local

💡 Pro Tip: Familiarize yourself with the CMake documentation before building from source, especially if you're new to CMake!

Consider locally building and installing pbatoolkit against your native GPU for the following reasons.

• Achieve optimal GPU performance for your platform.
• Support older/newer GPUs and CUDA Toolkit versions.

Configuration

Option	Values	Default	Description
PBAT_BUILD_PYTHON_BINDINGS	ON,OFF	OFF	Enable PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit Python bindings. Generates the CMake target PhysicsBasedAnimationToolkit_Python, an extension module for Python, built by this project.
PBAT_BUILD_TESTS	ON,OFF	OFF	Enable PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit unit tests. Generates the CMake target executable PhysicsBasedAnimationToolkit_Tests, built by this project.
PBAT_ENABLE_PROFILER	ON,OFF	`O