gwfast 1.1.2

A fisher matrix python package for GW studies

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 and arXiv:2207.06910.

Waveforms are also separatley released as WF4Py.

Developed by Francesco Iacovelli and Michele Mancarella.

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
• Installation
• Usage
• Citation

Documentation

gwfast has its documentation hosted on Read the Docs here, 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.

If willing to use numerical differentiation, a patch has to be applied to numdifftools. This can be done by running the following command while being in the environment gwfast has been installed into

patch $(python -c "import site; print(site.getsitepackages()[0])")"/numdifftools/limits.py" $(python -c "import site; print(site.getsitepackages()[0])")"/gwfast/.patch/patch_ndt_complex_0-9-41.patch

Usage

All details are reported in the accompanying paper arXiv:2207.06910 and some examples are in the gwfast_tutorial notebook.

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

mywf = waveforms.IMRPhenomD()

(more details on the waveforms are available in their dedicated git repository WF4Py)

and to build a signal object

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

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

Then computing SNRs and Fisher matrices is as easy as

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

CovMatr(FisherMatrs, events) 

For a list of features implemented after the publication of arXiv:2207.06910 see the NEW_FEATURES file and the new_features_tutorial notebook

Citation

If using this software, please cite this repository and the papers arXiv:2207.02771 and arXiv: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
• sphinx_rtd_theme
• nbsphinx
• myst-parser
• sphinx-copybutton
• readthedocs-sphinx-search
• docutils

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, available at 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, available at 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 sensnitivity curve.

Available at 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/ for O1 and O2, https://dcc.ligo.org/LIGO-P2000251/public for O3a, and computed using PyCBC around the times indicated in the caption of Fig. 2 of 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.

Available at 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, 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.