ml4gw.gw

Tools for manipulating raw gravitational waveforms and projecting them onto interferometer responses. Much of the projection code is an extension of the implementation made available in bilby. Specifically code from this module.

Functions

`breathing`(m, n)
`compute_antenna_responses`(theta, psi, phi, ...)	Compute the antenna pattern factors of a batch of waveforms as a function of the sky parameters of their sources as well as the detector tensors of the interferometers whose response is being calculated.
`compute_ifo_snr`(responses, psd, sample_rate)	Compute the SNRs of a batch of interferometer responses
`compute_network_snr`(responses, psd, sample_rate)	Compute the total SNR from a gravitational waveform from a network of interferometers.
`compute_observed_strain`(dec, psi, phi, ...)	Compute the strain timeseries \(h(t)\) observed by a network of interferometers from the given polarization timeseries corresponding to gravitational waveforms from sources with the indicated sky parameters.
`cross`(m, n)
`get_ifo_geometry`(*ifos)	For a given list of interferometer names, retrieve and concatenate the associated detector tensors and vertices of those interferometers.
`outer`(x, y)	Compute the outer product of two batches of vectors
`plus`(m, n)
`reweight_snrs`(responses, target_snrs, psd, ...)	Scale interferometer responses such that they have a desired SNR
`shift_responses`(responses, theta, phi, ...)

ml4gw.gw.breathing(m, n)

Return type:

Float[Tensor, 'batch space space']

Parameters:

m (Float[Tensor, 'batch space'])
n (Float[Tensor, 'batch space'])

ml4gw.gw.compute_antenna_responses(theta, psi, phi, detector_tensors, modes)

Compute the antenna pattern factors of a batch of waveforms as a function of the sky parameters of their sources as well as the detector tensors of the interferometers whose response is being calculated.

Parameters:

theta (Float[Tensor, 'batch']) -- Angle of each source in radians relative to the celestial equator
psi (Float[Tensor, 'batch']) -- Angle in radians between each source's natural polarization basis and the basis which has the 0th unit vector pointing along the celestial equator
phi (Float[Tensor, 'batch']) -- Angle in radians between each source's right ascension and the right ascension of the geocenter
detector_tensors (Float[Tensor, 'num_ifos 3 3']) -- Detector tensor for each of the interferometers for which a response is being calculated, stacked along the 0th axis
modes (List[str]) -- Which polarization modes to compute the response for

Return type:

Float[Tensor, 'batch polarizations num_ifos']

Returns:

A tensor representing interferometer antenna pattern: factors for each of the polarizations of each of the waveforms, for each interferometer.

ml4gw.gw.compute_ifo_snr(responses, psd, sample_rate, highpass=None, lowpass=None)

Compute the SNRs of a batch of interferometer responses

Compute the signal to noise ratio (SNR) of individual interferometer responses to gravitational waveforms with respect to a background PSD for each interferometer. The SNR of the \(i\) th waveform at the \(j\) th interferometer is computed as:

\[\rho_{ij} = 4 \int_{f_{\text{min}}}^{f_{\text{max}}} \frac{\tilde{h_{ij}}(f)\tilde{h_{ij}}^*(f)} {S_n^{(j)}(f)}df\]

Where \(f_{\text{min}}\) is a minimum frequency denoted by highpass, \(f_{\text{max}}\) is the maximum frequency denoted by lowpass, which defaults to the Nyquist frequency dictated by sample_rate; \(\tilde{h}_{ij}\) and \(\tilde{h}_{ij}^*\) indicate the fourier transform of the \(i\) th waveform at the \(j\) th inteferometer and its complex conjugate, respectively; and \(S_n^{(j)}\) is the backround PSD at the \(j\) th interferometer.

Parameters:

responses (Float[Tensor, 'batch num_ifos time']) -- A batch of interferometer responses to a batch of raw gravitational waveforms
psd (Float[Tensor, 'num_ifos frequency']) -- The one-sided power spectral density of the background noise at each interferometer to which a response in responses has been calculated. If 2D, each row of psd will be assumed to be the background PSD for each channel of _every_ batch element in responses. If 3D, this should contain a background PSD for each channel of each element in responses, and therefore the first two dimensions of psd and responses should match.
sample_rate (float) -- The frequency at which the waveform responses timeseries have been sampled. Upon fourier transforming, should match the frequency resolution of the provided PSDs.
highpass (Union[float, Float[Tensor, 'frequency'], None]) -- The minimum frequency above which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out low frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies up to lowpass will contribute to the SNR calculation.
lowpass (Union[float, Float[Tensor, 'frequency'], None]) -- The maximum frequency below which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out high frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies from highpass up to the Nyquist freqyency will contribute to the SNR calculation.

Return type:

Float[Tensor, 'batch num_ifos']

Returns:

Batch of SNRs computed for each interferometer

ml4gw.gw.compute_network_snr(responses, psd, sample_rate, highpass=None, lowpass=None)

Compute the total SNR from a gravitational waveform from a network of interferometers. The total SNR for the \(i\) th waveform is computed as

\[\rho_i = \sqrt{\sum_{j}^{N}\rho_{ij}^2}\]

where \(\rho_{ij}\) is the SNR for the \(i\) th waveform at the \(j\) th interferometer in the network and \(N\) is the total number of interferometers.

Parameters:

responses (Float[Tensor, 'batch num_ifos time']) -- A batch of interferometer responses to a batch of raw gravitational waveforms
backgrounds -- The one-sided power spectral density of the background noise at each interferometer to which a response in responses has been calculated. If 2D, each row of psd will be assumed to be the background PSD for each channel of every batch element in responses. If 3D, this should contain a background PSD for each channel of each element in responses, and therefore the first two dimensions of psd and responses should match.
sample_rate (float) -- The frequency at which the waveform responses timeseries have been sampled. Upon fourier transforming, should match the frequency resolution of the provided PSDs.
highpass (Union[float, Float[Tensor, 'frequency'], None]) -- The minimum frequency above which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out low frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies up to sample_rate / 2 will contribute to the SNR calculation.
lowpass (Union[float, Float[Tensor, 'frequency'], None]) -- The maximum frequency below which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out high frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies from highpass up to the Nyquist freqyency will contribute to the SNR calculation.
psd (Float[Tensor, 'num_ifos frequency'])

Return type:

Float[Tensor, 'batch']

Returns:

Batch of SNRs for each waveform across the interferometer network

ml4gw.gw.compute_observed_strain(dec, psi, phi, detector_tensors, detector_vertices, sample_rate, **polarizations)

Compute the strain timeseries \(h(t)\) observed by a network of interferometers from the given polarization timeseries corresponding to gravitational waveforms from sources with the indicated sky parameters.

Parameters:

dec (Float[Tensor, 'batch']) -- Declination of each source in radians relative to the celestial north
psi (Float[Tensor, 'batch']) -- Angle in radians between each source's natural polarization basis and the basis which has the 0th unit vector pointing along the celestial equator
phi (Float[Tensor, 'batch']) -- Angle in radians between each source's right ascension and the right ascension of the geocenter
detector_tensors (Float[Tensor, 'num_ifos 3 3']) -- Detector tensor for each of the interferometers for which observed strain is being calculated, stacked along the 0th axis
detector_vertices (Float[Tensor, 'num_ifos 3']) -- Vertices for each interferometer's spatial location relative to the geocenter. Used to compute delay between the waveform observed at the geocenter and the one observed at the detector site. To avoid adding any delay between the two, reset your coordinates such that the desired interferometer is at (0., 0., 0.).
sample_rate (float) -- Rate at which the polarization timeseries have been sampled
polarziations -- Timeseries for each waveform polarization which contributes to the interferometer response. Allowed polarizations are cross, plus, and breathing.
polarizations (Float[Tensor, 'batch time'])

Return type:

Float[Tensor, 'batch num_ifos time']

Returns:

Tensor representing the observed strain at each interferometer for each waveform.

ml4gw.gw.cross(m, n)

Return type:

Float[Tensor, 'batch space space']

Parameters:

m (Float[Tensor, 'batch space'])
n (Float[Tensor, 'batch space'])

ml4gw.gw.get_ifo_geometry(*ifos)

For a given list of interferometer names, retrieve and concatenate the associated detector tensors and vertices of those interferometers.

Parameters:: ifos (str) -- Names of the interferometers whose geometry to retrieve
Return type:: Tuple[Float[Tensor, 'num_ifos 3 3'], Float[Tensor, 'num_ifos 3']]
Returns:: A concatenation of the detector tensors of each interferometer A concatenation of the vertices of each interferometer

ml4gw.gw.outer(x, y)

Compute the outer product of two batches of vectors

Return type:

Float[Tensor, 'batch space space']

Parameters:

x (Float[Tensor, 'batch space'])
y (Float[Tensor, 'batch space'])

ml4gw.gw.plus(m, n)

Return type:

Float[Tensor, 'batch space space']

Parameters:

m (Float[Tensor, 'batch space'])
n (Float[Tensor, 'batch space'])

ml4gw.gw.reweight_snrs(responses, target_snrs, psd, sample_rate, highpass=None, lowpass=None)

Scale interferometer responses such that they have a desired SNR

Parameters:

responses (Float[Tensor, 'batch num_ifos time']) -- A batch of interferometer responses to a batch of raw gravitational waveforms
target_snrs (Union[float, Float[Tensor, 'batch']]) -- Either a tensor of desired SNRs for each waveform, or a single SNR to which all waveforms should be scaled.
psd (Float[Tensor, 'num_ifos frequency']) -- The one-sided power spectral density of the background noise at each interferometer to which a response in responses has been calculated. If 2D, each row of psd will be assumed to be the background PSD for each channel of every batch element in responses. If 3D, this should contain a background PSD for each channel of each element in responses, and therefore the first two dimensions of psd and responses should match.
sample_rate (float) -- The frequency at which the waveform responses timeseries have been sampled. Upon fourier transforming, should match the frequency resolution of the provided PSDs.
highpass (Union[float, Float[Tensor, 'frequency'], None]) -- The minimum frequency above which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out low frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies up to sample_rate / 2 will contribute to the SNR calculation.
lowpass (Union[float, Float[Tensor, 'frequency'], None]) -- The maximum frequency below which to compute the SNR. If a tensor is provided, it will be assumed to be a pre-computed mask used to 0-out high frequency components. If a float, it will be used to compute such a mask. If left as None, all frequencies from highpass up to the Nyquist freqyency will contribute to the SNR calculation.

Return type:

Float[Tensor, 'batch num_ifos time']

Returns:

Rescaled interferometer responses

ml4gw.gw.shift_responses(responses, theta, phi, vertices, sample_rate)

Return type:

Float[Tensor, 'batch num_ifos time']

Parameters:

responses (Float[Tensor, 'batch num_ifos time'])
theta (Float[Tensor, 'batch'])
phi (Float[Tensor, 'batch'])
vertices (Float[Tensor, 'num_ifos 3'])
sample_rate (float)