pbatoolkit
Advanced tools
A flexible C++20 library for physics-based simulation
Quick Start • Documentation • Examples • Installation • Contributing
⚠️ 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!
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.
🧮 Finite Element Method
🔷 Geometry Processing
|
🚀 GPU Acceleration
🔍 Spatial Acceleration
|
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).
💡 Pro Tip: Install the Tracy profiler to analyze performance and visualize algorithm execution in real-time!
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)
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-gpu
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.
Full online documentation hosted at q-minh.com/PhysicsBasedAnimationToolkit.
# 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:
Convert surface meshes to volumes using:
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
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.
| 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" -v
on 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:
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature).clang-format at repository rootclang-format before committing (VS Code/Visual Studio have built-in support)# 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_Tests
This 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}
}
FAQs
Physics Based Animation Toolkit
We found that pbatoolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.