PyMetric: A Geometry Informed Array Mathematics Package

Abstract

PyMetric is a lightweight Python library designed to streamline differential geometry and vector calculus operations in user-defined coordinate systems, with a focus on applications in astrophysics and computational physics. The library was originally created to provide a geometric backend for the Pisces project, an in-development, general purpose astrophysical modeling and initial conditions library, but has since grown into an independent library due to its size and complexity. In many physical modeling tasks, it is both natural and advantageous to work in non-Cartesian coordinate systems that align with the inherent symmetries of the system. These coordinate systems can feature complex geometric structure which makes the explicit handling of differential operations cumbersome, particularly for exotic coordinate systems (e.g., homoeoidal coordinate systems). PyMetric provides a unified abstraction that decouples the underlying coordinate representation from the operations themselves, allowing users to accurately compute gradients, divergences, Laplacians, and related geometric quantities through a consistent, coordinate-system-agnostic interface. The core design of PyMetric relies on a hybrid symbolic-numeric model that balances efficiency, flexibility, and accuracy: symbolic computation, via SymPy, is used to derive key geometric quantities, such as metric tensors, Christoffel symbols, and Jacobians, from a minimal set of coordinate system properties, and these are then converted into efficient NumPy-backed numerical routines computed lazily to avoid unnecessary overhead. PyMetric also provides structured abstractions for grids and field data that can interface with a variety of array backends, including in-memory arrays and HDF5 storage for lazy-loading and chunked computation. By automating core geometric operations across coordinate systems, PyMetric simplifies the development of physics-based modeling software that requires flexible geometric handling, establishing a modern and extensible foundation for geometry-aware computation in Python.

[Download paper here](https://joss.theoj.org/papers/10.21105/joss.08901.pdf) Recommended citation: Diggins, E. C., & Wik, D. R. (2026). PyMetric: A Geometry Informed Array Mathematics Package. _Journal of Open Source Software, 11_(117), 8901.