QuasiLocal Toolkit (qlt): A C++ Library for Quasilocal Angular Momentum Calculations in Numerical Relativity https://github.com/raydperu/quasilocal-toolkit

QuasiLocal Toolkit (qlt): OPEN WORK IN PROGRESS OverviewThe QuasiLocal Toolkit (qlt) is a C++ library for computing quasilocal angular momentum and related quantities in numerical relativity. It implements the mathematical framework presented in the paper "Geometric Vorticity and Quasilocal Angular Momentum Conservation" by Rayan D. Peru. Version 0.1.0 - Initial Release What's ImplementedThe toolkit provides complete implementations of: Core Mathematical Functions:- ✅ Axisymmetric angular momentum: J(r) = (1/3) α(r) r² f(r)- ✅ Axisymmetric surgical flux: ΔJ = (1/3)[α(r₂)r₂²f(r₂) - α(r₁)r₁²f(r₁)]- ✅ Clebsch-Komar angular momentum for general surfaces- ✅ Quasilocal mass (modified Brown-York formalism)- ✅ Surgical flux in general spacetimes- ✅ Vorticity bounds for solution verification- ✅ Zero angular momentum condition testing Grid I/O and Geometry:- ✅ Reading SpEC/SXS HDF5 format- ✅ Reading Einstein Toolkit/Cactus HDF5 and ASCII- ✅ Reading custom CSV data- ✅ 3D grid data structures- ✅ Spherical surface extraction- ✅ Cylindrical surface extraction- ✅ Killing vector generation (rotational, translational, approximate)- ✅ Surface integration (midpoint, trapezoidal, spherical quadrature)- ✅ Volume integration (midpoint, Monte Carlo)- ✅ Coordinate transformations (Cartesian, spherical, cylindrical) Python Bindings:- ✅ Complete Python module structure- ✅ MetricData class exposed- ✅ All submodules created (axisymmetric_j, clebsch_komar, quasilocal_mass, surgical_flux, vorticity_bounds)- ⚠️ Function bindings ready for implementation Build StatusThe library builds successfully on Windows with Visual Studio 2022 and CMake. All core C++ components compile without errors, and example programs run correctly, producing physically meaningful results consistent with Kerr spacetime predictions. Example ResultsTest calculations with Kerr-like data produce:- J(1) = 0.03- J(2) = 0.253- J(3) = 0.882- J(4) = 2.112- J(5) = 4.167- Surgical flux between r=2 and r=4: 1.859 These results match the expected quadratic growth J ∝ r²f(r) for rotating spacetimes. DocumentationA comprehensive user guide is included, covering:- Installation and building- Core library functions- Grid module for real simulation data- Python bindings- Advanced examples (Kerr black hole, binary mergers, neutron stars)- Troubleshooting- Mathematical background Target Audience- Numerical relativists analyzing simulation data- Gravitational wave scientists studying angular momentum loss- Theorists testing conservation laws- Students learning quasilocal formalism- Code developers validating new simulations ApplicationsThe toolkit enables researchers to:- Compute angular momentum profiles J(r) in axisymmetric spacetimes- Track angular momentum during binary black hole mergers- Measure gravitational wave angular momentum flux- Verify vorticity bounds for solution consistency- Test angular momentum conservation laws- Analyze neutron star tidal deformations- Study black hole superradiance Dependencies- C++17 compatible compiler (tested with Visual Studio 2022)- CMake 3.14+- Eigen3 linear algebra library- Python 3.8+ (optional, for bindings)- pybind11 (optional, for bindings)- HDF5 (optional, for simulation I/O) Repositoryhttps://github.com/raydperu/quasilocal-toolkit CitationIf you use this toolkit in your research, please cite: @article{Peru2026, author = {Peru, Rayan D.}, title = {Geometric Vorticity and Quasilocal Angular Momentum Conservation}, year = {2026},} LicenseMIT License Version Historyv0.1.0 (March 2026) - Initial release- Core mathematical functions complete- Grid I/O module complete- Python module structure in place- Comprehensive documentation- Working C++ examples