Skip to main content

few: FastEMRIWaveforms

Documentation Status DOI

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:

# For CPU-only version
pip install fastemriwaveforms

# For GPU-enabled versions with CUDA 12.Y.Z
pip install fastemriwaveforms-cuda12x
# For GPU-enabled versions with CUDA 13.Y.Z
pip install fastemriwaveforms-cuda13x

To know your CUDA version, run the tool nvidia-smi in a terminal a check the CUDA version reported in the table header:

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

  1. Ensure that your conda environment makes sole use of the conda-forge channel
  2. Install fastemriwaveforms directly when building your conda environment, not afterwards
# For CPU-only version, on either Linux, macOS or Windows:
conda create --name few_cpu -c conda-forge --override-channels python=3.12 fastemriwaveforms
conda activate few_cpu

# For CUDA 12.x version, only on Linux
conda create --name few_cuda -c conda-forge --override-channels python=3.12 fastemriwaveforms-cuda12x
conda activate few_cuda

Now, in a python file or notebook:

import few

You may check the currently available backends:

>>> for backend in ["cpu", "cuda12x", "cuda13x", "cuda", "gpu"]:
...     print(f" - Backend '{backend}': {"available" if few.has_backend(backend) else "unavailable"}")
 - Backend 'cpu': available
 - Backend 'cuda12x': unavailable
 - Backend 'cuda13x': unavailable
 - Backend 'cuda': unavailable
 - Backend 'gpu': unavailable

Note that the cuda backend is an alias for cuda13x and 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:

>>> import few
>>> few.get_backend("cuda12x")
ModuleNotFoundError: No module named 'few_backend_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++, ...)
  • Python 3.12 or newer (wheels are built and tested for 3.12, 3.13 and 3.14)

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

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.

conda create -n few_env -c conda-forge fastemriwaveforms-cuda12x python=3.12
conda activate few_env

Test the installation device by running python

import few
few.get_backend("cuda12x")

Installation instructions using conda on WSL

First clone the repo

git clone https://github.com/BlackHolePerturbationToolkit/FastEMRIWaveforms.git
cd FastEMRIWaveforms

Now create an environment

conda create -n few_env python=3.12
conda activate few_env 
conda install -c conda-forge --override-channels cxx-compiler pkg-config
conda install -c conda-forge h5py jsonschema lisaconstants multispline numba nvidia-ml-py platformdirs pydantic pyyaml requests rich scipy tqdm wrapt

Then we can install locally for development:

pip install -e '.[dev, testing]'

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:

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

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

$ 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.

Metadata

Release files for fastemriwaveforms 2.2.1.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for fastemriwaveforms 2.2.1.post1
File Actions
fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl CPython 3.14 CPython 3.14 Linux glibc 2.24+ ARM64, Linux glibc 2.28+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
fastemriwaveforms-2.2.1.post1-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp314-cp314-macosx_14_0_arm64.whl
fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl CPython 3.13 CPython 3.13 Linux glibc 2.24+ ARM64, Linux glibc 2.28+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
fastemriwaveforms-2.2.1.post1-cp313-cp313-macosx_14_0_arm64.whl CPython 3.13 CPython 3.13 macOS 14.0+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp313-cp313-macosx_14_0_arm64.whl
fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ ARM64, Linux glibc 2.24+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
fastemriwaveforms-2.2.1.post1-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details for fastemriwaveforms-2.2.1.post1-cp312-cp312-macosx_14_0_arm64.whl

Total release size: 3.5 MB

Release files / fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 397.8 kB
Tags CPython 3.14 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
9922eacc0a80ec7e95fab8995c99baf77e957f49daae8398f07e4d9421ecd9ad
BLAKE2b-256 checksum
How to use checksums
931bafdf6d09c9bb24f48dad937e7fbd1e85ca44d688d44c09c9f49354dc2438
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 388.8 kB
Tags CPython 3.14 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
4a9a94ab95d58cbe2776f3539d7bffb9e0ebc0c2f9938d07de0604b959a2607f
BLAKE2b-256 checksum
How to use checksums
5add11da91a2db17a0eae8034fc37bbba79257a9af1a01e0e054fe2f5cccf77d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp314-cp314-macosx_14_0_arm64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp314-cp314-macosx_14_0_arm64.whl
Size 376.1 kB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
23f3fea0eb3442b0127067fbe39427f68b1d11513808223430eea3d450ad14e7
BLAKE2b-256 checksum
How to use checksums
d01b03cf9693615597960ecfa482fd5b1f4173d15bad46e5c88a5d7f2f174e7b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 397.4 kB
Tags CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
a363a72707964c078a29bfaac7cc79bdd6bbe53dd9988afe8c3d36fd823ba28e
BLAKE2b-256 checksum
How to use checksums
43b56ea22df8a38cb730a7c7c329a8f43887692b9fd04d36316998a2a0cc9c86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 386.9 kB
Tags CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
84db7c1b86e9075d5642c488d55cedbd53f6d0109e58cb5eef0bdfa725a8c205
BLAKE2b-256 checksum
How to use checksums
514042743ac591404523389ed33e99f7ae0d42b8bc05e517e8f563c19e13aaa6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp313-cp313-macosx_14_0_arm64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp313-cp313-macosx_14_0_arm64.whl
Size 376.1 kB
Tags CPython 3.13 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
42be8e690a10054fe9fc1617e9c7453f0005ff8eca8491990e933bc1699e9d31
BLAKE2b-256 checksum
How to use checksums
55789b93c68c3fcdbb4b28c70ad0d23ce54b4c3c3153b28992842f80a84bd6d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 399.5 kB
Tags CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e09b4b0c2e070c0a74ca6d25f62c5940a747d61250c0e8ad949242a3fdcc32dd
BLAKE2b-256 checksum
How to use checksums
8972a060f5b8379f8bc8384b1e68c0f88f46fed36df0b58e3343ad779c0dd2b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 389.4 kB
Tags CPython 3.12 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
016026bb5baad0a061ec544ae5cdd7ef2fd01847345b2f332e542ee70ab9f49e
BLAKE2b-256 checksum
How to use checksums
0c4551bdbcb26f0d461b5f0b38ada0b9e55fc716fae6e4b68c2c63706ab1b121
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Release files / fastemriwaveforms-2.2.1.post1-cp312-cp312-macosx_14_0_arm64.whl

Download URL fastemriwaveforms-2.2.1.post1-cp312-cp312-macosx_14_0_arm64.whl
Size 375.7 kB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
e393d38502b4fad94b370a5a039687abc391d7cc489e5669e2a8c334ef45b529
BLAKE2b-256 checksum
How to use checksums
cdf9928b42e5cbc6430f71e908638cbba6c56ef7cc7115d6d67f7d9fc03f6155
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.4

Security for fastemriwaveforms 2.2.1.post1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page