Skip to content

Detector

Functions:

Name Description
get_CE

Return a GroundBased2G instance for Cosmic Explorer (CE).
get_ET

Return a list of three GroundBased2G instances for Einstein Telescope (ET).
get_H1

Return a GroundBased2G instance for LIGO Hanford (H1).
get_L1

Return a GroundBased2G instance for LIGO Livingston (L1).
get_V1

Return a GroundBased2G instance for Virgo (V1).
get_detector_preset

Return a dictionary of pre-configured detector instances.

Detector ¤

Bases: ABC

Base class for all detectors.

Attributes:

Name Type Description
name str

Name of the detector.
data Data

Detector data object.
psd PowerSpectrum

Power spectral density object.
frequency_bounds tuple[float, float]

Lower and upper frequency bounds.

Methods:

Name Description
clear_data_and_psd

Clear the data and PSD of the detector.
fd_response

Modulate the waveform in the sky frame by the detector response in the frequency domain.
set_frequency_bounds

Set the frequency bounds for the detector.
td_response

Modulate the waveform in the sky frame by the detector response in the time domain.

sliced_fd_data: Complex[Array, ' n_freq'] property ¤

Get frequency-domain data slice based on frequency bounds.

Returns:

Type Description
Complex[Array, ' n_freq']

Complex[Array, "n_freq"]: Sliced frequency-domain data.

sliced_frequencies: Float[Array, ' n_freq'] property ¤

Get frequency-domain data slice based on frequency bounds.

Returns:

Type Description
Float[Array, ' n_freq']

Float[Array, "n_sample"]: Sliced frequency-domain data.
Float[Array, ' n_freq']

Float[Array, "n_sample"]: Frequency array.

sliced_psd: Float[Array, ' n_freq'] property ¤

Get PSD slice based on frequency bounds.

Returns:

Type Description
Float[Array, ' n_freq']

Float[Array, "n_freq"]: Sliced power spectral density.

start_time: float property ¤

GPS start time of the data segment.

clear_data_and_psd() -> None ¤

Clear the data and PSD of the detector.

fd_response(frequency: Float[Array, ' n_sample'], h_sky: dict[str, Float[Array, ' n_sample']], params: dict) -> Complex[Array, ' n_sample'] abstractmethod ¤

Modulate the waveform in the sky frame by the detector response in the frequency domain.

Parameters:

Name Type Description Default
frequency Float[Array, n_sample]

Array of frequency samples.

 required
h_sky dict[str, Float[Array, n_sample]]

Dictionary mapping polarization names to frequency-domain waveforms. The keys are polarization names (e.g., 'plus', 'cross') and values are complex strain arrays.

 required
params dict

Dictionary of source parameters including: - ra (Float): Right ascension in radians - dec (Float): Declination in radians - psi (Float): Polarization angle in radians - trigger_time (Float): The trigger time in sec - t_c (Float): The difference between peak time and trigger time in sec - gmst (Float): The greenwich mean sidereal time at the trigger time in radian

 required

Returns:

Type Description
Complex[Array, ' n_sample']

Complex[Array, "n_sample"]: Complex strain measured by the detector in frequency domain.

set_frequency_bounds(f_min: Optional[float] = None, f_max: Optional[float] = None) -> None ¤

Set the frequency bounds for the detector. This also set the sliced frequencies, data and psd.

Parameters:

Name Type Description Default
f_min Optional[float]

Minimum frequency.

 None
f_max Optional[float]

Maximum frequency.

 None

td_response(time: Float[Array, ' n_sample'], h_sky: dict[str, Float[Array, ' n_sample']], params: dict) -> Float[Array, ' n_sample'] abstractmethod ¤

Modulate the waveform in the sky frame by the detector response in the time domain.

Parameters:

Name Type Description Default
time Float[Array, ' n_sample']

Array of time samples.

 required
h_sky dict[str, Float[Array, ' n_sample']]

Dictionary mapping polarization names to time-domain waveforms.

 required
params dict

Dictionary of source parameters.

 required

Returns:

Type Description
Float[Array, ' n_sample']

Array of detector response in time domain.

GroundBased2G ¤

Bases: Detector

Object representing a ground-based detector.

Contains information about the location and orientation of the detector on Earth, as well as actual strain data and the PSD of the associated noise.

Attributes:

Name Type Description
name str

Name of the detector.
latitude Float

Latitude of the detector in radians.
longitude Float

Longitude of the detector in radians.
xarm_azimuth Float

Azimuth of the x-arm in radians.
yarm_azimuth Float

Azimuth of the y-arm in radians.
xarm_tilt Float

Tilt of the x-arm in radians.
yarm_tilt Float

Tilt of the y-arm in radians.
elevation Float

Elevation of the detector in meters.
polarization_mode list[Polarization]

List of polarization modes (pc for plus and cross) to be used in computing antenna patterns; in the future, this could be expanded to include non-GR modes.
data Data

Array of Fourier-domain strain data.
psd PowerSpectrum

Power spectral density object.

Methods:

Name Description
__init__

Initialize a ground-based detector.
antenna_pattern

Compute antenna patterns for polarizations at specified sky location.
delay_from_geocenter

Calculate time delay between two detectors in geocentric coordinates.
fd_response

Modulate the waveform in the sky frame by the detector response in the frequency domain.
get_whitened_frequency_domain_strain

Get the whitened frequency-domain strain.
inject_signal

Inject a signal into the detector data.
load_and_set_psd

Load power spectral density (PSD) from file or default GWTC-2 catalog,
set_data

Add data to the detector.
set_psd

Add PSD to the detector.
td_response

Modulate the waveform in the sky frame by the detector response in the time domain.
whitened_frequency_to_time_domain_strain

Get the whitened frequency-domain strain.

arms: tuple[Float[Array, 3], Float[Array, 3]] property ¤

Get the detector arm vectors.

Returns:

Type Description
tuple[Float[Array, 3], Float[Array, 3]]

tuple[Float[Array, "3"], Float[Array, "3"]]: A tuple containing: - x: X-arm vector in geocentric Cartesian coordinates - y: Y-arm vector in geocentric Cartesian coordinates

tensor: Float[Array, '3 3'] property ¤

Get the detector tensor defining the strain measurement.

For a 2-arm differential-length detector, this is given by:

$$

D_{ij} = \left(x_i x_j - y_i y_j\right)/2

$$

for unit vectors \(x\) and \(y\) along the x and y arms.

Returns:

Type Description
Float[Array, '3 3']

Float[Array, "3 3"]: The 3x3 detector tensor in geocentric coordinates.

vertex: Float[Array, 3] property ¤

Detector vertex coordinates in the reference celestial frame.

Based on arXiv:gr-qc/0008066 Eqs. (B11-B13) except for a typo in the definition of the local radius; see Section 2.1 of LIGO-T980044-10.

Returns:

Type Description
Float[Array, 3]

Float[Array, "3"]: Detector vertex coordinates in geocentric Cartesian coordinates.

whitened_frequency_domain_data: Complex[Array, ' n_sample'] property ¤

Get the whitened frequency-domain data.

Parameters:

Name Type Description Default
frequency Float[Array, n_sample]

Array of frequency samples.

 required

Returns:

Type Description
Complex[Array, ' n_sample']

Float[Array, "n_sample"]: Whitened frequency-domain data.

whitened_time_domain_data: Float[Array, ' n_sample'] property ¤

Get the whitened time-domain data.

Parameters:

Name Type Description Default
time Float[Array, n_sample]

Array of time samples.

 required

Returns:

Type Description
Float[Array, ' n_sample']

Float[Array, "n_sample"]: Whitened time-domain data.

__init__(name: str, latitude: float = 0, longitude: float = 0, elevation: float = 0, xarm_azimuth: float = 0, yarm_azimuth: float = 0, xarm_tilt: float = 0, yarm_tilt: float = 0, modes: str = 'pc') ¤

Initialize a ground-based detector.

Parameters:

Name Type Description Default
name str

Name of the detector.

 required
latitude float

Latitude of the detector in radians. Defaults to 0.

 0
longitude float

Longitude of the detector in radians. Defaults to 0.

 0
elevation float

Elevation of the detector in meters. Defaults to 0.

 0
xarm_azimuth float

Azimuth of the x-arm in radians. Defaults to 0.

 0
yarm_azimuth float

Azimuth of the y-arm in radians. Defaults to 0.

 0
xarm_tilt float

Tilt of the x-arm in radians. Defaults to 0.

 0
yarm_tilt float

Tilt of the y-arm in radians. Defaults to 0.

 0
modes str

Polarization modes. Defaults to "pc".

 'pc'

antenna_pattern(ra: FloatScalar, dec: FloatScalar, psi: FloatScalar, gmst: FloatScalar) -> dict[str, Complex] ¤

Compute antenna patterns for polarizations at specified sky location.

In the long-wavelength approximation, the antenna pattern for a given polarization is the dyadic product between the detector tensor and the corresponding polarization tensor.

Parameters:

Name Type Description Default
ra Float

Source right ascension in radians.

 required
dec Float

Source declination in radians.

 required
psi Float

Source polarization angle in radians.

 required
gmst Float

Greenwich mean sidereal time (GMST) in radians.

 required

Returns:

Type Description
dict[str, Complex]

dict[str, Complex]: Dictionary mapping polarization names to their antenna pattern values.

delay_from_geocenter(ra: FloatScalar, dec: FloatScalar, gmst: FloatScalar) -> FloatScalar ¤

Calculate time delay between two detectors in geocentric coordinates.

Based on XLALArrivaTimeDiff in TimeDelay.c https://lscsoft.docs.ligo.org/lalsuite/lal/grouptimedelayh.html

Parameters:

Name Type Description Default
ra Float

Right ascension of the source in radians.

 required
dec Float

Declination of the source in radians.

 required
gmst Float

Greenwich mean sidereal time in radians.

 required

Returns:

Name Type Description
Float FloatScalar

Time delay from Earth center in seconds.

fd_response(frequency: Float[Array, ' n_sample'], h_sky: dict[str, Float[Array, ' n_sample']], params: dict[str, Float]) -> Complex[Array, ' n_sample'] ¤

Modulate the waveform in the sky frame by the detector response in the frequency domain.

Parameters:

Name Type Description Default
frequency Float[Array, n_sample]

Array of frequency samples.

 required
h_sky dict[str, Float[Array, n_sample]]

Dictionary mapping polarization names to frequency-domain waveforms. Keys are polarization names (e.g., 'plus', 'cross') and values are complex strain arrays.

 required
params dict[str, Float]

Dictionary of source parameters containing: - ra (Float): Right ascension in radians - dec (Float): Declination in radians - psi (Float): Polarization angle in radians - trigger_time (Float): The trigger time in sec - t_c (Float): The difference between peak time and trigger time in sec - gmst (Float): The greenwich mean sidereal time at the trigger time in radian

 required

Returns:

Name Type Description
Array Complex[Array, ' n_sample']

Complex strain measured by the detector in frequency domain, obtained by combining the antenna patterns for each polarization mode.

get_whitened_frequency_domain_strain(frequency_series: Complex[Array, ' n_freq']) -> Complex[Array, ' n_freq'] ¤

Get the whitened frequency-domain strain. Args: frequency_series (Complex[Array, "n_freq"]): Array of frequency domain data/signal. Returns: Complex[Array, "n_freq"]: Whitened frequency-domain strain.

inject_signal(duration: float, sampling_frequency: float, trigger_time: float, waveform_model, parameters: dict[str, float], f_min: float, f_max: float, start_time: Optional[float] = None, zero_noise: bool = False, rng_key: Optional[Key] = None) -> None ¤

Inject a signal into the detector data.

Note: The power spectral density must be set beforehand.

Parameters:

Name Type Description Default
duration float

Duration of the data segment in seconds.

 required
sampling_frequency float

Sampling frequency in Hz.

 required
trigger_time float

GPS time of the event trigger. Used to stamp trigger_time and derive gmst for the waveform projection, mirroring the behavior of TransientLikelihoodFD.

 required
waveform_model

The waveform model to be injected.

 required
parameters dict

Dictionary of likelihood-space source parameters.

 required
f_min float

Minimum frequency in Hz. The waveform is zeroed below this frequency.

 required
f_max float

Maximum frequency in Hz. Should be set to the same value used in the likelihood.

 required
start_time Optional[float]

GPS start time of the data buffer in seconds. If None, defaults to trigger_time - duration + 2.0 (2 s of data after the trigger). Defaults to None.

 None

Returns:

Type Description
None

None

load_and_set_psd(psd_file: str = '', asd_file: str = '') -> PowerSpectrum ¤

Load power spectral density (PSD) from file or default GWTC-2 catalog, and set it to the detector.

Supported formats: .npz, .txt, .dat, .csv. Pass asd_file (or is_asd=True via :meth:PowerSpectrum.from_file) when the file contains amplitude spectral density values (Hz⁻¹/²); they are squared internally to produce a PSD.

Parameters:

Name Type Description Default
psd_file str

Path to a PSD file (Hz⁻¹). If empty, uses GWTC-2 ASD.

 ''
asd_file str

Path to an ASD file (Hz⁻¹/²). Values are squared.

 ''

Returns:

Name Type Description
PowerSpectrum PowerSpectrum

The loaded PSD, already set on the detector.

set_data(data: Data | Array, **kws) -> None ¤

Add data to the detector.

Parameters:

Name Type Description Default
data Data | Array

Data to be added to the detector, either as a Data object or as a timeseries array.

 required
**kws dict

Additional keyword arguments to pass to Data constructor.

 {}

Returns:

Type Description
None

None

set_psd(psd: PowerSpectrum | Array, **kws) -> None ¤

Add PSD to the detector.

Parameters:

Name Type Description Default
psd PowerSpectrum | Array

PSD to be added to the detector, either as a PowerSpectrum object or as a timeseries array.

 required
**kws dict

Additional keyword arguments to pass to PowerSpectrum constructor.

 {}

Returns:

Type Description
None

None

td_response(time: Float[Array, ' n_sample'], h_sky: dict[str, Float[Array, ' n_sample']], params: dict) -> Array ¤

Modulate the waveform in the sky frame by the detector response in the time domain.

Parameters:

Name Type Description Default
time Float[Array, ' n_sample']

Array of time samples.

 required
h_sky dict[str, Float[Array, ' n_sample']]

Dictionary mapping polarization names to time-domain waveforms.

 required
params dict

Dictionary of source parameters.

 required

Returns:

Type Description
Array

Array of detector response in time domain.

whitened_frequency_to_time_domain_strain(whitened_frequency_series: Complex[Array, ' n_time // 2 + 1']) -> Float[Array, ' n_time'] ¤

Get the whitened frequency-domain strain. Args: whitened_frequency_series (Complex[Array, "n_time // 2 + 1"]): Array of whitened frequency domain data/signal. Returns: Float[Array, "n_time"]: Whitened time-domain strain/signal.

get_CE() -> GroundBased2G ¤

Return a GroundBased2G instance for Cosmic Explorer (CE).

CE shares the LIGO Hanford site geometry.

get_ET() -> list[GroundBased2G] ¤

Return a list of three GroundBased2G instances for Einstein Telescope (ET).

ET is modelled as a triangle of three interferometers at adjacent vertices, with arms rotated by 120° relative to each other. Vertex positions are propagated using the spherical forward-azimuth (haversine) formula with a latitude-dependent Earth radius derived from the WGS-84 ellipsoid.

get_H1() -> GroundBased2G ¤

Return a GroundBased2G instance for LIGO Hanford (H1).

get_L1() -> GroundBased2G ¤

Return a GroundBased2G instance for LIGO Livingston (L1).

get_V1() -> GroundBased2G ¤

Return a GroundBased2G instance for Virgo (V1).

get_detector_preset() -> dict[str, GroundBased2G | list[GroundBased2G]] ¤

Return a dictionary of pre-configured detector instances.

Returns:

Name Type Description
dict dict[str, GroundBased2G | list[GroundBased2G]]

Mapping of detector name to detector object(s). Keys are "H1", "L1", "V1", "CE" (single GroundBased2G) and "ET" (list of three).