Overview¶
This page summarizes the conceptual structure behind the API contracts in
l2d_interface.contract.
Typical L2D workflow for modelled signals¶
In a typical L2D workflow for modelled signals, we start with preprocessed L1 data, and then prepare it in a certain representation (e.g. time-series, Fourier-domain, or wavelets, etc) for matched-filtering. Representations are classified by their domain (time, frequency, time-frequency), and different representations in the same domain can be further distinguished by their kind (e.g. short-time Fourier transform vs wavelet).
The matched-filtering step computes an inner product between the prepared data and a signal template, which gives the correlation between both. Conceptually, the signal template is obtained by first feeding parameters into a waveform model to get a waveform, and then applying the LISA response to get its projection onto different channels. It is the projected waveform that enters the inner product to correlate with the data.
Information flow:
Processed L1 Data ──────────────> TransformedData ────────────────────────────────────>┐
[channel → TDRep] [channel → Rep] |
| │
TD/FD/TF │
│
PlusCrossWaveform ────> [LISA Response] ──────> ProjectedWaveform ────────────────────>|
Rep [channel → Rep] |
[OR] |
│
HarmonicWaveform ─────> [LISA Response] ───> HarmonicProjectedWaveform ─────────────────>|
[harmonic → Rep] [harmonic → ProjectedWaveform] |
[channel → Rep] |
│ │
┌─────────────────────────────────────────────────────────┐ |
│ DOWNSTREAM PROCESSING │ |
│ (correlation inner product, likelihood evaluation, etc) │<──────────────────────────────┘
└─────────────────────────────────────────────────────────┘
Representation¶
The core information carriers are the representations of GW data and signals,
for which we design contracts (see l2d_interface.contract.Representation).
The classification of representations by domain and kind is reflected in the
following hierarchy:
Representation[DomainT, GridT, KindT]
|
____________|______________
| |
| Time-Frequency
| |
__________|_________ ________|__________
| | | |
TD FD Dense Sparse
Rep Rep TFRep TFRep
| |
Uniform Uniform
TDRep FDRep
Representations not only carry the signal content (called entries)
but also the grid on which the signal is presented.
A grid is a collection of axes, where an axis is conceptually
a 1D array of coordinates, which may be lazily evaluated.
For the domains we consider, there are three types of grids:
Grid1D ─── tuple[Axis] (1D)
Grid2D ─── tuple[Axis, Axis] (2D, Cartesian product)
Grid2DSparse ─── Protocol with indices (2D, sparse points)
It is part of the contract that the entries must be array objects following the shape convention:
``(n_batches, n_channels, n_harmonics, n_features, *grid_like)``
The last part of the shape, *grid_like, depends on the type of grid:
1D:
(n_batches, n_channels, n_harmonics, n_features, n_grid)2D, Cartesian:
(n_batches, n_channels, n_harmonics, n_features, n_freq, n_time)2D, sparse:
(n_batches, n_channels, n_harmonics, n_features, n_sparse)
Note that n_harmonics=1 should be considered as trivial placeholders for cases
where there is sementically no harmonic decomposition (e.g. for data, \(h_{+}\)
or \(h_{\times}\)).
Transformed Data¶
The transformed data contract (see l2d_interface.contract.TransformedData) is a mapping from
channel names to representations. For data, the channel names include the LISA TDI
channel names (e.g. “X”, “Y”, “Z”, “A”, “E”, “T”, etc) and those for
data quality indicators.
As part of the contract, the different channels must have the same
domain, kind, and grid. It is thus possible to obtain an array following the aforementioned shape convention
by stacking the entries of different channels along the channel axis (in an
actual implementation, it could be the stacked array that is stored internally).
This array is returned by a method called get_kernel. The channel names and the common domain, kind, and grid
are attributes of the data object. Downstream can stay agnostic about the
concrete implementation of the data object to fetch all the information it needs
to do its job.
Projected Waveform¶
We provide contracts for PlusCrossWaveform, HarmonicWaveform,
ProjectedWaveform, and HarmonicProjectedWaveform (see
l2d_interface.contract.PlusCrossWaveform,
l2d_interface.contract.HarmonicWaveform,
l2d_interface.contract.ProjectedWaveform,
and l2d_interface.contract.HarmonicProjectedWaveform).
A PlusCrossWaveform object is a Representation where the entries
have the shape convention with n_channels=1, n_harmonics=1, n_features=2,
where the first component along the features axis corresponds to the plus polarization,
and the second to the cross polarization.
A HarmonicWaveform object is a mapping from harmonic modes (tuple of integers)
to representations. It is still expected that all the representations
are in the same domain and of the same kind, but they can have
different grids.
A ProjectedWaveform object is a mapping from channel names to representations,
where domain, kind, and grid should be the same for all channels,
and it provides get_kernel method to return an array following the shape convention
by stacking the entries of different channels along the channel axis.
This object also has attributes for channel names, domain, kind, and grid just like the transformed data contract.
The difference here, is that we do not expect non-TDI channel names as mapping keys.
A HarmonicProjectedWaveform object is a mapping from harmonic modes to projected waveform objects.
Similar to the harmonic waveform contract, the projected waveform objects can have different grids,
but they should have the same domain and kind. The harmonic projected waveform contract
also provides a method called get_kernel that tries to stack the entries of different harmonics along
the harmonic axis if possible (i.e. if they actually have the same grid), and raises an exception if not.