Detailed Description

API for the DetectorStates.c functions.

Author: Reinhard Prix

Date: 2005

Prototypes
int	XLALFillDetectorTensor (DetectorState detState, const LALDetector detector)
	Function to compute the LWL detector-tensor for the given detector in SSB-fixed cartesian coordinates at time tgps. More...

int	XLALTensorSquareVector3 (SymmTensor3 *vxv, REAL4 v[3])
	Compute the "squared-tensor" v x v for given vector v, the result is returned in a "detectorTensor" struct. More...

int	XLALSymmetricTensorProduct3 (SymmTensor3 *vxw, REAL4 v[3], REAL4 w[3])
	Compute the symmetrized tensor product T = v x w + w x v. More...

int	XLALAddSymmTensor3s (SymmTensor3 sum, const SymmTensor3 aT, const SymmTensor3 *bT)
	Convenience function for adding two SymmTensor3s: aT + bT NOTE: it is safe to have sum point to the same tensor-struct as either aT or bT. More...

int	XLALSubtractSymmTensor3s (SymmTensor3 diff, const SymmTensor3 aT, const SymmTensor3 *bT)
	Convenience function for subtracting two SymmTensor3s: aT - bT NOTE: it is safe to have diff point to the same tensor-struct as either aT or bT. More...

int	XLALScaleSymmTensor3 (SymmTensor3 mult, const SymmTensor3 aT, REAL4 factor)
	Convenience function for multiplying a SymmTensor3 by a scalar factor. More...

REAL4	XLALContractSymmTensor3s (const SymmTensor3 T1, const SymmTensor3 T2)
	Contract two symmetric tensors over both indices T1 : T2. More...

void	XLALDestroyDetectorStateSeries (DetectorStateSeries *detStates)
	Get rid of a DetectorStateSeries. More...

void	XLALDestroyMultiDetectorStateSeries (MultiDetectorStateSeries *mdetStates)
	Helper function to get rid of a multi-IFO DetectorStateSeries 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. More...

DetectorStateSeries *	XLALCreateDetectorStateSeries (UINT4 length)
	Create a DetectorStateSeries with length entries. More...

DetectorStateSeries *	XLALGetDetectorStates (const LIGOTimeGPSVector timestamps, const LALDetector detector, const EphemerisData *edat, REAL8 tOffset)
	Get the 'detector state' (ie detector-tensor, position, velocity, etc) for the given vector of timestamps, shifted by a common time-shift tOffset. More...

MultiDetectorStateSeries *	XLALGetMultiDetectorStates (const MultiLIGOTimeGPSVector multiTS, const MultiLALDetector multiIFO, const EphemerisData *edat, REAL8 tOffset)
	Get the detector-time series for the given MultiLIGOTimeGPSVector. More...

MultiDetectorStateSeries *	XLALGetMultiDetectorStatesFromMultiSFTs (const MultiSFTVector multiSFTs, const EphemerisData edat, REAL8 tOffset)
	Get the 'detector state' (ie detector-tensor, position, velocity, etc) for the given multi-vector of SFTs, shifted by a common time-shift tOffset. More...

int	XLALParseMultiNoiseFloor (MultiNoiseFloor multiNoiseFloor, const LALStringVector sqrtSX, UINT4 numDetectors)
	Parse string-vectors (typically input by user) of N detector noise-floors \( \sqrt{S_X} \) for detectors \( X=1\ldots N \) , where here we assume equal number of SFTs per detector such that \( S^{-1} = \frac{1}{N}\sum_{X=0}^{N-1} S_X^{-1} \) . More...

int	XLALParseMultiNoiseFloorMapped (MultiNoiseFloor multiNoiseFloor, const LALStringVector multiNoiseFloorDetNames, const LALStringVector sqrtSX, const LALStringVector sqrtSXDetNames)
	Parse string-vectors (typically input by user) of N detector noise-floors \( \sqrt{S_X} \) for detectors \( X=1\ldots N \) , where here we assume equal number of SFTs per detector such that \( S^{-1} = \frac{1}{N}\sum_{X=0}^{N-1} S_X^{-1} \) . More...

int	XLALParseMultiLALDetector (MultiLALDetector detInfo, const LALStringVector detNames)
	Parse string-vectors (typically input by user) of N detector-names for detectors \( X=1\ldots N \) , returns a MultiLALDetector struct. More...

int	XLALMultiLALDetectorFromMultiSFTCatalogView (MultiLALDetector multiIFO, const MultiSFTCatalogView multiView)
	Extract multi detector-info from a given multi SFTCatalog view. More...

int	XLALMultiLALDetectorFromMultiSFTs (MultiLALDetector multiIFO, const MultiSFTVector multiSFTs)
	Extract multi detector-info from a given multi SFTCatalog view. More...

Data Structures
struct	SymmTensor3
	A symmetric 3x3 tensor (such as detector-tensors), storing only the upper triangle. More...

struct	SymmTensor3d
	A symmetric 3x3 tensor (such as detector-tensors), storing only the upper triangle, using REAL8 precision. More...

struct	DetectorArm
	Struct containing pre-computed quantites describing a single detector arm: unit-vector along detector-arm, arm-length, and arm "basis-tensor" n x n. More...

struct	MultiLALDetector
	array of detectors definitions 'LALDetector' More...

struct	MultiNoiseFloor
	array of detector-specific 'noise floors' (ie PSD values), assumed constant over the frequency-band of interest More...

struct	DetectorState
	State-info about position, velocity and LMST of a detector together with corresponding EarthState. More...

struct	DetectorStateSeries
	Timeseries of DetectorState's, representing the detector-info at different timestamps. More...

struct	MultiDetectorStateSeries
	Multi-IFO time-series of DetectorStates. More...

Typedefs
typedef DetectorArm	Detector3Arms[3]
	used to allow functions some type/size checking More...

Error-codes
#define	DETECTORSTATES_ENULL 1

#define	DETECTORSTATES_ENONULL 2

#define	DETECTORSTATES_EINPUT 3

#define	DETECTORSTATES_EMEM 4

#define	DETECTORSTATES_EXLAL 5

#define	DETECTORSTATES_EIEEE 6

#define	DETECTORSTATES_MSGENULL "Arguments contained an unexpected null pointer"

#define	DETECTORSTATES_MSGENONULL "Output pointer is non-NULL"

#define	DETECTORSTATES_MSGEINPUT "Invalid input"

#define	DETECTORSTATES_MSGEMEM "Out of memory. Bad."

#define	DETECTORSTATES_MSGEXLAL "XLAL function call failed"

#define	DETECTORSTATES_MSGEIEEE "Floating point failure"

Function Documentation

◆ XLALFillDetectorTensor()

int XLALFillDetectorTensor	(	DetectorState *	detState,
		const LALDetector *	detector
	)

Function to compute the LWL detector-tensor for the given detector in SSB-fixed cartesian coordinates at time tgps.

The coordinates used are: EQUATORIAL for Earth-based detectors, but ECLIPTIC for LISA. RETURN: 0 = OK, -1 = ERROR

Parameters

[in,out]	detState	: detector state: fill in detector-tensor
[in]	detector	: which detector

Definition at line 60 of file DetectorStates.c.

◆ XLALTensorSquareVector3()

int XLALTensorSquareVector3	(	SymmTensor3 *	vxv,
		REAL4	v[3]
	)

Compute the "squared-tensor" v x v for given vector v, the result is returned in a "detectorTensor" struct.

Definition at line 140 of file DetectorStates.c.

◆ XLALSymmetricTensorProduct3()

int XLALSymmetricTensorProduct3	(	SymmTensor3 *	vxw,
		REAL4	v[3],
		REAL4	w[3]
	)

Compute the symmetrized tensor product T = v x w + w x v.

Definition at line 163 of file DetectorStates.c.

◆ XLALAddSymmTensor3s()

int XLALAddSymmTensor3s	(	SymmTensor3 *	sum,
		const SymmTensor3 *	aT,
		const SymmTensor3 *	bT
	)

Convenience function for adding two SymmTensor3s: aT + bT NOTE: it is safe to have sum point to the same tensor-struct as either aT or bT.

Definition at line 187 of file DetectorStates.c.

◆ XLALSubtractSymmTensor3s()

int XLALSubtractSymmTensor3s	(	SymmTensor3 *	diff,
		const SymmTensor3 *	aT,
		const SymmTensor3 *	bT
	)

Convenience function for subtracting two SymmTensor3s: aT - bT NOTE: it is safe to have diff point to the same tensor-struct as either aT or bT.

Definition at line 211 of file DetectorStates.c.

◆ XLALScaleSymmTensor3()

int XLALScaleSymmTensor3	(	SymmTensor3 *	mult,
		const SymmTensor3 *	aT,
		REAL4	factor
	)

Convenience function for multiplying a SymmTensor3 by a scalar factor.

NOTE: it is safe to have aT and mult point to the same tensor-struct

Definition at line 235 of file DetectorStates.c.

◆ XLALContractSymmTensor3s()

REAL4 XLALContractSymmTensor3s	(	const SymmTensor3 *	T1,
		const SymmTensor3 *	T2
	)

Contract two symmetric tensors over both indices T1 : T2.

Definition at line 258 of file DetectorStates.c.

◆ XLALDestroyDetectorStateSeries()

void XLALDestroyDetectorStateSeries ( DetectorStateSeries * detStates )

Get rid of a DetectorStateSeries.

Definition at line 279 of file DetectorStates.c.

◆ XLALDestroyMultiDetectorStateSeries()

void XLALDestroyMultiDetectorStateSeries ( MultiDetectorStateSeries * mdetStates )

Helper function to get rid of a multi-IFO DetectorStateSeries 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 301 of file DetectorStates.c.

◆ XLALCreateDetectorStateSeries()

DetectorStateSeries * XLALCreateDetectorStateSeries ( UINT4 length )

Create a DetectorStateSeries with length entries.

Parameters

length number of entries

Definition at line 326 of file DetectorStates.c.

◆ XLALGetDetectorStates()

DetectorStateSeries * XLALGetDetectorStates	(	const LIGOTimeGPSVector *	timestamps,
		const LALDetector *	detector,
		const EphemerisData *	edat,
		REAL8	tOffset
	)

Get the 'detector state' (ie detector-tensor, position, velocity, etc) for the given vector of timestamps, shifted by a common time-shift tOffset.

This function just calls XLALBarycenterEarth() and XLALBarycenter() for the given vector of timestamps (shifted by tOffset) and returns the positions, velocities and LMSTs of the detector, stored in a DetectorStateSeries. There is also an entry containing the EarthState at each timestamp, which can be used as input for subsequent calls to XLALBarycenter().

tOffset allows one to easily use the midpoints of SFT-timestamps, for example.

Parameters

timestamps	array of GPS timestamps t_i
detector	detector info
edat	ephemeris file data
tOffset	compute detector states at timestamps SHIFTED by tOffset

Definition at line 362 of file DetectorStates.c.

◆ XLALGetMultiDetectorStates()

MultiDetectorStateSeries * XLALGetMultiDetectorStates	(	const MultiLIGOTimeGPSVector *	multiTS,
		const MultiLALDetector *	multiIFO,
		const EphemerisData *	edat,
		REAL8	tOffset
	)

Get the detector-time series for the given MultiLIGOTimeGPSVector.

NOTE: contrary to the deprecated XLALGetMultiDetectorStatesFromMultiSFTs() interface, this function computes detector-states at the given timestamps shifted by tOffset

Parameters

[in]	multiTS	multi-IFO timestamps
[in]	multiIFO	multi-IFO array holding detector info
[in]	edat	ephemeris data
[in]	tOffset	shift all timestamps by this amount

Definition at line 468 of file DetectorStates.c.

◆ XLALGetMultiDetectorStatesFromMultiSFTs()

MultiDetectorStateSeries * XLALGetMultiDetectorStatesFromMultiSFTs	(	const MultiSFTVector *	multiSFTs,
		const EphemerisData *	edat,
		REAL8	tOffset
	)

Get the 'detector state' (ie detector-tensor, position, velocity, etc) for the given multi-vector of SFTs, shifted by a common time-shift tOffset.

tOffset allows one to easily use the midpoints of SFT-timestamps, for example.

Parameters

[in]	multiSFTs	multi-IFO SFTs
[in]	edat	ephemeris data
[in]	tOffset	shift all timestamps by this amount

Definition at line 537 of file DetectorStates.c.

◆ XLALParseMultiNoiseFloor()

int XLALParseMultiNoiseFloor	(	MultiNoiseFloor *	multiNoiseFloor,
		const LALStringVector *	sqrtSX,
		UINT4	numDetectors
	)

Parse string-vectors (typically input by user) of N detector noise-floors \( \sqrt{S_X} \) for detectors \( X=1\ldots N \) , where here we assume equal number of SFTs per detector such that \( S^{-1} = \frac{1}{N}\sum_{X=0}^{N-1} S_X^{-1} \) .

Note: input of length(sqrtSX)=1 < numDetectors is valid: use that single number for all detectors, otherwise we enforce length(sqrtSX) == numDetectors.

returns result in MultiNoiseFloor struct 'multiNoiseFloor'.

Parameters

[out]	multiNoiseFloor	parsed multi-IFO noise floor info
[in]	sqrtSX	string-list of \( \sqrt{S_X} \) for detectors \( X \)
[in]	numDetectors	number of detectors. NOTE: length[sqrtSX] must be EITHER =numDetectors OR =1

Definition at line 578 of file DetectorStates.c.

◆ XLALParseMultiNoiseFloorMapped()

int XLALParseMultiNoiseFloorMapped	(	MultiNoiseFloor *	multiNoiseFloor,
		const LALStringVector *	multiNoiseFloorDetNames,
		const LALStringVector *	sqrtSX,
		const LALStringVector *	sqrtSXDetNames
	)

Parse string-vectors (typically input by user) of N detector noise-floors \( \sqrt{S_X} \) for detectors \( X=1\ldots N \) , where here we assume equal number of SFTs per detector such that \( S^{-1} = \frac{1}{N}\sum_{X=0}^{N-1} S_X^{-1} \) .

The detectors corresponding to each noise-floor may be a subset of the input string-vectors, e.g. if parsing noise-floors for a segment where SFTs from some detectors are missing.

Parameters

[out]	multiNoiseFloor	parsed multi-IFO noise floor info
[in]	multiNoiseFloorDetNames	detector names for entries in `multiNoiseFloor`
[in]	sqrtSX	string-list of \( \sqrt{S_X} \) for detectors \( X \)
[in]	sqrtSXDetNames	detector names for entries in `sqrtSX`

Definition at line 616 of file DetectorStates.c.

◆ XLALParseMultiLALDetector()

int XLALParseMultiLALDetector	(	MultiLALDetector *	detInfo,
		const LALStringVector *	detNames
	)

Parse string-vectors (typically input by user) of N detector-names for detectors \( X=1\ldots N \) , returns a MultiLALDetector struct.

Parameters

[out]	detInfo	parsed detector-info struct
[in]	detNames	list of detector names

Definition at line 662 of file DetectorStates.c.

◆ XLALMultiLALDetectorFromMultiSFTCatalogView()

int XLALMultiLALDetectorFromMultiSFTCatalogView	(	MultiLALDetector *	multiIFO,
		const MultiSFTCatalogView *	multiView
	)

Extract multi detector-info from a given multi SFTCatalog view.

Parameters

[out]	multiIFO	list of detectors found in catalog
[in]	multiView	multi-IFO view of SFT catalog

Definition at line 691 of file DetectorStates.c.

◆ XLALMultiLALDetectorFromMultiSFTs()

int XLALMultiLALDetectorFromMultiSFTs	(	MultiLALDetector *	multiIFO,
		const MultiSFTVector *	multiSFTs
	)

Extract multi detector-info from a given multi SFTCatalog view.

Parameters

[out]	multiIFO	list of detectors found in catalog
[in]	multiSFTs	multi-IFO SFT vector

Definition at line 719 of file DetectorStates.c.

Typedef Documentation

◆ Detector3Arms

typedef DetectorArm Detector3Arms[3]

used to allow functions some type/size checking

Definition at line 102 of file DetectorStates.h.

Macro Definition Documentation

◆ DETECTORSTATES_ENULL

#define DETECTORSTATES_ENULL 1

Definition at line 47 of file DetectorStates.h.

◆ DETECTORSTATES_ENONULL

#define DETECTORSTATES_ENONULL 2

Definition at line 48 of file DetectorStates.h.

◆ DETECTORSTATES_EINPUT

#define DETECTORSTATES_EINPUT 3

Definition at line 49 of file DetectorStates.h.

◆ DETECTORSTATES_EMEM

#define DETECTORSTATES_EMEM 4

Definition at line 50 of file DetectorStates.h.

◆ DETECTORSTATES_EXLAL

#define DETECTORSTATES_EXLAL 5

Definition at line 51 of file DetectorStates.h.

◆ DETECTORSTATES_EIEEE

#define DETECTORSTATES_EIEEE 6

Definition at line 52 of file DetectorStates.h.

◆ DETECTORSTATES_MSGENULL

#define DETECTORSTATES_MSGENULL "Arguments contained an unexpected null pointer"

Definition at line 54 of file DetectorStates.h.

◆ DETECTORSTATES_MSGENONULL

#define DETECTORSTATES_MSGENONULL "Output pointer is non-NULL"

Definition at line 55 of file DetectorStates.h.

◆ DETECTORSTATES_MSGEINPUT

#define DETECTORSTATES_MSGEINPUT "Invalid input"

Definition at line 56 of file DetectorStates.h.

◆ DETECTORSTATES_MSGEMEM

#define DETECTORSTATES_MSGEMEM "Out of memory. Bad."

Definition at line 57 of file DetectorStates.h.

◆ DETECTORSTATES_MSGEXLAL

#define DETECTORSTATES_MSGEXLAL "XLAL function call failed"

Definition at line 58 of file DetectorStates.h.

◆ DETECTORSTATES_MSGEIEEE

#define DETECTORSTATES_MSGEIEEE "Floating point failure"

Definition at line 59 of file DetectorStates.h.

Detailed Description

Prototypes

Data Structures

Typedefs

Error-codes

Function Documentation

◆ XLALFillDetectorTensor()

◆ XLALTensorSquareVector3()

◆ XLALSymmetricTensorProduct3()

◆ XLALAddSymmTensor3s()

◆ XLALSubtractSymmTensor3s()

◆ XLALScaleSymmTensor3()

◆ XLALContractSymmTensor3s()

◆ XLALDestroyDetectorStateSeries()

◆ XLALDestroyMultiDetectorStateSeries()

◆ XLALCreateDetectorStateSeries()

◆ XLALGetDetectorStates()

◆ XLALGetMultiDetectorStates()

◆ XLALGetMultiDetectorStatesFromMultiSFTs()

◆ XLALParseMultiNoiseFloor()

◆ XLALParseMultiNoiseFloorMapped()

◆ XLALParseMultiLALDetector()

◆ XLALMultiLALDetectorFromMultiSFTCatalogView()

◆ XLALMultiLALDetectorFromMultiSFTs()

Typedef Documentation

◆ Detector3Arms

Macro Definition Documentation

◆ DETECTORSTATES_ENULL

◆ DETECTORSTATES_ENONULL

◆ DETECTORSTATES_EINPUT

◆ DETECTORSTATES_EMEM

◆ DETECTORSTATES_EXLAL

◆ DETECTORSTATES_EIEEE

◆ DETECTORSTATES_MSGENULL

◆ DETECTORSTATES_MSGENONULL

◆ DETECTORSTATES_MSGEINPUT

◆ DETECTORSTATES_MSGEMEM

◆ DETECTORSTATES_MSGEXLAL

◆ DETECTORSTATES_MSGEIEEE