pespace.detector.tdi

Module for handling TDI combinations and data of TDI channels.

Classes

DataInformation(channels, duration, ...)	Store TDI channel data information.
FDMichelsonConstantEqualArm([generation, ...])	Frequency-domain Michelson TDI combination for constant equal-arm detectors.
FDMichelsonConstantEqualArmFFT()	Frequency-domain Michelson TDI combination using FFT approach.
TDIChannelData([scaling])	Store and manipulate TDI channel data.
TDICombinationModel()	Abstract base class for TDI combination models.
TDMichelsonConstantEqualArm([generation, ...])	Time-domain Michelson TDI combination for constant equal-arm detectors (UNCOMPLETE).

pespace.detector.tdi._add_input_field_into_tdi_data(tdi_data, input)

Add the input into TDI data.

The input field must have the same shape and channels as TDI_data. StructField has the default layout of AoS, unrolling the channels in the inner loop for memory accessing efficiency. This function is dimensionality-independent and can be used for TDI data of all domains.

Parameters:

• tdi_data (ti.template()) – Target TDI data field to add into.

• input (ti.template()) – Input field to be added, must have same shape and channels as tdi_data.

class pespace.detector.tdi.DataInformation(channels, duration, delta_time, start_time, minimum_frequency, maximum_frequency)

Bases: object

Store TDI channel data information.

Parameters:

• channels (tuple[str, ...])

• duration (float)

• delta_time (float)

• start_time (float)

• minimum_frequency (float)

• maximum_frequency (float)

channels

TDI channel names.

Type:

tuple[str, …]

duration

Observing duration of data, in seconds.

Type:

float

delta_time

Sampling cadence, in seconds.

Type:

float

start_time

Time label for the first time sample, in seconds.

Type:

float

minimum_frequency

Minimum frequency for the limited frequency band, in Hz.

Type:

float

maximum_frequency

Maximum frequency for the limited frequency band, in Hz.

Type:

float

sampling_frequency

Sampling frequency, computed as 1/delta_time.

Type:

float

delta_frequency

Frequency resolution, computed as 1/duration.

Type:

float

time_series_length

Number of time samples.

Type:

int

time_samples_array

Numpy array of time sample values.

Type:

NDArray

full_frequency_series_length

Length of full frequency series from FFT.

Type:

int

full_frequency_samples_array

Array of all frequency samples from FFT.

Type:

NDArray

frequency_mask_array

Boolean mask for selecting frequencies within [minimum_frequency, maximum_frequency].

Type:

NDArray[np.bool_]

frequency_samples_array

Numpy array of frequency samples within the specified range.

Type:

NDArray

frequency_series_length

Number of frequency samples within the specified range.

Type:

int

channels: tuple[str, ...]

duration: float

delta_time: float

start_time: float

minimum_frequency: float

maximum_frequency: float

sampling_frequency: float

delta_frequency: float

time_series_length: int

time_samples_array: ndarray[tuple[Any, ...], dtype[_ScalarT]]

full_frequency_series_length: int

full_frequency_samples_array: ndarray[tuple[Any, ...], dtype[_ScalarT]]

frequency_mask_array: ndarray[tuple[Any, ...], dtype[bool]]

frequency_samples_array: ndarray[tuple[Any, ...], dtype[_ScalarT]]

frequency_series_length: int

class pespace.detector.tdi.TDIChannelData(scaling=False)

Bases: object

Store and manipulate TDI channel data.

Parameters:

scaling (bool)

__init__(scaling=False)

Initialize TDIChannelData instance.

Parameters:

scaling (bool, optional) – Whether to apply scaling to the data. Default is False. If False and using f32 precision, a warning will be issued about potential numerical errors.

Raises:

UserWarning – If scaling is False and default float precision is f32.

Return type:

None

_reset()

Reset the instance to initial state.

Return type:

None

_initialize_state()

Initialize all data fields to None.

Return type:

None

property data_info: None | DataInformation

Get data information.

Returns:

Metadata about the TDI data, or None if not set.

Return type:

DataInformation or None

set_data_info(channels, duration, delta_time, start_time, minimum_frequency, maximum_frequency)

Set data information for TDI channels.

Parameters:

• channels (tuple[str, ...]) – TDI channel names.

• duration (float) – Observing duration of data, in seconds.

• delta_time (float) – Sampling cadence, in seconds.

• start_time (float) – Time label for the first time sample, in seconds.

• minimum_frequency (float) – Minimum frequency for the limited frequency band, in Hz.

• maximum_frequency (float) – Maximum frequency for the limited frequency band, in Hz.

Raises:

UserWarning – If data_info is being set when TDI data already exists.

Return type:

None

_init_td_data()

Initialize taichi.field for time domain data.

Creates time_samples and td_data fields. This is an internal method that should be called after setting data_info. Use set_td_data_from_zero or set_td_data_from_input to set time domain data externally.

Return type:

None

_init_fd_data()

Initialize taichi.field for frequency domain data.

Creates frequency_samples and fd_data fields. This is an internal method that should be called after setting data_info. Use set_fd_data_from_zero or set_fd_data_from_input to set frequency domain data externally.

Return type:

None

_init_wd_data()

Initialize taichi.field for wavelet domain data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

set_td_data_from_input(channels, duration, delta_time, tdi_data_array, start_time=0.0, minimum_frequency=1e-05, maximum_frequency=0.1)

Set time domain TDI data from input numpy array.

Parameters:

• channels (tuple[str, ...]) – TDI channel names.

• duration (float) – Observing duration of data, in seconds.

• delta_time (float) – Sampling cadence, in seconds.

• tdi_data_array (NDArray) – Array storing TDI data with shape (len(channels), time_series_length). The order in channels list must match the order in tdi_data_array.

• start_time (float, optional) – Time label for the first time sample, in seconds. Default is 0.0.

• minimum_frequency (float, optional) – Minimum frequency for the limited frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency for the limited frequency band, in Hz. Default is 0.1.

Raises:

• ValueError – If the shape of tdi_data_array does not match the expected dimensions.

• UserWarning – If TDI data has been set previously, the instance will be reset.

Return type:

None

set_fd_data_from_input(channels, duration, delta_time, tdi_data_array, start_time=0.0, minimum_frequency=1e-05, maximum_frequency=0.1)

Set frequency domain TDI data from input numpy array.

Parameters:

• channels (tuple[str, ...]) – TDI channel names.

• duration (float) – Observing duration of data, in seconds.

• delta_time (float) – Sampling cadence, in seconds.

• tdi_data_array (NDArray) – Complex array storing TDI data with shape (len(channels), frequency_series_length). The order in channels list must match the order in tdi_data_array.

• start_time (float, optional) – Time label for the first time sample, in seconds. Default is 0.0.

• minimum_frequency (float, optional) – Minimum frequency for the limited frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency for the limited frequency band, in Hz. Default is 0.1.

Raises:

• ValueError – If the shape of tdi_data_array does not match the expected dimensions.

• UserWarning – If TDI data has been set previously, the instance will be reset.

Return type:

None

Notes

The length of input tdi_data_array must match self.data_info.frequency_series_length. If the frequency series are obtained from FFT, self.data_info.frequency_mask_array may be needed to mask the array before input.

set_td_data_from_zero(channels, duration, delta_time, start_time=0.0, minimum_frequency=1e-05, maximum_frequency=0.1)

Initialize time domain TDI data with zeros.

Parameters:

• channels (tuple[str, ...]) – TDI channel names.

• duration (float) – Observing duration of data, in seconds.

• delta_time (float) – Sampling cadence, in seconds.

• start_time (float, optional) – Time label for the first time sample, in seconds. Default is 0.0.

• minimum_frequency (float, optional) – Minimum frequency for the limited frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency for the limited frequency band, in Hz. Default is 0.1.

Raises:

UserWarning – If TDI data has been set previously, the instance will be reset.

Return type:

None

set_fd_data_from_zero(channels, duration, delta_time, start_time=0.0, minimum_frequency=1e-05, maximum_frequency=0.1)

Initialize frequency domain TDI data with zeros.

Parameters:

• channels (tuple[str, ...]) – TDI channel names.

• duration (float) – Observing duration of data, in seconds.

• delta_time (float) – Sampling cadence, in seconds.

• start_time (float, optional) – Time label for the first time sample, in seconds. Default is 0.0.

• minimum_frequency (float, optional) – Minimum frequency for the limited frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency for the limited frequency band, in Hz. Default is 0.1.

Raises:

UserWarning – If TDI data has been set previously, the instance will be reset.

Return type:

None

set_wd_data_from_zero()

Initialize wavelet domain TDI data with zeros.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

set_fd_data_from_td(window=None)

Compute frequency domain data from time domain data using FFT.

Parameters:

window (None, float, str, tuple, or NDArray, optional) – Window function to apply before FFT. See scipy.signal.get_window for details. If None, no windowing is applied. Default is None.

Raises:

ValueError – If td_data is not set or fd_data has already been set.

Return type:

None

Notes

• time-shift of start time is not applied in current implementation.

• The FFT is normalized by dividing by the sampling frequency.

set_td_data_from_fd(window=None)

Compute time domain data from frequency domain data using inverse FFT.

Raises:

NotImplementedError – This method is not yet implemented.

Parameters:

window (None | float | str | tuple[str | float] | ndarray[tuple[Any, ...], dtype[_ScalarT]])

Return type:

None

set_wd_data_from_td()

Compute wavelet domain data from time domain data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

set_wd_data_from_fd()

Compute wavelet domain data from frequency domain data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

set_fd_noise_power_density_from_td_data()

Estimate frequency domain noise power spectral density from time domain data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

set_fd_noise_power_density_from_model(noise_model, **model_kwards)

Set frequency domain noise power spectral density from a noise model.

Parameters:

• noise_model (str or FrequencyDomainNoiseModel) – Name of an available noise model or a FrequencyDomainNoiseModel instance.

• **model_kwards (dict) – Additional keyword arguments passed to the noise model.

Raises:

• ValueError – If data_info has not been set, or if the noise_model string is not recognized.

• UserWarning – If fd_noise_power_density has been set previously.

Return type:

None

get_td_noise_realization()

Generate a noise realization in time domain.

Raises:

NotImplementedError – This method is not yet implemented.

get_fd_noise_realization(seed=None, output_type='taichi')

Generate a noise realization in frequency domain from the power spectral density.

This method generates colored Gaussian noise in the frequency domain based on the stored noise power spectral density. The noise is generated as white noise and then colored by multiplying with the square root of the PSD.

Parameters:

• seed (int, optional) – Seed for the random number generator for reproducible results. Default is None.

• output_type (str, optional) – Output format, either “taichi” for taichi.StructField or “numpy” for dict of arrays. Default is “taichi”.

Returns:

Noise realization in frequency domain. Format depends on output_type parameter.

Return type:

ti.StructField or dict[str, NDArray]

Raises:

ValueError – If fd_noise_power_density has not been set, or if output_type is invalid.

References

[1]

Eq. 12 in Phys. Rev. D 102, 023033 (2020) https://journals.aps.org/prd/abstract/10.1103/PhysRevD.102.023033

[2]

Bilby PowerSpectralDensity.get_noise_realisation https://lscsoft.docs.ligo.org/bilby/api/bilby.gw.detector.psd.PowerSpectralDensity.html#bilby.gw.detector.psd.PowerSpectralDensity.get_noise_realisation

Notes

To avoid directly modifying the stored tdi_data internally, which could potentially lead to mismatch among data of different domains, this method only returns the generated noise data. Use add_into_fd_data to manually add the noise realization into the TDI data.

add_into_td_data()

Add data into time domain TDI data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

add_into_fd_data(input)

Add input data into frequency domain TDI data.

Parameters:

input (ti.StructField or dict[str, NDArray]) – Input data to add. Can be either a taichi.StructField or a dictionary of numpy arrays. Must have the same shape and channels as fd_data.

Raises:

• ValueError – If input shape or channels do not match fd_data.

• TypeError – If input type is not taichi.StructField or dict[str, NDArray].

Return type:

None

add_into_wd_data()

Add data into wavelet domain TDI data.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

save_to_file(filename)

Save the data stored in the instance to an HDF5 file.

Parameters:

filename (str) – Path to the output HDF5 file.

Return type:

None

Notes

The file will contain three groups:

• data_info: metadata about the TDI data

• tdi_data: TDI data in various domains (td_data, fd_data, wd_data)

• noise_data: noise power spectral densities

static recover_from_file(filename)

Recover TDIChannelData instance from an HDF5 file.

This method reconstructs a TDIChannelData instance from a file saved by the save_to_file method.

Parameters:

filename (str) – Path to the input HDF5 file.

Returns:

Recovered TDIChannelData instance with all stored data.

Return type:

TDIChannelData

Raises:

AssertionError – If any derived quantities in the file do not match the recomputed values.

Notes

For other data formats, use methods for setting from input arrays according to the domain of the data, such as set_td_data_from_input, etc.

property td_data_numpy: dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]

Get time domain data as numpy arrays.

Returns:

Dictionary mapping channel names to time domain data arrays.

Return type:

dict[str, NDArray]

property fd_data_numpy: dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]

Get frequency domain data as complex numpy arrays.

Returns:

Dictionary mapping channel names to complex frequency domain data arrays.

Return type:

dict[str, NDArray]

property wd_data_numpy: dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]

Get wavelet domain data as numpy arrays.

Returns:

Dictionary mapping channel names to wavelet domain data arrays.

Return type:

dict[str, NDArray]

property fd_noise_power_density_numpy: dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]

Get frequency domain noise power spectral density as numpy arrays.

Returns:

Dictionary mapping channel names to noise PSD arrays.

Return type:

dict[str, NDArray]

class pespace.detector.tdi.TDICombinationModel

Bases: ABC

Abstract base class for TDI combination models.

This class defines the interface for TDI combination models that compute TDI observables from single-link responses.

abstract property domain: str

Get the domain of the TDI combination.

Returns:

Domain identifier, either ‘td’ (time domain) or ‘fd’ (frequency domain).

Return type:

str

abstractmethod update_tdi_response()

Update TDI response from single-link responses.

This method computes TDI observables from the detector’s single-link responses.

Return type:

None

_abc_impl = <_abc._abc_data object>

class pespace.detector.tdi.TDMichelsonConstantEqualArm(generation='1.5', orthogonal=True)

Bases: TDICombinationModel

Time-domain Michelson TDI combination for constant equal-arm detectors (UNCOMPLETE).

This class implements TDI combinations in the time domain for space-borne interferometers with constant and equal arm lengths. Supports both generation 1.5 and 2.0 TDI, and both orthogonal (A, E, T) and non-orthogonal (X, Y, Z) channel combinations.

domain = 'td'

__init__(generation='1.5', orthogonal=True)

Initialize time-domain Michelson TDI combination model.

Parameters:

• generation (str, optional) – TDI generation, either ‘1.5’ or ‘2.0’. Default is ‘1.5’.

• orthogonal (bool, optional) – Whether to use orthogonal channels (A, E, T) or non-orthogonal (X, Y, Z). Default is True.

Raises:

ValueError – If generation is not ‘1.5’ or ‘2.0’.

init_tdi_combination_model(detector)

Initialize the TDI combination model with a detector instance.

Parameters:

detector (InterferometerAntenna) – Detector instance to associate with this TDI model.

Return type:

None

update_tdi_response()

Update TDI response from single-link responses in time domain.

_abc_impl = <_abc._abc_data object>

_data_oriented = True

class pespace.detector.tdi.FDMichelsonConstantEqualArm(generation='1.5', orthogonal=True)

Bases: TDICombinationModel

Frequency-domain Michelson TDI combination for constant equal-arm detectors.

This class implements TDI combinations in the frequency domain for space-based interferometers with constant and equal arm lengths. Supports both generation 1.5 and 2.0 TDI, and both orthogonal (A, E, T) and non-orthogonal (X, Y, Z) channel combinations.

domain = 'fd'

__init__(generation='1.5', orthogonal=True)

Initialize frequency-domain Michelson TDI combination model.

Parameters:

• generation (str, optional) – TDI generation, either ‘1.5’ or ‘2.0’. Default is ‘1.5’.

• orthogonal (bool, optional) – Whether to use orthogonal channels (A, E, T) or non-orthogonal (X, Y, Z). Default is True.

Raises:

ValueError – If generation is not ‘1.5’ or ‘2.0’.

init_tdi_combination_model(detector)

Initialize the TDI combination model with a detector instance.

Parameters:

detector (InterferometerAntenna) – Detector instance to associate with this TDI model.

Return type:

None

_set_cached_field()

Compute and cache frequency-dependent prefactors and delay factors.

This method computes and caches the delay factors \(\mathrm{exp}(-i2\pi fL)\) and generation-dependent prefactors for TDI computation.

static _get_X_channel_response(delay_factor, singlelink_response)

Compute X channel of TDI combination in frequency domain.

Parameters:

• delay_factor (ti.template()) – Delay factor, \(\mathrm{exp}(-i2\pi fL)\).

• singlelink_response (ti.template()) – Single-link responses for six links.

Returns:

X channel response without the generation prefactor.

Return type:

ti_complex

static _get_Y_channel_response(delay_factor, singlelink_response)

Compute Y channel of TDI combination in frequency domain.

Parameters:

• delay_factor (ti.template()) – Delay factor, \(\mathrm{exp}(-i2\pi fL)\).

• singlelink_response (ti.template()) – Single-link responses for all six links.

Returns:

Y channel response without the generation prefactor.

Return type:

ti_complex

_abc_impl = <_abc._abc_data object>

_data_oriented = True

static _get_Z_channel_response(delay_factor, singlelink_response)

Compute Z channel of TDI combination in frequency domain.

Parameters:

• delay_factor (ti.template()) – Delay factor, \(\mathrm{exp}(-i2\pi fL)\).

• singlelink_response (ti.template()) – Single-link responses for all six links.

Returns:

Z channel response without the generation prefactor.

Return type:

ti_complex

update_tdi_response()

Update TDI response from single-link responses in frequency domain.

class pespace.detector.tdi.FDMichelsonConstantEqualArmFFT

Bases: TDICombinationModel

Frequency-domain Michelson TDI combination using FFT approach.

This class is a placeholder for implementing TDI combinations in the frequency domain using FFT-based methods for constant equal-arm detectors.

Notes

This class is not yet implemented.

_abc_impl = <_abc._abc_data object>

_data_oriented = True