README.md 4.87 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.
66
67
68
* [pycuda](https://pypi.org/project/pycuda/), required for the tCWFstatMapVersion=pycuda
  option of the TransientGridSearch class.
  (Note: 'pip install pycuda' requires a working nvcc compiler in your path.)
Gregory Ashton's avatar
Gregory Ashton committed
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

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
86
87
88

### `pyfstat` installation

89
The script can be installed system wide, assuming you are in the source directory, via
90
```
91
$ python setup.py install
92
```
93
94
95
96
97
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
98
99
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.
100
101
102
103

### Ephemeris installation

The scripts require a path to ephemeris files in order to use the
104
`lalpulsar.ComputeFstat` module. This can either be 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
here, we use the default ephemeris files provided with `lalsuite`.
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}}
}
```