Metadata-Version: 2.4
Name: gw_remnant
Version: 0.4.0
Summary: Python package to extract remnant black hole properties from gravitational waveforms
Author: Scott Field, Gaurav Khanna
Author-email: Tousif Islam <tousifislam24@gmail.com>
Maintainer-email: Tousif Islam <tousifislam24@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/tousifislam/gw_remnant
Project-URL: Bug Reports, https://github.com/tousifislam/gw_remnant/issues
Project-URL: Source, https://github.com/tousifislam/gw_remnant
Project-URL: Documentation, https://tousifislam.github.io/gw_remnant/
Keywords: gravitational waves,black holes,numerical relativity,remnant properties
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Other Audience
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: gwtools
Provides-Extra: surrogates
Requires-Dist: gwsurrogate; extra == "surrogates"
Requires-Dist: surfinBH; extra == "surrogates"
Provides-Extra: nr
Requires-Dist: sxs; extra == "nr"
Requires-Dist: mayawaves; extra == "nr"
Provides-Extra: eob
Requires-Dist: pyseobnr; extra == "eob"
Provides-Extra: all
Requires-Dist: gwsurrogate; extra == "all"
Requires-Dist: surfinBH; extra == "all"
Requires-Dist: sxs; extra == "all"
Requires-Dist: mayawaves; extra == "all"
Requires-Dist: pyseobnr; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="logo.png" alt="gw_remnant logo" width="400"/>
</p>

# gw_remnant

[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://tousifislam.github.io/gw_remnant/)
[![PyPI](https://img.shields.io/pypi/v/gw-remnant)](https://pypi.org/project/gw-remnant/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:
```bash
pip install gw_remnant
```

Install with optional dependencies for waveform surrogates:
```bash
pip install gw_remnant[surrogates]
```

Install with optional dependencies for numerical relativity catalogs:
```bash
pip install gw_remnant[nr]
```

Install all optional dependencies:
```bash
pip install gw_remnant[all]
```

Install from source (development):
```bash
git clone https://github.com/tousifislam/gw_remnant.git
cd gw_remnant
pip install -e .[dev]
```

### Dependencies

**Core** (always installed):

| Package | Version |
|---------|---------|
| Python | >= 3.8 |
| numpy | >= 1.20.0 |
| scipy | >= 1.7.0 |
| matplotlib | >= 3.3.0 |
| gwtools | — |

**Optional extras:**

| Install option | Packages | Purpose |
|----------------|----------|---------|
| `pip install gw_remnant[surrogates]` | gwsurrogate, surfinBH | Waveform surrogate models and remnant fits |
| `pip install gw_remnant[nr]` | sxs, mayawaves | Numerical relativity catalog access |
| `pip install gw_remnant[dev]` | pytest, pytest-cov, black, flake8, ipython, jupyter | Development and testing |
| `pip install gw_remnant[docs]` | sphinx, pydata-sphinx-theme, sphinx-autodoc-typehints, nbsphinx, pandoc, ipykernel | Building documentation |
| `pip install gw_remnant[eob]` | pyseobnr | Effective-one-body waveforms |
| `pip install gw_remnant[all]` | gwsurrogate, surfinBH, sxs, mayawaves, pyseobnr | All non-dev optional dependencies |

## Quick Start

```python
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)
# h_dict: dictionary of complex waveform modes, e.g. {(2,2): h22(t), ...}
calc = GWRemnantCalculator(time, h_dict, q=2.0,
                           chi1=[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](https://tousifislam.github.io/gw_remnant/quickstart.html) for more details.

## Architecture

The package uses a mixin-based class hierarchy that composes into a single entry point:

```
GWRemnantCalculator   (gw_remnant_calculator.py)
 ├── GWPlotter                    — diagnostic plots (mass, momentum, spin, kick, trajectory)
 ├── PeakLuminosityCalculator     — peak dE/dt via spline interpolation
 ├── AngularMomentumCalculator    — J_dot, Joft, remnant spin (scalar + 3-vector)
 ├── TrajectoryCalculator         — center-of-mass displacement x(t) = ∫v dt
 ├── LinearMomentumCalculator     — P_dot, Poft, kick velocity v(t) = P/M(t)
 ├── RemnantMassCalculator        — dE/dt, E_rad(t), Bondi mass M(t), remnant mass
 └── InitialEnergyMomenta         — initial E, L from post-Newtonian (PN) expressions
```

Everything is computed eagerly in `__init__` — constructing a `GWRemnantCalculator` runs the full pipeline bottom-up.

```
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
│       ├── trajectory_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
```

## Supported Waveform Models

The package includes built-in waveform generators for `NRHybSur3dq8`, `NRSur7dq4`, `BHPTNRSur1dq1e4`, and `BHPTNRSur2dq1e3`. It can also accept waveforms generated by any other method — see [Providing Waveform Data](https://tousifislam.github.io/gw_remnant/user_guide/waveform_input.html).

## Tutorials

Example notebooks are provided in the [`tutorials/`](tutorials/) directory:

| # | Notebook | Waveform source |
|---|----------|-----------------|
| 1 | [Remnant from default waveforms](tutorials/1_remnant_from_default_waveform.ipynb) | Built-in surrogate generators (BHPTNRSur1dq1e4, NRHybSur3dq8) |
| 2 | [Remnant from NRSur7dq4 waveforms](tutorials/2_remnant_from_NRSur7dq4_waveforms.ipynb) | NRSur7dq4 (precessing surrogate) |
| 3 | [Remnant from NRHybSur3dq8 waveforms](tutorials/3_remnant_from_NRHybSur3dq8_waveforms.ipynb) | NRHybSur3dq8 (aligned-spin surrogate) |
| 4 | [Remnant from SXS quasi-circular simulations](tutorials/4_remnant_from_sxs_quasicircular_simulations.ipynb) | SXS NR catalog (non-spinning, aligned-spin, precessing) |
| 5 | [Remnant from SXS eccentric simulations](tutorials/5_remnant_from_sxs_eccentric_simulations.ipynb) | SXS NR catalog (eccentric orbits) |
| 6 | [Remnant from Maya catalog waveforms](tutorials/6_remnant_from_maya_catalog_waveforms.ipynb) | Maya/Georgia Tech NR catalog |
| 7 | [Remnant from pySEOBNR waveforms](tutorials/7_remnant_from_pyseobnr_waveforms.ipynb) | pySEOBNR EOB models (SEOBNRv5HM/PHM/EHM) |

These are also rendered in the [online documentation](https://tousifislam.github.io/gw_remnant/tutorials/index.html).


## 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:

```bibtex
@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"
}
```
