README.md 4.86 KB
Newer Older
1 2
# PyFstat

Gregory Ashton's avatar
Gregory Ashton committed
3
This is a python package providing an interface to perform F-statistic based
4
continuous gravitational wave (CW) searches.
Gregory Ashton's avatar
Gregory Ashton committed
5

6
For documentation, please use the [wiki](https://gitlab.aei.uni-hannover.de/GregAshton/PyFstat/wikis/home).
7

Gregory Ashton's avatar
Gregory Ashton committed
8 9 10 11 12
In the
[examples](https://gitlab.aei.uni-hannover.de/GregAshton/PyFstat/tree/master/examples),
we have a number of scripts demonstrating different use cases.


13 14
## Installation

Gregory Ashton's avatar
Gregory Ashton committed
15 16 17 18 19 20 21 22 23 24
### `python` installation
The scripts are written in `python 2.7+` and therefore require a working
`python` installation. While many systems come with a system wide python
installation, it can often be easier to manage a user-specific python
installation. This way one does not require root access to install or remove
modules. One method to do this, is to use the `conda` system, either through
the stripped down [miniconda](http://conda.pydata.org/miniconda.html)
installation, or the full-featured
[anaconda](https://www.continuum.io/downloads) (these are essentially the
same, but the `anaconda` version installs a variety of useful packages such as
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
`numpy` and `scipy` by default).

The fastest/easiest method is to follow your OS instructions
[here](https://conda.io/docs/install/quick.html) which will install Miniconda.

For the rest of this tutorial, we will make use of `pip` to install modules (
not all packages can be installed with `conda` and for those using alternatives
to `conda`, `pip` is more universal).

This can be installed with
```
$ conda install pip
```

### Clone the repository

Gregory Ashton's avatar
Gregory Ashton committed
41
In a terminal, clone the directory:
42 43

```
Gregory Ashton's avatar
Gregory Ashton committed
44
$ git clone https://gitlab.aei.uni-hannover.de/GregAshton/PyFstat.git
45
```
Gregory Ashton's avatar
Gregory Ashton committed
46 47 48

### Dependencies

Gregory Ashton's avatar
Gregory Ashton committed
49
`pyfstat` makes uses the following external python modules:
Gregory Ashton's avatar
Gregory Ashton committed
50 51

* [numpy](http://www.numpy.org/)
52
* [matplotlib](http://matplotlib.org/) >= 1.4
Gregory Ashton's avatar
Gregory Ashton committed
53
* [scipy](https://www.scipy.org/)
Gregory Ashton's avatar
Gregory Ashton committed
54
* [ptemcee](https://github.com/willvousden/ptemcee)
Gregory Ashton's avatar
Gregory Ashton committed
55 56
* [corner](https://pypi.python.org/pypi/corner/)
* [dill](https://pypi.python.org/pypi/dill)
David Keitel's avatar
David Keitel committed
57
* [peakutils](https://pypi.python.org/pypi/PeakUtils)
Gregory Ashton's avatar
Gregory Ashton committed
58 59

*Optional*
Gregory Ashton's avatar
Gregory Ashton committed
60 61
* [tqdm](https://pypi.python.org/pypi/tqdm)(optional), if installed, this
  provides a useful progress bar and estimate of the remaining run-time.
Gregory Ashton's avatar
Gregory Ashton committed
62 63
* [bashplotlib](https://github.com/glamp/bashplotlib), if installed, presents
  a histogram of the loaded SFT data
64 65
* [pathos](https://pypi.python.org/pypi/pathos), if installed, this provides
  support for multiprocessing some functions.
Gregory Ashton's avatar
Gregory Ashton committed
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82

For an introduction to installing modules see
[here](https://docs.python.org/3.5/installing/index.html). If you are using
`pip`, to install all of these modules, run
```
$ pip install -r /PATH/TO/THIS/DIRECTORY/requirements.txt
```

In addition to these modules, you also need a working **swig-enabled**
[`lalapps`](http://software.ligo.org/docs/lalsuite/lalsuite/) with
  at least `lalpulsar`. A minimal confuration line to use when installing
`lalapps` is

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

Gregory Ashton's avatar
Gregory Ashton committed
83 84 85

### `pyfstat` installation

86
The script can be installed system wide, assuming you are in the source directory, via
87
```
88
$ python setup.py install
89
```
90 91 92 93 94
or simply add this directory to your python path. To check that the installation
was successful, run
```
$ python -c 'import pyfstat'
```
Gregory Ashton's avatar
Gregory Ashton committed
95 96
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.
97 98 99

### Ephemeris installation

100 101 102 103 104
The scripts require paths to earth and sun ephemeris files in order to use the
`lalpulsar.ComputeFstat` module. This should be automatically picked up from
the $LALPULSAR_DATADIR environment variable, defaulting to the
00-40-DE421 ephemerides or 00-19-DE421 as a backup.
Alternatively, these can either be manually specified when initialising
Gregory Ashton's avatar
Gregory Ashton committed
105 106
each search (as one of the arguments), or simply by placing a file
`~/.pyfstat.conf` into your home directory which looks like
107 108 109 110 111

```
earth_ephem = '/home/<USER>/lalsuite-install/share/lalpulsar/earth00-19-DE421.dat.gz'
sun_ephem = '/home/<USER>/lalsuite-install/share/lalpulsar/sun00-19-DE421.dat.gz'
```
112
Paths set in this way will take precedence over the environment variable.
113

Gregory Ashton's avatar
Gregory Ashton committed
114
### Contributors
115

Gregory Ashton's avatar
Gregory Ashton committed
116 117 118 119 120 121 122 123
* Greg Ashton
* David Keitel
* Reinhard Prix
* Karl Wette
* Sylvia Zhu

This project is open to development, please feel free to contact us
for advice or just jump in and submit a pull request.
Gregory Ashton's avatar
Gregory Ashton committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

## Citing this work

If you use `PyFstat` in a publication we would appreciate if you cite the
original paper introducing the code, the [ADS page can be found
here](http://adsabs.harvard.edu/abs/2018arXiv180205450A) and the version
release:

```
@misc{pyfstat,
  author       = {{Ashton}, G. and {Keitel}, D.},
  title        = {{PyFstat-v1.2}},
  month        = may,
  year         = 2018,
  doi          = {10.5281/zenodo.1243931},
  url          = {https://doi.org/10.5281/zenodo.1243931},
  note= {\url{https://doi.org/10.5281/zenodo.1243931}}
}
```