Detailed Description

Header-file for computing antenna-pattern components for amplitude demodulation.

Computes quantities for amplitude demodulation.

Author: S.J. Berukoff, Reinhard Prix, John Whelan

Date: 2007

#include <lal/LALComputeAM.h>

In order to compute the optimal statistic for pulsar searches, one must take account of the various modulations that change the emitted, (fairly) simple sinusoid into a non-trivial function of parameters. The frequency evolution of the signal (spindown effects, Doppler modulation, etc.) have already been accounted for; this routine filters the amplitude modulation effects.

Author: S.J. Berukoff, Reinhard Prix, John Whelan

Date: 2007

This routine computes the quantities \( a(t) \) and \( b(t) \) as defined in Jaranowski, Krolak, and Schutz [9] , hereafter JKS. These functions quantify the dependence of the detector output on the beam-pattern functions \( F_{+} \) and \( F_{\times} \) ; in fact, \( a(t) \) and \( b(t) \) are the beam-pattern functions, without the dependence on polarization angle and detector arm angle. Since the LALDemod() suite is an attempt to compute an optimal statistic, it is necessary to include these quantities in the computation. Otherwise, the motion of the Earth as it revolves about its axis will smear the signal into several neighboring bins centered about the search frequency, consequently losing valuable SNR.

Algorithm

The routine is really simple. From JKS,

\begin{eqnarray*} F_{+} &=& \sin\zeta [ a(t) \cos 2 \psi + b(t) \sin 2 \psi ] \\ F_{\times} &=& \sin\zeta [ b(t) \cos 2 \psi - a(t) \sin 2 \psi ] \end{eqnarray*}

We use the routine LALComputeDetAMResponse() to calculate \( F_{+} \) and \( F_{\times} \) for a given polarization angle, and then extract \( a(t) \) and \( b(t) \) , once for each timestamp \( t \) . Additionally, computation of the optimal statistic requires that we compute inner products of these two quantities for later use.

Prototypes
int	XLALComputeAntennaPatternCoeffs (REAL8 ai, REAL8 bi, const SkyPosition skypos, const LIGOTimeGPS tGPS, const LALDetector site, const EphemerisData edat)
	Compute single time-stamp antenna-pattern coefficients a(t), b(t) Note: this function uses REAL8 precision, so this can be used in high-precision integration of the F-metric. More...

int	XLALWeightMultiAMCoeffs (MultiAMCoeffs multiAMcoef, const MultiNoiseWeights multiWeights)
	Replace AM-coeffs by weighted AM-coeffs, i.e. More...

AMCoeffs *	XLALComputeAMCoeffs (const DetectorStateSeries *DetectorStates, SkyPosition skypos)
	Compute the 'amplitude coefficients' \( a(t)\sin\zeta \) , \( b(t)\sin\zeta \) as defined in [9] for a series of timestamps. More...

MultiAMCoeffs *	XLALComputeMultiAMCoeffs (const MultiDetectorStateSeries multiDetStates, const MultiNoiseWeights multiWeights, SkyPosition skypos)
	Multi-IFO version of XLALComputeAMCoeffs(). More...

AMCoeffs *	XLALCreateAMCoeffs (UINT4 numSteps)
	Create an AMCeoffs vector for given number of timesteps. More...

void	XLALDestroyMultiAMCoeffs (MultiAMCoeffs *multiAMcoef)
	Destroy a MultiAMCoeffs structure. More...

void	XLALDestroyAMCoeffs (AMCoeffs *amcoef)
	Destroy a AMCoeffs structure. More...

REAL4	XLALComputeAntennaPatternSqrtDeterminant (REAL4 A, REAL4 B, REAL4 C, REAL4 E)
	Compute (sqrt of) determinant of the antenna-pattern matrix Mmunu = [ A, C, 0, -E; C B E, 0; 0 E A C; -Ed 0 C B; ] which is det(Mmunu) = ( A B - C^2 - E^2 )^2;. More...

void	XLALSetAntennaPatternMaxCond (REAL4 max_cond)
	Set a new module-local maximal acceptable condition number of computing antenna-pattern matrix determinant. More...

void	XLALSetAntennaPatternIllCondDeterminant (REAL4 illCondDeterminant)
	Set the 'fallback' determinant to use for ill-conditioned antenna-pattern matrix. More...

Data Structures
struct	AMCoeffs
	This structure contains the per-SFT (weighted) antenna-pattern functions \( \widehat{a}_{X\alpha}, \widehat{b}_{X\alpha} \) , with \( \alpha \) the SFT-index, and \( X \) the IFO index. More...

struct	AMCoeffsParams
	This structure contains the parameters for the routine. More...

struct	AntennaPatternMatrix
	Struct holding the "antenna-pattern" matrix \( \mathcal{M}_{\mu\nu} \equiv \left( \mathbf{h}_\mu\|\mathbf{h}_\nu\right) \) , in terms of the multi-detector scalar product. More...

struct	MultiAMCoeffs
	Multi-IFO container for antenna-pattern coefficients \( a_{X\alpha}, b_{X\alpha} \) and atenna-pattern matrix \( \mathcal{M}_{\mu\nu} \). More...

Files
file	XLALComputeAMTest.c
	Test for XLALComputeAMCoeffs() and XLALComputeMultiAMCoeffs() by comparison with the old LAL functions old_LALGetAMCoeffs() and old_LALGetMultiAMCoeffs().

Function Documentation

◆ XLALComputeAntennaPatternCoeffs()

int XLALComputeAntennaPatternCoeffs	(	REAL8 *	ai,
		REAL8 *	bi,
		const SkyPosition *	skypos,
		const LIGOTimeGPS *	tGPS,
		const LALDetector *	site,
		const EphemerisData *	edat
	)

Compute single time-stamp antenna-pattern coefficients a(t), b(t) Note: this function uses REAL8 precision, so this can be used in high-precision integration of the F-metric.

Parameters

[out]	ai	antenna-pattern function a(t)
[out]	bi	antenna-pattern function b(t)
[in]	skypos	skyposition {alpha, delta}
[in]	tGPS	GPS time t
[in]	site	detector
[in]	edat	ephemeris-data

Definition at line 79 of file LALComputeAM.c.

◆ XLALWeightMultiAMCoeffs()

int XLALWeightMultiAMCoeffs	(	MultiAMCoeffs *	multiAMcoef,
		const MultiNoiseWeights *	multiWeights
	)

Replace AM-coeffs by weighted AM-coeffs, i.e.

\( a_{X\alpha} \rightarrow \widehat{a}_{X\alpha} \equiv a_{X\alpha} \sqrt{w_{X\alpha}} \) , and \( b_{X\alpha} \rightarrow \widehat{b}_{X\alpha} \equiv a_{X\alpha} \sqrt{w_{X\alpha}} \) , where \( w_{X\alpha} \) are the multiWeights for SFT \( \alpha \) and detector \( X \) .

Also compute the resulting per-detector \( X \) antenna-pattern matrix coefficients \( \widehat{A}_X \equiv \sum_{\alpha} \widehat{a}^2_{X\alpha} \) , \( \widehat{B}_X \equiv \sum_{\alpha} \widehat{b}^2_{X\alpha} \) , \( \widehat{C}_X \equiv \sum_{\alpha} \widehat{a}_{X\alpha}\widehat{b}_{X\alpha} \) ,

and corresponding multi-detector antenna-pattern matrix coefficients \( \widehat{A} \equiv \sum_{X} \widehat{A}_X \) , \( \widehat{B} \equiv \sum_{X} \widehat{B}_X \) , \( \widehat{C} \equiv \sum_{X} \widehat{C}_X \) .

See Sec.4.1 in CFSv2.pdf notes https://dcc.ligo.org/cgi-bin/DocDB/ShowDocument?docid=T0900149&version=4

Note: *) this function modifies the input AMCoeffs->{a,b,c} in place !; *) if multiWeights = NULL, we assume unit-weights.

Definition at line 188 of file LALComputeAM.c.

◆ XLALComputeAMCoeffs()

AMCoeffs * XLALComputeAMCoeffs	(	const DetectorStateSeries *	DetectorStates,
		SkyPosition	skypos
	)

Compute the 'amplitude coefficients' \( a(t)\sin\zeta \) , \( b(t)\sin\zeta \) as defined in [9] for a series of timestamps.

The input consists of the DetectorState-timeseries, which contains the detector-info and the LMST's corresponding to the different times.

Note: This implementation is based on the geometrical definition of \( a\sin\zeta \) and \( b\sin\zeta \) as detector response coefficients in a preferred polarization basis. (It is thereby more general than the JKS expressions and could be used e.g., with the response tensor of a bar detector with no further modification needed.); The fields AMCoeffs->{A, B, C, D} are not computed by this function, as they require correct SFT noise-weights. These fields would be computed, for example by XLALWeightMultiAMCoeffs().

Parameters

DetectorStates	timeseries of detector states
skypos	{alpha,delta} of the source

Definition at line 297 of file LALComputeAM.c.

◆ XLALComputeMultiAMCoeffs()

MultiAMCoeffs * XLALComputeMultiAMCoeffs	(	const MultiDetectorStateSeries *	multiDetStates,
		const MultiNoiseWeights *	multiWeights,
		SkyPosition	skypos
	)

Multi-IFO version of XLALComputeAMCoeffs().

Computes noise-weighted combined multi-IFO antenna pattern functions.

This function applies the noise-weights and computes the multi-IFO antenna-pattern matrix components {A, B, C}, and single-IFO matrix components {A_X,B_X,C_X} for detector X.

Therefore: DONT use XLALWeightMultiAMCoeffs() on the result!

Note: *) an input of multiWeights = NULL corresponds to unit-weights

Parameters

[in]	multiDetStates	detector-states at timestamps t_i
[in]	multiWeights	noise-weigths at timestamps t_i (can be NULL)
	skypos	source sky-position [in equatorial coords!]

Definition at line 379 of file LALComputeAM.c.

◆ XLALCreateAMCoeffs()

AMCoeffs * XLALCreateAMCoeffs ( UINT4 numSteps )

Create an AMCeoffs vector for given number of timesteps.

Definition at line 435 of file LALComputeAM.c.

◆ XLALDestroyMultiAMCoeffs()

void XLALDestroyMultiAMCoeffs ( MultiAMCoeffs * multiAMcoef )

Destroy a MultiAMCoeffs structure.

Note, this is "NULL-robust" in the sense that it will not crash on NULL-entries anywhere in this struct, so it can be used for failure-cleanup even on incomplete structs

Definition at line 469 of file LALComputeAM.c.

◆ XLALDestroyAMCoeffs()

void XLALDestroyAMCoeffs ( AMCoeffs * amcoef )

Destroy a AMCoeffs structure.

Note: This function is "NULL-robust" in the sense that it will not crash on NULL-entries anywhere in this struct, so it can be used for failure-cleanup even on incomplete structs

Definition at line 497 of file LALComputeAM.c.

◆ XLALComputeAntennaPatternSqrtDeterminant()

REAL4 XLALComputeAntennaPatternSqrtDeterminant	(	REAL4	A,
		REAL4	B,
		REAL4	C,
		REAL4	E
	)

Compute (sqrt of) determinant of the antenna-pattern matrix Mmunu = [ A, C, 0, -E; C B E, 0; 0 E A C; -Ed 0 C B; ] which is det(Mmunu) = ( A B - C^2 - E^2 )^2;.

in addition this function checks if the condition number exceeds a module-local tolerance value 'AntennaPatternMaxCond' and outputs a warning and returns NAN if it does. Use XLALSetAntennaPatternMaxCond() to change the acceptable tolerance value.

Definition at line 544 of file LALComputeAM.c.

◆ XLALSetAntennaPatternMaxCond()

void XLALSetAntennaPatternMaxCond ( REAL4 max_cond )

Set a new module-local maximal acceptable condition number of computing antenna-pattern matrix determinant.

Definition at line 565 of file LALComputeAM.c.

◆ XLALSetAntennaPatternIllCondDeterminant()

void XLALSetAntennaPatternIllCondDeterminant ( REAL4 illCondDeterminant )

Set the 'fallback' determinant to use for ill-conditioned antenna-pattern matrix.

Use 'INFINITY' (=default) to allow 2F-calculation to continue by 'turning off' the 2F value, or 'NAN' to force an error-condition to terminate the code.

Definition at line 575 of file LALComputeAM.c.

Detailed Description

Algorithm

Prototypes

Data Structures

Files

Function Documentation

◆ XLALComputeAntennaPatternCoeffs()

◆ XLALWeightMultiAMCoeffs()

◆ XLALComputeAMCoeffs()

◆ XLALComputeMultiAMCoeffs()

◆ XLALCreateAMCoeffs()

◆ XLALDestroyMultiAMCoeffs()

◆ XLALDestroyAMCoeffs()

◆ XLALComputeAntennaPatternSqrtDeterminant()

◆ XLALSetAntennaPatternMaxCond()

◆ XLALSetAntennaPatternIllCondDeterminant()