API Reference

API contract for L2D data and waveform representations.

This module defines the protocol-based contracts for representing gravitational wave signals in different domains and on different grids.

For conceptual diagrams and shape conventions, see Overview.

class l2d_interface.contract.LinspaceLike

Protocol for custom linspace-like objects that can be used as axes in representations.

Classes implementing this protocol replace the standard 1D array axis with more memory efficiency.

property start: float

Start point of the linspace.

property step: float

Step size (cadence) of the linspace.

__len__() → int

Return the number of points in the linspace.

l2d_interface.contract.Axis = l2d_interface.array.Array[typing.Any, typing.Any] | l2d_interface.contract.LinspaceLike

Axis can be either a standard 1D array following the Python Array API standard, or a custom linspace-like object that implements the LinspaceLike protocol for memory-efficient axis representation.

class l2d_interface.contract.Grid2DSparse

Protocol for sparse 2D (time-frequency) grids.

A sparse grid selects a subset of points from the Cartesian product of two axes. Implements tuple-like indexing to access axes (compatible with dense Grid2D interface) and provides an indices property mapping sparse points to dense grid coordinates.

__getitem__(_Grid2DSparse__index: int) → Array[Any, Any] | LinspaceLike

Get the axis for the specified dimension index (0 for frequency, 1 for time).

__len__() → Literal[2]

Return the number of dimensions (always 2 for Grid2DSparse).

property indices: Array[Any, Any]

Array of shape (n_sparse, 2) containing the indices of the non-zero points in the 2D grid.

l2d_interface.contract.Grid = tuple[l2d_interface.array.Array[typing.Any, typing.Any] | l2d_interface.contract.LinspaceLike] | tuple[l2d_interface.array.Array[typing.Any, typing.Any] | l2d_interface.contract.LinspaceLike, l2d_interface.array.Array[typing.Any, typing.Any] | l2d_interface.contract.LinspaceLike] | l2d_interface.contract.Grid2DSparse

Physical domain of representations.

It can be one of the following:

• Grid1D: A tuple containing a single Axis

• Grid2D: A tuple containing two Axis objects

• Grid2DSparse: A protocol for sparse 2D grids, where the non-zero points are specified by a indices array of shape (n_sparse, 2).

class l2d_interface.contract.Representation

API contract for representation of gravitational wave signals.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.TDRepresentation

API contract for time-domain representations of gravitational wave signals.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.UniformTDRepresentation

API contract for uniformly sampled time-domain representations of gravitational wave signals.

property dt: float

Uniform time sampling interval.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.FDRepresentation

API contract for frequency-domain representations of gravitational wave signals.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.UniformFDRepresentation

API contract for uniformly sampled frequency-domain representations of gravitational wave signals.

property df: float

Uniform frequency sampling interval.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.DenseTFRepresentation

API contract for dense time-frequency representations of gravitational wave signals.

The entries array has shape (n_batches, n_channels, n_harmonics, n_features, n_freq, n_time) representing the full Cartesian product of frequency and time axes.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.SparseTFRepresentation

API contract for sparse time-frequency representations of gravitational wave signals.

For sparse representations, entries are flattened along the time-frequency dimensions. The actual TF point coordinates are recovered from grid.indices.

The entries array has shape (n_batches, n_channels, n_harmonics, n_features, n_sparse) where n_sparse is the number of non-zero time-frequency points.

Example

Sparse time-frequency representation (only 5000 active points out of 100×500=50000):

# entries shape: (1, 1, 1, 1, 5000)
# grid.indices: (5000, 2)  with (freq_idx, time_idx) pairs
# Only 10% of the dense grid is used, enabling memory-efficient storage

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.Data

API contract for data containers of gravitational wave signals.

Data objects represent the output from (pre-processed) L1 Data, which is the source of truth for the entire L2D pipeline. They should not be modified by L2D analysis.

Maps channel names to time-domain TDRepresentation objects. All channels share the same time grid.

__getitem__(key: str) → TDRepresentation[None]

Get a channel representation by name.

See _ChannelMapping.__getitem__().

property domain: Literal['time']

Physical domain (always ‘time’ for Data).

See _ChannelMapping.domain.

property grid: tuple[Array[Any, Any] | LinspaceLike]

1D time grid specification shared by all channels.

See _ChannelMapping.grid.

property times: Array[Any, Any] | LinspaceLike

Time axis.

__iter__() → Iterator[str]

Iterate over channel names.

__len__() → int

Return the number of channels.

property channel_names: tuple[str, ...]

Names of all channels and their order.

get_kernel(backend: str | None = None) → Array[Any, Any]

Return an array of the conventional shape (n_batches, n_channels, 1, n_features, *grid_like) for downstream processing (e.g., by noise models to compute inner products).

Parameters:

• backend (Optional string specifying the desired array library for the returned array.) – If None, use the underlying array library of the entries.

• note:: (..) – This method can be trivially implemented if the underlying data entries are already stored in the conventional shape. Otherwise, it can be implemented by stacking the representations of individual channels along the channel dimension.

property kind: KindT

Semantic kind shared by all channels.

All Representation objects must share the same kind.

class l2d_interface.contract.TransformedData

Protocol for objects transformed from Data objects.

TransformedData objects are outputs of transformation of Data objects, e.g., by Fourier transform, or time-frequency transform. They preserve channel semantics of Data objects.

Maps channel names to Representation objects in any domain (time, frequency, or time-frequency). All channels share the same domain, grid, kind.

TransformedData and HarmonicProjectedWaveform are the two only entry points for downstream processing of L2D.

__getitem__(key: str) → Representation

Get a channel representation by name.

The Representation objects returned by this method must have n_channels=1 (i.e. shape[1] == 1) and n_harmonics=1 (i.e. shape[2] == 1).

Note

Though not strictly required, implementations are encouraged to return views of the same underlying array rather than storing independent arrays per channel.

__iter__() → Iterator[str]

Iterate over channel names.

__len__() → int

Return the number of channels.

property channel_names: tuple[str, ...]

Names of all channels and their order.

property domain: DomainT

Physical domain shared by all channels.

All Representation objects must share the same domain.

get_kernel(backend: str | None = None) → Array[Any, Any]

Return an array of the conventional shape (n_batches, n_channels, 1, n_features, *grid_like) for downstream processing (e.g., by noise models to compute inner products).

Parameters:

• backend (Optional string specifying the desired array library for the returned array.) – If None, use the underlying array library of the entries.

• note:: (..) – This method can be trivially implemented if the underlying data entries are already stored in the conventional shape. Otherwise, it can be implemented by stacking the representations of individual channels along the channel dimension.

property grid: GridT

Grid specification shared by all channels.

All Representation objects must share the same grid.

property kind: KindT

Semantic kind shared by all channels.

All Representation objects must share the same kind.

class l2d_interface.contract.HarmonicWaveform

API contract for gravitational wave signals generated by waveform models.

HarmonicWaveform objects are keyed by harmonic mode, supporting heterogeneous grids across modes.

__getitem__(key: HarmonicT) → Representation

Get a harmonic representation by mode index.

The Representation objects returned by this method must have n_harmonics=1 (i.e. shape[2] == 1).

__iter__() → Iterator

Iterate over harmonic modes.

__len__() → int

Return the number of harmonic modes.

property domain: DomainT

Physical domain shared by all harmonics.

All Representation objects must share the same domain.

property harmonics: tuple[HarmonicT, ...]

All harmonic modes and their order.

class l2d_interface.contract.PlusCrossWaveform

API contract for plus and cross polarization waveforms.

PlusCrossWaveform contains the plus and cross polarization waveforms. The entries array has shape (n_batches, 1, 1, 2, *grid_like) where the features dimension of size 2 corresponds to the plus (the 0 component) and cross (the 1 component) polarizations.

property domain: DomainT

Physical domain of the representation.

One of: 'time', 'frequency', or 'time-frequency'. See TDRepresentation, FDRepresentation, DenseTFRepresentation and SparseTFRepresentation.

property entries: Array[Any, Any]

Multi-dimensional array following the Python Array API standard.

Shape convention: (n_batches, n_channels, n_harmonics, n_features, *grid_like)

• n_batches: Independent signal realizations

• n_channels: Detector channels (e.g., 1 for single, 3 for TDI X, Y, Z)

• n_harmonics: Harmonic modes (1 for single-mode, >1 for multi-mode)

• n_features: Features per grid point (1 for scalar, >1 for multivariate)

  • Most common case: time-series of scalar or Fourier coefficients (n_features=1)

  • Multivariate example: frequency-domain series with both amplitude and phase (n_features=2)

• *grid_like: Remaining dimensions determined by grid type

  • 1D grid: time-domain series or frequency-domain series (n_grid,)

  • 2D dense grid: dense time-frequency representations (n_freq, n_time)

  • 2D sparse grid: sparse time-frequency representations (n_sparse,) where n_sparse is the number of non-zero points. This can be read from grid.indices which is of shape (n_sparse, 2)

Note

Never squeeze dimensions, even if trivial (e.g., n_channels=1).

The presence of reserved dimensions for channels and harmonics is a design choice to support efficient cross-channel and cross-harmonic operations where applicable. It should not be taken to imply that all representations must have multiple channels or harmonics (many will have just one), nor that it is priledged to populate these dimensions by all means. In fact, when signals are homogeneous acros harmonics (common in waveform generation), we should use mapping containers keyed by harmonic mode and valued by representations with n_harmonics=1 (i.e., shape[2] == 1) rather than forcing them into a single array with n_harmonics > 1 (see HarmonicWaveform and HarmonicProjectedWaveform). Even more so, when signals are homogeneous across channels (common in detector response and recorded data), mapping containers keyed by channel name and valued by representations with n_channels=1 (i.e., shape[1] == 1) also provide more semantic clarity (see Data, TransformedData, and ProjectedWaveform).

property grid: GridT

Grid specification defining axis points.

1D grid for time-domain or frequency-domain series; 2D for time-frequency.

property kind: KindT

Optional semantic kind for domain-specific variants.

Examples: 'wavelet' for time-frequency representations. None for standard representations (e.g., scalar time/frequency series).

class l2d_interface.contract.ProjectedWaveform

API contract for waveforms projected onto detector channels without harmonic decomposition.

All channels share the same domain, grid, and kind.

__getitem__(key: str) → Representation

Get a channel representation by name.

The Representation objects returned by this method must have n_channels=1 (i.e. shape[1] == 1) and n_harmonics=1 (i.e. shape[2] == 1).

Note

Though not strictly required, implementations are encouraged to return views of the same underlying array rather than storing independent arrays per channel.

__iter__() → Iterator[str]

Iterate over channel names.

__len__() → int

Return the number of channels.

property channel_names: tuple[str, ...]

Names of all channels and their order.

property domain: DomainT

Physical domain shared by all channels.

All Representation objects must share the same domain.

get_kernel(backend: str | None = None) → Array[Any, Any]

Return an array of the conventional shape (n_batches, n_channels, 1, n_features, *grid_like) for downstream processing (e.g., by noise models to compute inner products).

Parameters:

• backend (Optional string specifying the desired array library for the returned array.) – If None, use the underlying array library of the entries.

• note:: (..) – This method can be trivially implemented if the underlying data entries are already stored in the conventional shape. Otherwise, it can be implemented by stacking the representations of individual channels along the channel dimension.

property grid: GridT

Grid specification shared by all channels.

All Representation objects must share the same grid.

property kind: KindT

Semantic kind shared by all channels.

All Representation objects must share the same kind.

class l2d_interface.contract.HarmonicProjectedWaveform

API contract for gravitational wave signals projected onto detector channels.

This is in general obtained by applying LISA response to generated waveforms.

TransformedData and HarmonicProjectedWaveform are the two only entry points for downstream processing of L2D. Due to the heterogeneity of harmonic modes, HarmonicProjectedWaveform does not provide a get_kernel method, but the kernels for individual harmonic modes can be retrieved by the get_kernel method of the corresponding ProjectedWaveform objects returned by __getitem__.

__getitem__(key: HarmonicT) → ProjectedWaveform

Get the projected waveform for a harmonic mode (across all detector channels).

Though not strictly required, implementations are encouraged to return views of the same underlying array rather than storing independent ProjectedWaveform objects per harmonic (if possible).

__iter__() → Iterator

Iterate over harmonic modes.

__len__() → int

Return the number of harmonic modes.

property domain: DomainT

Physical domain shared by all harmonics.

All ProjectedWaveform objects must share the same domain.

property harmonics: tuple[HarmonicT, ...]

All harmonic modes and their order.

property channel_names: tuple[str, ...]

Names of all detector channels and their order.

All ProjectedWaveform objects must share the same channel names.

property is_homogeneous: bool

Whether the projected waveform is homogeneous across harmonic modes.

If True, all harmonic modes share the same grid. If False, different harmonic modes can have different grids.

get_kernel(backend: str | None = None) → Array[Any, Any]

Return an array of the conventional shape (n_batches, n_channels, n_harmonics, n_features, *grid_like) for downstream processing (e.g., by noise models to compute inner products), only when is_homogeneous is True. Otherwise, this method should raise an error.

Parameters:

backend (Optional string specifying the desired array library for the returned array.) – If None, use the underlying array library of the response entries.