commensurability: a Python package for classifying astronomical orbits based on their toroid volume

Abstract

As a star orbits the center of its host galaxy, the trajectory is encompassed within a 3D toroid. The orbit probes all points in this toroid, unless its orbital frequencies exhibit integer ratios (commensurate frequencies), in which case a small sub-volume is traversed. commensurability is a Python package that implements a tessellation-based algorithm for identifying orbital families that satisfy commensurabilities by measuring the toroid volume traversed over orbit integration. Compared to standard orbit classification methods such as frequency analysis, tessellation analysis relies on configuration space properties alone, making classification results more robust to frequency instabilities or limited integration times. The package provides a framework for analyzing phase-space coordinates using tessellation analysis, including a subpackage for the implementation of the general tessellation algorithm. The package is to be used with a galactic dynamics library; it currently supports AGAMA, gala, and galpy.