A flexible C++20 library for physics-based simulation
Quick Start • Documentation • Examples • Installation • Contributing
⚠️ This library is currently under active developmentWhile 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!
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.
- 🧩 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
|
|
- 🐍 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
masterbranch may contain breaking changes at any point in time. We recommend users to use specific git tags, i.e. viagit checkout v<major>.<minor>.<patch>, where the version<major>.<minor>.<patch>matches the installedpbatoolkit's version downloaded from PyPI (i.e. frompip install pbatoolkit).
- 🎯 What is PBAT?
- ✨ Features
- 🚀 Quick Start
- 📦 Installation
- 🎨 Gallery
- 📚 Documentation
- 🛠️ Advanced Topics
- 🤝 Contributing
- 📄 License
- 📖 Citation
💡 Pro Tip: Install the Tracy profiler to analyze performance and visualize algorithm execution in real-time!
pip install pbatoolkitTry 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)Check out our unit tests!
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-gpuFor 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" -vRefer to scikit-build-core and CMake for more fine-grained build customization.
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
# 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/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
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.
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.
💡 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.
| 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 |
OFF |
Enable Tracy instrumentation profiling in built PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit. |
PBAT_PROFILE_ON_DEMAND |
ON,OFF |
OFF |
Activate Tracy's on-demand profiling when PBAT_ENABLE_PROFILER is ON. |
PBAT_USE_SUITESPARSE |
ON,OFF |
OFF |
Link to user-provided SuiteSparse installation via CMake's find_package. |
PBAT_BUILD_SHARED_LIBS |
ON,OFF |
OFF |
Build project's library targets as shared/dynamic. |
PBAT_USE_CUDA |
ON,OFF |
OFF |
Link to CUDA Toolkit for GPU API. |
PBAT_BUILD_DOC |
ON,OFF |
OFF |
Build project's doxygen documentation. |
Our project provides configuration presets that capture typical use configurations. For the best experience, install vcpkg and set VCPKG_ROOT=path/to/vcpkg as an environment variable. Then, you can select one of our available presets, for example cmake --preset=default. Refer to the CMake presets documentation for more information.
Refer to the corresponding CMake build and install workflows. We recommend writing a customized CMakeUserPresets.json for your development environment.
| Target | Description |
|---|---|
PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit |
The PBA Toolkit library. |
PhysicsBasedAnimationToolkit_Tests |
The test executable, using doctest. |
PhysicsBasedAnimationToolkit_Python |
PBAT's Python extension module, using nanobind. |
PhysicsBasedAnimationToolkit_Docs |
Documentation. |
For a local installation, which builds from source, our Python bindings build relies on scikit-build-core, which in turn relies on CMake's install mechanism. As such, you can configure the installation as you typically would when using the CMake CLI directly, by now passing the corresponding CMake arguments in pip's config-settings parameter (refer to the scikit-build-core documentation for the relevant parameters). See our pyinstall workflow for working examples of building from source on Linux, MacOS and Windows. Then, assuming that external dependencies are found via CMake's find_package, you can build and install our Python package pbatoolkit locally and get the most up to date features.
💡 Pro Tip: Consider using a Python virtual environment for this step.
As an example, assuming use of vcpkg for external dependency management with VCPKG_ROOT=path/to/vcpkg set as an environment variable, run
pip install . --config-settings=cmake.args="--preset=pip-cuda" -von the command line to build pbatoolkit from source with GPU algorithms included. Additional environment variables (i.e. CUDA_PATH) and/or CMake variables (i.e. CMAKE_CUDA_COMPILER) may be required to be set in order for CMake to correctly discover and compile against your targeted local CUDA installation. Refer to the CMake documentation for more details.
See PBAT in action! These examples showcase what's possible with just a few lines of code. Full source code available in python/examples/.
Our GPU implementation of the eXtended Position Based Dynamics (XPBD) algorithm simulates a ~324k element FEM elastic mesh interactively with contact.
Combining pbatoolkit's FEM+elasticity features and the IPC Toolkit results in guaranteed inter-penetration free contact dynamics between deformable bodies.
The hyper elastic beam's representative deformation modes, i.e. its low frequency eigen vectors, are animated as time continuous signals.
Real-time collision detection between 2 large scale meshes (~324k tetrahedra) is accelerated by highly parallel implementations of the sweep and prune algorithm, or linear bounding volume hierarchies.
A smooth (harmonic) function is constructed on Entei, required to evaluate to 1 on its paws, and 0 at the top of its tail, using piece-wise linear (left) and quadratic (right) shape functions. Its isolines are displayed as black curves.
Approximate geodesic distances are computed from the top center vertex of Metagross by diffusing heat from it (left), and recovering a function whose gradient matches the normalized heat's negative gradient. Its isolines are displayed as black curves.
Fine details of Godzilla's skin are smoothed out by diffusing x,y,z coordinates in time.
Computation details are gathered when using pbatoolkit and consulted in the Tracy profiling server GUI.
We welcome contributions from the community! Here's how you can help:
- Use our issue tracker to report bugs
- Include detailed reproduction steps and system information
- Check existing issues to avoid duplicates
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Follow our coding standards (see below)
- Add tests for new functionality
- Commit your changes (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
- We use clang-format for consistent code styling
- Configuration provided in
.clang-formatat repository root - Run
clang-formatbefore committing (VS Code/Visual Studio have built-in support) - Follow modern C++20 best practices
- Add comprehensive tests for new features
# Clone your fork
git clone https://github.com/YOUR_USERNAME/PhysicsBasedAnimationToolkit.git
cd PhysicsBasedAnimationToolkit
# Set up dependencies (requires vcpkg)
export VCPKG_ROOT=/path/to/vcpkg
# Build with tests enabled
cmake --preset=dev --log-level=verbose
cmake --build build --target PhysicsBasedAnimationToolkit_TestsThis project is licensed under the MIT License - see the LICENSE file for details.
If you use PBAT in your research, please cite:
@software{pbat2024,
title={Physics Based Animation Toolkit},
author={Ton-That, Quoc-Minh},
url={https://github.com/Q-Minh/PhysicsBasedAnimationToolkit},
version={0.0.1},
year={2024}
}