sage.dsp.multirate_sampling

Filename = Foobar.py Description = Lorem ipsum dolor sit amet

Created on Tue Mar 29 23:41:28 2022

__author__ = nnarenraju __copyright__ = Copyright 2022, ProjectName __credits__ = nnarenraju __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = nnarenraju __email__ = nnarenraju@gmail.com __status__ = [‘inProgress’, ‘Archived’, ‘inUsage’, ‘Debugging’]

Github Repository: NULL

Documentation: NULL

Classes

MultirateSampler	Physics-informed multi-rate decimator for batched GW time-domain data.
DyadicPyramidBinning	Physics-driven multi-rate bin layout for GW inspiral signals.

Module Contents

class MultirateSampler(binning_method, reflect_pad=None, **kwargs)

Bases: torch.nn.Module

Physics-informed multi-rate decimator for batched GW time-domain data.

Different parts of a gravitational-wave chirp sweep through different frequency bands at different times. This module partitions each time-domain segment into frequency-appropriate bins (as specified by a DyadicPyramidBinning object) and decimates each bin to the minimum sample rate that satisfies the Nyquist condition for the GW signal content in that time interval. The decimated chunks are concatenated back into a single (shorter) time series that contains the same signal information at a fraction of the original sample count.

Decimation is performed by cascaded half-band FIR lowpass filters (Kaiser-windowed sinc, 63 taps, ~90 dB stopband attenuation). Each call to _decimate_once() halves the sample rate; bins requiring a factor-of-4 reduction get two passes, factor-of-8 get three, etc. Intermediate decimated signals are reused across bins that share the same decimation factor, avoiding redundant computation.

Reflect padding is applied before each filter pass to suppress edge effects; the pad width is conservatively chosen to fully cover the filter group delay at the highest decimation factor used.

Parameters:

• binning_method (DyadicPyramidBinning) – Pre-computed bin layout (sample index ranges + target sample rate per bin).

• reflect_pad (int or None) – Override the automatically computed reflect-padding width. Must be ≥ max(2 * max_dec_factor, kernel_len) if set manually.

• **kwargs – Forwarded to nn.Module.__init__.

bins

Columns: [start_sample, end_sample, target_fs].

Type:

np.ndarray, shape (N_bins, 3)

kernel

Kaiser-windowed half-band FIR filter registered as a buffer.

Type:

torch.Tensor, shape (1, 1, 63)

Input / Output

--------------

forward(noisy_signals)

where L_compressed ≪ L with all signal information preserved.

Type:

(B, D, L) float32 → (B, D, L_compressed) float32

Return type:

torch.Tensor | GWBatch

Initialize internal Module state, shared by both nn.Module and ScriptModule.

cfg = None

bins

num_bins

original_fs

min_fs

max_power

power_to_bins

order_decimations(dec_powers)

Group bins by their required decimation power and compute the slice indices into the decimated signal for each bin.

Bins that require the same decimation factor are processed together in a single pass, reusing the already-decimated intermediate signal.

Parameters:

dec_powers (torch.Tensor, shape (N_bins,) int64) – log2(original_fs / target_fs) for each bin.

Returns:

Maps each unique decimation power to a list of (start_idx, end_idx, original_bin_index) tuples giving the slice positions in the decimated signal array.

Return type:

dict[int, list[tuple[int, int, int]]]

output_time_grid()

Physical time (seconds, from the unpadded window start) of every output sample, in output order. Shape (L_compressed,).

The forward concatenates the per-bin decimated chunks in bin order, and detailed_bins is sorted by start sample, so this grid is monotonically increasing. For bin i (decimation div = 2**power), output sample m comes from padded index (sidx + m) * div, i.e. unpadded sample (sidx + m) * div - pad. Computed once (off the hot path); used to map the tc soft-argmax onto physical time.

forward(input)

Decimate the input signal according to the pre-computed bin layout.

Accepts either a raw float32 tensor (legacy) or a GWBatch. When a GWBatch is provided, the state is validated — the grid must be TD_UNIFORM (uniform time-domain data produced by FiducialWhitening). A PipelineError is raised immediately if the grid is incompatible (e.g. FD_COARSE — non-uniform FD data cannot be multirate-sampled).

Parameters:

input (torch.Tensor or GWBatch) – Whitened time-domain strain (B, D, L) float32, or a GWBatch wrapping it with TD_UNIFORM state.

Returns:

Multi-rate compressed time series (B, D, L_compressed) float32. Returns a GWBatch when input is a GWBatch (TD_MULTIRATE state); returns a raw tensor when input is a raw tensor.

Return type:

torch.Tensor or GWBatch

class DyadicPyramidBinning(param_bounds, lowest_allowed_fs=64.0, safe_nyquist_gap=20.0, min_bin_duration=0.05, verify_nyquist=False)

Physics-driven multi-rate bin layout for GW inspiral signals.

Constructs a set of time-frequency bins such that each bin is sampled at the minimum power-of-2 sample rate that satisfies the Nyquist criterion for the GW signal content in that time interval, given the prior mass range.

Algorithm overview

1. Compute the time-frequency (t, f) evolution of the longest possible inspiral in the mass prior using pnutils.get_inspiral_tf.

2. Walk backward in frequency from f_ISCO to the signal low-frequency cutoff, halving the frequency at each step to define a dyadic ladder of boundary frequencies.

3. For each ladder step, compute the sample index at which the GW signal first enters that frequency band, using the t(f) relationship from step 1.

4. Assign each time interval between consecutive boundaries the minimum power-of-2 sample rate sufficient to cover it (plus a safe Nyquist gap).

5. The merger / ringdown region (tc ± fudge) is always kept at the full detector sample rate.

6. Merge contiguous bins with identical sample rates and eliminate tiny bins by raising their sample rate to that of the neighbouring bin.

The resulting detailed_bins array is passed to MultirateSampler, which uses it to set up the FIR decimation cascade.

param param_bounds:

Prior parameter bounds dict with keys "mass1" and "tc". mass1 sets the lowest / highest mass for the frequency-ladder computation; tc sets the injection window for the unchanged region.

type param_bounds:

dict

param lowest_allowed_fs:

Minimum sample rate (Hz) for any bin. Must be a power of 2 or will be rounded up to the next power of 2 internally.

type lowest_allowed_fs:

float

param safe_nyquist_gap:

Extra margin (Hz) added to the required Nyquist frequency when choosing a bin’s sample rate. Guards against PN approximation error near bin boundaries.

type safe_nyquist_gap:

float

param min_bin_duration:

Bins shorter than this (seconds) are merged with their higher-fs neighbour to avoid extremely short decimated arrays.

type min_bin_duration:

float

param verify_nyquist:

If True, call verify_nyquist_condition() immediately after construction and raise if any bin violates the Nyquist limit.

type verify_nyquist:

bool

detailed_bins

Columns: [start_sample, end_sample, sample_rate]. Both indices are relative to the start of the full-rate segment.

Type:

np.ndarray, shape (N_bins, 3)

MTSUN_SI = 4.92549102554e-06

MSUN_SI = 1.989e+30

signal_low_freq_cutoff

sample_rate

signal_length

lowest_allowed_fs = 64.0

safe_nyquist_gap = 20.0

min_bin_duration = 0.05

extra_pre_tc_leeway

extra_post_tc_leeway

f_isco

fs_anchor

light_travel_time

pre_fudge_factor

post_fudge_factor

detailed_bins

get_imr_chirp_time(m1, m2, s1z, s2z, fl)

Return 1.1× the IMRPhenomD chirp time (seconds) for the given parameters.

plot_multirate_tf()

Plot the multi-rate time-frequency assignment manifold for the configured prior.

verify_nyquist_condition(verbose=True)

Verifies that for every multirate bin:

f(t) <= fs/2 - safe_nyquist_gap/2

across the entire bin.

Raises AssertionError if violated.