Detailed Description

Provides routines for transforming from arrival time at detector (GPS) to pulse emission time (TDB); ie for `‘barycentering’' the measured astronomical time series.

Author: Curt Cutler

Date: 2001

Synopsis

#include <lal/LALInitBarycenter.h>

#include <lal/LALBarycenter.h>

Prototypes
int	XLALBarycenterEarth (EarthState earth, const LIGOTimeGPS tGPS, const EphemerisData *edat)
	Computes the position and orientation of the Earth, at some arrival time \( t_a \) , specified `LIGOTimeGPS` input structure. More...

int	XLALBarycenterEarthNew (EarthState earth, const LIGOTimeGPS tGPS, const EphemerisData edat, const TimeCorrectionData tdat, TimeCorrectionType ttype)
	Computes the position and orientation of the Earth, at some arrival time, but unlike `XLALBarycenterEarth` uses look-up tables for the Einstein delay calculation. More...

int	XLALBarycenter (EmissionTime emit, const BarycenterInput baryinput, const EarthState *earth)
	Transforms from detector arrival time \( t_a \) in GPS (as specified in the LIGOTimeGPS structure) to pulse emission time \( t_e \) , in TDB. More...

int	XLALBarycenterOpt (EmissionTime emit, const BarycenterInput baryinput, const EarthState earth, BarycenterBuffer *buffer)
	Speed optimized version of XLALBarycenter(), should be fully equivalent except for the additional buffer argument. The 'buffer' is used to keep sky-specific and detector-specific values that can can potentially be re-used across subsequent calls to this function. More...

static void	precessionMatrix (REAL8 prn[3][3], REAL8 mjd, REAL8 dpsi, REAL8 deps)
	Function to calculate the precession matrix give Earth nutation values depsilon and dpsi for a given MJD time. More...

static void	observatoryEarth (REAL8 obsEarth[3], const LALDetector det, const LIGOTimeGPS *tgps, REAL8 gmst, REAL8 dpsi, REAL8 deps)
	Function to get the observatory site location with respect to the centre of the Earth, taking into account precession and nutation. More...

TimeCorrectionData *	XLALInitTimeCorrections (const CHAR *timeCorrectionFile)
	An XLAL interface for reading a time correction file containing a table of values for converting between Terrestrial Time TT (or TDT) to either TDB (i.e. More...

void	XLALDestroyTimeCorrectionData (TimeCorrectionData *tcd)
	Destructor for TimeCorrectionData struct, NULL robust. More...

EphemerisData *	XLALInitBarycenter (const CHAR earthEphemerisFile, const CHAR sunEphemerisFile)
	XLAL interface to reading ephemeris files 'earth' and 'sun', and return ephemeris-data in old backwards-compatible type EphemerisData. More...

void	XLALDestroyEphemerisData (EphemerisData *edat)
	Destructor for EphemerisData struct, NULL robust. More...

int	XLALRestrictEphemerisData (EphemerisData edat, const LIGOTimeGPS startGPS, const LIGOTimeGPS *endGPS)
	Restrict the EphemerisData 'edat' to the smallest number of entries required to cover the GPS time range ['startGPS', 'endGPS']. More...

EphemerisVector *	XLALCreateEphemerisVector (UINT4 length)
	simple creator function for EphemerisVector type More...

void	XLALDestroyEphemerisVector (EphemerisVector *ephemV)
	Destructor for EphemerisVector, NULL robust. More...

EphemerisVector *	XLALReadEphemerisFile (const CHAR *fname)
	XLAL function to read ephemeris-data from one file, returning a EphemerisVector. More...

int	XLALCheckEphemerisRanges (const EphemerisVector *ephemV, REAL8 avg[3], REAL8 range[3])
	Function to check rough consistency of ephemeris-data with being an actual 'Earth' ephemeris: ie check position, velocity and acceleration are within reasonable ranges {avg +- range}. More...

Data Structures
struct	PosVelAcc
	Structure holding a REAL8 time, and a position, velocity and acceleration vector. More...

struct	EphemerisData
	This structure contains all information about the center-of-mass positions of the Earth and Sun, listed at regular time intervals. More...

struct	TimeCorrectionData
	This structure will contain a vector of time corrections used during conversion from TT to TDB/TCB/Teph. More...

struct	EarthState
	Basic output structure of LALBarycenterEarth.c. More...

struct	BarycenterInput
	Basic input structure to LALBarycenter.c. More...

struct	EmissionTime
	Basic output structure produced by LALBarycenter.c. More...

Enumerations
enum	TimeCorrectionType { TIMECORRECTION_NONE = 0 , TIMECORRECTION_TDB , TIMECORRECTION_TCB , TIMECORRECTION_TEMPO , TIMECORRECTION_TEMPO2 , TIMECORRECTION_ORIGINAL , TIMECORRECTION_LAST }
	Enumerated type denoting the time system type to be produced in the solar system barycentring routines. More...

enum	EphemerisType { EPHEM_NONE = 0 , EPHEM_DE200 , EPHEM_DE405 , EPHEM_DE414 , EPHEM_DE421 , EPHEM_DE430 , EPHEM_LAST }
	Enumerated type denoting the JPL solar system ephemeris to be used in calculating barycentre time corrections. More...

Macros
#define	JPL_AU_DE405 149597870.6910000
	Definition of 1 AU from the JPL DE405 ephemeris in km. More...

#define	JPL_AU_DE200 149597870.6600000
	Definition of 1 AU from the JPL DE200 ephemeris in km. More...

#define	CURT_AU 149597870.6600
	1 AU from create_solar_system_barycenter.c as used in Curt's original routines More...

Files
file	LALBarycenterTest.c
	Tests the routine XLALBarycenter(): exercises some of the error conditions and makes sure that they work.

Constants from Irwin and Fukushima, A&A, 348, 1999 (taken from TEMPO2)
used for ephemeris conversions.
#define	IFTE_JD0 2443144.5003725
	Epoch of TCB, TCG and TT in Julian Days. More...

#define	IFTE_MJD0 43144.0003725
	Epoch of TCB, TCG and TT in Modified Julian Days. More...

#define	IFTE_TEPH0 -65.564518e-6
	Equation 17 of Irwin and Fukushima. More...

#define	IFTE_LC 1.48082686742e-8
	Equation 20 of Irwin and Fukushima. More...

#define	IFTE_KM1 1.55051979176e-8
	Value of K-1, defined using the IAU definition of L_B = 1.55051976772e-8 and K=1/(1-L_B) (see TEMPO2). More...

#define	IFTE_K (((long double)1.0) + ((long double)IFTE_KM1))
	Factor relating ephemeris units for time and distance to corresponding SI units, from Eq. More...

Function Documentation

◆ XLALBarycenterEarth()

int XLALBarycenterEarth	(	EarthState *	earth,
		const LIGOTimeGPS *	tGPS,
		const EphemerisData *	edat
	)

Computes the position and orientation of the Earth, at some arrival time \( t_a \) , specified LIGOTimeGPS input structure.

Author: Curt Cutler

The Einstein delay is also calculated. The results are stored in the EarthState output structure, which can then be fed as input to LALBarycenter(). The idea is that LALBarycenterEarth() calculates quantities that are independent of the source location and detector position on Earth. Thus this function is called ONCE for every desired arrival time; the results are then re-used as one steps around the sky (and/or changes detector) at that time.

Parameters

[out]	earth	the earth's state at time tGPS
[in]	tGPS	GPS time tgps
[in]	edat	ephemeris-files

Definition at line 78 of file LALBarycenter.c.

◆ XLALBarycenterEarthNew()

int XLALBarycenterEarthNew	(	EarthState *	earth,
		const LIGOTimeGPS *	tGPS,
		const EphemerisData *	edat,
		const TimeCorrectionData *	tdat,
		TimeCorrectionType	ttype
	)

Computes the position and orientation of the Earth, at some arrival time, but unlike XLALBarycenterEarth uses look-up tables for the Einstein delay calculation.

The function replicates the functionality of XLALBarycenterEarth, but (as in the pulsar timing software TEMPO2) will use a look-up table to compute the Einstein delay term. This function will also allow the final solar system barycentre correction to be in either Barycentric Dynamical Time (TDB), as used previously in XLALBarycenterEarth, or in Coordinate Barycentric Time (TCB), as is the default for TEMPO2.

The function can revert to using the original XLALBarycenterEarth code by supplying TIMECORRECTION_ORIGINAL as the ttype input.

Parameters

[out]	earth	the earth's state at time tGPS
[in]	tGPS	GPS time tgps
[in]	edat	ephemeris-files
[in]	tdat	time correction file data
[in]	ttype	time correction type

Definition at line 487 of file LALBarycenter.c.

◆ XLALBarycenter()

int XLALBarycenter	(	EmissionTime *	emit,
		const BarycenterInput *	baryinput,
		const EarthState *	earth
	)

Transforms from detector arrival time \( t_a \) in GPS (as specified in the LIGOTimeGPS structure) to pulse emission time \( t_e \) , in TDB.

Author: Curt Cutler

Actually, the returned \( t_e \) is the emission time plus the constant light-travel-time from source to SSB.) The inputs to XLALBarycenter(), through the BarycenterInput structure, are the source location, detector site identifier, and GPS arrival time. The function returns the emission time \( t_e(t_a) \) , the derivative \( d t_e/d t_a \) , and the difference \( t_e(t_a) - t_a \) through the EmissionTime structure. The emission time \( t_e(t_a) \) is returned in the LIGOTimeGPS format, while the other two quantities are REAL8's.

Parameters

[out]	emit	emission-time information
[in]	baryinput	info about detector and source-location
[in]	earth	earth-state (from XLALBarycenterEarth())

Definition at line 833 of file LALBarycenter.c.

◆ XLALBarycenterOpt()

int XLALBarycenterOpt	(	EmissionTime *	emit,
		const BarycenterInput *	baryinput,
		const EarthState *	earth,
		BarycenterBuffer **	buffer
	)

Speed optimized version of XLALBarycenter(), should be fully equivalent except for the additional buffer argument. The 'buffer' is used to keep sky-specific and detector-specific values that can can potentially be re-used across subsequent calls to this function.

Author: Curt Cutler, Miroslav Shaltev, R Prix

NOTE: The 'buffer' argument is a pointer to a buffer-pointer, which is allowed to be buffer==NULL (=> no buffering), otherwise a given non-NULL (*buffer) is re-used, or if (*buffer==NULL) we create a new one and return in (*buffer).

Parameters

[out]	emit	emission-time information
[in]	baryinput	info about detector and source-location
[in]	earth	earth-state (from XLALBarycenterEarth())
	buffer	[in/out] internal buffer for speed optimization

Definition at line 1136 of file LALBarycenter.c.

◆ precessionMatrix()

void precessionMatrix	(	REAL8	prn[3][3],
		REAL8	mjd,
		REAL8	dpsi,
		REAL8	deps
	)

static

Function to calculate the precession matrix give Earth nutation values depsilon and dpsi for a given MJD time.

This function is a slightly modified version of the TEMPO2 function get_precessionMatrix in get_ObsCoord.C (itself translated from the TEMPO FORTRAN functions for precession and nutation).

Parameters

[out]	prn	The precession matrix
[in]	mjd	The UT1 local mean siderial time (in MJD format)
[in]	dpsi	The dpsi value for the Earth nutation
[in]	deps	The deps value for the Earth nutation

Definition at line 1461 of file LALBarycenter.c.

◆ observatoryEarth()

void observatoryEarth	(	REAL8	obsEarth[3],
		const LALDetector	det,
		const LIGOTimeGPS *	tgps,
		REAL8	gmst,
		REAL8	dpsi,
		REAL8	deps
	)

static

Function to get the observatory site location with respect to the centre of the Earth, taking into account precession and nutation.

This is based on the routines in the TEMPO2 get_ObsCoord.C code

Parameters

[out]	obsEarth	The x, y, z coordinates of the observatory from the centre of the Earth
[in]	det	The LAL detector site
[in]	tgps	The GPS time at the detector
[in]	gmst	The Greenwich Mean Sidereal Time
[in]	dpsi	dpsi for Earth nutation
[in]	deps	deps for Earth nutation

Definition at line 1528 of file LALBarycenter.c.

◆ XLALInitTimeCorrections()

TimeCorrectionData* XLALInitTimeCorrections ( const CHAR * timeCorrectionFile )

An XLAL interface for reading a time correction file containing a table of values for converting between Terrestrial Time TT (or TDT) to either TDB (i.e.

the file contains time corrections related to the Einstein delay) or Teph (a time system from Irwin and Fukushima, 1999, closely related to Coordinate Barycentric Time, TCB) depending on the file.

The file contains a header with the GPS start time, GPS end time, time interval between subsequent entries (seconds), and the number of entries.

The rest of the file contains a list of the time delays (in seconds).

The tables for the conversion to TDB and Teph are derived from the ephemeris file TDB.1950.2050 and TIMEEPH_short.te405 within TEMPO2 http://www.atnf.csiro.au/research/pulsar/tempo2/. They are created from the Chebychev polynomials in these files using the conversion in the code lalpulsar_create_time_correction_ephemeris

Parameters

timeCorrectionFile File containing Earth's position.

Definition at line 86 of file LALInitBarycenter.c.

◆ XLALDestroyTimeCorrectionData()

void XLALDestroyTimeCorrectionData ( TimeCorrectionData * tcd )

Destructor for TimeCorrectionData struct, NULL robust.

Definition at line 165 of file LALInitBarycenter.c.

◆ XLALInitBarycenter()

EphemerisData* XLALInitBarycenter	(	const CHAR *	earthEphemerisFile,
		const CHAR *	sunEphemerisFile
	)

XLAL interface to reading ephemeris files 'earth' and 'sun', and return ephemeris-data in old backwards-compatible type EphemerisData.

These ephemeris data files contain arrays of center-of-mass positions for the Earth and Sun, respectively.

The tables are derived from the JPL ephemeris.

Files tabulate positions for one calendar year (actually, a little more than one year, to deal with overlaps). The first line of each table summarizes what is in it. Subsequent lines give the time (GPS) and the Earth's position \( (x,y,z) \) , velocity \( (v_x, v_y, v_z) \) , and acceleration \( (a_x, a_y, a_z) \) at that instant. All in units of seconds; e.g. positions have units of seconds, and accelerations have units 1/sec.

Parameters

earthEphemerisFile	File containing Earth's position.
sunEphemerisFile	File containing Sun's position.

Definition at line 206 of file LALInitBarycenter.c.

◆ XLALDestroyEphemerisData()

void XLALDestroyEphemerisData ( EphemerisData * edat )

Destructor for EphemerisData struct, NULL robust.

Definition at line 322 of file LALInitBarycenter.c.

◆ XLALRestrictEphemerisData()

int XLALRestrictEphemerisData	(	EphemerisData *	edat,
		const LIGOTimeGPS *	startGPS,
		const LIGOTimeGPS *	endGPS
	)

Restrict the EphemerisData 'edat' to the smallest number of entries required to cover the GPS time range ['startGPS', 'endGPS'].

Definition at line 357 of file LALInitBarycenter.c.

◆ XLALCreateEphemerisVector()

EphemerisVector * XLALCreateEphemerisVector ( UINT4 length )

simple creator function for EphemerisVector type

Definition at line 418 of file LALInitBarycenter.c.

◆ XLALDestroyEphemerisVector()

void XLALDestroyEphemerisVector ( EphemerisVector * ephemV )

Destructor for EphemerisVector, NULL robust.

Definition at line 440 of file LALInitBarycenter.c.

◆ XLALReadEphemerisFile()

EphemerisVector * XLALReadEphemerisFile ( const CHAR * fname )

XLAL function to read ephemeris-data from one file, returning a EphemerisVector.

This is a helper-function to XLALInitBarycenter().

NOTE: This function tries to read ephemeris from "<fname>" first, if that fails it also tries to read "<fname>.gz" instead. This allows us to handle gzip-compressed ephemeris-files without having to worry about the detailed filename extension used in the case of compression.

NOTE2: files are searched using XLAL_FILE_RESOLVE_PATH()

Definition at line 478 of file LALInitBarycenter.c.

◆ XLALCheckEphemerisRanges()

int XLALCheckEphemerisRanges	(	const EphemerisVector *	ephemV,
		REAL8	avg[3],
		REAL8	range[3]
	)

Function to check rough consistency of ephemeris-data with being an actual 'Earth' ephemeris: ie check position, velocity and acceleration are within reasonable ranges {avg +- range}.

where 'avg' and 'range' are 3-D arrays with [0]=position, [1]=velocity and [2]=acceleration

Definition at line 614 of file LALInitBarycenter.c.

Enumeration Type Documentation

◆ TimeCorrectionType

enum TimeCorrectionType

Enumerated type denoting the time system type to be produced in the solar system barycentring routines.

The type denotes the time system in which solar system barycentred times should be given. TIMECORRECTION_TDB and TIMECORRECTION_TEMPO will mean times are in the Barycentric Dynamical Time (TDB) system, where the conversion has been performed using a time correction ephemeris look-up table as used by TEMPO2 (TIMECORRECTION_TEMPO is so-called because the pulsar timing software TEMPO uses the TDB time system by default); TIMECORRECTION_ORIGINAL will mean times are in the TDB system, but with the conversion performed using the original XLALBarycenterEarth function; and, TIMECORRECTION_TCB and TIMECORRECTION_TEMPO2 will mean times are in the Coordinate Barycentric Time (TCB) system, where the conversion has been performed using a time correction ephemeris look-up table as used by TEMPO2 (TIMECORRECTION_TEMPO2 is so-called because the pulsar timing software TEMPO2 uses the TCB time system by default).

Enumerator
TIMECORRECTION_NONE
TIMECORRECTION_TDB
TIMECORRECTION_TCB
TIMECORRECTION_TEMPO
TIMECORRECTION_TEMPO2
TIMECORRECTION_ORIGINAL
TIMECORRECTION_LAST

Definition at line 72 of file LALBarycenter.h.

◆ EphemerisType

enum EphemerisType

Enumerated type denoting the JPL solar system ephemeris to be used in calculating barycentre time corrections.

Enumerator
EPHEM_NONE
EPHEM_DE200
EPHEM_DE405
EPHEM_DE414
EPHEM_DE421
EPHEM_DE430
EPHEM_LAST

Definition at line 86 of file LALBarycenter.h.

Macro Definition Documentation

◆ IFTE_JD0

#define IFTE_JD0 2443144.5003725

Epoch of TCB, TCG and TT in Julian Days.

Definition at line 101 of file LALBarycenter.h.

◆ IFTE_MJD0

#define IFTE_MJD0 43144.0003725

Epoch of TCB, TCG and TT in Modified Julian Days.

Definition at line 102 of file LALBarycenter.h.

◆ IFTE_TEPH0

#define IFTE_TEPH0 -65.564518e-6

Equation 17 of Irwin and Fukushima.

Definition at line 103 of file LALBarycenter.h.

◆ IFTE_LC

#define IFTE_LC 1.48082686742e-8

Equation 20 of Irwin and Fukushima.

Definition at line 104 of file LALBarycenter.h.

◆ IFTE_KM1

#define IFTE_KM1 1.55051979176e-8

Value of K-1, defined using the IAU definition of L_B = 1.55051976772e-8 and K=1/(1-L_B) (see TEMPO2).

Definition at line 105 of file LALBarycenter.h.

◆ IFTE_K

#define IFTE_K (((long double)1.0) + ((long double)IFTE_KM1))

Factor relating ephemeris units for time and distance to corresponding SI units, from Eq.

2 of Irwin and Fukushima.

Definition at line 106 of file LALBarycenter.h.

◆ JPL_AU_DE405

#define JPL_AU_DE405 149597870.6910000

Definition of 1 AU from the JPL DE405 ephemeris in km.

Definition at line 109 of file LALBarycenter.h.

◆ JPL_AU_DE200

#define JPL_AU_DE200 149597870.6600000

Definition of 1 AU from the JPL DE200 ephemeris in km.

Definition at line 110 of file LALBarycenter.h.

◆ CURT_AU

#define CURT_AU 149597870.6600

1 AU from create_solar_system_barycenter.c as used in Curt's original routines

Definition at line 111 of file LALBarycenter.h.

Detailed Description

Synopsis

Prototypes

Data Structures

Enumerations

Macros

Files

Constants from Irwin and Fukushima, A&A, 348, 1999 (taken from TEMPO2)

Function Documentation

◆ XLALBarycenterEarth()

◆ XLALBarycenterEarthNew()

◆ XLALBarycenter()

◆ XLALBarycenterOpt()

◆ precessionMatrix()

◆ observatoryEarth()

◆ XLALInitTimeCorrections()

◆ XLALDestroyTimeCorrectionData()

◆ XLALInitBarycenter()

◆ XLALDestroyEphemerisData()

◆ XLALRestrictEphemerisData()

◆ XLALCreateEphemerisVector()

◆ XLALDestroyEphemerisVector()

◆ XLALReadEphemerisFile()

◆ XLALCheckEphemerisRanges()

Enumeration Type Documentation

◆ TimeCorrectionType

◆ EphemerisType

Macro Definition Documentation

◆ IFTE_JD0

◆ IFTE_MJD0

◆ IFTE_TEPH0

◆ IFTE_LC

◆ IFTE_KM1

◆ IFTE_K

◆ JPL_AU_DE405

◆ JPL_AU_DE200

◆ CURT_AU