Fourier transforms and detectors

class GWFrames.WaveformAtAPointFT

Fourier transform of a waveform measured by a detector at one point.

A WaveformAtAPointFT stores the Fourier transform of the real signal that a detector would measure from a Waveform evaluated in one direction on the sphere, in physical units. It is used to compute signal-to-noise ratios, inner products, and matches weighted by a detector’s noise curve.

A WaveformAtAPointFT is constructed as

WaveformAtAPointFT(W, Dt, Vartheta, Varphi, TotalMass, ...)

The Fourier transform of the waveform W at the point (Vartheta, Varphi), computed as described below. The optional parameters WindowNCycles, DetectorResponseAmp, DetectorResponsePhase, and ExtraZeroPadPowers follow, in that order.

The construction takes these steps:

  1. W is interpolated to times beginning with its first time and spaced uniformly by Dt. The number of samples is a power of 2, large enough to cover the duration of W, and is multiplied further by \(2^{\mathtt{ExtraZeroPadPowers}}\); samples after the end of W are zero.

  2. The waveform is evaluated at the point (Vartheta, Varphi) with Waveform.EvaluateAtPoint, giving a complex time series \(h(t)\).

  3. The detector response \(F = F_+ + i F_\times\), given by its amplitude DetectorResponseAmp and phase DetectorResponsePhase, is applied, and the real part \(\mathrm{Re}(F h)\) is kept as the signal.

  4. The signal is set to zero before its first zero crossing and is tapered smoothly to its full amplitude over the following WindowNCycles cycles.

  5. The times are converted to seconds using TotalMass, and the signal is Fourier transformed.

The transform is normalized as an approximation to the continuous Fourier transform (the discrete sum is multiplied by the time step in seconds), and only the nonnegative frequencies are stored, from zero up to the Nyquist frequency. The values at the Nyquist frequency and the imaginary part at zero frequency are set to zero. No rescaling of the amplitude, by distance or otherwise, is applied.

Parameters:

  • W (Waveform) – The waveform, whose times are in units of the total mass.

  • Dt (float) – The uniform time step, in units of the total mass, to which W is interpolated.

  • Vartheta (float) – The polar angle of the point at which the waveform is evaluated.

  • Varphi (float) – The azimuthal angle of the point at which the waveform is evaluated.

  • TotalMass (float) – The total mass of the system in solar masses, which sets the conversion of time to seconds.

  • WindowNCycles (int, default 1) – The number of cycles of the signal over which it is tapered at the start.

  • DetectorResponseAmp (float, default 1.0) – The amplitude of the complex detector response \(F_+ + i F_\times\).

  • DetectorResponsePhase (float, default 0.0) – The phase of the complex detector response \(F_+ + i F_\times\).

  • ExtraZeroPadPowers (int, default 0) – The number of additional factors of 2 by which the data are padded with zeros before the transform.

classmethod __new__(*args, **kwargs)

Accessing the data

WaveformAtAPointFT.F() → ndarray
WaveformAtAPointFT.F(f: int) → float

Return the frequencies of the Fourier transform, in hertz.

The frequencies are nonnegative and uniformly spaced, starting at zero.

Parameters:

f (int, optional) – Index of the frequency. If omitted, all frequencies are returned.

Returns:

float or ndarray of float – The frequency with the given index, or all frequencies.

WaveformAtAPointFT.NFreq() → int

Return the number of frequencies stored.

Returns:

int – The number of frequencies.

WaveformAtAPointFT.Re() → ndarray
WaveformAtAPointFT.Re(f: int) → float

Return the real part of the Fourier transform.

Parameters:

f (int, optional) – Index of the frequency. If omitted, the values at all frequencies are returned.

Returns:

float or ndarray of float – The real part at the frequency with the given index, or at each of the frequencies WaveformAtAPointFT.F.

WaveformAtAPointFT.Im() → ndarray
WaveformAtAPointFT.Im(f: int) → float

Return the imaginary part of the Fourier transform.

Parameters:

f (int, optional) – Index of the frequency. If omitted, the values at all frequencies are returned.

Returns:

float or ndarray of float – The imaginary part at the frequency with the given index, or at each of the frequencies WaveformAtAPointFT.F.

WaveformAtAPointFT.Dt() → float

Return the time step used before the Fourier transform.

Returns:

float – The uniform time step, in units of the total mass, to which the waveform was interpolated.

WaveformAtAPointFT.Vartheta() → float

Return the polar angle of the point at which the waveform was evaluated.

Returns:

float – The polar angle.

WaveformAtAPointFT.Varphi() → float

Return the azimuthal angle of the point at which the waveform was evaluated.

Returns:

float – The azimuthal angle.

WaveformAtAPointFT.IsNormalized() → bool

Return whether the transform has been normalized.

Returns:

bool – True if WaveformAtAPointFT.Normalize has been applied to this object.

Noise-weighted inner products

WaveformAtAPointFT.InversePSD(Detector: str = 'AdvLIGO_ZeroDet_HighP') → ndarray

Return the inverse noise power spectral density of a detector.

The inverse PSD \(1/S_n(f)\) is evaluated at each of the frequencies WaveformAtAPointFT.F, and may be passed as the InversePSD argument of WaveformAtAPointFT.SNR, WaveformAtAPointFT.InnerProduct, WaveformAtAPointFT.Match, and WaveformAtAPointFT.Normalize. It is zero (or negligibly small) outside the sensitive band of the detector.

Parameters:

Detector (str, default "AdvLIGO_ZeroDet_HighP") –

The name of the noise curve, which must be one of these:

  • "AdvLIGO_ZeroDet_HighP": Advanced LIGO, zero detuning and high power, from LIGO-T0900288-v3, between 10 Hz and 16384 Hz.

  • "AdvLIGO_ZeroDet_LowP": Advanced LIGO, zero detuning and low power, from LIGO-T0900288-v3, between 10 Hz and 16384 Hz.

  • "AdvLIGO_NSNSOptimal": a fit to the Advanced LIGO noise curve optimized for neutron-star binaries, between 10 Hz and 8192 Hz.

  • "IniLIGO_Approx": an approximation to the design goal of initial LIGO, between 40 Hz and 8192 Hz.

  • "Flat": a PSD equal to 1 at every frequency.

Any other name raises an error.

Returns:

ndarray of float – The inverse PSD at each frequency.

WaveformAtAPointFT.InnerProduct(B: WaveformAtAPointFT, InversePSD: ndarray) → float

Compute the noise-weighted inner product with another waveform.

The inner product is

\[(A|B) = 4\, \Delta f \sum_k \frac{\mathrm{Re}[\tilde{A}(f_k) \tilde{B}^*(f_k)]}{S_n(f_k)},\]

where \(A\) is this waveform, the sum runs over the stored frequencies \(f_k\), and \(\Delta f\) is their spacing. No maximization over time or phase offsets is done; for that, use WaveformAtAPointFT.Match.

Parameters:
Returns:

float – The inner product.

WaveformAtAPointFT.SNR(InversePSD: ndarray) → float
WaveformAtAPointFT.SNR(Detector: str = 'AdvLIGO_ZeroDet_HighP') → float

Compute the signal-to-noise ratio of the waveform.

The signal-to-noise ratio is

\[\rho = \sqrt{4\, \Delta f \sum_k \frac{|\tilde{h}(f_k)|^2}{S_n(f_k)}},\]

where the sum runs over the stored frequencies \(f_k\) and \(\Delta f\) is their spacing.

Parameters:
Returns:

float – The signal-to-noise ratio.

WaveformAtAPointFT.Match(B: WaveformAtAPointFT, InversePSD: ndarray) → float
WaveformAtAPointFT.Match(
B: WaveformAtAPointFT,
Detector: str = 'AdvLIGO_ZeroDet_HighP',
) → float
WaveformAtAPointFT.Match(
B: WaveformAtAPointFT,
InversePSD: ndarray,
timeOffset: float,
phaseOffset: float,
match: float,
) → tuple[float, float, float]
WaveformAtAPointFT.Match(
B: WaveformAtAPointFT,
timeOffset: float,
phaseOffset: float,
match: float,
Detector: str = 'AdvLIGO_ZeroDet_HighP',
) → tuple[float, float, float]

Compute the match between this waveform and another.

The complex noise-weighted overlap of the two waveforms is computed as a function of the time offset between them by an inverse Fourier transform, and its magnitude is maximized over that offset; maximizing the magnitude also maximizes over the phase offset. The match is

\[4\, \Delta f \max_t \left| \sum_k \frac{\tilde{A}(f_k) \tilde{B}^*(f_k)}{S_n(f_k)} e^{2\pi i f_k t} \right|.\]

This is the conventional match, between 0 and 1, only if both waveforms have been normalized with WaveformAtAPointFT.Normalize; otherwise, a warning is printed and the unnormalized overlap is returned. The two waveforms must have the same number of frequencies and the same frequency spacing, or an error is raised.

The method may be called as Match(B, InversePSD) or Match(B, Detector), which return only the match, or as Match(B, InversePSD, timeOffset, phaseOffset, match) or Match(B, timeOffset, phaseOffset, match, Detector), which return the tuple (timeOffset, phaseOffset, match). In the latter forms, the input values of timeOffset, phaseOffset, and match are ignored; they serve only to select the form that returns the offsets.

Parameters:
Returns:

  • timeOffset (float) – The time offset between the waveforms, in seconds, at which the overlap is maximized. It is returned only in the tuple forms.

  • phaseOffset (float) – Half the phase of the complex overlap at that time offset. It is returned only in the tuple forms.

  • match (float) – The match between the two waveforms.

WaveformAtAPointFT.Normalize(InversePSD: ndarray) → object
WaveformAtAPointFT.Normalize(Detector: str = 'AdvLIGO_ZeroDet_HighP') → object

Normalize the waveform to unit signal-to-noise ratio.

The Fourier transform is divided by the signal-to-noise ratio computed by WaveformAtAPointFT.SNR with the given noise curve. If the waveform has already been normalized, it is left unchanged, even if a different noise curve is given.

Parameters:
Returns:

WaveformAtAPointFT – This object, modified in place.

WaveformAtAPointFT.ZeroAbove(Frequency: float) → object

Set the Fourier transform to zero above a frequency.

Parameters:

Frequency (float) – The frequency, in hertz, above which the data are set to zero.

Returns:

WaveformAtAPointFT – This object, modified in place.