pespace.detector.tdi

Module for handling TDI combinations and data of TDI channels.

Functions

_add_into_tdi_data(tdi_data, input)

Add the input into TDI data.

Classes

DataInformation(channels, duration, ...)	Store TDI channel data information.
FDMichelsonConstantEqualArm([generation, ...])	Frequency-domain Michelson TDI combination with constant equal-arm approximation.
FDMichelsonConstantEqualArmFFT()	Frequency-domain Michelson TDI combination using FFT approach.
TDIChannelData([scaling, backend])	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 (INCOMPLETE).
_FDMichelsonConstantEqualArmTaichi(tdi_model)	Taichi backend for FDMichelsonConstantEqualArm.

pespace.detector.tdi._add_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 of the frequency band, in Hz.

Type:

float

maximum_frequency

Maximum frequency of the 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, backend='taichi')

Bases: object

Store and manipulate TDI channel data.

Parameters:

• scaling (bool)

• backend (str)

__init__(scaling=False, backend='taichi')

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.

• backend (str, optional) – Computation backend, 'taichi' (default) or 'jax'.

Raises:

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

Return type:

None

_reset()

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.

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 of the frequency band, in Hz.

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

Raises:

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

Return type:

None

_init_td_data_taichi()

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_taichi()

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_taichi()

Initialize taichi.field for wavelet domain data.

Raises:

NotImplementedError –

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 of the frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency of the 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 of the frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency of the 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 of the frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency of the 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 of the frequency band, in Hz. Default is 1e-5.

• maximum_frequency (float, optional) – Maximum frequency of the 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 –

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 of the sampling frequency.

set_td_data_from_fd(window=None)

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

Raises:

NotImplementedError –

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 –

Return type:

None

set_wd_data_from_fd()

Compute wavelet domain data from frequency domain data.

Raises:

NotImplementedError –

Return type:

None

set_fd_noise_power_density_from_td_data()

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

Raises:

NotImplementedError –

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 –

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” to return taichi.StructField or “numpy” to return NamedTuple of arrays. Default is “taichi”.

Returns:

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

Return type:

ti.StructField or NamedTuple

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 may accidentally 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 –

Return type:

None

add_into_fd_data(input)

Add input data into frequency domain TDI data.

Parameters:

input (ti.StructField or NamedTuple) – Input data to add. If backend is taichi, expect StructField as input. If backend is``jax``, expect NamedTuple as input. The input data 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 for taichi backend, or not Namedtuple for jax backend.

Return type:

None

add_into_wd_data()

Add data into wavelet domain TDI data.

Raises:

NotImplementedError –

Return type:

None

save_to_file(filename)

Save the data of the instance to an hdf5 file.

Parameters:

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

Return type:

None

Notes

The file will contain groups: - class_attrs: including scaling, backend, _np_fp, and _np_cp - 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. - The numerical precision should match the settings of the current environment.

property td_data_numpy: tuple

Get time domain data as arrays.

Returns:

NamedTuple mapping channel names to time domain data arrays.

Return type:

NamedTuple

property fd_data_numpy: tuple

Get frequency domain data as arrays.

Returns:

NamedTuple mapping channel names to complex frequency domain data arrays.

Return type:

NamedTuple

property wd_data_numpy: tuple

Get wavelet domain data as arrays.

Returns:

NamedTuple mapping channel names to wavelet domain data arrays.

Return type:

NamedTuple

property fd_noise_power_density_numpy: tuple

Get frequency domain noise power spectral density as arrays.

Returns:

NamedTuple mapping channel names to noise psd arrays.

Return type:

NamedTuple

class pespace.detector.tdi.TDICombinationModel

Bases: ABC

Abstract base class for TDI combination models.

abstractmethod update_tdi_response()

Update TDI response from 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 (INCOMPLETE).

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, backend='taichi')

Bases: object

Frequency-domain Michelson TDI combination with constant equal-arm approximation.

Supports generation 1.5 and 2.0 TDI, orthogonal channels (A, E, T) and non-orthogonal channels (X, Y, Z).

domain = 'fd'

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

Parameters:

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

• orthogonal (bool, optional) – Whether to use orthogonal channels. If True, computating (A, E, T), otherwise, computating (X, Y, Z). Default is True.

• backend (str, optional) – Computation backend, 'taichi' (default) or 'jax'.

class pespace.detector.tdi._FDMichelsonConstantEqualArmTaichi(tdi_model)

Bases: TDICombinationModel

Taichi backend for FDMichelsonConstantEqualArm.

Parameters:

tdi_model (FDMichelsonConstantEqualArm)

init_tdi_combination_model(detector)

Initialize with the detector instance (taichi).

Basic properties are bound with self.tdi_model (external interface class), detector and _cached_field are bound with self (backend-dependent internal computation class).

Parameters:

detector (InterferometerAntenna)

Return type:

None

_set_cached_field()

Compute and cache frequency-dependent prefactors and delay factors.

Including the delay factors \(\mathrm{exp}(-i2\pi fL)\) and the generation-dependent prefactors.

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

_abc_impl = <_abc._abc_data object>

_data_oriented = True

static _get_Y_channel_response(delay_factor, singlelink_response)

Compute Y channel of TDI combination in frequency domain.

Parameters:

• delay_factor (<taichi.types.annotations.Template object at 0x7dc7f6e597d0>)

• singlelink_response (<taichi.types.annotations.Template object at 0x7dc7f6e59810>)

Return type:

<taichi.lang.matrix.VectorType object at 0x7dc864c46590>

static _get_Z_channel_response(delay_factor, singlelink_response)

Compute Z channel of TDI combination in frequency domain.

Parameters:

• delay_factor (<taichi.types.annotations.Template object at 0x7dc7f6e59e90>)

• singlelink_response (<taichi.types.annotations.Template object at 0x7dc7f6e59ed0>)

Return type:

<taichi.lang.matrix.VectorType object at 0x7dc864c46590>

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