khunsang / gwfast

A Fisher information matrix python package for GW detector networks.

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.

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"
}