OctApps: a library of Octave functions for continuous gravitational-wave data analysis

Gravitational waves are minute ripples in spacetime, first predicted by Einstein's general theory of relativity in 1916. Gravitational waves from rapidly-rotating neutron stars, whose shape deviates from perfect axisymmetry, are a potential astrophysical source of gravitational waves, but which so far have not been detected. The search for this type of signals, also known as continuous waves, presents a significant data analysis challenge, as their weak signatures are expected to be buried deep within the instrumental noise of the LIGO and Virgo detectors. The OctApps library provides various functions, written in Octave, intended to aid research scientists who perform searches for continuous gravitational waves.


Summary
Gravitational waves are minute ripples in spacetime, first predicted by Einstein's general theory of relativity in 1916. Their existence has now been confirmed by the recent successful detections of gravitational waves from the collision and merger of binary black holes (Abbott 2016) and binary neutron stars (Abbott 2017) in data from the LIGO and Virgo gravitational-wave detectors. Gravitational waves from rapidly-rotating neutron stars, whose shape deviates from perfect axisymmetry, are another potential astrophysical source of gravitational waves, but which so far have not been detected. The search for this type of signals, also known as continuous waves, presents a significant data analysis challenge, as their weak signatures are expected to be buried deep within the instrumental noise of the LIGO and Virgo detectors. For reviews of continuous-wave sources, data analysis techniques, and recent searches of LIGO and Virgo data, see for example Prix (2009) and Riles (2017).
The OctApps library provides various functions, written in Octave (Eaton et al. 2015), intended to aid research scientists who perform searches for continuous gravitational waves. They are organized into the following directories: • src/cw-data-analysis: general-purpose functions for continuous-wave data analysis. • src/cw-line-veto: functions which implement detection statistics which are robust to instrumental disturbances in the detector data, as described in (Keitel et al. 2014). • src/cw-metric-template-banks: functions which determine the number of filtering operations required to search for continuous waves over various astrophysical parameter spaces, described further in (Wette and Prix 2013) and (Leaci and Prix 2015). • src/cw-optimal-search-setup: functions which determine the optimally-sensitive search for continuous gravitational waves, given a fixed computing budget, following the method of (Prix and Shaltev 2012). • src/cw-sensitivity: functions which predict the sensitivity of a search for continuous waves, following the method of (Wette 2012).
• src/cw-weave-models: functions which characterize the behaviour of Weave, an implementation of an optimized search pipeline for continuous waves (Wette et al. 2018).
Many of these scripts make use of C functions from the LSC Algorithm Library Suite (LALSuite), using SWIG to provide the C-to-Octave interface.
In addition, OctApps provides various general-purpose functions, which may be of broader interest to users of Octave, organized into the following directories: • src/array-handling: manipulation of Octave arrays and cell arrays.
• src/command-line: includes parseOptions(), a powerful parser for Octave function argument lists in the form of key-value pairs. Together with octapps_run, a Unix shell script, it allows Octave functions to also be called directly from the Unix command line using a --key=value argument syntax. • src/condor-jobs: submission of jobs to a computer cluster using the HTCondor job submission system. It includes depends(), a low-level function written using Octave's C++ API which, given the name of an Octave function, returns the names of all Octave functions called by the named function; it is used to deploy a self-contained tarball of Octave .m files to a remote node on a computer cluster. • src/convert-units: functions which convert between different angular units, and between different time standards. • src/file-handling: parsing of various file formats, such as FITS and .ini.
• src/geometry: mathematical operations associated with geometric objects, e.g. computing the intersection of two lines. • src/histograms: includes @Hist, an Octave class representing a histogram, with various method functions which perform common statistical operations, e.g. computing the cumulative distribution function. • src/lattices: mathematical operations associated with lattice theory, e.g. computing the nearest point in a lattice to a given point in space. • src/mathematical: miscellaneous general mathematical functions, including some C functions incorporated from the GNU Scientific Library (Galassi 2009), using SWIG to provide the C-to-Octave interface. • src/plotting: helper functions for plot creation and output in TeX format. • src/statistics: miscellaneous statistical functions, particularly for probability distributions. • src/text-handling: various functions for creating formatted text output.
• src/version-handling: handling of version information, particularly from the Git version control system.
Development of OctApps is hosted on GitHub; a test suite of all functions in OctApps is regularly integrated on Travis CI. The README file provides instructions for building, testing, and contributing to OctApps, as well as a full list of prerequisite software required by OctApps. A reference manual for OctApps in HTML format is available; documentation of each OctApps function can also be accessed through the help function in Octave.