Metadata-Version: 2.1
Name: gwfast
Version: 1.1.1
Summary: A fisher matrix python package for GW studies
Home-page: https://github.com/CosmoStatGW/gwfast
License: GNU GPLv3
Keywords: python,automatic-differentiation,gravitational-waves,fisher-information,jax
Author: Francesco Iacovelli
Author-email: francesco.iacovelli@unige.ch
Requires-Python: >=3.8
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Provides-Extra: docs
Provides-Extra: lal
Provides-Extra: teobresum
Requires-Dist: astropy (>=5.2.1,<6.0.0)
Requires-Dist: docutils (>=0.17.1,<0.18.0) ; extra == "docs"
Requires-Dist: h5py (>=3.2.1,<4.0.0)
Requires-Dist: jax[cpu] (>=0.2.20,<0.4.0)
Requires-Dist: lalsuite ; extra == "lal"
Requires-Dist: mpmath (>=1.2.1,<2.0.0)
Requires-Dist: myst-parser (>=0.18.1,<0.19.0) ; extra == "docs"
Requires-Dist: nbsphinx (>=0.8.10) ; extra == "docs"
Requires-Dist: numdifftools (>=0.9.40)
Requires-Dist: numpy (>=1.20.3)
Requires-Dist: readthedocs-sphinx-search (>=0.1.2,<0.2.0) ; extra == "docs"
Requires-Dist: schwimmbad (>=0.3.2,<0.4.0)
Requires-Dist: scipy (>=1.6.3)
Requires-Dist: sphinx (==5.3.0) ; extra == "docs"
Requires-Dist: sphinx-copybutton (>=0.5.1,<0.6.0) ; extra == "docs"
Requires-Dist: sphinx_rtd_theme (>=1.1.1) ; extra == "docs"
Requires-Dist: teobresums ; extra == "teobresum"
Project-URL: Documentation, https://gwfast.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/CosmoStatGW/gwfast
Description-Content-Type: text/markdown

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.18914.svg)](http://dx.doi.org/10.5281/zenodo.7060236) [![Documentation Status](https://readthedocs.org/projects/gwfast/badge/?version=latest)](https://gwfast.readthedocs.io/en/latest/?badge=latest) <a href="https://ascl.net/2212.001"><img src="https://img.shields.io/badge/ascl-2212.001-blue.svg?colorB=262255" alt="ascl:2212.001" /></a>[![INSPIRE](https://img.shields.io/badge/INSPIRE-Iacovelli:2022bbs-001529.svg)](https://inspirehep.net/literature/2106524) [![INSPIRE](https://img.shields.io/badge/INSPIRE-Iacovelli:2022mbg-001529.svg)](https://inspirehep.net/literature/2112457)

![alt text](<https://raw.githubusercontent.com/CosmoStatGW/gwfast/master/gwfast_logo_bkgd.png>)

# gwfast
Fisher Information Matrix package for GW cosmology, written in Python and based on automatic differentiation.

The detail of implementations and results can be found in the papers [arXiv:2207.02771](<https://arxiv.org/abs/2207.02771>) and [arXiv:2207.06910](<https://arxiv.org/abs/2207.06910>).

Waveforms are also separatley released as [WF4Py](<https://github.com/CosmoStatGW/WF4Py>).

Developed by [Francesco Iacovelli](<https://github.com/FrancescoIacovelli>) and [Michele Mancarella](<https://github.com/Mik3M4n>).

## Code Organization
The organisation of the repository is the following:

```
gwfast/gwfast/
			├── gwfastGlobals.py 
					Physical constants, positions and duty cycles of existing detectors
			├── gwfastUtils.py
					Auxiliary functions: angles and time conversions, ...
			├── waveforms.py
					Abstract class WaveFormModel; different sublasses for each wf model - TaylorF2, IMRPhenomD, ...
			├── signal.py
					A class to compute the GW signal in a single detector (L shaped or triangular), the SNR and the Fisher matrix
			├── fisherTools.py
					Covariance matrix and functions to perform sanity checks on the Fisher - condition number, inversion error, marginalization, localization area, plotting tools
			├── network.py
					A class to model a network of detectors with different locations

gwfast/psds/ 
			Some detector Power Spectral Densities 
			
gwfast/WFfiles/ 
			Text files needed for waveform computation
			
gwfast/run/
			Script to run in parallel on catalogs
			
gwfast/docs/ 
			Code documentation in Sphinx
						
```

## Summary

* [Documentation](https://github.com/CosmoStatGW/gwfast#Documentation)
* [Installation](https://github.com/CosmoStatGW/gwfast#Installation)
* [Usage](https://github.com/CosmoStatGW/gwfast#Usage)
* [Citation](https://github.com/CosmoStatGW/gwfast#Citation)

## Documentation

gwfast has its documentation hosted on Read the Docs [here](<https://gwfast.readthedocs.io/en/latest/>), and it can also be built from the ```docs``` directory.

## Installation
To install the package without cloning the git repository, and a CPU-only version of JAX 

```
pip install --upgrade pip
pip install gwfast
```

or 

```
pip install --upgrade pip
pip install --upgrade "jax[cpu]" 
pip install git+https://github.com/CosmoStatGW/gwfast
```

To install a JAX version for GPU or TPU proceed as explained in [https://github.com/google/jax#installation](<https://github.com/google/jax#installation>).


## Usage

All details are reported in the accompanying paper [arXiv:2207.06910](<https://arxiv.org/abs/2207.06910>) and some examples are in the [gwfast_tutorial](<https://github.com/CosmoStatGW/gwfast/blob/master/notebooks/gwfast_tutorial.ipynb>) notebook.

To initialise a *waveform* object simply run, e.g.

```python
mywf = waveforms.IMRPhenomD()
```
(more details on the waveforms are available in their dedicated git repository [WF4Py](<https://github.com/CosmoStatGW/WF4Py>))

and to build a *signal* object 

```python
MyDet = signal.GWSignal(mywf, psd_path= 'path/to/Detector/psd',
 						detector_shape = 'L', det_lat=43.6, 
 						det_long=10.5, det_xax=115.) 
```

More signal objects can be used to form a *network*

```python
myNet = network.DetNet({'Det1':MyDet1, 'Det2':MyDet2, ...}) 
```

Then computing **SNRs** and **Fisher matrices** is as easy as

```python
SNRs = myNet.SNR(events) 
FisherMatrs = myNet.FisherMatr(events)  
```
where ```events ``` is a dictionary containing the parameters of the chosen events.

Finally, to compute the **covariance matrices** it is sufficient to

```python
CovMatr(FisherMatrs, events) 
```

#### For a list of features implemented after the publication of [arXiv:2207.06910](<https://arxiv.org/abs/2207.06910>) see the [NEW_FEATURES](<https://github.com/CosmoStatGW/gwfast/blob/master/NEW_FEATURES.md>) file and the [new\_features_tutorial](<https://github.com/CosmoStatGW/gwfast/blob/master/notebooks/new_features_tutorial.ipynb>) notebook

## Citation

If using this software, please cite this repository and the papers [arXiv:2207.02771](<https://arxiv.org/abs/2207.02771>) and [arXiv:2207.06910](<https://arxiv.org/abs/2207.06910>). Bibtex:

```
@article{Iacovelli:2022bbs,
    author = "Iacovelli, Francesco and Mancarella, Michele and Foffa, Stefano and Maggiore, Michele",
    title = "{Forecasting the Detection Capabilities of Third-generation Gravitational-wave Detectors Using GWFAST}",
    eprint = "2207.02771",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    doi = "10.3847/1538-4357/ac9cd4",
    journal = "Astrophys. J.",
    volume = "941",
    number = "2",
    pages = "208",
    year = "2022"
}
```

```
@article{Iacovelli:2022mbg,
    author = "Iacovelli, Francesco and Mancarella, Michele and Foffa, Stefano and Maggiore, Michele",
    title = "{GWFAST: A Fisher Information Matrix Python Code for Third-generation Gravitational-wave Detectors}",
    eprint = "2207.06910",
    archivePrefix = "arXiv",
    primaryClass = "astro-ph.IM",
    doi = "10.3847/1538-4365/ac9129",
    journal = "Astrophys. J. Supp.",
    volume = "263",
    number = "1",
    pages = "2",
    year = "2022"
}
```
# gwfast documentation

## Documentation requirements

In order to build the documentation, the following packages have to be installed

* [```sphinx```](<https://www.sphinx-doc.org/en/master>)
* [```sphinx_rtd_theme```](<https://sphinx-rtd-theme.readthedocs.io/en/stable/>)
* [```nbsphinx```](<https://nbsphinx.readthedocs.io/en/0.8.11/>)
* [```myst-parser```](<https://myst-parser.readthedocs.io/en/latest/>)
* [```sphinx-copybutton```](<https://sphinx-copybutton.readthedocs.io/en/latest/?badge=latest>)
* [```readthedocs-sphinx-search```](<https://readthedocs-sphinx-search.readthedocs.io/en/latest/>)
* [```docutils```](<https://docutils.sourceforge.io>)

To install them just run in the terminal 

```
pip install --upgrade pip
pip install -r docs/docs_requirements.txt
```

## Build the documentation

The HTML documentation can easily be built from the ```docs``` folder, running in the terminal 

```
cd docs/
make html
```

The produced ```.html``` files will be stored in the directory ```./build/html```.

It is also possible to build a LaTex version, running in the terminal 

```
make latexpdf
```

the output pdf of this command will be ```./build/latex/gwfast.pdf```.

# gwfast/psds
We here list the sources of the available Power Spectral Densities, PSDs, or Amplitude Spectral Densities, ASDs available in GWFast, in alphabetical order

### ce\_strain/

Cosmic Explorer ASDs from [*Science-Driven Tunable Design of Cosmic Explorer Detectors*](https://arxiv.org/abs/2201.10668), available at [https://dcc.cosmicexplorer.org/cgi-bin/DocDB/ShowDocument?.submit=Identifier&docid=T2000017&version=](https://dcc.cosmicexplorer.org/cgi-bin/DocDB/ShowDocument?.submit=Identifier&docid=T2000017&version=).

The folder contains ASDs for:

* the baseline 40km detector (```cosmic_explorer```)
* the baseline 20 km detector compact binary tuned (```cosmic_explorer_20km```)
* the 20 km detector tuned for post-merger signals (```cosmic_explorer_20km_pm```)
* the 40 km detector tuned for low-freqency signals (```cosmic_explorer_40km_lf```)

### ET\_designs\_comparison\_paper/

Einstein Telescope ASDs from [*Science with the Einstein Telescope: a comparison of different designs*](https://arxiv.org/abs/2303.15923), available at [https://apps.et-gw.eu/tds/?content=3&r=18213](https://apps.et-gw.eu/tds/?content=3&r=18213).

The folder contains two subfolders with ASDs for:

* the high frequency (HF) only ET instrument with a length of 10 km (```ETLength10km```), 15 km (```ETLength15km```) and 20 km (```ETLength20km```), in the **HF_only/** folder
* the full high frequency (HF) and low frequency (LF) ET instrument in the cryogenic design with a length of 10 km (```ETLength10km```), 15 km (```ETLength15km```) and 20 km (```ETLength20km```), in the **HFLF_cryo/** folder


### ET-0000A-18.txt

Public [ET-D](https://arxiv.org/abs/1012.0908) sensnitivity curve. 

Available at [https://apps.et-gw.eu/tds/?content=3&r=14065](https://apps.et-gw.eu/tds/?content=3&r=14065). Notice that we kept only the first and last column of the file, corresponding to the frequencies and the total ET-D sensitivity, obtained combining the LF and HF instruments.

### LVC_O1O2O3/

The folder contains ASDs for the LIGO and Virgo detectors during their O1, O2 and O3 observing runs, extracted in specific moment from actual data.

Available at [https://dcc.ligo.org/P1800374/public/](https://dcc.ligo.org/P1800374/public/) for O1 and O2, [https://dcc.ligo.org/LIGO-P2000251/public](https://dcc.ligo.org/LIGO-P2000251/public) for O3a, and computed using [PyCBC](https://pycbc.org) around the times indicated in the caption of Fig. 2 of [https://arxiv.org/abs/2111.03606](https://arxiv.org/abs/2111.03606).

### observing\_scenarios\_paper/

ASDs used for the paper [*Prospects for observing and localizing gravitational-wave transients with Advanced LIGO, Advanced Virgo and KAGRA*, KAGRA Collaboration, LIGO Scientific Collaboration and Virgo Collaboration](https://link.springer.com/article/10.1007/s41114-020-00026-9).

Available at [https://dcc.ligo.org/LIGO-T2000012/public](https://dcc.ligo.org/LIGO-T2000012/public). 

The folder contains ASDs for the Advanced LIGO, Advanced Virgo and KAGRA detectors during the O3, O4 and O5 observing runs.

### unofficial\_curves\_all\_dets/

Public ASDs for both the current and future generation of detectors (last update in January 2020). 

Available at [https://dcc.ligo.org/LIGO-T1500293/public](https://dcc.ligo.org/LIGO-T1500293/public), in the *curves\_Jan\_2020.zip* file.
  
The folder contains ASDs for:

* Advanced LIGO and Advanced Virgo during both the O1, O2 and O3 runs, at design sensitivity and in the *Advanced plus* stage;
* KAGRA;
* LIGO Voyager;
* ET-D;
* CE1 and CE2.

