Prototypes
REAL8Vector *	XLALHeterodynedPulsarPhaseDifference (PulsarParameters params, PulsarParameters origparams, const LIGOTimeGPSVector datatimes, REAL8 freqfactor, REAL8Vector ssbdts, UINT4 calcSSBDelay, REAL8Vector bsbdts, UINT4 calcBSBDelay, REAL8Vector glphase, UINT4 calcglphase, REAL8Vector fitwavesphase, UINT4 calcfitwaves, const LALDetector detector, const EphemerisData ephem, const TimeCorrectionData tdat, TimeCorrectionType ttype)
	The phase evolution difference compared to a heterodyned phase (for a pulsar) More...

REAL8Vector *	XLALHeterodynedPulsarGetSSBDelay (PulsarParameters pars, const LIGOTimeGPSVector datatimes, const LALDetector detector, const EphemerisData ephem, const TimeCorrectionData *tdat, TimeCorrectionType ttype)
	Computes the delay between a GPS time at Earth and the solar system barycentre. More...

REAL8Vector *	XLALHeterodynedPulsarGetBSBDelay (PulsarParameters pars, const LIGOTimeGPSVector datatimes, const REAL8Vector dts, const EphemerisData edat)
	Computes the delay between a pulsar in a binary system and the barycentre of the system. More...

void	XLALGetEarthPosVel (EarthState earth, const EphemerisData edat, const LIGOTimeGPS *tGPS)
	Get the position and velocity of the Earth at a given time. More...

REAL8Vector *	XLALHeterodynedPulsarGetGlitchPhase (PulsarParameters params, const LIGOTimeGPSVector datatimes, const REAL8Vector ssbdts, const REAL8Vector bsbdts)
	Computes the phase evolution due to the presence of glitches. More...

REAL8Vector *	XLALHeterodynedPulsarGetFITWAVESPhase (PulsarParameters params, const LIGOTimeGPSVector datatimes, const REAL8Vector *ssbdts, REAL8 freq)
	Computes the phase evolution due to the presence of FITWAVES parameters. More...

COMPLEX16TimeSeries *	XLALHeterodynedPulsarGetAmplitudeModel (PulsarParameters pars, REAL8 freqfactor, UINT4 varyphase, UINT4 useroq, UINT4 nonGR, const LIGOTimeGPSVector timestamps, const DetResponseTimeLookupTable *resp)
	The amplitude model of a complex heterodyned signal from the \( l=2, m=1,2 \) harmonics of a rotating neutron star. More...

COMPLEX16TimeSeries *	XLALHeterodynedPulsarGetModel (PulsarParameters pars, PulsarParameters origpars, REAL8 freqfactor, UINT4 usephase, UINT4 useroq, UINT4 nonGR, const LIGOTimeGPSVector timestamps, REAL8Vector hetssbdelays, UINT4 calcSSBDelay, REAL8Vector hetbsbdelays, UINT4 calcBSBDelay, REAL8Vector glphase, UINT4 calcglphase, REAL8Vector fitwavesphase, UINT4 calcfitwaves, const DetResponseTimeLookupTable resp, const EphemerisData ephem, const TimeCorrectionData tdat, TimeCorrectionType ttype)
	Generate the model of the neutron star signal. More...

DetResponseTimeLookupTable *	XLALDetResponseLookupTable (REAL8 t0, const LALDetector *det, REAL8 alpha, REAL8 delta, UINT4 timeSteps, REAL8 avedt)
	Creates a lookup table of the detector antenna pattern. More...

void	XLALDestroyDetResponseTimeLookupTable (DetResponseTimeLookupTable *resp)
	Free memory for antenna response look-up table structure. More...

void	XLALPulsarSourceToWaveformParams (PulsarParameters *params)
	Convert source parameters into amplitude and phase notation parameters. More...

Macros
#define	ROUND(x) (floor(x+0.5))
	Macro to round a value to the nearest integer. More...

#define	SQUARE(x) ( (x) * (x) )
	Macro to square a value. More...

Macro Definition Documentation

◆ ROUND

#define ROUND ( x ) (floor(x+0.5))

Macro to round a value to the nearest integer.

Definition at line 23 of file HeterodynedPulsarModel.c.

◆ SQUARE

#define SQUARE ( x ) ( (x) * (x) )

Macro to square a value.

Definition at line 26 of file HeterodynedPulsarModel.c.

Function Documentation

◆ XLALHeterodynedPulsarPhaseDifference()

REAL8Vector* XLALHeterodynedPulsarPhaseDifference	(	PulsarParameters *	params,
		PulsarParameters *	origparams,
		const LIGOTimeGPSVector *	datatimes,
		REAL8	freqfactor,
		REAL8Vector *	ssbdts,
		UINT4	calcSSBDelay,
		REAL8Vector *	bsbdts,
		UINT4	calcBSBDelay,
		REAL8Vector *	glphase,
		UINT4	calcglphase,
		REAL8Vector *	fitwavesphase,
		UINT4	calcfitwaves,
		const LALDetector *	detector,
		const EphemerisData *	ephem,
		const TimeCorrectionData *	tdat,
		TimeCorrectionType	ttype
	)

The phase evolution difference compared to a heterodyned phase (for a pulsar)

This function will calculate the difference in the phase evolution of a source at a particular sky location as observed in a detector on Earth compared with that used to heterodyne (or SpectralInterpolate) the data. If the phase evolution is described by a Taylor expansion:

\[ \phi(T) = \sum_{k=1}^n \frac{f^{(k-1)}}{k!} T^k, \]

where \( f^{(x)} \) is the xth time derivative of the gravitational-wave frequency, and \( T \) is the pulsar proper time, then the phase difference is given by

\[ \Delta\phi(t) = \sum_{k=1}^n \left( \frac{\Delta f^{(k-1)}}{k!}(t+\delta t_1)^k + \frac{f^{(k-1)}_2}{k!} \sum_{i=0}^{i<k} \left(\begin{array}{c}k \\ i\end{array}\right) (\Delta t)^{k-i} (t+\delta t_1)^i \right), \]

where \( t \) is the signal arrival time at the detector minus the given pulsar period epoch, \( \delta t_1 \) is the barycentring time delay (from both solar system and binary orbital effects) calculated at the heterodyned values, \( \Delta f^{(x)} = f_2^{(x)}-f1^{(x)} \) is the diffence in frequency (derivative) between the current value ( \( f_2^{(x)} \) ) and the heterodyne value ( \( f_1^{(x)} \) ), and \( \Delta t = \delta t_2 - \delta t_1 \) is the difference between the barycentring time delay calculated at the current values ( \( \delta t_1 \) ) and the heterodyned values. Frequency time derivatives up to any order are allowed. The pulsar proper time is calculated by correcting the time of arrival at Earth, \( t \) to the solar system barycentre and if necessary the binary system barycenter, so \( T = t + \delta{}t_{\rm SSB} + \delta{}t_{\rm BSB} \) .

In this function the time delay needed to correct to the solar system barycenter is only calculated if required, i.e., if an update is required due to a change in the sky position. The same is true for the binary system time delay, which is only calculated if it needs updating due to a change in the binary system parameters. The function will also calculate any phase evolution due to pulsar glitch parameters and/or FITWAVES parameters (parameters that define sinusoidal terms used to represent strong red noise in the signal) if required.

This function can just return the phase evolution (and not phase evolution difference) if ssbdts, bsbdts, and origparams are NULL, which will be based on the parameters set in the params structure.

Parameters

params	[in] A set of pulsar parameters
origparams	[in] The original parameters used to heterodyne the data
datatimes	[in] A vector of GPS times at which to calculate the phase difference
freqfactor	[in] The multiplicative factor on the pulsar frequency for a particular model
ssbdts	[in] The vector of SSB time delays used for the original heterodyne. If this is `NULL` then the SSB delay for the given position will be calculated.
calcSSBDelay	[in] Set to a non-zero value if the SSB delay needs to be calculated. This would be required if using an updated sky position compared to that used for the heterodyne, or if calculating the full phase evolution rather than a phase difference.
bsbdts	[in] The vector of BSB time delays used for the original heterodyne. If this is `NULL` then the BSB delay for the given binary parameters will be calculated.
calcBSBDelay	[in] Set to a non-zero value if the BSB delay needs to be calculated. This would be required if using updated binary parameters compared to that used for the heterodyne, or if calculating the full phase evolution rather than a phase difference.
glphase	[in] The vector of the glitch phase evolution (in EM cycles) used in the original heterodyne. If this is `NULL` then the glitch phase for the given glitch parameters will be calculated.
calcglphase	[in] Set to a non-zero value if the glitch phase needs to be calculated. This would be required if using a set of updated glitch parameters compared to that used for the heterodyne, or if calculating the full phase evolution rather than a phase difference.
fitwavesphase	[in] The vector of the phase evolution (in EM cycles) for any FITWAVES (sinusoids used to fit red noise) parameters used in the original heterodyne. If this is `NULL` then the FITWAVES phase for the given parameters will be calculated.
calcfitwaves	[in] Set to a non-zero value if the FITWAVES phase needs to be calculated. This would be required if using an updated set of FITWAVES parameters, or if calculating the full phase evolution rather than a phase difference.
detector	[in] A pointer to a `LALDetector` structure for a particular detector
ephem	[in] A pointer to an `EphemerisData` structure containing solar system ephemeris information
tdat	[in] A pointer to a `TimeCorrectionData` structure containing time system correction information
ttype	[in] The `TimeCorrectionType` value

Returns: A vector of rotational phase difference values (in cycles NOT radians)

See also: XLALHeterodynedPulsarGetSSBDelay; XLALHeterodynedPulsarGetBSBDelay

Definition at line 107 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetSSBDelay()

REAL8Vector* XLALHeterodynedPulsarGetSSBDelay	(	PulsarParameters *	pars,
		const LIGOTimeGPSVector *	datatimes,
		const LALDetector *	detector,
		const EphemerisData *	ephem,
		const TimeCorrectionData *	tdat,
		TimeCorrectionType	ttype
	)

Computes the delay between a GPS time at Earth and the solar system barycentre.

This function calculates the time delay between a GPS time at a specific location (e.g., a gravitational-wave detector) on Earth and the solar system barycentre. The delay consists of three components: the geometric time delay (Roemer delay) \( t_R = \mathbf{r}(t)\hat{n}/c \) (where \( \mathbf{r}(t) \) is the detector's position vector at time \( t \) ), the special relativistic Einstein delay \( t_E \) , and the general relativistic Shapiro delay \( t_S \) .

Parameters

pars	[in] A set of pulsar parameters
datatimes	[in] A vector of GPS times at Earth
detector	[in] Information on the detector position on the Earth
ephem	[in] Information on the solar system ephemeris
tdat	[in] Informaion on the time system corrections
ttype	[in] The type of time system corrections to perform

Returns: A vector of time delays in seconds

See also: XLALBarycenter; XLALBarycenterEarthNew

Definition at line 362 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetBSBDelay()

REAL8Vector* XLALHeterodynedPulsarGetBSBDelay	(	PulsarParameters *	pars,
		const LIGOTimeGPSVector *	datatimes,
		const REAL8Vector *	dts,
		const EphemerisData *	edat
	)

Computes the delay between a pulsar in a binary system and the barycentre of the system.

This function uses XLALBinaryPulsarDeltaTNew to calculate the time delay between for a pulsar in a binary system between the time at the pulsar and the time at the barycentre of the system. This includes Roemer delays and relativistic delays. The orbit may be described by different models and can be purely Keplarian or include various relativistic corrections.

Parameters

pars	[in] A set of pulsar parameters
datatimes	[in] A vector of GPS times
dts	[in] A vector of solar system barycentre time delays
edat	[in] Solar system ephemeris information

Returns: A vector of time delays in seconds

See also: XLALBinaryPulsarDeltaTNew

Definition at line 489 of file HeterodynedPulsarModel.c.

◆ XLALGetEarthPosVel()

void XLALGetEarthPosVel	(	EarthState *	earth,
		const EphemerisData *	edat,
		const LIGOTimeGPS *	tGPS
	)

Get the position and velocity of the Earth at a given time.

This function will get the position and velocity of the Earth from the ephemeris data at the time t. It will be returned in an EarthState structure. This is based on the start of the XLALBarycenterEarth function.

Parameters

earth	[out] The returned `EarthState` structure containing the Earth's position and velocity
edat	[in] The solar system ephemeris data
tGPS	[in] A `LIGOTimeGPS` structure containing a GPS time

See also: XLALBarycenterEarth

Definition at line 550 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetGlitchPhase()

REAL8Vector* XLALHeterodynedPulsarGetGlitchPhase	(	PulsarParameters *	params,
		const LIGOTimeGPSVector *	datatimes,
		const REAL8Vector *	ssbdts,
		const REAL8Vector *	bsbdts
	)

Computes the phase evolution due to the presence of glitches.

This function calculates the phase offset due to the presence on pulsar glitches. This is based on the equations in the formResiduals.C file of TEMPO2 from Eqn. 1 of [37] .

Parameters

params	[in] A set of pulsar parameters
datatimes	[in] A vector of GPS times at Earth
ssbdts	[in] A vector of solar system barycentre time delays
bsbdts	[in] A vector of binary system barycentre time delays

Returns: A vector of (EM) phases in cycles

Definition at line 612 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetFITWAVESPhase()

REAL8Vector* XLALHeterodynedPulsarGetFITWAVESPhase	(	PulsarParameters *	params,
		const LIGOTimeGPSVector *	datatimes,
		const REAL8Vector *	ssbdts,
		REAL8	freq
	)

Computes the phase evolution due to the presence of FITWAVES parameters.

This function calculates the phase due to the presence on FITWAVES parameters in the pulsar timing model. These are used to fit multiple sinusoids to account for strong red noise effects (e.g., timing noise) in the pulsar model.

Parameters

params	[in] A set of pulsar parameters
datatimes	[in] A vector of GPS times at Earth
ssbdts	[in] A vector of solar system barycentre time delays
freq	[in] The EM frequency.

Returns: A vector of (EM) phases in cycles

Definition at line 729 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetAmplitudeModel()

COMPLEX16TimeSeries* XLALHeterodynedPulsarGetAmplitudeModel	(	PulsarParameters *	pars,
		REAL8	freqfactor,
		UINT4	varyphase,
		UINT4	useroq,
		UINT4	nonGR,
		const LIGOTimeGPSVector *	timestamps,
		const DetResponseTimeLookupTable *	resp
	)

The amplitude model of a complex heterodyned signal from the \( l=2, m=1,2 \) harmonics of a rotating neutron star.

This function calculates the complex heterodyned time series model for a rotating neutron star. It will currently calculate the model for emission from the \( l=m=2 \) harmonic (which gives emission at twice the rotation frequency) and/or the \( l=2 \) and \( m=1 \) harmonic (which gives emission at the rotation frequency). See LIGO T1200265-v3. Further harmonics can be added and are defined by the freqFactor value, which is the multiple of the spin-frequency at which emission is produced.

The antenna pattern functions are contained in a 1D lookup table, so within this function the correct value for the given time is interpolated from this lookup table using linear interpolation.

Parameters

pars	[in] A set of pulsar parameters
freqfactor	[in] The harmonic frequency of the signal in units of the pulsar rotation frequency
varyphase	[in] Set to a non-zero value is the signal phase is different to the heterodyne phase (or if wanting the signal output at all time stamps).
useroq	[in] Set to a non-zero value if a reduced order quadrature likelihood is being used
nonGR	[in] Set to a non-zero value to indicate a non-GR polarisation is used
timestamps	[in] A vector of GPS times at which to calculate the signal
resp	[in] A detector response function look-up table

Returns: A COMPLEX16TimeSeries the amplitude time series

Definition at line 811 of file HeterodynedPulsarModel.c.

◆ XLALHeterodynedPulsarGetModel()

COMPLEX16TimeSeries* XLALHeterodynedPulsarGetModel	(	PulsarParameters *	pars,
		PulsarParameters *	origpars,
		REAL8	freqfactor,
		UINT4	usephase,
		UINT4	useroq,
		UINT4	nonGR,
		const LIGOTimeGPSVector *	timestamps,
		REAL8Vector *	hetssbdelays,
		UINT4	calcSSBDelay,
		REAL8Vector *	hetbsbdelays,
		UINT4	calcBSBDelay,
		REAL8Vector *	glphase,
		UINT4	calcglphase,
		REAL8Vector *	fitwavesphase,
		UINT4	calcfitwaves,
		const DetResponseTimeLookupTable *	resp,
		const EphemerisData *	ephem,
		const TimeCorrectionData *	tdat,
		TimeCorrectionType	ttype
	)

Generate the model of the neutron star signal.

Firstly the time varying amplitude of the signal will be calculated based on the antenna pattern and amplitude parameters. Then, if searching over phase parameters, the phase evolution of the signal will be calculated. The difference between the new phase model, \( \phi(t)_n \) , and that used to heterodyne the data, \( \phi(t)_h \) , will be calculated and the complex signal model, \( M \) , modified accordingly:

\[ M'(t) = M(t)\exp{i((\phi(t)_n - \phi(t)_h))}. \]

This does not try to undo the signal modulation in the data, but instead replicates the modulation in the model, hence the positive phase difference rather than a negative phase in the exponential function.

The model is described in Equations 7 and 8 of [19] .

Parameters

pars	[in] A `PulsarParameters` structure containing the model parameters
origpars	[in] A `PulsarParameters` structure containing the original heterodyne parameters
freqfactor	[in] The harmonic frequency of the signal in units of the pulsar rotation frequency
usephase	[in] Set to a non-zero value is the signal phase is different to the heterodyne phase (or if wanting the signal output at all time stamps).
useroq	[in] Set to a non-zero value if a reduced order quadrature likelihood is being used
nonGR	[in] Set to a non-zero value to indicate a non-GR polarisation is used
timestamps	[in] A vector of GPS times at which to calculate the signal
hetssbdelays	[in] The vector of SSB time delays used for the original heterodyne. If this is `NULL` then the SSB delay for the given position will be calculated.
calcSSBDelay	[in] Set to a non-zero value if the SSB delay needs to be recalculated at an updated sky position compared to that used for the heterodyne.
hetbsbdelays	[in] The vector of BSB time delays used for the original heterodyne. If this is `NULL` then the BSB delay for the given binary parameters will be calculated.
calcBSBDelay	[in] Set to a non-zero value if the BSB delay needs to be calulated at a set of updated binary system parameters.
glphase	[in] The vector containing the glitch phase evolution used for the original heterodyne. If this is `NULL` then the glitch phase for the given glitch parameters will be calculated.
calcglphase	[in] Set to a non-zero value if the glitch phase needs to be calulated at a set of updated glitch parameters.
fitwavesphase	[in] The vector of FITWAVES phases used for the original heterodyne. If this is `NULL` then the FITWAVES phase for the given FITWAVES parameters will be calculated.
calcfitwaves	[in] Set to a non-zero value if the FITWAVES phase needs to be calulated at a set of updated FITWAVES parameters.
resp	[in] A loop-up table for the detector response function.
ephem	[in] A pointer to an `EphemerisData` structure containing solar system ephemeris information
tdat	[in] A pointer to a `TimeCorrectionData` structure containing time system correction information
ttype	[in] The `TimeCorrectionType` value

See also: XLALHeterodynedPulsarGetAmplitudeModel; XLALHeterodynedPulsarGetPhaseModel

Definition at line 1100 of file HeterodynedPulsarModel.c.

◆ XLALDetResponseLookupTable()

DetResponseTimeLookupTable* XLALDetResponseLookupTable	(	REAL8	t0,
		const LALDetector *	det,
		REAL8	alpha,
		REAL8	delta,
		UINT4	timeSteps,
		REAL8	avedt
	)

Creates a lookup table of the detector antenna pattern.

This function creates a lookup table of the tensor, vector and scalar antenna patterns for a given detector orientation and source sky position. For the tensor modes these are the functions given by equations 10-13 in [9] , whilst for the vector and scalar modes they are the \( \psi \) independent parts of e.g. equations 5-8 of [17] . We remove the \( \psi \) dependance by setting \( \psi=0 \) .

If avedt is a value over 60 seconds then the antenna pattern will actually be the mean value from 60 second intervals within that timespan. This accounts for the fact that each data point is actually an averaged value over the given timespan.

Parameters

t0	[in] initial GPS time of the data
det	[in] structure containing the detector
alpha	[in] the source right ascension in radians
delta	[in] the source declination in radians
timeSteps	[in] the number of grid bins to use in time
avedt	[in] average the antenna pattern over this timespan

Definition at line 1195 of file HeterodynedPulsarModel.c.

◆ XLALDestroyDetResponseTimeLookupTable()

void XLALDestroyDetResponseTimeLookupTable ( DetResponseTimeLookupTable * resp )

Free memory for antenna response look-up table structure.

Parameters

resp	[in] the look-up table structure to be freed

Definition at line 1284 of file HeterodynedPulsarModel.c.

◆ XLALPulsarSourceToWaveformParams()

void XLALPulsarSourceToWaveformParams ( PulsarParameters * params )

Convert source parameters into amplitude and phase notation parameters.

Convert the physical source parameters into the amplitude and phase notation given in Eqns 62-65 of [12] .

Note that phi0 is essentially the rotational phase of the pulsar. Also, note that if using \( h_0 \) , and therefore the convention for a signal as defined in [9] , the sign of the waveform model is the opposite of that in [12] , and therefore a sign flip is required in the amplitudes.

Definition at line 1325 of file HeterodynedPulsarModel.c.

Prototypes

Macros

Macro Definition Documentation

◆ ROUND

◆ SQUARE

Function Documentation

◆ XLALHeterodynedPulsarPhaseDifference()

◆ XLALHeterodynedPulsarGetSSBDelay()

◆ XLALHeterodynedPulsarGetBSBDelay()

◆ XLALGetEarthPosVel()

◆ XLALHeterodynedPulsarGetGlitchPhase()

◆ XLALHeterodynedPulsarGetFITWAVESPhase()

◆ XLALHeterodynedPulsarGetAmplitudeModel()

◆ XLALHeterodynedPulsarGetModel()

◆ XLALDetResponseLookupTable()

◆ XLALDestroyDetResponseTimeLookupTable()

◆ XLALPulsarSourceToWaveformParams()