Detector networks

The network module allows to build a detector network, made up of single gwfast.signal.GWSignal objects. We here present the core class, gwfast.network.DetNet, and its methods.

Initialising a detector network

A detector network object can be initialised as follows from multiple gwfast.signal.GWSignal objects

class gwfast.network.DetNet(signals, verbose=True)[source]

Class to build a network of multiple detectors.

The functions defined within this class allow to get e.g. the network SNR and Fisher matrix.

Parameters

  • signals (dict(GWSignal, ...)) – Dictionary containing one or multiple individual detector objects.

  • verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.

It is possible to initialise all the seed s for the duty cycle, i.e. the percentage of time each detector is supposed to be operational, using

DetNet._update_all_seeds(seeds=[], verbose=True)[source]

Update the seeds for the duty cycle in each individual detector with user input values.

Parameters

  • seeds (list(int)) – User input values for the seeds.

  • verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.

Also, to store a detector configuration in a json file, it is possible to use the function

gwfast.gwfastUtils.save_detectors(fname, detectors)[source]

Store a collection of dictionaries containing the detector characteristics in json file.

Parameters

  • fname (str) – The name of the file to store the detector characteristics in. This has to include the path and the json extension.

  • detectors (dict(dict, dict, ...)) – The collection of dictionaries conatining the detector characteristics (lat, long, xax and psd_path if desired), as in gwfast.gwfastGlobals.detectors.

Definition of SNR and Fisher for a detector network

In Formalism setup we introduced how the SNRs and FIM for a single detector are defined. We here generalise the definition to a detector network.

When considering a detector network, the network SNR can be simply computed as the sum in quadrature of the SNRs in each individual detector

(1)\[{\rm SNR} = \sqrt{\sum_{\rm d\in dets} {\rm SNR}_d^2}\]

Similarly, when considering a detector network, the total FIM can be simply computed as the sum of the FIMs in each individual detector

(2)\[\Gamma_{ij} = \sum_{\rm d\in dets} \Gamma_{ij}^{(d)}\]

SNR computation in a detector network

To compute the network SNR defined in eq. (1), for one or multiple events, it is sufficient to use the function

DetNet.SNR(evParams, res=1000, return_all=False)[source]

Compute the network signal-to-noise-ratio, SNR, as a function of the parameters of the event(s).

Parameters

  • evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.

  • res (int) – The resolution of the frequency grid to use.

  • return_all (bool, optional) – Boolean specifying if the SNRs of the individual detectors have to be returned separately, together with the network SNR(s). In this case the return type is dict(array, array, …).

Returns

Network SNR(s) as a function of the parameters of the event(s). The shape is \((N_{\rm events})\).

Return type

1-D array

Fisher matrix computation in a detector network

To compute the total network FIM defined in eq. (2), for one or multiple events, it is sufficient to use the function

DetNet.FisherMatr(evParams, return_all=False, return_derivatives=False, return_SNR_derivatives=False, **kwargs)[source]

Compute the total Fisher information matrix, FIM, as a function of the parameters of the event(s).

Parameters

  • evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.

  • return_all (bool, optional) – Boolean specifying if the FIMs of the individual detectors have to be returned separately, together with the network FIM(s). In this case the return type is dict(array, array, …).

  • return_derivatives (bool, optional) – Boolean specifying if the derivatives of the individual detectors have to be returned (all separately). In this case return_all is set to True the return type is dict(array, array, …), dict(array, array, …).

  • return_SNR_derivatives (bool, optional) – Boolean specifying if the derivatives of the SNR have to be returned. In this case return_all is set to True, return_derivatives is set to False and the return type is dict(array, array, …), dict(array, array, …).

  • kwargs – Optional arguments to be passed to gwfast.signal.GWSignal.FisherMatr, such as res or use_m1m2.

Returns

FIM(s) as a function of the parameters of the event(s). The shape is \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).

Return type

3-D array

Note

We recall that the order (row/column numbers) in which the parameters appear in the FIM is stored in the gwfast.waveforms.WaveFormModel.ParNums attribute of the gwfast.waveforms.WaveFormModel object.

Optimal location for a detector network

gwfast provides a method to compute the optimal location in the sky for a signal to be detected with the highest possible SNR at a given time. This is obtained maximising the sum in quadrature of the Pattern functions of the individual detectors, and the computation assumes \(\psi=0\).

To compute the optimal \(\theta\) and \(\phi\) sky coordinates for a detector network it is possible to use

DetNet.optimal_location(tcoal, is_tGPS=False)[source]

Compute the optimal sky position for a signal to be seen by the detector at a given time.

The computation assumes \(\psi = 0\).

Parameters

  • tcoal (float) – The time at which to compute the optimal location, as GMST in days.

  • is_tGPS (bool, optional) – Boolean specifying if the provided time is a GPS time (in seconds) rather than a GMST.

Returns

Optimal \(\theta\) and \(\phi\) sky coordinates, in \(\rm rad\).

Return type

array(float, float)

Warning

The estimate provided by this function works only if the detectors in the network have comparable characteristics, i.e. PSDs and shape. See the gwfast code paper for discussion.

Note

Even if considering Earth rotation, the highest SNR is still be obtained if the source is in the optimal location close to the merger.

Waveform overlap for a detector network

New in version 1.0.2.

In Waveform overlap for a single detector we introduced the overlap between two waveform models in a single detector. Similarly to the SNR and FIM, also this definition can be generalised to a network of detectors, as

\[{\rm overlap}(h_1, h_2) = \frac{\sum_{d\in {\rm dets}}(h_1|h_2)_d}{\sqrt{\sum_{d\in {\rm dets}}(h_1|h_1)_d(h_2|h_2)_d}}\]

gwfast offers the possibility to compute this quantity for a detector network on two sets of events parameters (for one or multiple events at a time), using the function

DetNet.WFOverlap(WF1, WF2, evParams1, evParams2, res=1000, **kwargs)[source]

Compute the overlap of two waveforms in a detector network on two sets of parameters, for one or multiple events.

Parameters

  • WF1 (WaveFormModel) – Object containing the first waveform model to analyse.

  • WF2 (WaveFormModel) – Object containing the second waveform model to analyse.

  • evParams1 (dict(array, array, ...)) – Dictionary containing the parameters of the event(s) for the first waveform model, as in events.

  • evParams2 (dict(array, array, ...)) – Dictionary containing the parameters of the event(s) for the second waveform model, as in events.

  • res (int) – The resolution of the frequency grid to use.

  • kwargs (unused) – Optional arguments.

Returns

Overlap(s) of the two waveforms. The shape is \((N_{\rm events})\).

Return type

1-D array

Relative orientation and distance between detectors

New in version 1.1.0.

Relative orientation

The relative orientation of two detectors with respect to the great circle that joins them can be computed using the function

gwfast.gwfastUtils.ang_btw_dets_GC(det1, det2)[source]

Compute the angle between two detectors with respect to the great circle that joins them, see https://en.wikipedia.org/wiki/Great-circle_navigation.

Parameters
Returns

Angle between the two detectors, in \(\rm deg\).

Return type

float

Detector distance