Mayawaves: Python Library for Interacting with the Einstein Toolkit and the MAYA Catalog

Numerical relativity simulations are crucial for studying black holes and have been instrumental in the detection of gravitational waves by the LVK. However, these simulations produce vast amounts of data that must be processed in order to perform studies, create models, and use them with gravitational wave detection pipelines. This paper introduces mayawaves, an open-source python library for processing, studying, and exporting numerical relativity simulations performed using the Einstein Toolkit and MAYA. Mayawaves streamlines the process of analyzing simulations with an intuitive interface, greatly reducing the learning curve for numerical relativity.

While analytic solutions exist for the simplest cases within GR, e.g.single BHs, merging BBHs have no analytic solution.Approximate methods can be used when the BHs are far apart or have highly unequal masses, but the coalescence of BHs of comparable mass must be solved computationally.Numerical relativity (NR) simulations accomplish this by evolving a BBH space-time on supercomputers, enabling us to study the dynamics of BBH systems as well as predict the GWs they emit.The Einstein Toolkit (ETK) is a set of tools created to perform these NR simulations (Löffler et al., 2012), and MAYA is a branch of ETK used by the MAYA collaboration (Ferguson et al., 2023;Healy et al., 2009;Herrmann et al., 2007;Jani et al., 2016;Pekowsky et al., 2013;Vaishnav et al., 2007).The Einstein Toolkit is a finite-differencing code, evolved using the BSSN formulation (Baumgarte & Shapiro, 1998;Shibata & Nakamura, 1995).It is built upon the Cactus infrastructure (Goodale et al., 2003) with Carpet mesh refinement (Schnetter et al., 2004).
These tools allow us to study the coalescence of compact objects, their evolution, and the gravitational radiation they emit.The Mayawaves library introduced in this paper is an analysis pipeline used to process and analyze such NR simulations, specifically for BBHs.

Statement of need
NR simulations are crucial for studying BHs and have been instrumental in the detection of GWs by the LVK.However, these simulations produce vast amounts of data that must be processed in order to perform studies, create models, and use them with GW detection pipelines.Additionally, given the complexity of these simulations, they are typically performed for many days or weeks across many processors, leading to data which is split into several output directories and files.Sifting through all this data can be overwhelming for newcomers to the field and is cumbersome for even the most experienced numerical relativists.While it can be important to develop an understanding of these files and their complexities, in many situations, a simpler, more streamlined workflow is beneficial.
Mayawaves is an open-source Python library for processing, studying, and exporting NR simulations performed using ETK and MAYA.While other tools exist to analyze ETK simulations including, but not limited to, Kuibit (Bozzola, 2021), POWER (Johnson et al., 2017), PyCactus (Kastaun, 2021), and SimulationTools (Hinder & Wardell, n.d.), Mayawaves is unique in the way it not only streamlines simulation analysis but also the production of NR catalogs.Mayawaves builds upon the existing set of tools, creating a new Python library designed for convenience and intuition, while still being versatile and powerful enough to perform more complex analyses.It interacts effortlessly with the MAYA waveform catalog and also easily exports ETK simulations to the LVK catalog of NR waveforms.The architecture of Mayawaves is easily extensible, designed to naturally grow to encompass more types of simulation output.One of the ways in which Mayawaves has uniquely improved the NR analysis infrastructure is that it stitches together raw NR simulations and stores them in HDF5 files, a format that handles numerical data more efficiently than ASCII.This significantly reduces the disc space taken by simulations while still retaining the precision of the raw data.By preprocessing the simulations into this format, the library also reduces computational time for future analysis, as the data only has to be stitched once.It also keeps all the data organized in one place, making it easier to share and distribute simulations.
When using the library to interact with a simulation, the user does not need to be familiar with all the types of output files generated by the simulation, but rather, can think in terms of physical concepts such as coalescences and compact objects.This dramatically reduces the barrier to entry for the field of NR.Some of the key functionalities of this library are as follows: • read and stitch raw NR data • store NR data in a more efficient format • track properties of the BHs (trajectories, spins, masses, horizon information, etc.) • compute information about the binary orbit (eccentricity, separation, orbital frequency, kick, etc.) • compute quantities pertaining to the gravitational radiation (Ψ 4 , strain, extrapolated strain, energy radiated, etc.) • export NR data to the format required for LIGO analyses • analyze the MAYA waveform catalog The Coalescence class is the fundamental basis for Mayawaves.It represents the entirety of the BBH coalescence and serves as the interface between the user and the simulation data.The main data format used with mayawaves is an HDF5 file constructed from the raw simulation data.With this HDF5 file in hand, the user need only create a Coalescence object and then proceed with analyzing the data.
Each Coalescence object contains CompactObjects associated with each of the merging bodies as well as any remnant object.Through these CompactObjects, the user can track the objects' positions, spins, masses, etc.All radiative information is stored within the RadiationBundle class.Each Coalescence object contains a RadiationBundle and uses it to compute GW strain, energy radiated, etc.
A number of utility modules are included to create effortless workflows that can move from raw simulations to community standard formats.A typical workflow would be to use the PostProcessingUtils functions to create the HDF5 file from the raw simulation data, use the Coalescence class to read that HDF5 file and analyze the simulation, and finally export the Coalescence object to another format such as that required by the LVK catalog (Schmidt et al., 2017).
Mayawaves is also the primary way to interact with the MAYA Public Catalog of NR waveforms (Ferguson et al., 2023) hosted at https://cgp.ph.utexas.edu/waveform.The simulations are stored in the Mayawaves HDF5 file format, and can be read using the Coalescence class.Mayawaves has a CatalogUtils module for interacting with the MAYA waveform catalog.This module includes functions for accessing and plotting the metadata for the entire catalog as well as functions to download simulations from the catalog.
Several papers have already been released using the Mayawaves library for their analysis including the Second MAYA Catalog of NR Waveforms (Ferguson et al., 2023), a study of the impact of NR errors on GW parameter estimation (Jan et al., 2023), and a study of the impact of neutron star compactness when a neutron star merges with a BH (Tsao et al., 2024).
Mayawaves is open source and is designed to be easily extensible, and we look forward to additional contributions from the ETK community.