fastemriwaveforms
Blazingly fast EMRI waveforms
https://github.com/blackholeperturbationtoolkit/fastemriwaveforms
Science Score: 67.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
✓DOI references
Found 2 DOI reference(s) in README -
✓Academic publication links
Links to: zenodo.org -
○Academic email domains
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (16.1%) to scientific vocabulary
Repository
Blazingly fast EMRI waveforms
Basic Info
- Host: GitHub
- Owner: BlackHolePerturbationToolkit
- License: other
- Language: Python
- Default Branch: master
- Size: 179 MB
Statistics
- Stars: 69
- Watchers: 11
- Forks: 40
- Open Issues: 2
- Releases: 5
Metadata Files
README.md
few: FastEMRIWaveforms
This package contains a highly modular framework for the rapid generation of accurate extreme-mass-ratio inspiral (EMRI) waveforms. FEW combines a variety of separately accessible modules to construct EMRI waveform models for both CPUs and GPUs.
- Generally, the modules fall into four categories: trajectory, amplitudes, summation, and utilities. Please see the documentation for further information on these modules.
- The code can be found on Github here.
- The data necessary for various modules in this package will automatically download the first time it is needed. If you would like to view the data, it can be found on Zenodo.
- The current and all past code release zip files can also be found on Zenodo here.
Please see the citation section below for information on citing FEW. This package is part of the Black Hole Perturbation Toolkit.
Getting started
Detailed installation instructions can be found in the documentation. Below is a quick set of instructions to install the FastEMRIWaveform package on CPUs and GPUs.
To install the latest version of fastemriwaveforms using pip, simply run:
```sh
For CPU-only version
pip install fastemriwaveforms
For GPU-enabled versions with CUDA 11.Y.Z
pip install fastemriwaveforms-cuda11x
For GPU-enabled versions with CUDA 12.Y.Z
pip install fastemriwaveforms-cuda12x ```
To know your CUDA version, run the tool nvidia-smi in a terminal a check the CUDA version reported in the table header:
sh
$ nvidia-smi
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.54.15 Driver Version: 550.54.15 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
...
You may also install fastemriwaveforms directly using conda (including on Windows)
as well as its CUDA 12.x plugin (only on Linux). It is strongly advised to:
- Ensure that your conda environment makes sole use of the
conda-forgechannel - Install
fastemriwaveformsdirectly when building your conda environment, not afterwards
```sh
For CPU-only version, on either Linux, macOS or Windows:
conda create --name fewcpu -c conda-forge --override-channels python=3.12 fastemriwaveforms conda activate fewcpu
For CUDA 12.x version, only on Linux
conda create --name fewcuda -c conda-forge --override-channels python=3.12 fastemriwaveforms-cuda12x conda activate fewcuda ```
Now, in a python file or notebook:
py3
import few
You may check the currently available backends:
```py3
for backend in ["cpu", "cuda11x", "cuda12x", "cuda", "gpu"]: ... print(f" - Backend '{backend}': {"available" if few.has_backend(backend) else "unavailable"}") - Backend 'cpu': available - Backend 'cuda11x': unavailable - Backend 'cuda12x': unavailable - Backend 'cuda': unavailable - Backend 'gpu': unavailable ```
Note that the cuda backend is an alias for either cuda11x or cuda12x. If any is available, then the cuda backend is available.
Similarly, the gpu backend is (for now) an alias for cuda.
If you expected a backend to be available but it is not, run the following command to obtain an error message which can guide you to fix this issue:
```py3
import few few.getbackend("cuda12x") ModuleNotFoundError: No module named 'fewbackend_cuda12x'
The above exception was the direct cause of the following exception: ...
few.cutils.BackendNotInstalled: The 'cuda12x' backend is not installed.
The above exception was the direct cause of the following exception: ...
few.cutils.MissingDependencies: FastEMRIWaveforms CUDA plugin is missing. If you are using few in an environment managed using pip, run: $ pip install fastemriwaveforms-cuda12x
The above exception was the direct cause of the following exception: ...
few.cutils.BackendAccessException: Backend 'cuda12x' is unavailable. See previous error messages. ```
Once FEW is working and the expected backends are selected, check out the examples notebooks on how to start with this software.
Installing from sources
Prerequisites
To install this software from source, you will need:
- A C++ compiler (g++, clang++, ...)
- A Python version supported by scikit-build-core (>=3.7 as of Jan. 2025)
Some installation steps require the external library LAPACK along with its C-bindings provided by LAPACKE.
If these libraries and their header files (in particular lapacke.h) are available on your system, they will be detected
and used automatically. If they are available on a non-standard location, see below for some options to help detecting them.
Note that by default, if LAPACKE is not available on your system, the installation step will attempt to download its sources
and add them to the compilation tree. This makes the installation a bit longer but a lot easier.
If you want to enable GPU support in FEW, you will also need the NVIDIA CUDA Compiler nvcc in your path as well as
the CUDA toolkit (with, in particular, the
libraries CUDA Runtime Library, cuBLAS and cuSPARSE).
There are a set of files required for total use of this package. They will download automatically the first time they are needed. Files are generally under 10MB. However, there is a 100MB file needed for the slow waveform and the bicubic amplitude interpolation. This larger file will only download if you run either of those two modules. The files are hosted on the Black Hole Perturbation Toolkit Download Server.
Installation instructions using conda
We recommend to install FEW using conda in order to have the compilers all within an environment. First clone the repo
git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git
cd FastEMRIWaveforms
Now create an environment (these instructions work for all platforms but some adjustements can be needed, refer to the detailed installation documentation for more information):
conda create -n few_env -y -c conda-forge --override-channels |
cxx-compiler pkgconfig conda-forge/label/lapack_rc::liblapacke
activate the environment
conda activate few_env
Then we can install locally for development:
pip install -e '.[dev, testing]'
Installation instructions using conda on GPUs and linux
Below is a quick set of instructions to install the Fast EMRI Waveform package on GPUs and linux.
sh
conda create -n few_env -c conda-forge fastemriwaveforms-cuda12x python=3.12
conda activate few_env
Test the installation device by running python
python
import few
few.get_backend("cuda12x")
Running the installation
To start the from-source installation, ensure the pre-requisite are met, clone
the repository, and then simply run a pip install command:
```sh
Clone the repository
git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git cd FastEMRIWaveforms
Run the install
pip install . ```
If the installation does not work, first check the detailed installation documentation. If it still does not work, please open an issue on the GitHub repository or contact the developers through other means.
Running the Tests
The tests require a few dependencies which are not installed by default. To install them, add the [testing] label to FEW package
name when installing it. E.g:
```sh
For CPU-only version with testing enabled
pip install fastemriwaveforms[testing]
For GPU version with CUDA 12.Y and testing enabled
pip install fastemriwaveforms-cuda12x[testing]
For from-source install with testing enabled
git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git cd FastEMRIWaveforms pip install '.[testing]' ```
To run the tests, open a terminal in a directory containing the sources of FEW and then run the unittest module in discover mode:
```sh $ git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git $ cd FastEMRIWaveforms $ python -m few.tests # or "python -m unittest discover"
...
Ran 20 tests in 71.514s OK ```
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
If you want to develop FEW and produce documentation, install few from source with the [dev] label and in editable mode:
$ git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git
$ cd FastEMRIWaveforms
pip install -e '.[dev, testing]'
This will install necessary packages for building the documentation (sphinx, pypandoc, sphinx_rtd_theme, nbsphinx) and to run the tests.
The documentation source files are in docs/source. To compile the documentation locally, change to the docs directory and run make html.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Contributors
A (non-exhaustive) list of contributors to the FEW code can be found in CONTRIBUTORS.md.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Citation
Please make sure to cite FEW papers and the FEW software on Zenodo.
We provide a set of prepared references in PAPERS.bib. There are other papers that require citation based on the classes used. For most classes this applies to, you can find these by checking the citation attribute for that class. All references are detailed in the CITATION.cff file.
Acknowledgments
- This research resulting in this code was supported by National Science Foundation under grant DGE-0948017 and the Chateaubriand Fellowship from the Office for Science & Technology of the Embassy of France in the United States.
- It was also supported in part through the computational resources and staff contributions provided for the Quest/Grail high performance computing facility at Northwestern University.
Owner
- Name: Black Hole Perturbation Toolkit
- Login: BlackHolePerturbationToolkit
- Kind: organization
- Website: bhptoolkit.org
- Repositories: 14
- Profile: https://github.com/BlackHolePerturbationToolkit
Open tools for black hole perturbation theory
Citation (CITATION.cff)
# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!
cff-version: 1.2.0
title: FastEMRIWaveforms
message: >-
If you use this software, please make sure to cite both
the software itself, the papers 'arXiv:2008.06071' and
'arXiv:2104.04582' as well as the papers specific to the
classes that you use (see the class "citation" attribute
and the documentation).
type: software
authors:
- given-names: Michael
family-names: Katz
orcid: 'https://orcid.org/0000-0002-7605-5767'
affiliation: NASA Marshall Space Flight Center
email: mikekatz04@gmail.com
- given-names: Lorenzo
family-names: Speri
orcid: 'https://orcid.org/0000-0002-5442-7267'
affiliation: European Space Research Technology Center
- given-names: Christian
family-names: Chapman-Bird
affiliation: University of Birmingham
orcid: 'https://orcid.org/0000-0002-2728-9612'
- given-names: Alvin J. K.
family-names: Chua
affiliation: National University of Singapore
- given-names: Niels
family-names: Warburton
affiliation: University College Dublin
orcid: 'https://orcid.org/0000-0003-0914-8645'
- given-names: Scott
family-names: Hughes
affiliation: Massachusetts Institute of Technology
orcid: 'https://orcid.org/0000-0001-6211-1388'
identifiers:
- type: doi
value: 10.5281/zenodo.3969004
description: Zenodo repository of this project
repository-code: >-
https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms
url: 'https://bhptoolkit.org/FastEMRIWaveforms/html/index.html'
repository: 'https://zenodo.org/records/3969004'
repository-artifact: 'https://pypi.org/project/fastemriwaveforms/'
abstract: >-
This package contains the highly modular framework for
fast and accurate extreme mass ratio inspiral (EMRI)
waveforms from arxiv.org/2104.04582 and
arxiv.org/2008.06071. The waveforms in this package
combine a variety of separately accessible modules to form
EMRI waveforms on both CPUs and GPUs.
keywords:
- Gravitational Wave
- LISA
- EMRI
- Waveform
license: MIT
references:
- abbreviation: "Chapman-Bird:2025xtd"
authors:
- family-names: Chapman-Bird
given-names: Christian E. A.
- family-names: Speri
given-names: Lorenzo
- family-names: Nazipak
given-names: Zachary
- family-names: Burke
given-names: Ollie
- family-names: Katz
given-names: Michael L.
- family-names: Santini
given-names: Alessandro
- family-names: Kejriwal
given-names: Shubham
- family-names: Lynch
given-names: Philip
- family-names: Mathews
given-names: Josh
- family-names: Khalvati
given-names: Hassan
- family-names: Thompson
given-names: Jonathan E.
- family-names: Isoyama
given-names: Soichiro
- family-names: Hughes
given-names: Scott A.
- family-names: Warburton
given-names: Niels
- family-names: Chua
given-names: Alvin J. K.
- family-names: Pigou
given-names: Maxime
doi: 10.48550/arXiv.2506.09470
year: 2025
month: 6
title: >-
The Fast and the Frame-Dragging: Efficient waveforms for asymmetric-mass
eccentric equatorial inspirals into rapidly-spinning black holes
identifiers:
- type: other
value: 'arXiv:gr-qc/2506.09470'
description: arXiv preprint of this article
type: article
- abbreviation: "Chua:2020stf"
authors:
- family-names: Chua
given-names: Alvin J. K.
- family-names: Katz
given-names: Michael L.
- family-names: Warburton
given-names: Niels
- family-names: Hugues
given-names: Scott A.
doi: 10.1103/PhysRevLett.126.051102
year: 2021
month: 2
journal: Physical Review Letters
volume: 126
issue: 5
title: >-
Rapid Generation of Fully Relativistic Extreme-Mass-Ratio-Inspiral
Waveform Templates for LISA Data Analysis
pages: 6
start: 51102
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevLett.126.051102'
issn: 1079-7114
identifiers:
- type: other
value: 'arXiv:gr-qc/2008.06071'
description: arXiv preprint of this article
type: article
- abbreviation: "Katz:2021yft"
authors:
- family-names: Katz
given-names: Michael L.
- family-names: Chua
given-names: Alvin J. K.
- family-names: Speri
given-names: Lorenzo
- family-names: Warburton
given-names: Niels
- family-names: Hugues
given-names: Scott A.
doi: 10.1103/physrevd.104.064047
year: 2021
month: 9
journal: Physical Review D
volume: 104
issue: 6
title: >-
Fast extreme-mass-ratio-inspiral waveforms: New tools for millihertz
gravitational-wave data analysis
pages: 25
start: 64047
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevD.104.064047'
issn: 2470-0029
identifiers:
- type: other
value: 'arXiv:gr-qc/2104.04582'
description: arXiv preprint of this article
type: article
- abbreviation: "Chua:2018woh"
authors:
- family-names: Chua
given-names: Alvin J. K.
- family-names: Galley
given-names: Chad R.
- family-names: Vallisneri
given-names: Michele
doi: 10.1103/physrevlett.122.211101
year: 2019
month: 5
journal: Physical Review Letters
volume: 122
issue: 21
title: >-
Reduced-Order Modeling with Artificial Neurons for Gravitational-Wave
Inference
pages: 7
start: 211101
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevLett.122.211101'
issn: 1079-7114
identifiers:
- type: other
value: 'arXiv:astro-ph.IM/1811.05491'
description: arXiv preprint of this article
type: article
- abbreviation: "Fujita:2020zxe"
authors:
- family-names: Fujita
given-names: Ryuichi
- family-names: Shibata
given-names: Masaru
doi: 10.1103/physrevd.102.064005
year: 2020
month: 9
journal: Physical Review D
volume: 102
issue: 6
title: >-
Extreme mass ratio inspirals on the equatorial plane in the adiabatic
order
pages: 18
start: 64005
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevD.102.064005'
issn: 2470-0029
identifiers:
- type: other
value: 'arXiv:gr-qc/2008.13554'
description: arXiv preprint of this article
type: article
- abbreviation: "Stein:2019buj"
authors:
- family-names: Stein
given-names: Leo C.
- family-names: Warburton
given-names: Niels
doi: 10.1103/physrevd.101.064007
year: 2020
month: 3
journal: Physical Review D
volume: 101
issue: 6
title: Location of the last stable orbit in Kerr spacetime
pages: 16
start: 64007
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/physrevd.101.064007'
issn: 2470-0029
identifiers:
- type: other
value: 'arXiv:gr-qc/1912.07609'
description: arXiv preprint of this article
type: article
- abbreviation: "Chua:2015mua"
authors:
- family-names: Chua
given-names: Alvin J. K.
- family-names: Gair
given-names: Jonathan R.
doi: 10.1088/0264-9381/32/23/232002
year: 2015
month: 11
journal: Classical and Quantum Gravity
volume: 32
issue: 23
title: >-
Improved analytic extreme-mass-ratio inspiral model for scoping out eLISA
data analysis
pages: 8
start: 232002
publisher:
name: IOP Publishing
issn: 1361-6382
identifiers:
- type: other
value: 'arXiv:gr-qc/1510.06245'
description: arXiv preprint of this article
type: article
- abbreviation: "Chua:2017ujo"
authors:
- family-names: Chua
given-names: Alvin J. K.
- family-names: Moore
given-names: Christopher J.
- family-names: Gair
given-names: Jonathan R.
doi: 10.1103/physrevd.96.044005
year: 2017
month: 8
journal: Physical Review D
volume: 96
issue: 4
title: Augmented kludge waveforms for detecting extreme-mass-ratio inspirals
pages: 17
start: 44005
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevD.96.044005'
issn: 2470-0029
identifiers:
- type: other
value: 'arXiv:gr-qc/1705.04259'
description: arXiv preprint of this article
type: article
- abbreviation: "Barack:2003fp"
authors:
- family-names: Barack
given-names: Leor
- family-names: Cutler
given-names: Curt
doi: 10.1103/physrevd.69.082005
year: 2004
month: 4
journal: Physical Review D
volume: 69
issue: 8
title: >-
LISA capture sources: Approximate waveforms, signal-to-noise ratios, and
parameter estimation accuracy
pages: 24
start: 82005
publisher:
name: American Physical Society
url: 'https://link.aps.org/doi/10.1103/PhysRevD.69.082005'
issn: 1550-2368
identifiers:
- type: other
value: 'arXiv:gr-qc/0310125'
description: arXiv preprint of this article
type: article
- abbreviation: "Speri:2023jte"
authors:
- family-names: Speri
given-names: Lorenzo
- family-names: Katz
given-names: Michael L.
- family-names: Chua
given-names: Alvin J. K.
- family-names: Hugues
given-names: Scott A.
- family-names: Warburton
given-names: Niels
- family-names: Thompson
given-names: Jonathan E.
- family-names: Chapman-Bird
given-names: Christian E. A.
- family-names: Gair
given-names: Jonathan R.
doi: 10.3389/fams.2023.1266739
year: 2024
month: 1
journal: Frontiers in Applied Mathematics and Statistics
volume: 9
title: >-
Fast and Fourier: extreme mass ratio inspiral waveforms in the frequency
domain
pages: 13
publisher:
name: Frontiers Media SA
issn: 2297-4687
identifiers:
- type: other
value: 'arXiv:gr-qc/2307.12585'
description: arXiv preprint of this article
type: article
GitHub Events
Total
- Issues event: 16
- Watch event: 20
- Delete event: 1
- Issue comment event: 35
- Push event: 130
- Pull request review comment event: 10
- Pull request review event: 15
- Pull request event: 77
- Fork event: 11
- Create event: 5
Last Year
- Issues event: 16
- Watch event: 20
- Delete event: 1
- Issue comment event: 35
- Push event: 130
- Pull request review comment event: 10
- Pull request review event: 15
- Pull request event: 77
- Fork event: 11
- Create event: 5
Issues and Pull Requests
Last synced: 11 months ago
All Time
- Total issues: 11
- Total pull requests: 43
- Average time to close issues: 4 months
- Average time to close pull requests: 11 days
- Total issue authors: 10
- Total pull request authors: 7
- Average comments per issue: 0.82
- Average comments per pull request: 0.42
- Merged pull requests: 24
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 6
- Pull requests: 39
- Average time to close issues: 3 months
- Average time to close pull requests: 12 days
- Issue authors: 5
- Pull request authors: 6
- Average comments per issue: 0.67
- Average comments per pull request: 0.46
- Merged pull requests: 23
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- angrai00 (2)
- lorenzsp (1)
- avivajpeyi (1)
- gyy0592 (1)
- TinaMcNally (1)
- OllieBurke (1)
- znasipak (1)
- susannabarsanti (1)
- verasha (1)
- mpigou (1)
- joshbmat (1)
- DrAndrewSpiers (1)
- smmasruk (1)
Pull Request Authors
- mpigou (30)
- OllieBurke (4)
- cchapmanbird (3)
- lorenzsp (3)
- CChapmanbird (2)
- barrywardell (1)
- Patrick-Bourg (1)
- znasipak (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 3
-
Total downloads:
- pypi 529 last-month
-
Total dependent packages: 0
(may contain duplicates) -
Total dependent repositories: 0
(may contain duplicates) - Total versions: 17
- Total maintainers: 2
pypi.org: fastemriwaveforms-cuda12x
Fast and accurate EMRI Waveforms.
- Homepage: https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms
- Documentation: https://bhptoolkit.org/FastEMRIWaveforms/html/index.html
- License: MIT License
-
Latest release: 2.0.0
published about 1 year ago
Rankings
Maintainers (1)
pypi.org: fastemriwaveforms-cuda11x
Fast and accurate EMRI Waveforms.
- Homepage: https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms
- Documentation: https://bhptoolkit.org/FastEMRIWaveforms/html/index.html
- License: MIT License
-
Latest release: 2.0.0
published about 1 year ago
Rankings
Maintainers (1)
pypi.org: fastemriwaveforms
Fast and accurate EMRI Waveforms.
- Homepage: https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms
- Documentation: https://bhptoolkit.org/FastEMRIWaveforms/html/index.html
- License: MIT License
-
Latest release: 2.0.0
published about 1 year ago