pbatoolkit 0.0.2

Physics Based Animation Toolkit

Physics Based Animation Toolkit

We recommend exploring the official CMake documentation to beginner CMake users.

Overview

The Physics Based Animation Toolkit (PBAT) is a (mostly templated) cross-platform C++20 library of algorithms and data structures commonly used in computer graphics research on physically-based simulation in dimensions 1,2,3. For most use cases, we recommend using our library via its Python interface, enabling seamless integration into Python's ecosystem of powerful scientific computing packages.

Our Python bindings are currently not available on MacOS via PyPI.

Dependencies

See vcpkg.json for a versioned list of our dependencies, available via vcpkg (use of vcpkg is not mandatory, as long as dependencies have compatible versions and are discoverable by CMake's find_package mechanism).

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	OFF	Enable Tracy instrumentation profiling in built PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit.
PBAT_USE_INTEL_MKL	ON,OFF	OFF	Link to user-provided Intel MKL installation via CMake's find_package.
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.

Build

Build transparently across platforms using the cmake build CLI.

CMake build targets:

Target	Description
PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit	The PBA Toolkit library.
PhysicsBasedAnimationToolkit_Tests	The test executable, using doctest.
PhysicsBasedAnimationToolkit_Python	PBAT's Python extension module, using pybind11.

Install

From command line:

cd path/to/PhysicsBasedAnimationToolkit
cmake -S . -B build -A x64 -DPBAT_ENABLE_PROFILER:BOOL=ON -DPBAT_BUILD_TESTS:BOOL=ON
cmake --install build --config Release

Quick start

We recommend downloading the Tracy profiler server to analyze execution of PBAT algorithms, available as precompiled executable.

C++

Take a look at the unit tests, found in the library's source (.cpp) files.

Python

To download and install from PyPI, run in command line:

pip install pbatoolkit libigl numpy scipy

To install locally, run in command line:

pip install .

In Python:

import pbatoolkit as pbat, pbatoolkit.fem, igl, numpy as np, scipy as sp
V, C, F = igl.read_mesh("path/to/mesh.mesh")
mesh = pbat.fem.mesh(V.T, C.T, element=pbat.fem.Element.Tetrahedron, order=1)
x = mesh.X.reshape(mesh.X.shape[0]*mesh.X.shape[1], order='f')
detJeM = pbat.fem.jacobian_determinants(mesh, quadrature_order=2)
M = pbat.fem.mass_matrix(mesh, detJeM, rho=1000., dims=3, quadrature_order=2).to_matrix()
detJeU = pbat.fem.jacobian_determinants(mesh, quadrature_order=1)
GNeU = pbat.fem.shape_function_gradients(mesh, quadrature_order=1)
Y = np.full(mesh.E.shape[1], 1e6)
nu = np.full(mesh.E.shape[1], 0.45)
hep = pbat.fem.hyper_elastic_potential(mesh, detJeU, GNeU, Y, nu, psi= pbat.fem.HyperElasticEnergy.StableNeoHookean, quadrature_order=1)
hep.precompute_hessian_sparsity()
hep.compute_element_elasticity(x)
U, gradU, HU = hep.eval(), hep.to_vector(), hep.to_matrix()
l, V = sp.sparse.linalg.eigsh(HU, k=30, M=M, which='SM')

Profiling is also accessible via the Python interface:

import pbatoolkit.profiling
profiler = pbatoolkit.profiling.Profiler()
connected = profiler.wait_for_server_connection(timeout=10)
# Check connected...
for t in range(timesteps):
    profiler.begin_frame("physics")
    # Physics time integration goes here...
    profiler.end_frame("physics")

To profile relevant calls to pbatoolkit functions/methods, connect to python.exe in the Tracy profiler server GUI. All calls to pbat will be profiled on a per-frame basis in the Tracy profiler server GUI.

Use method profile of pbatoolkit.profiling.Profiler to profile code external to PBAT, allowing for an integrated profiling experience while using various scientific computing packages.

def modes_from_stiffness_matrix():
    l, V = sp.sparse.linalg.eigsh(HU, k=30, M=M, which='SM')
profiler.profile("Compute stiffness' low frequency modes", modes_from_stiffness_matrix)

Contributing

Coding style

A .clang-format description file is provided in the repository root which should be used to enforce a uniform coding style throughout the code base using the clang-format tool. Recent versions of Visual Studio Code and Visual Studio should come bundled with a clang-format installation. On Unix-like systems, clang-format can be installed using your favorite package manager.