gwModels 0.2.0

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 tousifislam24@gmail.com. Detailed documentation is available at https://tousifislam.com/gwModels/

Conventions

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

Getting the package

This package requires Python 3 and gwtools.

From PyPI

pip install gwModels                # core (numpy, scipy, matplotlib, gwtools)
pip install gwModels[surrogates]    # + gwsurrogate
pip install gwModels[lal]           # + lalsuite
pip install gwModels[seob]          # + pyseobnr
pip install gwModels[kicks]         # + scikit-learn, torch, nflows (remnant kick models)
pip install gwModels[all]           # all optional dependencies

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.

2. Eccentric Higher-Mode Waveforms

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

3. Eccentricity Estimation

4. Dynamics: Eccentricity Evolution

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

gwModelRem family (unified remnant models)

A single framework covering aligned-spin, precessing and eccentric binaries, plus the point-particle limit, from Islam, Wadekar & Khanna (2026) (2608.00934). All fitted coefficients are inline in the source.

import numpy as np
import gwModels

Mf, chif, Lpeak, wpeak, vkick = gwModels.remnants.gwModelRemS(3.0, 0.5, -0.2)
Mf, af, theta_f, Lpeak = gwModels.remnants.gwModelRemP(
    2.0, 0.7, 0.3, np.pi/3, np.pi/4, 0.0, 0.0)

flow = gwModels.remnants.gwModelRemP_flow()
median, p5, p95 = flow.predict(2.0, 0.7, 0.3, np.pi/3, np.pi/4, 0.0, 0.0)

Per-quantity functions are also available: gwModelRemS_mf, gwModelRemS_chif, gwModelRemS_Lpeak, gwModelRemS_omega_peak, gwModelRemS_kick, and the corresponding gwModelRemP_* and gwModelRemSE_* entry points.

Two caveats worth reading before use:

• gwModelRemPE applies the gwModelRemSE corrections to a precessing baseline, treating eccentricity and precession as independent at leading order. This is the intended construction, but the factorization has not been checked against precessing eccentric NR, of which very little exists, so treat its eccentric corrections with the same caution as gwModelRemSE.
• gwModelRemSE is provisional. The circular limit is exact, but at $e_{\rm ref} > 0$ the correction does not yet improve on the quasi-circular baseline on NR data (neutral to a few percent worse inside its calibration domain). Do not extrapolate past $e_{\rm ref} \sim 0.3$, where the anomaly modulation becomes an order of magnitude larger than the residual it corrects.
• gwModelEMRI's separatrix solver does not always converge, failing for about 6% of a grid over $(\chi, \theta_{\rm inc}, e)$, worst near polar inclination at high spin. It warns by default; pass return_converged=True for the mask. Equatorial orbits always converge.

The gwModelRemS recoil is a refit of gwModel_kick_q200 on an expanded dataset, and gwModelRemP_flow supersedes gwModel_kick_prec_flow. Both earlier models remain available and unchanged.

Kick velocity models

Final mass and spin models

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"
}