Header LALSimulation.h

Detailed Description

Routines to calculate detector strain for general waveforms.

Author

Kipp Cannon, Jolien Creighton, Teviet Creighton

These routines compute the external strain on a detector caused by a general waveform and inject these waveforms into time series.

The following example illustrates the basic usage of these routines.

#include <lal/Date.h>
#include <lal/LALSimulation.h>
...
const LALDetector *detector;
REAL8TimeSeries *data;
REAL8TimeSeries *strain;
REAL8TimeSeries *hplus;
REAL8TimeSeries *hcross;
LIGOTimeGPS geocentric_arrival_time;
double right_ascension, declination, psi;
...
// get detector data
// generate waveform hplus and hcross
// set geocentric_arrival_time for the injection
// set right_ascension, declination, and psi for the injection
...
XLALGPSAddGPS(&hplus->epoch, &geocentric_arrival_time);
XLALGPSAddGPS(&hcross->epoch, &geocentric_arrival_time);
detector = XLALDetectorPrefixToLALDetector(data->name);
strain = XLALSimDetectorStrainREAL8TimeSeries(hplus, hcross, right_ascension, declination, psi, detector);
XLALSimAddInjectionREAL8TimeSeries(data, strain, NULL);

Coordinate Systems

The diagram below illustrates the relationship between the wave frame (X,Y,Z) and the Earth's equatorial frame. The Earth is at the origin of the diagram with its North pole in the direction indicated by N.

Injection Coordinates

The gravitational wave travels in the Z-direction in this diagram, and the reference direction on the wave-plane (the X-Y-plane) is given by the X-axis. Note that the direction to the source is in the negative Z direction.

The plus- and cross-polarizations of the gravitational waveform are defined in this wave frame. Specifically, if \( h^{ij} \) is the metric perturbation, then

\[ h_+ = \frac12 ( \hat{p}_i \hat{p}_j - \hat{q}_i \hat{q}_j ) h^{ij} \]

and

\[ h_\times = \frac12 ( \hat{p}_i \hat{q}_j + \hat{q}_i \hat{p}_j ) h^{ij} \]

where \( \hat{p}_i \) are the components of the unit vector pointing along the X-axis and \( \hat{q}_i \) are the components of the unit vector pointing along the Y-axis.

The angles relating the wave frame to the equatorial frame are:

• Declination (δ). The angle along the hour circle passing through the source between the equatorial plane and the source. It is positive for a source that is north of the equatorial plane and negative for a source that is south of the equatorial plane. The hour circle passing through the source is the great arc on the celestial sphere that passes through the north celestial pole (marked as N in the diagram), the source, and the south celestial pole.

  Note that the diagram depicts a source having a negative declination.

• Right ascension (α). The angle from the vernal equinox ♈ to the hour circle passing through the source. The angle is measured counter-clockwise about the axis pointing toward the north celestial pole.
• Greenwich sidereal time (GST). The right ascension of the prime meridian at the time of arrival of the signal.

• Greenwich hour angle (GHA). The angle along the equatorial plane between the prime meridian and the hour circle containing the source. This angle is measured clockwise about the axis pointing toward the north celestial pole.

  The right ascension, Greenwich hour angle, and Greenwich sidereal time are related by GHA = GST - α.

• Polarization angle (ψ). The angle from the ascending line of nodes to the X-axis of the wave plane. The angle is measured counter clockwise about the Z-axis of the wave plane.

See also

A complete description of the coordinate conventions adopted here can be found in

‍Warren Anderson, Patrick Brady, David Chin, Jolien Creighton, Keith Riles, and John Whelan, "Beam Pattern Response Functions and Times of Arrival for Earthbound Interferometer", LIGO Technical Document LIGO-T010110-v1 (2009) https://dcc.ligo.org/LIGO-T010110/public

The conventions are also described in Appendix B of

‍Warren G. Anderson, Patrick R. Brady, Jolien D. E. Creighton, and Eanna E. Flanagan, "Excess power statistic for detection of burst sources of gravitational radiation", Phys. Rev. D 63, 042003 (2001) http://dx.doi.org/10.1103/PhysRevD.63.042003 http://arxiv.org/abs/gr-qc/0008066

Prototypes
const LALDetector *	XLALDetectorPrefixToLALDetector (const char *string)
	Turn a detector prefix string into a LALDetector structure. More...
REAL8TimeSeries *	XLALSimDetectorStrainREAL8TimeSeries (const REAL8TimeSeries *hplus, const REAL8TimeSeries *hcross, REAL8 right_ascension, REAL8 declination, REAL8 psi, const LALDetector *detector)
	Transforms the waveform polarizations into a detector strain. More...
int	XLALSimAddInjectionREAL8TimeSeries (REAL8TimeSeries *target, REAL8TimeSeries *h, const COMPLEX16FrequencySeries *response)
	Adds a detector strain time series to detector data. More...
int	XLALSimAddInjectionREAL4TimeSeries (REAL4TimeSeries *target, REAL4TimeSeries *h, const COMPLEX8FrequencySeries *response)
	Adds a detector strain time series to detector data. More...
int	XLALSimInjectDetectorStrainREAL8TimeSeries (REAL8TimeSeries *target, const REAL8TimeSeries *hplus, const REAL8TimeSeries *hcross, double ra, double dec, double psi, LALDetector *detector, const COMPLEX16FrequencySeries *response)
	Computes strain for a detector and injects into target time series. More...
int	XLALSimInjectDetectorStrainREAL4TimeSeries (REAL4TimeSeries *target, const REAL4TimeSeries *hplus, const REAL4TimeSeries *hcross, double ra, double dec, double psi, LALDetector *detector, const COMPLEX8FrequencySeries *response)
	Computes strain for a detector and injects into target time series. More...
int	XLALSimInjectLWLDetectorStrainREAL8TimeSeries (REAL8TimeSeries *target, const REAL8TimeSeries *hplus, const REAL8TimeSeries *hcross, double ra, double dec, double psi, LALDetector *detector, const COMPLEX16FrequencySeries *response)
	Computes strain for a detector and injects into target time series. More...
int	XLALSimInjectLWLDetectorStrainREAL4TimeSeries (REAL4TimeSeries *target, const REAL4TimeSeries *hplus, const REAL4TimeSeries *hcross, double ra, double dec, double psi, LALDetector *detector, const COMPLEX8FrequencySeries *response)
	Computes strain for a detector and injects into target time series. More...

Function Documentation

XLALDetectorPrefixToLALDetector()

const LALDetector * XLALDetectorPrefixToLALDetector

(

const char *

string

)

Turn a detector prefix string into a LALDetector structure.

The first two characters of the input string are used as the instrument name, which allows channel names in the form H1:LSC-STRAIN to be used. The return value is a pointer into the lalCachedDetectors array, so modifications to the contents are global. Make a copy of the structure if you want to modify it safely.

Parameters

[in]

string

The detector prefix string.

Returns

A cached LALDetector structure corresponding to the supplied prefix.

Return values

NULL	Unrecognized prefix string.

Definition at line 85 of file LALSimulation.c.

XLALSimDetectorStrainREAL8TimeSeries()

REAL8TimeSeries * XLALSimDetectorStrainREAL8TimeSeries	(	const REAL8TimeSeries *	hplus,
		const REAL8TimeSeries *	hcross,
		REAL8	right_ascension,
		REAL8	declination,
		REAL8	psi,
		const LALDetector *	detector
	)

Transforms the waveform polarizations into a detector strain.

This routine takes the plus and cross waveform polarizations, along with the sky position, polarization angle, and detector structure, and computes the external strain on the detector.

The input time series should have their epochs set to the start of those time series at the geocetre (for simplicity the epochs must be the same, and they must have the same length and sample rates)

Parameters

[in]	hplus	Pointer to a REAL8TimeSeries containing the plus polarization waveform
[in]	hcross	Pointer to a REAL8TimeSeries containing the cross polarization waveform
[in]	right_ascension	The right ascension of the source in radians
[in]	declination	The declination of the source in radians
[in]	psi	The polarization angle giving the orientation of the wave co-ordinate system in radians
[in]	detector	Pointer to a LALDetector structure for the detector into which the injection is destined to be injected

Returns

The strain time series as seen in the detector, with the epoch set to the start of the time series at that detector. The output time series units are the same as the two input time series (which must both have the same sample units).

Return values

NULL

Failure

Note

A 19-sample Welch-windowed sinc kernel is used for sub-sample interpolation. See XLALREAL8TimeSeriesInterpEval() for more information, and consider the frequency response of this kernel when using this function with injections whose frequency content approaches the Nyquist frequency.

The geometric delay and antenna response are only recalculated every 250 ms — the Earth's rotation is modelled as discontinuous jumps occurring at a rate of 4 Hz. The Earth rotates at 7e-5 rad/s, therefore given a radius of 6e6 m and c=3e8 m/s, the maximum geometric speed for points on the surface is about 1.5 us/s. Updating the detector response and geometric delay every 250 ms means the antenna response is accurate to about +/- 20 urad and the geometric delay to about +/- 300 ns (about 0.01 sample at 32 kHz). Because we use UTC (instead of UT1) sidereal time is only accurate to +/- 900 ms, so assuming the Earth's orientation to be fixed for 250 ms at a time is not the dominant source of Earth orientation error in these calculations, but one should be aware of the periodic nature of the updates if extreme phase stability is required.

The output time series is padded to capture the interpolation kernel structure resulting from possible sharp edges at the start or end of the input time series data. Neglecting the padding for the interpolation kernel's impulse response, the output time series is, in general, not the same duration as the input time series due to Doppler compression or resulting from Earth rotation.

Definition at line 254 of file LALSimulation.c.

XLALSimAddInjectionREAL8TimeSeries()

int XLALSimAddInjectionREAL8TimeSeries	(	REAL8TimeSeries *	target,
		REAL8TimeSeries *	h,
		const COMPLEX16FrequencySeries *	response
	)

Adds a detector strain time series to detector data.

Essentially a wrapper for XLALAddREAL8TimeSeries(), but performs sub-sample re-interpolation to adjust the source time series epoch to lie on an integer sample boundary in the target time series. This transformation is done in the frequency domain, so it is convenient to allow a response function to be applied at the same time. Passing NULL for the response function turns this feature off (i.e., uses a unit response).

This function accepts source and target time series whose units are not the same, and allows the two time series to be herterodyned (although it currently requires them to have the same heterodyne frequency).

Parameters

[in,out]	target	Pointer to the time series into which the strain will be added
[in,out]	h	Pointer to the time series containing the detector strain (the strain data is modified by this routine)
[in]	response	Pointer to the response function transforming strain to detector output units, or NULL for unit response.

Return values

0	Success
<0	Failure

Attention

The source time series is modified in place by this function!

Definition at line 479 of file LALSimulation.c.

XLALSimAddInjectionREAL4TimeSeries()

int XLALSimAddInjectionREAL4TimeSeries	(	REAL4TimeSeries *	target,
		REAL4TimeSeries *	h,
		const COMPLEX8FrequencySeries *	response
	)

Adds a detector strain time series to detector data.

Essentially a wrapper for XLALAddREAL4TimeSeries(), but performs sub-sample re-interpolation to adjust the source time series epoch to lie on an integer sample boundary in the target time series. This transformation is done in the frequency domain, so it is convenient to allow a response function to be applied at the same time. Passing NULL for the response function turns this feature off (i.e., uses a unit response).

This function accepts source and target time series whose units are not the same, and allows the two time series to be herterodyned (although it currently requires them to have the same heterodyne frequency).

Parameters

[in,out]	target	Pointer to the time series into which the strain will be added
[in,out]	h	Pointer to the time series containing the detector strain (the strain data is modified by this routine)
[in]	response	Pointer to the response function transforming strain to detector output units, or NULL for unit response.

Return values

0	Success
<0	Failure

Attention

The source time series is modified in place by this function!

Definition at line 729 of file LALSimulation.c.

XLALSimInjectDetectorStrainREAL8TimeSeries()

int XLALSimInjectDetectorStrainREAL8TimeSeries	(	REAL8TimeSeries *	target,
		const REAL8TimeSeries *	hplus,
		const REAL8TimeSeries *	hcross,
		double	ra,
		double	dec,
		double	psi,
		LALDetector *	detector,
		const COMPLEX16FrequencySeries *	response
	)

Computes strain for a detector and injects into target time series.

This routine takes care of the time-changing time delay from the Earth's center and the time-changing antenna response pattern; it also accounts for deviations from the long-wavelength limit at high frequencies. An optional calibration response function can be provided if the output time series is not in strain units.

Parameters

[in,out]	target	Time series to inject strain into.
[in]	hplus	Time series with plus-polarization gravitational waveform.
[in]	hcross	Time series with cross-polarization gravitational waveform.
[in]	ra	Right ascension of the source (radians).
[in]	dec	Declination of the source (radians).
[in]	psi	Polarization angle of the source (radians).
[in]	detector	Detector to use when computing strain.
[in]	response	Response function to use, or NULL if none.

Return values

0	Success.
<0	Failure.

Definition at line 1250 of file LALSimulation.c.

XLALSimInjectDetectorStrainREAL4TimeSeries()

int XLALSimInjectDetectorStrainREAL4TimeSeries	(	REAL4TimeSeries *	target,
		const REAL4TimeSeries *	hplus,
		const REAL4TimeSeries *	hcross,
		double	ra,
		double	dec,
		double	psi,
		LALDetector *	detector,
		const COMPLEX8FrequencySeries *	response
	)

Computes strain for a detector and injects into target time series.

This routine takes care of the time-changing time delay from the Earth's center and the time-changing antenna response pattern; it also accounts for deviations from the long-wavelength limit at high frequencies. An optional calibration response function can be provided if the output time series is not in strain units.

Parameters

[in,out]	target	Time series to inject strain into.
[in]	hplus	Time series with plus-polarization gravitational waveform.
[in]	hcross	Time series with cross-polarization gravitational waveform.
[in]	ra	Right ascension of the source (radians).
[in]	dec	Declination of the source (radians).
[in]	psi	Polarization angle of the source (radians).
[in]	detector	Detector to use when computing strain.
[in]	response	Response function to use, or NULL if none.

Return values

0	Success.
<0	Failure.

Definition at line 1473 of file LALSimulation.c.

XLALSimInjectLWLDetectorStrainREAL8TimeSeries()

int XLALSimInjectLWLDetectorStrainREAL8TimeSeries	(	REAL8TimeSeries *	target,
		const REAL8TimeSeries *	hplus,
		const REAL8TimeSeries *	hcross,
		double	ra,
		double	dec,
		double	psi,
		LALDetector *	detector,
		const COMPLEX16FrequencySeries *	response
	)

Computes strain for a detector and injects into target time series.

This routine takes care of the time-changing time delay from the Earth's center and the time-changing antenna response pattern; it does NOT account for deviations from the long-wavelength limit at high frequencies. An optional calibration response function can be provided if the output time series is not in strain units.

Parameters

[in,out]	target	Time series to inject strain into.
[in]	hplus	Time series with plus-polarization gravitational waveform.
[in]	hcross	Time series with cross-polarization gravitational waveform.
[in]	ra	Right ascension of the source (radians).
[in]	dec	Declination of the source (radians).
[in]	psi	Polarization angle of the source (radians).
[in]	detector	Detector to use when computing strain.
[in]	response	Response function to use, or NULL if none.

Return values

0	Success.
<0	Failure.

Warning

This routine assumes the long-wavelength limit (LWL) is valid when computing the detector strain; at high frequencies near the free spectral range of an interferometric detector this approximation becomes invalid.

Definition at line 1955 of file LALSimulation.c.

XLALSimInjectLWLDetectorStrainREAL4TimeSeries()

int XLALSimInjectLWLDetectorStrainREAL4TimeSeries	(	REAL4TimeSeries *	target,
		const REAL4TimeSeries *	hplus,
		const REAL4TimeSeries *	hcross,
		double	ra,
		double	dec,
		double	psi,
		LALDetector *	detector,
		const COMPLEX8FrequencySeries *	response
	)

Computes strain for a detector and injects into target time series.

This routine takes care of the time-changing time delay from the Earth's center and the time-changing antenna response pattern; it does NOT account for deviations from the long-wavelength limit at high frequencies. An optional calibration response function can be provided if the output time series is not in strain units.

Parameters

[in,out]	target	Time series to inject strain into.
[in]	hplus	Time series with plus-polarization gravitational waveform.
[in]	hcross	Time series with cross-polarization gravitational waveform.
[in]	ra	Right ascension of the source (radians).
[in]	dec	Declination of the source (radians).
[in]	psi	Polarization angle of the source (radians).
[in]	detector	Detector to use when computing strain.
[in]	response	Response function to use, or NULL if none.

Return values

0	Success.
<0	Failure.

Warning

This routine assumes the long-wavelength limit (LWL) is valid when computing the detector strain; at high frequencies near the free spectral range of an interferometric detector this approximation becomes invalid.

Definition at line 2180 of file LALSimulation.c.