sage.data.waveform.project

Filename : project.py Description : Short description of the file

Created on 2026-01-23 16:17:38

__author__ = Narenraju Nagarajan __copyright__ = Copyright 2026, ProjectName __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = Narenraju Nagarajan __affiliation__ = N/A __email__ = N/A __status__ = [‘inProgress’, ‘Archived’, ‘inUsage’, ‘Debugging’]

GitHub Repository: NULL

Documentation: NULL

Classes

ConstantProjection

GPU-native frequency-domain detector projection for batched GW waveforms.

Module Contents

class ConstantProjection[source]

Bases: torch.nn.Module

GPU-native frequency-domain detector projection for batched GW waveforms.

Projects a batch of plus/cross polarisation waveforms (hp, hc) onto each detector’s antenna pattern and applies the sky-position-dependent time-delay phase shift to produce detector-frame strain h(f).

The module pre-computes and caches:

Detector response tensors (D, 3, 3) built from LAL-derived arm azimuths and altitudes via Euler rotation matrices.
Detector ECEF position vectors (D, 3) for time-delay calculation.
Frequency array (F,) on the target device.

The Greenwich Mean Sidereal Time (GMST) is randomised per batch rather than looked up from GPS time — this is an approximation suitable for training where the source position is already drawn isotropically.

:param None — all configuration is read from get_cfg(): :param and get_data_cfg() at construction time.: :param Inputs to forward(): :param ————————-: :param hp: Plus and cross polarisations in the frequency domain. :type hp: torch.Tensor, shape (B, F), complex :param hc: Plus and cross polarisations in the frequency domain. :type hc: torch.Tensor, shape (B, F), complex :param ra: Right ascension (rad), declination (rad), and polarisation angle (rad). :type ra: torch.Tensor, shape (B,) :param dec: Right ascension (rad), declination (rad), and polarisation angle (rad). :type dec: torch.Tensor, shape (B,) :param polarization: Right ascension (rad), declination (rad), and polarisation angle (rad). :type polarization: torch.Tensor, shape (B,)

Returns:

hf (torch.Tensor, shape (B, D, F), complex) – Detector-frame frequency-domain strain for each detector.
Initialize internal Module state, shared by both nn.Module and ScriptModule.

device[source]

dtype[source]

batch_size[source]

detnames[source]

freqs[source]

response[source]

dx[source]

resp[source]

get_relative_position(detname)[source]

Return the ECEF position vector of detname as a torch.Tensor.

Parameters:: detname (str) – Detector name (e.g. "H1", "L1").
Returns:: Earth-centred, Earth-fixed [x, y, z] coordinates in metres.
Return type:: torch.Tensor, shape (3,)

get_detector_response(longitude, latitude, yangle=0, xangle=None, xaltitude=0, yaltitude=0)[source]

Add a new detector on the earth

Parameters:

longitude (float) – Longitude in radians using geodetic coordinates of the detector
latitude (float) – Latitude in radians using geodetic coordinates of the detector
yangle (float) – Azimuthal angle of the y-arm (angle drawn from pointing north)
xangle (float) – Azimuthal angle of the x-arm (angle drawn from point north). If not set we assume a right angle detector following the right-hand rule.
xaltitude (float) – The altitude angle of the x-arm measured from the local horizon.
yaltitude (float) – The altitude angle of the y-arm measured from the local horizon.

random_gmst_estimate(B=None)[source]

Return a batch of uniformly random GMST values in [0, 2π).

Exact GPS-to-GMST conversion requires expensive table look-ups. Randomising GMST instead effectively marginalises over Earth’s rotation, which is equivalent to drawing uniformly from all possible observation times.

Parameters:: B (int or None) – Batch size to use. When None, falls back to self.batch_size (the value fixed at construction time from cfg.batch_size * cfg.class_balance). Pass an explicit value when calling from a context where the runtime batch size may differ from the training batch size (e.g. validation), because using the fixed self.batch_size would produce a shape mismatch. NOTE: torch.compile with static shapes requires a fixed batch size; if you re-enable compilation, revert to the self.batch_size path and ensure the caller always uses the same B.
Returns:: GMST values in radians.
Return type:: torch.Tensor, shape (B,)

antenna_pattern(right_ascension, declination, polarization, gmst_estimate)[source]

Return the detector response.

Parameters:

right_ascension (float or numpy.ndarray) – The right ascension of the source
declination (float or numpy.ndarray) – The declination of the source
polarization (float or numpy.ndarray) – The polarization angle of the source

Returns:

fplus(default) or fx or fb (float or numpy.ndarray) – The plus or vector-x or breathing polarization factor for this sky location / orientation
fcross(default) or fy or fl (float or numpy.ndarray) – The cross or vector-y or longitudnal polarization factor for this sky location / orientation

time_delay_from_earth_center(right_ascension, declination, gmst_estimate)[source]

Return the time delay from the given location to detector for a signal with the given sky location In other words return t1 - t2 where t1 is the arrival time in this detector and t2 is the arrival time in the other location.

Parameters:

right_ascension (float) – The right ascension (in rad) of the signal.
declination (float) – The declination (in rad) of the signal.

Returns:

The arrival time difference between the detectors.

Return type:

float

forward(hp, hc, ra, dec, polarization, freqs=None, return_delay=False)[source]

Return the strain of a waveform as measured by all detectors. Apply the time shift for all given detectors relative to the assumed geocentric frame and apply the antenna patterns to the plus and cross polarizations.

When return_delay=True also return the per-detector time delay dt of shape (B, D) (seconds, relative to the geocentre) that was applied. This is the quantity that converts a geocentric coalescence time into the per-detector arrival time: tc_det = tc_geocentric + dt.

Parameters:

hp (torch.Tensor, shape (B, F)) – Plus polarization of the GW
hc (torch.Tensor, shape (B, F)) – Cross polarization of the GW
ra (float) – Right ascension of source location
dec (float) – Declination of source location
polarization (float) – Polarization angle of the source
freqs (torch.Tensor, shape (F,) or None) – Frequency array in Hz. When None the module’s stored full uniform grid (self.freqs) is used. Pass the coarse multibanding frequency array here when hp/hc are already in the coarse representation so the time-delay phase is computed at the right frequencies.