sage.dsp.heterodyning

Frequency-domain heterodyning for GW signals.

Heterodyning removes a reference chirp phase from a waveform, leaving a slowly-varying residual that can be sampled more coarsely.

h_het(f) = h(f) × exp(-i φ_ref(f))

where φ_ref(f) = angle(h_ref(f)) is the chirp phase of a chosen reference binary. The apply_heterodyne function mirrors DINGO’s BaseFrequencyDomain.add_phase convention and supports the same data representations (numpy complex, torch complex, torch real/imag pairs).

For a search pipeline the reference binary is not known per-event. Use make_median_reference_binary to select a fixed reference from the median of the prior, then compute_reference_phase to obtain φ_ref(f).

Functions

apply_heterodyne(h, phase_ref)

Remove a reference chirp phase from frequency-domain strain data.

compute_reference_phase(m1, m2[, s1z, s2z, ...])

Compute the chirp phase of a reference binary on the rFFT grid.

make_median_reference_binary(m_min, m_max[, spin_max, ...])

Find a symmetric zero-spin binary whose chirp time matches the prior median.

residual_chirp_time(h_het, duration, *[, valid_threshold])

Measure the residual chirp time from a heterodyned waveform.

Module Contents

apply_heterodyne(h, phase_ref)[source]

Remove a reference chirp phase from frequency-domain strain data.

Computes h_het(f) = h(f) × exp(-i phase_ref(f)). Mirrors DINGO’s BaseFrequencyDomain.add_phase convention and supports the same set of data representations:

  • np.ndarray (complex dtype)

  • torch.Tensor (complex dtype)

  • torch.Tensor with real/imag encoding (shape (..., 2, N_freq))

Parameters:

  • h (np.ndarray or torch.Tensor) – Complex frequency-domain strain, shape (..., N_freq) for complex dtype or (..., 2+, N_freq) for real/imag encoding.

  • phase_ref (np.ndarray or torch.Tensor) – Reference phase φ_ref(f) in radians, shape (N_freq,).

Return type:

Heterodyned strain of the same type and shape as h.

compute_reference_phase(m1, m2, s1z=0.0, s2z=0.0, *, sample_rate, duration, f_min, f_max, approximant='IMRPhenomD', distance=100.0, coa_phase=0.0)[source]

Compute the chirp phase of a reference binary on the rFFT grid.

Generates h_ref(f) via PyCBC and returns φ_ref(f) = angle(h_ref(f)). Bins outside [f_min, f_max] or where |h_ref| = 0 are set to 0.

Parameters:

  • m1 (float) – Component masses [M_sun].

  • m2 (float) – Component masses [M_sun].

  • s1z (float) – Aligned spin parameters.

  • s2z (float) – Aligned spin parameters.

  • sample_rate (float) – Sample rate [Hz].

  • duration (float) – Segment duration [s].

  • f_min (float) – Lower frequency cutoff [Hz].

  • f_max (float) – Upper frequency cutoff [Hz].

  • approximant (str) – Waveform approximant (default IMRPhenomD, fast and accurate for aligned-spin binaries).

  • distance (float) – Source distance [Mpc]. Affects amplitude only — not the phase.

  • coa_phase (float) – Coalescence phase [rad]. With t_c = 0 (PyCBC default) and coa_phase = 0 the waveform phase equals the intrinsic SPA chirp phase with no additional carrier term.

Returns:

Reference phase φ_ref(f) in radians on the rFFT grid.

Return type:

np.ndarray, shape (N_freq,)

make_median_reference_binary(m_min, m_max, spin_max=0.99, *, f_eval, n_samples=2000, seed=42)[source]

Find a symmetric zero-spin binary whose chirp time matches the prior median.

Draws n_samples binaries from the flat-in-component-mass prior (m1, m2 ∈ [m_min, m_max] with m2 ≤ m1; s1z, s2z ∈ [-spin_max, spin_max]) and computes the median chirp time τ at f_eval. Then binary-searches for the equal-mass, zero-spin binary with the same τ.

Parameters:

  • m_min (float) – Component mass range [M_sun].

  • m_max (float) – Component mass range [M_sun].

  • spin_max (float) – Maximum aligned spin magnitude.

  • f_eval (float) – Frequency [Hz] at which the median chirp time is evaluated.

  • n_samples (int) – Number of prior samples.

  • seed (int) – RNG seed for reproducibility.

Returns:

Equal-mass, zero-spin reference binary [M_sun].

Return type:

(m_ref, m_ref, 0.0, 0.0)

residual_chirp_time(h_het, duration, *, valid_threshold=0.0)[source]

Measure the residual chirp time from a heterodyned waveform.

Computes τ_het(f_k) = |angle(h_het[k+1] × conj(h_het[k]))| × T / (2π) which is the local phase-gradient estimate of the remaining chirp rate after heterodyning.

Parameters:

  • h_het (np.ndarray, complex, shape (N_freq,)) – Heterodyned frequency-domain strain.

  • duration (float) – Segment duration [s]; sets Δf = 1/T.

  • valid_threshold (float) – Bins with |h_het| ≤ valid_threshold are treated as zero.

Returns:

Residual chirp time estimate at each native bin boundary.

Return type:

np.ndarray, shape (N_freq - 1,)