sage.core.pipeline

Sage pipeline state tracking.

Grid, ProcessingState, PipelineError, and GWBatch form a lightweight state machine that tracks how a batch of gravitational-wave data has been processed and raises informative errors when an invalid operation is attempted.

The three supported pipeline paths are:

FD_UNIFORM → FiducialWhitening → TD_UNIFORM → MultirateSampler → TD_MULTIRATE

(whiten + IFFT) (decimate)

FD_COARSE → FiducialWhitening → FD_COARSE (whitened)

(whiten, no IFFT —

non-uniform grid)

FD_UNIFORM → FiducialWhitening → TD_UNIFORM

(no multirate)

FD_COARSE data cannot be IFFTed (the grid is non-uniform) and cannot be multirate-sampled (which requires uniform time-domain data). Attempting either raises PipelineError immediately, before any computation begins.

Exceptions

PipelineError

Raised when an invalid processing step is attempted given the current state.

Classes

Grid	The frequency/time grid type of the current data representation.
ProcessingState	Immutable descriptor of a GWBatch's processing history.
GWBatch	A batch of gravitational-wave data paired with its processing state.

Module Contents

class Grid

Bases: str, enum.Enum

The frequency/time grid type of the current data representation.

Initialize self. See help(type(self)) for accurate signature.

FD_UNIFORM = 'fd_uniform'

FD_COARSE = 'fd_coarse'

TD_UNIFORM = 'td_uniform'

TD_MULTIRATE = 'td_multirate'

exception PipelineError

Bases: RuntimeError

Raised when an invalid processing step is attempted given the current state.

Initialize self. See help(type(self)) for accurate signature.

class ProcessingState

Immutable descriptor of a GWBatch’s processing history.

Each transition method returns a new ProcessingState or raises PipelineError when the requested operation is incompatible with the current state. Validation fires at call time — before any tensor operations — so invalid pipelines fail fast.

Parameters:

• grid (Grid) – Current frequency/time grid type.

• whitened (bool) – Whether the batch has been whitened (divided by the ASD).

grid: Grid

whitened: bool = False

is_fd()

Return type:

bool

is_td()

Return type:

bool

n_channels()

Number of network input channels: 1 for TD (real), 2 for FD (real+imag).

Return type:

int

after_whiten()

Return type:

ProcessingState

after_ifft()

Return type:

ProcessingState

after_multirate()

Return type:

ProcessingState

class GWBatch

A batch of gravitational-wave data paired with its processing state.

Parameters:

• data (torch.Tensor) – Shape (B, D, F) complex for FD grids, or (B, D, T) float32 for TD grids.

• state (ProcessingState) – Current processing state — tracks the grid type and whether the batch has been whitened.

• freqs (torch.Tensor or None) – Frequency array in Hz, shape (F,). Non-None for FD grids. None for TD grids.

• coarse_indices (torch.Tensor or None) – Integer indices into the full uniform FD array (0-to-Nyquist) that correspond to the coarse grid points. Non-None only when state.grid == Grid.FD_COARSE (worst-case multibanding). Allows whitening and other FD operations to select the correct coefficients from full-resolution buffers without recomputing frequencies.

data: torch.Tensor

state: ProcessingState

freqs: torch.Tensor | None = None

coarse_indices: torch.Tensor | None = None

property n_channels: int

1 (TD, real) or 2 (FD, real + imag).

Type:

Network input channels

Return type:

int

to_network_input()

Convert to a real float tensor ready for the neural network.

Returns:

TD data (B, D, T) — returned as-is (already float32). FD data (B, D, F) complex — real and imaginary parts of every detector are stacked into (B, 2·D, F) float32.

Return type:

torch.Tensor