Single detector analysis¶

The signal module allows to model the response of a single detector to a GW signal. We here present the core class, gwfast.signal.GWSignal, and its methods.

Initialising a single detector¶

A single detector object can be initialised as follows

class gwfast.signal.GWSignal(wf_model, psd_path=None, detector_shape='T', det_lat=40.44, det_long=9.45, det_xax=0.0, verbose=True, is_ASD=True, useEarthMotion=False, noMotion=False, fmin=2.0, fmax=None, IntTablePath=None, DutyFactor=None, compute2arms=True, jitCompileDerivs=False)[source]¶

Class to compute the GW signal emitted by a coalescing binary system as seen by a detector on Earth.

The functions defined within this class allow to get e.g. the amplitude of the signal, its phase, SNR and Fisher matrix elements.

Parameters

wf_model (WaveFormModel) – Object containing the waveform model.
psd_path (str) – Full path to the file containing the detector’s Power Spectral Density, PSD, or Amplitude Spectral Density, ASD, including the file extension. The file is assumed to have two columns, the first containing the frequencies (in \(\rm Hz\)) and the second containing the detector’s PSD/ASD at each frequency.
detector_shape (str) – The shape of the detector, to be chosen among 'L' for an L-shaped detector (90°-arms) and 'T' for a triangular detector (3 nested detectors with 60°-arms).
det_lat (float) – Latitude of the detector, in degrees.
det_long (float) – Longitude of the detector, in degrees.
det_xax (float) – Angle between the bisector of the detector’s arms (the first detector in the case of a triangle) and local East, in degrees.
verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.
is_ASD (bool, optional) – Boolean specifying if the provided file is a PSD or an ASD.
useEarthMotion (bool, optional) – Boolean specifying if the effect of the Earth rotation has to be included in the analysis.
noMotion (bool, optional) – Boolean specifying if the Earth should be considered fixed at tcoal=0. In the case useEarthMotion=False the system is rotated depending on tcoal and then left fixed. This was needed for checks and is not to be used.
fmin (float) – Minimum frequency to use for the grid in the analysis, in \(\rm Hz\).
fmax (float) – Maximum frequency to use for the grid in the analysis, in \(\rm Hz\). The cut frequency of the waveform (which depends on the events parameters) will be used as maximum frequency if fmax=None or if it is smaller than fmax.
IntTablePath (str) – Deprecated, not used.
DutyFactor (float) – Duty factor of the detector, between 0 and 1, representing the percentage of time the detector (each detector independently in the case of a triangular detector) is supposed to be operational.
compute2arms (bool, optional) – Boolean specifying if, in the case of a triangular detector, the computation can be performed only in two of the instruments, using the null-stream to get the signal in the third instrument, speeding up the computation by 1/3.
jitCompileDerivs (bool, optional) – Boolean specifying if the derivatives function has to be jit compiled.

The locations and orientations of some detectors are already provided in gwfast.gwfastGlobals.detectors

gwfast.gwfastGlobals.detectors¶

Type: dict(dict, dict, …)

{
"L1": {
    "lat": 30.563,
    "long": -90.774,
    "xax": 242.716,
    "shape": "L"
},
"H1": {
    "lat": 46.455,
    "long": -119.408,
    "xax": 170.999,
    "shape": "L"
},
"Virgo": {
    "lat": 43.631,
    "long": 10.504,
    "xax": 115.568,
    "shape": "L"
},
"KAGRA": {
    "lat": 36.412,
    "long": 137.306,
    "xax": 15.396,
    "shape": "L"
},
"LIGOI": {
    "lat": 19.613,
    "long": 77.031,
    "xax": 287.384,
    "shape": "L"
},
"ETS": {
    "lat": 40.517,
    "long": 9.417,
    "xax": 0.0,
    "shape": "T"
},
"ETMR": {
    "lat": 50.723,
    "long": 5.921,
    "xax": 0.0,
    "shape": "T"
},
"ETSL": {
    "lat": 40.517,
    "long": 9.417,
    "xax": 45.0,
    "shape": "L"
},
"ETMRL45d": {
    "lat": 50.723,
    "long": 5.921,
    "xax": 90.0,
    "shape": "L"
},
"ETMRLpar": {
    "lat": 50.723,
    "long": 5.921,
    "xax": 45.0,
    "shape": "L"
},
"CE1Id": {
    "lat": 43.827,
    "long": -112.825,
    "xax": -45.0,
    "shape": "L"
},
"CE2NM": {
    "lat": 33.16,
    "long": -106.48,
    "xax": -105.0,
    "shape": "L"
},
"CE2NSW": {
    "lat": -34.0,
    "long": 145.0,
    "xax": 0.0,
    "shape": "L"
}
}

where "L1" and "H1" denote the two LIGO detectors in Livingston and Hanford, respectively, "Virgo" denotes the Virgo detector, "KAGRA" denotes the KAGRA detector, "LIGOI" denotes the LIGO India detector, "ETS" and "ETMR" denote the ET detector in Sardinia and Meuse-Rhine in its triangular design, "ETSL" the ET detector in Sardinia as an L-shaped detector, "ETMRL45d" and "ETMRLpar" the ET detector in Meuse-Rhine as an L-shaped detector both at \(45^{\circ}\) and parallel with respect to "ETSL" (with respect to local north), respectively, while "CE1Id", "CE2NM" and "CE2NSW" denote the CE detector(s) in Idaho, New Mexico and New South Wales, respectively. We stress that, for third generation detectors, locations and orientations are illustrative examples.

Also many ASDs for different stages and desings of the detectors are included in the gwfast/psds/ directory, see gwfast/psds.

It is possible to initialise the seed for the duty cycle, i.e. the percentage of time the detector (each detector independently in the case of a triangular detector) is supposed to be operational, using

GWSignal._update_seed(seed=None)[source]¶

Update the seed for the duty cycle with a random value or a user input value.

Parameters: seed (int, optional) – User input value for the seed.

Projecting the signal onto the detector¶

We will now list the methods inside gwfast.signal.GWSignal needed to project the signal onto a single detector. We refer to Parameters names and conventions for a complete list of the parameters conventions, units and ranges.

Pattern functions¶

The so-called detector pattern functions \(F_+ (\theta, \phi, t, \psi)\) and \(F_{\times} (\theta, \phi, t, \psi)\) as a function of the sky position of the event, time and polarisation can be computed as

GWSignal._PatternFunction(theta, phi, t, psi, rot=0.0)[source]¶

Compute the value of the so-called pattern functions of the detector for a set of sky coordinates, GW polarisation(s) and time(s).

For the definition of the pattern functions see arXiv:gr-qc/9804014 eq. (10)–(13).

Parameters

theta (array or float) – The \(\theta\) sky position angle(s), in \(\rm rad\).
phi (array or float) – The \(\phi\) sky position angle(s), in \(\rm rad\).
t (array or float) – The time(s) given as GMST.
psi (array or float) – The GW polarisation angle(s) \(\psi\), in \(\rm rad\).
rot (float) – Further rotation of the interferometer with respect to the self.xax orientation, in degrees, needed for the triangular geometry. In this case, the three arms will have orientations 1 –> self.xax, 2 –> self.xax + 60°, 3 –> self.xax + 120°.

Returns

Plus and cross pattern functions of the detector evaluated at the given parameters.

Return type

tuple(array, array) or tuple(float, float)

Time delay from Earth center¶

The time needed to go from the Earth center to the detector location, as a function of the sky position of the event(s) and time(s), can be computed as

GWSignal._DeltLoc(theta, phi, t)[source]¶

Compute the time needed to go from Earth center to detector location for a set of sky coordinates and time(s). The result is given in seconds.

Parameters

theta (array or float) – The \(\theta\) sky position angle(s), in \(\rm rad\).
phi (array or float) – The \(\phi\) sky position angle(s), in \(\rm rad\).
t (array or float) – The time(s) given as GMST.

Returns

Time shift(s) to go from Earth center to detector location.

Return type

array or float

Amplitude at the detector¶

The GW signal amplitudes \(A_+\) and \(A_{\times}\) at the detector, for a set of event(s) parameters and frequency(ies) can be computed as

GWSignal.GWAmplitudes(evParams, f, rot=0.0)[source]¶

Compute the amplitude of the signal(s) as seen by the detector, as a function of the parameters, at given frequencies.

Parameters

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
f (array or float) – The frequency(ies) at which to perform the calculation, in \(\rm Hz\).
rot (float) – Further rotation of the interferometer with respect to the self.xax orientation, in degrees, needed for the triangular geometry.

Returns

Plus and cross amplitudes at the detector, evaluated at the given parameters and frequency(ies).

Return type

tuple(array, array) or tuple(float, float)

Complete phase¶

The complete phase(s) of the signal(s) [i.e. including the coalescence phase \(\Phi_{c}\) and time \(t_c\) terms and the \(-\pi/4\)], for a set of event(s) parameters and frequency(ies) can be computed as

GWSignal.GWPhase(evParams, f)[source]¶

Compute the complete phase of the signal(s), as a function of the parameters, at given frequencies.

Parameters

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
f (array or float) – The frequency(ies) at which to perform the calculation, in \(\rm Hz\).

Returns

Complete signal phase, evaluated at the given parameters and frequency(ies).

Return type

array or float

Complete strain¶

The complete signal strain(s) at the detector for a set of event(s) parameters and frequency(ies) can be computed as

GWSignal.GWstrain(f, Mc, eta, dL, theta, phi, iota, psi, tcoal, Phicoal, chiS, chiA, chi1x, chi2x, chi1y, chi2y, LambdaTilde, deltaLambda, ecc, rot=0.0, is_m1m2=False, is_chi1chi2=False, is_prec_ang=False, is_Lam1Lam2=False, return_single_comp=None)[source]¶

Compute the full GW strain (complex) as a function of the parameters, at given frequencies.

Parameters

f (array or float) – The frequency(ies) at which to perform the calculation, in \(\rm Hz\).
Mc (array or float) – The chirp mass(es), \({\cal M}_c\), in units of \(\rm M_{\odot}\). If is_m1m2=True this is interpreted as the primary mass, \(m_1\), in units of \(\rm M_{\odot}\).
eta (array or float) – The symmetric mass ratio(s), \(\eta\). If is_m1m2=True this is interpreted as the secondary mass, \(m_2\), in units of \(\rm M_{\odot}\).
dL (array or float) – The luminosity distance(s), \(d_L\), in \(\rm Gpc\).
theta (array or float) – The \(\theta\) sky position angle(s), in \(\rm rad\).
phi (array or float) – The \(\phi\) sky position angle(s), in \(\rm rad\).
iota (array or float) – The inclination angle(s), with respect to orbital angular momentum, \(\iota\), in \(\rm rad\). If is_prec_ang=True this is interpreted as the inclination angle(s) with respect to total angular momentum, \(\theta_{JN}\), in \(\rm rad\).
psi (array or float) – The polarisation angle(s), \(\psi\), in \(\rm rad\).
tcoal (array or float) – The time(s) of coalescence, \(t_{\rm coal}\), as a GMST.
Phicoal (array or float) – The phase(s) at coalescence, \(\Phi_{\rm coal}\), in \(\rm rad\).
chiS (array or float) – The symmetric spin component(s), \(\chi_s\). If self.wf_model is precessing or is_chi1chi2=True this is interpreted as the spin component(s) of the primary object(s) along the axis \(z\), \(\chi_{1,z}\). If is_prec_ang=True this is interpreted as the spin magnitude(s) of the primary object(s), \(\chi_1\).
chiA (array or float) – The antisymmetric spin component(s) \(\chi_a\). If self.wf_model is precessing or is_chi1chi2=True this is interpreted as the spin component(s) of the secondary object(s) along the axis \(z\), \(\chi_{2,z}\). If is_prec_ang=True this is interpreted as the spin magnitude(s) of the secondary object(s), \(\chi_2\).
chi1x (array or float) – The spin component(s) of the primary object(s) along the axis \(x\), \(\chi_{1,x}\). If is_prec_ang=True this is interpreted as the spin tilt angle(s) of the primary object(s), \(\theta_{s,1}\), in \(\rm rad\).
chi2x (array or float) – The spin component(s) of the secondary object(s) along the axis \(x\), \(\chi_{2,x}\). If is_prec_ang=True this is interpreted as the spin tilt angle(s) of the secondary object(s), \(\theta_{s,2}\), in \(\rm rad\).
chi1y (array or float) – spin component(s) of the primary object(s) along the axis \(y\), \(\chi_{1,y}\). If is_prec_ang=True this is interpreted as the azimuthal angle(s) of orbital angular momentum relative to total angular momentum, \(\phi_{JL}\), in \(\rm rad\).
chi2y (array or float) – spin component(s) of the secondary object(s) along the axis \(y\), \(\chi_{2,y}\). If is_prec_ang=True this is interpreted as the difference(s) in azimuthal angle between spin vectors, \(\phi_{1,2}\), in \(\rm rad\).
LambdaTilde (array or float) – The adimensional tidal deformability(ies) of combination \(\tilde{\Lambda}\).
deltaLambda (array or float) – The adimensional tidal deformability(ies) of combination \(\delta\tilde{\Lambda}\).
ecc (array or float) – The orbital eccentricity(ies), \(e_0\).
rot (float) – Further rotation of the interferometer with respect to the self.xax orientation, in degrees, needed for the triangular geometry.
is_m1m2 (bool, optional) – Boolean specifying if the Mc and eta inputs should be interpreted as the primary and secondary mass(es).
is_chi1chi2 (bool, optional) – Boolean specifying if the chiS and chiA inputs should be interpreted as the primary and secondary spin components along the axis \(z\).
is_prec_ang (bool, optional) – Boolean specifying if the iota input should be interpreted as the inclination angle with respect to total angular momentum, chiS and chiA as the primary and secondary spin magnitudes, chi1x and chi2x as the primary and secondary spin tilts, chi1y as the azimuthal angle of orbital angular momentum relative to total angular momentum and chi2y as the difference in azimuthal angle between spin vectors.
is_Lam1Lam2 (bool, optional) – Boolean specifying if the LambdaTilde and deltaLambda inputs should be interpreted as the individual tidal deformabilities.
return_single_comp (str) – String specifying if a single component of the signal should be returned, to be chosen among Ap and Ac, to return the plus and cross amplitude, \(A_+\) and \(A_{\times}\), respectively, and Psip and Psic, to return the plus and cross phase, \(\Phi_+\) and \(\Phi_{\times}\), respectively.

Returns

Complete signal strain (complex), evaluated at the given parameters and frequency(ies).

Return type

array or float

Formalism setup¶

We recall here the basics of the Fisher matrix formalism in GW parameter estimation. For comprehensive treatments see arXiv:gr-qc/9402014, arXiv:gr-qc/0703086 and arXiv:1308.1397, which study also the limitations of the approach. We assume that the time-domain signal in a GW detector can be written as the superposition of an expected signal \(h_0\) and stationary, Gaussian noise \(n\) with zero mean

(1)¶\[s(t) = h_0(t) + n(t)\]

The statistical properties of the noise are encoded in the one-sided Power Spectral Density (PSD) \(S_n(f)\), defined by

\[\langle \tilde{n}^*(f) \tilde{n}(f') \rangle = \dfrac{1}{2}\delta(f−f') S_n(f)\]

where the tilde denotes a temporal Fourier transform.

This determines an inner product for any two signals \(g(t)\) and \(h(t)\)

(2)¶\[\left( g \, | \, h \right) = 4 {\rm Re}{ \int_0^{\infty} {\rm d}f \, \frac{\tilde{g}^*(f) \, \tilde{h}(f) }{S_{n}(f)}}\]

Using eq. (2) we can express the signal–to–noise ratio (SNR) of the true signal as

(3)¶\[{\rm SNR} = \left(h_0 \, | \, h_0\right)^{1/2}\]

Eq.s (1) and eq. (2) result in the following likelihood for a data realisation \(s\) conditioned on the waveform parameters \(\overrightarrow{\theta}\)

(4)¶\[\mathcal{L}(s \;|\; \overrightarrow{\theta}) \propto \exp\left\{-\frac{1}{2}\left( s -h(\overrightarrow{\theta}) \, | \, s -h(\overrightarrow{\theta}) \right) \right\}\]

The Fisher Information Matrix (FIM) for the likelihood in eq. (4) is defined as

(5)¶\[\Gamma_{ij} \equiv - \langle \partial_{i} \partial_{j} \log \mathcal{L}(s \,|\, \overrightarrow{\theta}) \rangle_n {\Big |}_{\overrightarrow{\theta}=\overrightarrow{\theta}_0} =\left(h_i \, | \, h_j\right)\]

where \(h_i \equiv \partial_i h\), and the notation \(\langle\dots\rangle_n\) denotes an average over noise realizations with fixed parameters. Near a maximum of the likelihood, the latter is approximated by a multivariate Gaussian with covariance \(\Gamma_{ij}^{-1}\).

From the FIM it is then possible to have an estimation of the errors attainable on the parameters, without having to perform a full Bayesian parameter estimation, which is computationally very expensive.

SNR computation in a single detector¶

To compute the SNR defined in eq. (3) in a single detector, for one or multiple events, it is sufficient to use the function

GWSignal.SNRInteg(evParams, res=1000, return_all=False)[source]¶

Compute the 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, in the case of a triangular detector, the SNRs of the individual instruments have to be returned separately. In this case the return type is list(array, array, array).

Returns

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

Return type

1-D array

Signal derivatives¶

The fundamental ingredient to build the FIM in eq. (5) is the computation of the signal derivatives with respect to the parameters. In its pure Python implementation (when using the built-in Python waveform models), gwfast as a defualt uses a mixture of automatic differentiation through the JAX package and analytical derivatives.

Automatic differentiation is a technique to compute derivatives of any order in a pseudo-analytic way, iteratively applying the chain rule on a given function. For this to work it is required that the function is written in a way the machine can understand, in our case pure Python. For a review of automatic differentiation see arXiv:1811.05031. This technique ensures both numerical accuracy and speed.

gwfast also offers the possibility to compute the derivatives using numerical differentiation (finite differences) through the numdifftools package. This is the default option if using Wrappers to external waveform models.

The function to compute signal derivatives for one or multiple events is

GWSignal._SignalDerivatives(fgrids, Mc, eta, dL, theta, phi, iota, psi, tcoal, Phicoal, chiS, chiA, chi1x, chi2x, chi1y, chi2y, LambdaTilde, deltaLambda, ecc, rot=0.0, use_m1m2=False, use_chi1chi2=True, use_prec_ang=True, computeDerivFinDiff=False, computeAnalyticalDeriv=True, stepNDT=MaxStepGenerator(_base_step=1e-05, _step_nom=None, _num_steps=15, _step_ratio=None, offset=0, num_extrap=9, check_num_steps=True, use_exact_steps=False, _scale=500, _state=State(x=array(1), method='forward', n=1, order=2)), methodNDT='central', **kwargs)[source]¶

Compute the derivatives of the GW strain with respect to the parameters of the event(s) at given frequencies (in \(\rm Hz\)).

Parameters

fgrids (array or float) – The frequency(ies) at which to perform the calculation, in \(\rm Hz\).
Mc (array or float) – The chirp mass(es), \({\cal M}_c\), in units of \(\rm M_{\odot}\). If use_m1m2=True this is interpreted as the primary mass, \(m_1\), in units of \(\rm M_{\odot}\).
eta (array or float) – The symmetric mass ratio(s), \(\eta\). If use_m1m2=True this is interpreted as the secondary mass, \(m_2\), in units of \(\rm M_{\odot}\).
dL (array or float) – The luminosity distance(s), \(d_L\), in \(\rm Gpc\).
theta (array or float) – The \(\theta\) sky position angle(s), in \(\rm rad\).
phi (array or float) – The \(\phi\) sky position angle(s), in \(\rm rad\).
iota (array or float) – The inclination angle(s), with respect to orbital angular momentum, \(\iota\), in \(\rm rad\). If is_prec_ang=True this is interpreted as the inclination angle(s) with respect to total angular momentum, \(\theta_{JN}\), in \(\rm rad\).
psi (array or float) – The polarisation angle(s), \(\psi\), in \(\rm rad\).
tcoal (array or float) – The time(s) of coalescence, \(t_{\rm coal}\), as a GMST.
Phicoal (array or float) – The phase(s) at coalescence, \(\Phi_{\rm coal}\), in \(\rm rad\).
chiS (array or float) – The symmetric spin component(s), \(\chi_s\). If self.wf_model is precessing or use_chi1chi2=True this is interpreted as the spin component(s) of the primary object(s) along the axis \(z\), \(\chi_{1,z}\). If use_prec_ang=True this is interpreted as the spin magnitude(s) of the primary object(s), \(\chi_1\).
chiA (array or float) – The antisymmetric spin component(s) \(\chi_a\). If self.wf_model is precessing or use_chi1chi2=True this is interpreted as the spin component(s) of the secondary object(s) along the axis \(z\), \(\chi_{2,z}\). If use_prec_ang=True this is interpreted as the spin magnitude(s) of the secondary object(s), \(\chi_2\).
chi1x (array or float) – The spin component(s) of the primary object(s) along the axis \(x\), \(\chi_{1,x}\). If use_prec_ang=True this is interpreted as the spin tilt angle(s) of the primary object(s), \(\theta_{s,1}\), in \(\rm rad\).
chi2x (array or float) – The spin component(s) of the secondary object(s) along the axis \(x\), \(\chi_{2,x}\). If use_prec_ang=True this is interpreted as the spin tilt angle(s) of the secondary object(s), \(\theta_{s,2}\), in \(\rm rad\).
chi1y (array or float) – spin component(s) of the primary object(s) along the axis \(y\), \(\chi_{1,y}\). If use_prec_ang=True this is interpreted as the azimuthal angle(s) of orbital angular momentum relative to total angular momentum, \(\phi_{JL}\), in \(\rm rad\).
chi2y (array or float) – spin component(s) of the secondary object(s) along the axis \(y\), \(\chi_{2,y}\). If use_prec_ang=True this is interpreted as the difference(s) in azimuthal angle between spin vectors, \(\phi_{1,2}\), in \(\rm rad\).
LambdaTilde (array or float) – The adimensional tidal deformability(ies) of combination \(\tilde{\Lambda}\).
deltaLambda (array or float) – The adimensional tidal deformability(ies) of combination \(\delta\tilde{\Lambda}\).
ecc (array or float) – The orbital eccentricity(ies), \(e_0\).
rot (float) – Further rotation of the interferometer with respect to the self.xax orientation, in degrees, needed for the triangular geometry.
use_m1m2 (bool, optional) – Boolean specifying if the Mc and eta inputs should be interpreted as the primary and secondary mass(es). In this case the derivatives are then taken with respect to m1 and m2.
use_chi1chi2 (bool, optional) – Boolean specifying if the chiS and chiA inputs should be interpreted as the primary and secondary spin components along the axis \(z\). In this case the derivatives are then taken with respect to chi1z and chi2z.
use_prec_ang (bool, optional) – Boolean specifying if the iota input should be interpreted as the inclination angle with respect to total angular momentum, chiS and chiA as the primary and secondary spin magnitudes, chi1x and chi2x as the primary and secondary spin tilts, chi1y as the azimuthal angle of orbital angular momentum relative to total angular momentum and chi2y as the difference in azimuthal angle between spin vectors. In this case the derivatives are then taken with respect to thetaJN, chi1, chi2, tilt1, tilt2, phiJL and phi12.
computeDerivFinDiff (bool, optional) –
Boolean specifying if the derivatives have to be computed using numerical differentiation (finite differences) through the numdifftools package.
computeAnalyticalDeriv (bool, optional) – Boolean specifying if the derivatives with respect to dL, theta, phi, psi, tcoal, Phicoal and iota (the latter only for the fundamental mode in the non-precessing case) have to be computed analytically. This considerably speeds up the calculation and provides better accuracy.
stepNDT (float or numdifftools.step_generators.MaxStepGenerator) – The step size to use in the computation with numerical differentiation (finite differences).
methodNDT (str) – The method to use in the computation with numerical differentiation (finite differences). This can be 'central', 'complex', 'multicomplex', 'forward' or 'backward'.

Returns

Complete signal strain derivatives (complex), evaluated at the given parameters and frequency(ies).

Return type

array

Analytical derivatives can be computed for the parameters dL, theta, phi, psi, tcoal, Phicoal and iota (the latter only for the fundamental mode in the non-precessing case). These are cross-checked both with JAX derivatives and an independent Wolfram Mathematica code. Computing analytical derivatives for these parameters considerably speeds-up the computation and further improves the accuracy.

The function that computes analytical derivatives for one or multiple events is

GWSignal._AnalyticalDerivatives(f, Mc, eta, dL, theta, phi, iota, psi, tcoal, Phicoal, chiS, chiA, chi1x, chi2x, chi1y, chi2y, LambdaTilde, deltaLambda, ecc, rot=0.0, use_m1m2=False, use_chi1chi2=False, use_prec_ang=False)[source]¶

Compute analytical derivatives with respect to dL, theta, phi, psi, tcoal, Phicoal and iota (the latter only for the fundamental mode in the non-precessing case).

Parameters

f (array or float) – The frequency(ies) at which to perform the calculation, in \(\rm Hz\).
Mc (array or float) – The chirp mass(es), \({\cal M}_c\), in units of \(\rm M_{\odot}\). If use_m1m2=True this is interpreted as the primary mass, \(m_1\), in units of \(\rm M_{\odot}\).
eta (array or float) – The symmetric mass ratio(s), \(\eta\). If use_m1m2=True this is interpreted as the secondary mass, \(m_2\), in units of \(\rm M_{\odot}\).
dL (array or float) – The luminosity distance(s), \(d_L\), in \(\rm Gpc\).
theta (array or float) – The \(\theta\) sky position angle(s), in \(\rm rad\).
phi (array or float) – The \(\phi\) sky position angle(s), in \(\rm rad\).
iota (array or float) – The inclination angle(s), with respect to orbital angular momentum, \(\iota\), in \(\rm rad\). If is_prec_ang=True this is interpreted as the inclination angle(s) with respect to total angular momentum, \(\theta_{JN}\), in \(\rm rad\).
psi (array or float) – The polarisation angle(s), \(\psi\), in \(\rm rad\).
tcoal (array or float) – The time(s) of coalescence, \(t_{\rm coal}\), as a GMST.
Phicoal (array or float) – The phase(s) at coalescence, \(\Phi_{\rm coal}\), in \(\rm rad\).
chiS (array or float) – The symmetric spin component(s), \(\chi_s\). If self.wf_model is precessing or use_chi1chi2=True this is interpreted as the spin component(s) of the primary object(s) along the axis \(z\), \(\chi_{1,z}\). If use_prec_ang=True this is interpreted as the spin magnitude(s) of the primary object(s), \(\chi_1\).
chiA (array or float) – The antisymmetric spin component(s) \(\chi_a\). If self.wf_model is precessing or use_chi1chi2=True this is interpreted as the spin component(s) of the secondary object(s) along the axis \(z\), \(\chi_{2,z}\). If use_prec_ang=True this is interpreted as the spin magnitude(s) of the secondary object(s), \(\chi_2\).
chi1x (array or float) – The spin component(s) of the primary object(s) along the axis \(x\), \(\chi_{1,x}\). If use_prec_ang=True this is interpreted as the spin tilt angle(s) of the primary object(s), \(\theta_{s,1}\), in \(\rm rad\).
chi2x (array or float) – The spin component(s) of the secondary object(s) along the axis \(x\), \(\chi_{2,x}\). If use_prec_ang=True this is interpreted as the spin tilt angle(s) of the secondary object(s), \(\theta_{s,2}\), in \(\rm rad\).
chi1y (array or float) – spin component(s) of the primary object(s) along the axis \(y\), \(\chi_{1,y}\). If use_prec_ang=True this is interpreted as the azimuthal angle(s) of orbital angular momentum relative to total angular momentum, \(\phi_{JL}\), in \(\rm rad\).
chi2y (array or float) – spin component(s) of the secondary object(s) along the axis \(y\), \(\chi_{2,y}\). If use_prec_ang=True this is interpreted as the difference(s) in azimuthal angle between spin vectors, \(\phi_{1,2}\), in \(\rm rad\).
LambdaTilde (array or float) – The adimensional tidal deformability(ies) of combination \(\tilde{\Lambda}\).
deltaLambda (array or float) – The adimensional tidal deformability(ies) of combination \(\delta\tilde{\Lambda}\).
ecc (array or float) – The orbital eccentricity(ies), \(e_0\).
rot (float) – Further rotation of the interferometer with respect to the self.xax orientation, in degrees, needed for the triangular geometry.
use_m1m2 (bool, optional) – Boolean specifying if the Mc and eta inputs should be interpreted as the primary and secondary mass(es).
use_chi1chi2 (bool, optional) – Boolean specifying if the chiS and chiA inputs should be interpreted as the primary and secondary spin components along the axis \(z\).
use_prec_ang (bool, optional) – Boolean specifying if the iota input should be interpreted as the inclination angle with respect to total angular momentum, chiS and chiA as the primary and secondary spin magnitudes, chi1x and chi2x as the primary and secondary spin tilts, chi1y as the azimuthal angle of orbital angular momentum relative to total angular momentum and chi2y as the difference in azimuthal angle between spin vectors.

Returns

Analytical derivatives with respect to dL, theta, phi, iota, psi, tcoal and Phicoal. If the self.wf_model is precessing or includes higher order modes the derivative with respect to iota will be None

Return type

tuple(array, array, array, array, array, array, array)

Fisher matrix computation in a single detector¶

To compute the FIM defined in eq. (5) in a single detector, for one or multiple events, it is sufficient to use the function

GWSignal.FisherMatr(evParams, res=1000, df=None, spacing='geom', use_m1m2=False, use_chi1chi2=True, use_prec_ang=True, computeDerivFinDiff=False, computeAnalyticalDeriv=True, return_all=False, return_derivatives=False, return_SNR_derivatives=False, **kwargs)[source]¶

Compute the 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.
res (int) – The resolution of the frequency grid to use.
df (float) – The spacing of the frequency grid to use, in \(\rm Hz\). Alternative to res.
spacing (str) – The kind of spacing of the frequency grid to use. If 'geom' the grid will be spaced evenly on a log scale (geometric progression), if 'lin' it will be spaced evenly on a linear scale.
use_m1m2 (bool, optional) – Boolean specifying if the FIM has to be computed with respect to the individual masses m1 and m2 rather than Mc and eta.
use_chi1chi2 (bool, optional) – Boolean specifying if, in the non-precessing case, the FIM has to be computed with respect to the individual spins chi1z and chi2z rather than chiS and chiA.
use_prec_ang (bool, optional) – Boolean specifying if, in the precessing case, the FIM has to be computed with respect to the spin angular variables rather than the spin cartesian components.
computeDerivFinDiff (bool, optional) –
Boolean specifying if the derivatives have to be computed using numerical differentiation (finite differences) through the numdifftools package.
computeAnalyticalDeriv (bool, optional) – Boolean specifying if the derivatives with respect to dL, theta, phi, psi, tcoal, Phicoal and iota (the latter only for the fundamental mode in the non-precessing case) have to be computed analytically. This considerably speeds up the calculation and provides better accuracy.
return_all (bool, optional) – Boolean specifying if, in the case of a triangular detector, the FIMs of the individual instruments have to be returned separately. In this case the return type is list(array, 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 list(array, array, …), list(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 list(array, array, …), list(array, array, …).
kwargs – Optional arguments to be passed to gwfast.signal.GWSignal._SignalDerivatives, such as methodNDT.

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 single detector¶

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 Pattern functions of the detector and the computation assumes \(\psi=0\).

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

GWSignal.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)

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 single detector¶

New in version 1.0.2.

From the inner product in eq. (2), it is also possible to define the so-called overlap between two waveforms as

\[{\rm overlap}(h_1, h_2) \equiv \frac{(h_1|h_2)}{\sqrt{(h_1|h_1)(h_2|h_2)}} = \frac{(h_1|h_2)}{\rm SNR_1 \, SNR_2}\]

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

GWSignal.WFOverlap(WF1, WF2, evParams1, evParams2, res=1000, return_separate=False, **kwargs)[source]¶

Compute the overlap of two waveforms in a single detector 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.
return_all (bool, optional) – Boolean specifying if, instead of returning the overlap, the function has to return separately product at the numerator of the definition, \((h_1|h_2)\), and the SNRs at the denominator. This is needed to compute the overlap for a detector network. In this case the return type is tuple(array, array, array).
kwargs (unused) – Optional arguments.

Returns

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

Return type

1-D array