PyFstat: a Python package for continuous gravitational-wave data analysis

Gravitational waves in the sensitivity band of ground-based detectors can be emitted by a number of astrophysical sources, including not only binary coalescences, but also individual spinning neutron stars. The most promising signals from such sources, although not yet detected, are long-lasting, quasi-monochromatic Continuous Waves (CWs). The PyFstat package provides tools to perform a range of CW data-analysis tasks. It revolves around the F-statistic, a matched-filter detection statistic for CW signals that has been one of the standard methods for LIGO-Virgo CW searches for two decades. PyFstat is built on top of established routines in LALSuite but through its more modern Python interface it enables a flexible approach to designing new search strategies. Hence, it serves a dual function of (i) making LALSuite CW functionality more easily accessible through a Python interface, thus facilitating the new user experience and, for developers, the exploratory implementation of novel methods; and (ii) providing a set of production-ready search classes for use cases not yet covered by LALSuite itself, most notably for MCMC-based followup of promising candidates from wide-parameter-space searches.

The PyFstat package provides tools to perform a range of CW data analysis tasks. It revolves around the F-statistic, first introduced by Jaranowski, Krolak, and Schutz (1998): a matched-filter detection statistic for CW signals described by a set of frequency evolution parameters and maximized over amplitude parameters. It has been one of the standard methods for LIGO-Virgo CW searches for two decades. PyFstat is built on top of established routines in LALSuite (LIGO Scientific Collaboration 2018) but through its more modern Python interface it enables a flexible approach to designing new search strategies.
Classes for various search strategies and target signals are contained in three main submodules: • core : The basic wrappers to LALSuite's F-statistic algorithm. End-users should rarely need to access these directly. • grid_based_searches : Classes to search over regular parameter-space grids.
Besides standard CWs from isolated neutron stars, PyFstat can also be used to search for CWs from sources in binary systems (including the additional orbital parameters), for CWs with a discontinuity at a pulsar glitch, and for CW-like long-duration transient signals e.g. from after a pulsar glitch. Specialized versions of both grid-based and MCMC-based search classes are provided for these scenarios. Both fully-coherent and semi-coherent searches (where the data is split into several segments for efficiency) are covered, and an extension to the F-statistic that is more robust against single-detector noise artifacts (Keitel et al. 2014) is also supported. While PyFstat's grid-based searches do not compete with the sophisticated grid setups and semi-coherent algorithms implemented in various LALSuite programs, its main scientific use cases so far are for the MCMC exploration of interesting parameter-space regions and for the long-duration transient case.
PyFstat was first introduced in Ashton and  which remains the main reference for the MCMC-based analysis implemented in the package. The extension to transient signals, which uses PyCUDA (Klöckner et al. 2012) for speedup, is discussed in detail in Keitel and Ashton (2018), and the glitch-robust search approaches in Ashton, Prix, and Jones (2018).
Additional helper classes, utility functions and internals are included for handling the common Short Fourier Transform (SFT) data format for LIGO data, simulating artificial data with noise and signals in them, and plotting results and diagnostics. Most of the underlying LALSuite functionality is accessed through SWIG wrappings (Wette 2020) though for some parts, such as the SFT handling, we still (as of the writing of this paper) call stand-alone lalapps executables. Completing the backend migration to pure SWIG usage is planned for the future.
The source of PyFstat is hosted on GitHub. The repository also contains an automated test suite and a set of introductory example scripts. Issues with the software can be submitted through GitHub and pull requests are always welcome. PyFstat can be installed through pip, conda or docker containers. Documentation in html and pdf formats is available from readthedocs.org and installation instructions can be found there or in the README file.

Statement of need
The sensitivity of searches for CWs and long-duration transient GWs is generally limited by computational resources, as the required number of matched-filter templates increases steeply for long observation times and wide parameter spaces. The C-based LALSuite library (LIGO Scientific Collaboration 2018) contains many sophisticated search methods with a long development history and high level of optimization, but is not very accessible for researchers new to the field or for students; nor is it convenient for rapid development and integration with modern technologies like GPUs or machine learning. Hence, PyFstat serves a dual function of (i) making LALSuite CW functionality more easily accessible through a Python interface, thus facilitating the new user experience and, for developers, the exploratory implementation of novel methods; and (ii) providing a set of productionready search classes for use cases not yet covered by LALSuite itself, most notably for MCMC-based followup of promising candidates from wide-parameter-space searches.