gw-remnant 0.3.0

Python package to extract remnant black hole properties from gravitational waveforms

gw_remnant

During binary-black-hole (BBH) mergers, energy and momenta are carried away from the binary system as gravitational radiation. Access to the radiated energy and momenta allows us to accurately predict the properties of the remnant black hole.

gw_remnant is an easy-to-use Python package to efficiently extract the remnant mass, remnant spin, peak luminosity and the final kick imparted on the remnant black hole directly from the gravitational radiation.

Documentation: https://tousifislam.github.io/gw_remnant/

Installation

Install from PyPI:

pip install gw_remnant

Install with optional dependencies for waveform surrogates:

pip install gw_remnant[surrogates]

Install from source (development):

git clone https://github.com/tousifislam/gw_remnant.git
cd gw_remnant
pip install -e .[dev]

Requirements

• Python >= 3.8
• numpy >= 1.20.0
• scipy >= 1.7.0
• matplotlib >= 3.3.0
• gwtools
• lal, lalsimulation (optional, for kick velocity in km/s)

Quick Start

import numpy as np
from gw_remnant.gw_remnant_calculator import GWRemnantCalculator

# Provide time array and waveform modes (e.g. from a surrogate model)
# time: 1D array in geometric units (M)
# hdict: dictionary of complex waveform modes, e.g. {(2,2): h22(t), ...}
calc = GWRemnantCalculator(time, hdict, qinput=2.0,
                           spin1_input=[0, 0, 0.5])

# Print summary
calc.print_remnants()

# Access individual properties
props = calc.get_remnant_properties()
print(f"Remnant mass: {props['remnant_mass']:.6f} M")
print(f"Remnant spin: {props['remnant_spin']:.6f}")

# Plot diagnostics (optionally save to file)
calc.plot_mass_energy(save_path='mass_energy.png')

See the Quick Start guide for more details.

Supported Waveform Models

The package includes built-in waveform generators for NRHybSur3dq8, BHPTNRSur1dq1e4, and BHPTNRSur2dq1e3. It can also accept waveforms generated by any other method — see Providing Waveform Data.

Tutorials

Example notebooks are provided in the tutorials/ directory:

• Example with custom waveforms — no surrogate installation required
• Example with default waveforms — uses BHPTNRSur1dq1e4 and NRHybSur3dq8

These are also rendered in the online documentation.

Repository Structure

gw_remnant/
├── gw_remnant/                        # Main package directory
│   ├── __init__.py                    # Package initialization
│   ├── gw_remnant_calculator.py       # Main calculator class
│   ├── gw_waveform_generator.py       # Waveform generation utilities
│   │
│   ├── gw_utils/                      # Utility functions
│   │   ├── __init__.py
│   │   ├── waveform_generator.py      # Waveform generation helpers
│   │   └── gw_plotter.py              # Plotting utilities
│   │
│   └── remnant_calculators/           # Remnant property calculators
│       ├── __init__.py
│       ├── remnant_mass_calculator.py
│       ├── remnant_spin_calculator.py
│       ├── kick_velocity_calculator.py
│       ├── peak_luminosity_calculator.py
│       └── initial_energy_momenta.py
│
├── docs/                              # Sphinx documentation source
├── tutorials/                         # Example notebooks and tutorials
├── tests/                             # Unit tests
├── pyproject.toml                     # Packaging configuration
├── README.md                          # This file
├── LICENSE                            # License information
└── .gitignore                         # Git ignore rules

BHPTNRremnant

gw_remnant has been used in developing an NR-tuned perturbation-based remnant model that provides faithful estimates of the remnant properties for binaries with mass ratios ranging from q=3 to q=1000.

Citation

If you make use of any module from the Toolkit in your research please acknowledge using:

This work makes use of the Black Hole Perturbation Toolkit.

If you make use of the gw_remnant package or BHPTNRremnant surrogate models please cite the following paper:

@article{Islam:2022laz,
    author = "Islam, Tousif and Field, Scott E. and Khanna, Gaurav.",
    title = "{Remnant black hole properties from numerical-relativity-informed perturbation theory and implications for waveform modelling}",
    eprint = "https://arxiv.org/abs/2301.07215",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "1",
    year = "2023"
}