Defining eccentricity for gravitational wave astronomy

About

gw_eccentricity provides methods to measure eccentricity and mean anomaly from gravitational waveforms of binaries on generic bound orbits.

These methods are described in the following paper:

• [1] Md Arif Shaikh, Vijay Varma, Harald Pfeiffer, Antoni Ramos-Buades and Maarten van de Meent, "Defining eccentricity for gravitational wave astronomy", Phys. Rev. D 108, 104007 (2023), arXiv:2302.11257
• [2] Md Arif Shaikh, Vijay Varma, Antoni Ramos-Buades, Harald P. Pfeiffer, Michael Boyle, Lawrence E. Kidder and Mark A. Scheel, "Defining eccentricity for spin-precessing binaries", Class. Quantum Grav. 42 195012 (2025), arXiv:2507.08345

Please see Credits below for citing this work. This package lives on GitHub, is compatible with python3, and is tested every week. You can see the current build status of the main branch at the top of this page.

Installation

PyPI

gw_eccentricity is available through PyPI:

pip install gw_eccentricity

or

pip install "gw_eccentricity[postprocess]"

to additionally install the functionality for postprocessing posterior samples from parameter estimation pipelines.

Conda

gw_eccentricity can be installed using conda also:

conda install -c conda-forge gw_eccentricity

or

conda install -c conda-forge gw_eccentricity gw_eccentricity-postprocess

From source

git clone git@github.com:vijayvarma392/gw_eccentricity.git
cd gw_eccentricity
pip install .

or

pip install .["postprocess"]

If you do not have root permissions, replace the last step with pip install --user .

Dependencies

All of these can be installed through pip or conda.

Core

• numpy
• scipy
• h5py
• lalsuite
• sxs
• scri

Postprocessing

These are installed automatically with pip install "gw_eccentricity[postprocess]" or conda install gw_eccentricity-postprocess:

• pandas
• bilby
• joblib
• tqdm
• pyarrow
• mpi4py

Usage

See example notebooks:

• gw_eccentricity demo for how to use the package, along with diagnostic plots.
• Load waveforms demo for loading waveform data into a dictionary format suitable for gw_eccentricity, including for LAL, SXS, and LVCNR waveforms.
  • TEOBResumS-Dali demo for the same for TEOBResumS-Dali.
  • SEOBNRv5EHM demo for the same for SEOBNRv5EHM.

Postprocessing posterior samples

See the example notebooks and scripts here for postprocessing posterior from parameter estimation pipelines.

Making contributions

See this README for instructions on how to make contributions to this package.

Please report bugs by raising an issue on our GitHub repository.

Credits

The main contributors to this code are Md Arif Shaikh, Vijay Varma, and Harald Pfeiffer. You can find the full list of contributors here.

If you find this package useful in your work, please cite references [1] and [2] and this package. You can use the following bibtex keys:

@article{Shaikh:2023ypz,
    author = "Shaikh, Md Arif and Varma, Vijay and Pfeiffer, Harald P. and Ramos-Buades, Antoni and van de Meent, Maarten",
    title = "{Defining eccentricity for gravitational wave astronomy}",
    eprint = "2302.11257",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    doi = "10.1103/PhysRevD.108.104007",
    journal = "Phys. Rev. D",
    volume = "108",
    number = "10",
    pages = "104007",
    year = "2023",
    note = "{\href{https://pypi.org/project/gw_eccentricity}{pypi.org/project/gw\_eccentricity}}",
}

@article{Shaikh:2025tae,
    author = "Shaikh, Md Arif and Varma, Vijay and Ramos-Buades, Antoni and Pfeiffer, Harald P. and Boyle, Michael and Kidder, Lawrence E. and Scheel, Mark A.",
    title = "{Defining eccentricity for spin-precessing binaries}",
    eprint = "2507.08345",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    doi = "10.1088/1361-6382/ae085d",
    journal = "Class. Quant. Grav.",
    volume = "42",
    number = "19",
    pages = "195012",
    year = "2025",
	note = "{\href{https://pypi.org/project/gw_eccentricity}{pypi.org/project/gw\_eccentricity}}",
}

Image at the top shows an eccentric gravitational wave signal (SXS:BBH:2558) from arXiv:2209.03390.