Running script¶

gwfast includes the executable calculate_forecasts_from_catalog.py that implements parallelisation routines, on top of the possibility to vectorise the calculation of the FIM, and is ready to use both on single machines and on clusters. This is ideal to use gwfast for forecasting parameter estimation capabilities for large catalogs of sources, which is the main purpose of the code.

To use this script it is necessary to store a catalog in h5 format in the folder data/. This can be done using the function gwfast.gwfastUtils.save_data.

After creating a folder to store the results, e.g.

$ mkdir my_results

it is possible to run the executable calculate_forecasts_from_catalog.py as

usage: calculate_forecasts_from_catalog.py [-h] --fname_obs FNAME_OBS
                                           --fout FOUT
                                           [--wf_model WF_MODEL]
                                           [--batch_size BATCH_SIZE]
                                           [--npools NPOOLS] [--snr_th SNR_TH]
                                           [--idx_in IDX_IN] [--idx_f IDX_F]
                                           [--fmin FMIN] [--fmax FMAX]
                                           [--compute_fisher COMPUTE_FISHER]
                                           [--net NET [NET ...]]
                                           [--netfile NETFILE]
                                           [--psds PSDS [PSDS ...]]
                                           [--mpi MPI]
                                           [--duty_factor DUTY_FACTOR]
                                           [--concatenate CONCATENATE]
                                           [--params_fix PARAMS_FIX [PARAMS_FIX ...]]
                                           [--rot ROT]
                                           [--lalargs LALARGS [LALARGS ...]]
                                           [--return_all RETURN_ALL]
                                           [--seeds SEEDS [SEEDS ...]]

Named Arguments¶

--fname_obs

Name of the file containing the catalog, without the extension h5.

Default: ''

--fout

Path to output folder, which has to exist before the script is launched.

Default: 'test_gwfast'

--wf_model

Name of the waveform model.

The names corresponding to the various waveform models described in Waveform models are:

'tf2' for gwfast.waveforms.TaylorF2_RestrictedPN;

'tf2_tidal' for gwfast.waveforms.TaylorF2_RestrictedPN including tidal effects;

'tf2_ecc' for gwfast.waveforms.TaylorF2_RestrictedPN including orbital eccentricity;

'IMRPhenomD' for gwfast.waveforms.IMRPhenomD;

'IMRPhenomD_NRTidalv2' for gwfast.waveforms.IMRPhenomD_NRTidalv2;

'IMRPhenomHM' for gwfast.waveforms.IMRPhenomHM;

'IMRPhenomNSBH' for gwfast.waveforms.IMRPhenomNSBH;

'LAL-wfname' for gwfast.waveforms.LAL_WF , with wfname being the name of the desired approximant present in LAL (e.g. 'LAL-IMRPhenomXPHM');

Note

In this case it is necessary to specify the waveform characteristics ('tidal', 'HM', 'precessing' and 'eccentric') through the ––lalargs argument.

'TEOBResumSPA' for gwfast.waveforms.TEOBResumSPA_WF ;

'TEOBResumSPA_tidal' for gwfast.waveforms.TEOBResumSPA_WF including tidal effects;

Default: 'tf2'

--batch_size

Size of the batch to be computed in vectorised form on each process.

Default: 1

--npools

Number of parallel processes.

Default: 1

--snr_th

Threshold value for the SNR to consider the event detectable. FIMs are computed only for events with SNR exceeding this value.

Default: 12.0

--idx_in

Index of the event in the catalog from which to start the calculation.

Default: 0

--idx_f

Index of the event in the catalog from which to end the calculation.

Default: None

--fmin

Minimum frequency of the grid, in \(\rm Hz\).

Default: 2.0

--fmax

Maximum frequency of the grid, in \(\rm Hz\). If not specified, this coincides with the cut frequency of the waveform.

Default: None

--compute_fisher

Int specifying if the FIMs have to be computed (1) or not (0).

Default: 1

--net

The network of detectors to be used, separated by single spacing.

It is possible to use the locations and orientations of the detectors are already provided in gwfast.gwfastGlobals.detectors, passing the corresponding keys.

Default: ['ETS']

--netfile

json file containing the detector configuration, alternative to ––net and ––psds.

The json files can be created using the gwfast.gwfastUtils.save_detectors function.

Default: None

--psds

The paths to PSDs of each detector in the network inside the folder psds/, separated by single spacing.

For a list and description of the available PSDs and ASDs see gwfast/psds.

Default: ['ET-0000A-18.txt']

--mpi

Int specifying if the code has to parallelise using multiprocessing (0), or using MPI (1), suitable for clusters.

Default: 0

--duty_factor

Duty factor of the detectors (the same is used for all detectors in a network).

Default: 1.0

--concatenate

Int specifying if the results of the individual batches have to be concatenated (1) or not (0).

Default: 1

--params_fix

List of parameters to fix to the fiducial values, i.e. to eliminate from the FIMs, separated by single spacing. The names have to be the same as in Parameters names and conventions.

Default: []

--rot

Int specifying if the effect of the rotation of the Earth has to be included in the analysis (1) or not (0).

Default: 1

--lalargs

Specifications of the waveform when using LAL interface, separated by single spacing.

The specifications can be:

'tidal' if the waveform includes tidal effects;

'HM' if the waveform includes the contribution of sub-dominant (higher-order) modes;

'precessing' if the waveform includes precessing spins;

'eccentric' if the waveform includes orbital eccentricity.

Default: []

--return_all

Int specifying if, in case a network of detectors is used, the SNRs and Fisher matrices of the individual detector have to be stored (1) or not (0).

Default: 0

--seeds

List of seeds to set for the duty factors in individual detectors, to help reproducibility, separated by single spacing.

Default: []

--jit_Fisher

Int specifying if the Fisher function has to be jit compiled (1) or not (0). This works only if computing derivatives using JAX.

Default: 0

Script outputs¶

The script will produce the following files in the output folder (in alphabetical order):

cond_numbers_idxs.txt: File containing the condition numbers of the FIMs of the detected events (i.e. having SNR > ––snr_th);

covs_idxs.npy: File containing the covariance matrices of the detected events (i.e. having SNR > ––snr_th). The order of the parameters is the one given in gwfast.waveforms.WaveFormModel.ParNums (with the exception of the parameters that have been fixed through ––params_fix);

detectors.json: File containing the detector configuration used, as produced by the gwfast.gwfastUtils.save_detectors function;

errors_idxs.txt: File containing the errors on the parameters for the detected events (i.e. having SNR > ––snr_th). The order of the parameters is the one given in gwfast.waveforms.WaveFormModel.ParNums (with the exception of the parameters that have been fixed through ––params_fix);

events_detected_idxs.hdf5: File containing the parameters of the detected events (i.e. having SNR > ––snr_th). This is a dictionary as events, saved through gwfast.gwfastUtils.save_data , that can be loaded through gwfast.gwfastUtils.load_population;

fishers_idxs.npy: File containing the FIMs of the detected events (i.e. having SNR > ––snr_th). The order of the parameters is the one given in gwfast.waveforms.WaveFormModel.ParNums (with the exception of the parameters that have been fixed through ––params_fix);

idxs_det_idxs.txt: File containing the indices of the detected events (i.e. having SNR > ––snr_th) in the original catalog;

inversion_errors_idxs.txt: File containing the inversion errors of the FIMs of the detected events (i.e. having SNR > ––snr_th);

sky_area_idxs.txt: File containing the 90% sky localisation areas of the detected events (i.e. having SNR > ––snr_th) in \(\rm deg^2\);

snrs_idxs.txt: File containing the SNRs of all the events in the original catalog;

Note

All the above files refer to quantities evaluated by the full detector network.

Note

The suffix idxs present in all file names refers to the initial and final indices of the events used in the original catalog. As an example, if using the events from 0 to 5000 in the original catalog, the suffix of all files will be 0_to_5000, e.g. snrs_0_to_5000.txt.

Note

The npy files can be loaded using the numpy.load function.

Also, if ––return_all= 1, the following files will be produced:

all_fishers_idxs.hdf5 : File containing a dictionary with the FIMs of the detected events (i.e. having SNR > ––snr_th), both for the full network and for the single detectors. The order of the parameters is the one given in gwfast.waveforms.WaveFormModel.ParNums (with the exception of the parameters that have been fixed through ––params_fix);

all_snrs_idxs.hdf5 : File containing a dictionary with the SNRs of all the events in the original catalog, both for the full network and for the single detectors.