gwModels 0.1.5

Python package to provide models for gravitational waveforms, remnants and dynamics

gwModels

This package is intended to host a variety of data-driven and phenomenological models for the gravitational radiation (waveforms) emitted from binary black hole mergers. For questions, suggestions or collaborations, please feel free to drop an email to [e-mail]. Detailed documentation is available at https://tousifislam.com/gwModels/

Conventions

Throughout the package, we adopt the following conventions for binary black hole parameters:

Symbol	Description	Range
q	Mass ratio $m_1/m_2$ (body 1 is always the more massive)	$q \geq 1$
a1, a2	Dimensionless spin magnitudes	$[0, 1]$
chi1, chi2	Dimensionless spin vectors [chi1x, chi1y, chi1z]	—
chi1z, chi2z	Spin components along orbital angular momentum	$[-1, 1]$
theta1, theta2	Zenith angle between spin and orbital angular momentum	—
phi1, phi2	Azimuthal angle of spin projection onto the orbital plane	—
delta_phi	Azimuthal angle difference between spin projections	—
e_ref	Eccentricity at reference	—
ano_ref	Anomaly at reference	—

Getting the package

From PyPI

pip install gwModels

From source

git clone https://github.com/tousifislam/gwModels
cd gwModels
pip install -e .

Data files

Model data files are stored in the gwModels/data/ directory. After cloning from source, verify all data files are present:

python gwmodels_setup_data.py

Available Models

1. Waveform Frameworks

Frameworks for converting quasi-circular waveforms into eccentric waveforms using known quadrupolar eccentric waveforms.

Model	Description	Reference	Tutorial
gwNRHME	Non-spinning quasi-circular HM waveform → eccentric	2403.15506	1_1
gwNRXHME	Non-precessing quasi-circular HM waveform → eccentric	2502.02739	1_1

2. Eccentric Higher-Mode Waveforms

Eccentric waveform models obtained by combining circular surrogates with an eccentric model through gwNRHME.

Model	Components	Reference	Tutorial
NRHybSur3dq8-gwNRHME	NRHybSur3dq8 + SEOBNRv5EHM	2408.02762	2_1
BHPTNRSur1dq1e4-gwNRHME	BHPTNRSur1dq1e4 + SEOBNRv5EHM	2408.02762	2_2

3. Eccentricity Estimation

Model	Description	Reference	Tutorial
eccentricity_estimation	Computes $e_{\xi}$, $e_{\omega}$, $e_{\rm gw}$	2502.02739	3_1

4. Dynamics: Eccentricity Evolution

Model	Type	Parameter Range	Reference	Tutorial
gwEccEvNS	NR-based approximate	Non-spinning	2502.02739	4_1
gwEccEvNSv2	Analytical	Non-spinning	2604.17868	4_2
gwEccEvolve_NoSpinq4	SVD surrogate + GPR	$1 \leq q \leq 4$, $0.003 \leq e_0 \leq 0.443$	2604.17868	4_3

5. Remnant Properties: Final Mass, Spin, and Kick

Kick velocity models

Model	Type	Valid Range	Extra Deps	Reference	Tutorial
gwModel_kick_q200	Analytical (aligned-spin)	$1 \leq q \leq 1000$	—	2511.11536	5_1
gwModel_kick_q200_GPR	GPR (aligned-spin)	$1 \leq q \leq 1000$	scikit-learn	2511.11536	5_1
gwModel_kick_prec_flow	Normalizing flow (precessing)	$q \leq 100$	torch, nflows	2511.11536	5_1
HLZ_2014_aligned_spin	Analytical (aligned-spin)	—	—	1406.7295	5_2
bbh_final_kick_precessing_CLZM2007	Analytical (precessing)	—	—	Gonzalez+ 2007, Campanelli+ 2007	5_2

Final mass and spin models

Model	Quantity	Spin Type	Reference	Tutorial
bbh_final_mass_precessing_BMR2012	Final mass	Precessing	Barausse, Morozova & Rezzolla (2012)	5_2
bbh_final_spin_precessing_HBR2016	Final spin	Precessing	Hofmann, Barausse & Rezzolla (2016)	5_2
bbh_final_mass_non_precessing_UIB2016	Final mass	Aligned-spin	1611.00332	5_2
bbh_final_spin_non_precessing_UIB2016	Final spin	Aligned-spin	1611.00332	5_2

Requirements

This package requires Python 3 and gwtools.

pip install gwtools

Optional dependencies for specific models:

• scikit-learn — for gwModel_kick_q200_GPR
• torch, nflows — for gwModel_kick_prec_flow
• gwsurrogate — for NRHybSur3dq8-gwNRHME and BHPTNRSur1dq1e4-gwNRHME tutorials

Install optional groups with:

pip install gwModels[kicks]       # scikit-learn, torch, nflows for remnant kick models
pip install gwModels[all]         # all optional dependencies

Issue tracker

Known bugs are recorded in the project bug tracker: https://github.com/tousifislam/gwModels/issues

License

This code is distributed under the MIT License. Details can be found in the LICENSE file.

Maintainer

Tousif Islam

Citation guideline

If you make use of the gwModels framework, please cite the relevant papers:

@article{Islam:2024rhm,
    author = "Islam, Tousif",
    title = "{Straightforward mode hierarchy in eccentric binary black hole mergers and associated waveform model}",
    eprint = "2403.15506",
    archivePrefix = "arXiv",
    primaryClass = "astro-ph.HE",
    month = "3",
    year = "2024"
}

@article{Islam:2024tcs,
    author = "Islam, Tousif",
    title = "{Study of eccentric binary black hole mergers using numerical relativity and an inspiral-merger-ringdown model}",
    eprint = "2403.03487",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "3",
    year = "2024"
}

@article{Islam:2024zqo,
    author = "Islam, Tousif and Khanna, Gaurav and Field, Scott E.",
    title = "{Adding higher-order spherical harmonics in non-spinning eccentric binary black hole merger waveform models}",
    eprint = "2408.02762",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "8",
    year = "2024"
}

@article{Islam:2025oiv,
    author = "Islam, Tousif and Venumadhav, Tejaswi",
    title = "{Post-Newtonian theory-inspired framework for characterizing eccentricity in gravitational waveforms}",
    eprint = "2502.02739",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "2",
    year = "2025"
}

@article{Islam:2026blk,
    author = "Islam, Tousif and others",
    title = "{Including higher-order modes in a quadrupolar eccentric numerical relativity surrogate using universal eccentric modulation functions}",
    eprint = "2604.17868",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "4",
    year = "2026"
}

@article{Islam:2025drw,
    author = "Islam, Tousif and Wadekar, Digvijay",
    title = "{Accurate models for recoil velocity distribution in black hole mergers with comparable to extreme mass-ratios and their astrophysical implications}",
    eprint = "2511.11536",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    doi = "10.1103/4jvv-qg4h",
    journal = "Phys. Rev. D",
    volume = "113",
    number = "10",
    pages = "104017",
    year = "2026"
}