This page contains basic information about the PyFstat package, including installation instructions, a contributing guide and the proper way to cite the package and the underlying scientific literature. This is equivalent to the package’s file .

See here for the full API documentation.


This is a python package providing an interface to perform F-statistic based continuous gravitational wave (CW) searches, built on top of the LALSuite library.

Getting started:

PyPI version Conda version DOI ASCL JOSS Docker Binder Integration Tests codecov Documentation Status Code style: black


PyFstat releases can be installed in a variety of ways, including ``pip install` from PyPI <#pip-install-from-PyPi>`_, conda, Docker/Singularity images, and from source releases on Zenodo. Latest development versions can also be installed with pip or from a local git clone.

If you don’t have a recent python installation (3.7+) on your system, then Docker or conda are the easiest paths.

In either case, be sure to also check out the notes on dependencies and citing this work.

If you run into problems with ephemerides files, check the wiki page on ephemerides installation.

pip install from PyPI

PyPI releases are available from

A simple

pip install pyfstat

should give you the latest release version with all dependencies; recent releases now also include a sufficient minimal set of ephemerides files.

If you are not installing into a venv or conda environment (you really should!), on many systems you may need to use the --user flag.

Note that the PyFstat installation will fail at the LALSuite dependency stage if your pip is too old (e.g. 18.1); to fix this, do

pip install --upgrade pip setuptools

conda installation

See this wiki page for further instructions on installing conda itself, installing PyFstat into an existing environment, or for a minimal .yml recipe to set up a PyFstat-specific environment.

If getting PyFstat from conda-forge, it already includes the required ephemerides files.

Docker container

Ready-to-use PyFstat containers are available at the Packages page. A GitHub account together with a personal access token is required. Go to the wiki page to learn how to pull them from the GitHub registry using Docker or Singularity.

pip install from github

Development versions of PyFstat can also be easily installed by pointing pip directly to this git repository, which will give you the latest version of the master branch:

pip install git+

or, if you have an ssh key installed in github:

pip install git+ssh://

This should pull in all dependencies in the same way as installing from PyPI, and recent lalsuite dependencies will include ephemerides files too.

install PyFstat from source (Zenodo or git clone)

You can download a source release tarball from Zenodo and extract to an arbitrary temporary directory. Alternatively, clone this repository:

git clone

The module and associated scripts can be installed system wide (or to the currently active venv), assuming you are in the (extracted or cloned) source directory, via

python install

As a developer, alternatively

python develop


pip install -e /path/to/PyFstat

can be useful so you can directly see any changes you make in action. Alternatively (not recommended!), add the source directory directly to your python path.

To check that the installation was successful, run

python -c 'import pyfstat'

if no error message is output, then you have installed pyfstat. Note that the module will be installed to whichever python executable you call it from.

This should pull in all dependencies in the same way as installing from PyPI, and recent lalsuite dependencies will include ephemerides files too.


PyFstat uses the following external python modules, which should all be pulled in automatically if you use pip:

For a general introduction to installing modules, see here.

Optional dependencies

PyFstat manages optional dependencies through setuptool’s extras_require.

Available sets of optional dependencies are:

  • chainconsumer (Samreay/Chainconsumer): Required to run some optional plotting methods and some of the example scripts.

  • pycuda (PyPI): Required for the tCWFstatMapVersion=pycuda option of the TransientGridSearch class. (Note: Installing pycuda requires a working nvcc compiler in your path.)

  • style: Includes the flake8 linter ([flake8.pycqa](, black style checker (black.readthedocs), and isort for import ordering ( These checks are required to pass by the online integration pipeline.

  • test: For running the test suite locally using [pytest]( and some of its addons (python -m pytest tests/).

  • wheel: Includes wheel and check-wheel-contents.

  • dev: Collects style, test and wheel.

  • docs: Required dependencies to build the documentation.

Installation can be done by adding one or more of the aforementioned tags to the installation command.

For example, installing PyFstat including chainconsumer, pycuda and style dependencies would look like (mind the lack of whitespaces!)

pip install pyfstat[chainconsumer,pycuda,style]

This command accepts the “development mode” tag -e.

Using LALSuite built from source

If you prefer to make your own LALSuite installation from source, make sure it is swig-enabled and contains at least the lalpulsar and lalapps packages.

Following the instructions from their README, at the step where it tells you to run ./configure, an example minimal line would be e.g.:

./configure --prefix=${HOME}/lalsuite-install --disable-all-lal --enable-lalpulsar --enable-lalapps --enable-swig-python

Then after the make && make install step, you can point your environment to this installation by doing

source ${HOME}/lalsuite-install/etc/

You have to redo this in every new session, unless you tweak your venv / conda env activation script to do it automatically.

Alternatively, Python’s built-in site package can be used to direct the Python interpreter to the right LALSuite installation using site-packages. To do so, add the following minimal script to one of the available site-packages paths (which can be retrieved using python -c 'import site; print( site.getsitepackages())'):
import os
import sys

custom_lalsuite_lib = "${HOME}/lalsuite-install/lib/pythonX.Y/site-packages"
custom_lalsuite_bin = "${HOME}/lalsuite-install/lib/pythonX.Y/site-packages"

sys.path.insert(0, custom_lalsuite_lib)
os.environ["PATH"] = (custom_lalsuite_bin + os.pathsep) + os.environ["PATH"]

where pythonX.Y is dependent upon the Python version with which LALSuite was installed and ${HOME} may be substituted by any path of your choice.

Contributing to PyFstat

This project is open to development, please feel free to contact us for advice or just jump in and submit an issue or pull request.

Here’s what you need to know:

  • As a developer, you should install directly from a git clone, with either pip install -e .[dev] into some environment or creating a development-enabled conda environment directly from the pyfstat-dev.yml file as explained on this wiki page. Please also run, just once after installing:

    pre-commit install

    This sets up everything for automated code quality tests (see below) to be checked for you at every commit.

  • The github automated tests currently run on python [3.7,3.8,3.9,3.10] and new PRs need to pass all these.

  • You can also run the full test suite locally via pytest tests/, or run individual tests as explained on this page.

  • The automated test on github also runs the black style checker, the flake8 linter, and the isort import ordering helper.

  • If you have installed the dev dependencies correctly via pip or conda, and ran pre-commit install once, then you’re ready to let the pre-commit tool do all of this automatically for you every time you do git commit. For anything that would fail on the github integration tests, it will then either automatically reformat your code to match our style or print warnings for things to fix. The first time it will take a while for setup, later it should be faster.

  • If for some reason you can’t use pre-commit, you can still manually run these tools before pushing changes / submitting PRs: isort . to sort package imports, flake8 --count --statistics . to find common coding errors and then fix them manually, black --check --diff . to show the required style changes, or black . to automatically apply them.



  • Greg Ashton

  • David Keitel

Active contributors:

  • Reinhard Prix

  • Rodrigo Tenorio

Other contributors:

  • Karl Wette

  • Sylvia Zhu

  • Dan Foreman-Mackey (pyfstat.gridcorner is based on DFM’s

Citing this work

If you use PyFstat in a publication we would appreciate if you cite both a release DOI for the software itself (see below) and one or more of the following scientific papers:

If you’d additionally like to cite the PyFstat package in general, please refer to the version-independent Zenodo listing or use directly the following BibTeX entry:

  author       = {Ashton, Gregory and
                  Keitel, David and
                  Prix, Reinhard
                  and Tenorio, Rodrigo},
  title        = {{PyFstat}},
  month        = jul,
  year         = 2020,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.3967045},
  url          = {},
  note         = {\url{}}

You can also obtain DOIs for individual versioned releases (from 1.5.x upward) from the right sidebar at Zenodo.

Alternatively, if you’ve used PyFstat up to version 1.4.x in your works, the DOIs for those versions can be found from the sidebar at this older Zenodo record and please amend the BibTeX entry accordingly.

PyFstat uses the ``ptemcee` sampler <>`_, which can be cited as Vousden, Far & Mandel 2015 (ADS:2016MNRAS.455.1919V) and Foreman-Mackey, Hogg, Lang, and Goodman 2012 (2013PASP..125..306F).

PyFstat also makes generous use of functionality from the LALSuite library and it will usually be appropriate to also cite that project (see this recommended bibtex entry) and also Wette 2020 (inspire:1837108 / ADS:2020SoftX..1200634W) for the C-to-python SWIG bindings.