Detailed Description

Functions to read TEMPO(2) pulsar parameter files.

Author: Matt Pitkin

Date: 2013

Radio astronomers fit pulsar parameters using TEMPO(2) which will output the parameters in a .par file. The values allowed in this file can be found in the TEMPO documentation.

The function XLALReadTEMPOParFile() reads the parameters into a linked list PulsarParameters structure, from which the parameters can be accessed using the appropriate access function. These use a hash table to quick look-up. The parameters are assigned names, which are used as the hash table keys, which are fully uppercase versions of the TEMPO parameter names.

All parameters read in are converted into SI units.

Functions are is also included which converts a string containing the right ascension or declination in the format ddd/hh:mm:ss.s or ddd/hhmmss.s (as is given in the .par file) into a REAL8 value in radians.

Prototypes
static void	strtoupper (CHAR *s)
	Convert string to uppercase. More...

static void *	new_elem (const char name, PulsarParam itemPtr)

static void	del_elem (void *elem)

static UINT8	PulsarHash (const void *elem)

static int	PulsarHashElemCmp (const void elem1, const void elem2)

static PulsarParam *	PulsarGetParamItemSlow (const PulsarParameters pars, const CHAR name)
	Get a pointer to a parameter of a given name from a `PulsarParameters` structure. More...

static PulsarParam *	PulsarGetParamItem (const PulsarParameters pars, const CHAR name)
	Get a pointer to a parameter of a given name from a `PulsarParameters` structure. More...

void *	PulsarGetParam (const PulsarParameters pars, const CHAR name)
	Get the required parameter value from the PulsarParameters structure. More...

PulsarParamType	PulsarGetParamType (const PulsarParameters pars, const char name)
	Get the required parameter's type. More...

REAL8	PulsarGetREAL8Param (const PulsarParameters pars, const CHAR name)
	Return a `REAL8` parameter. More...

REAL8	PulsarGetREAL8ParamOrZero (const PulsarParameters pars, const CHAR name)
	Return a `REAL8` parameter if it exists, otherwise return zero. More...

UINT4	PulsarGetUINT4Param (const PulsarParameters pars, const CHAR name)
	Return a `UINT4` parameter. More...

UINT4	PulsarGetUINT4ParamOrZero (const PulsarParameters pars, const CHAR name)
	Return a `UINT4` parameter if it exists, otherwise return zero. More...

const CHAR *	PulsarGetStringParam (const PulsarParameters pars, const CHAR name)
	Return a string parameter. More...

const REAL8Vector *	PulsarGetREAL8VectorParam (const PulsarParameters pars, const CHAR name)
	Return a `REAL8Vector` parameter. More...

REAL8	PulsarGetREAL8VectorParamIndividual (const PulsarParameters pars, const CHAR name)
	Return an individual `REAL8` value from a `REAL8Vector` parameter. More...

void *	PulsarGetParamErr (const PulsarParameters pars, const CHAR name)
	Get the required parameter error value from the PulsarParameters structure. More...

const UINT4 *	PulsarGetParamFitFlag (const PulsarParameters pars, const CHAR name)
	Get the fit flag array for a given parameter from the PulsarParameters structure. More...

const UINT4Vector *	PulsarGetParamFitFlagAsVector (const PulsarParameters pars, const CHAR name)
	Get the fit flag array for a given parameter from the PulsarParameters structure. More...

REAL8	PulsarGetREAL8ParamErr (const PulsarParameters pars, const CHAR name)
	Return a `REAL8` parameter error value. More...

const REAL8Vector *	PulsarGetREAL8VectorParamErr (const PulsarParameters pars, const CHAR name)
	Return a `REAL8Vector` parameter error value. More...

REAL8	PulsarGetREAL8VectorParamErrIndividual (const PulsarParameters pars, const CHAR name)
	Return an individual `REAL8` value from a `REAL8Vector` parameter. More...

void	PulsarAddParam (PulsarParameters pars, const CHAR name, void *value, PulsarParamType type)
	Add a parameter and value to the PulsarParameters structure. More...

void	PulsarAddREAL8Param (PulsarParameters pars, const CHAR name, REAL8 value)
	Add a `REAL8` parameter to the PulsarParameters structure. More...

void	PulsarAddUINT4Param (PulsarParameters pars, const CHAR name, UINT4 value)
	Add a `UINT4` parameter to the PulsarParameters structure. More...

void	PulsarAddREAL8VectorParam (PulsarParameters pars, const CHAR name, const REAL8Vector *value)
	Add a `REAL8Vector` parameter to the PulsarParameters structure. More...

void	PulsarAddStringParam (PulsarParameters pars, const CHAR name, const CHAR *value)
	Add a string parameter to the PulsarParameters structure. More...

int	PulsarCheckParam (const PulsarParameters pars, const CHAR name)
	Check for the existence of the parameter `name` in the PulsarParameters structure. More...

void	PulsarClearParams (PulsarParameters *pars)
	Free all the parameters from a PulsarParameters structure. More...

void	PulsarRemoveParam (PulsarParameters pars, const CHAR name)
	Remove a given parameter from a PulsarParameters structure. More...

void	PulsarSetParam (PulsarParameters pars, const CHAR name, const void *value)
	Set the value of a parameter in the PulsarParameters structure. More...

void	PulsarSetParamErr (PulsarParameters pars, const CHAR name, void value, const UINT4 fitFlag, UINT4 len)
	Set the value of the error of a parameter in the PulsarParameters structure. More...

void	PulsarSetREAL8ParamErr (PulsarParameters pars, const CHAR name, REAL8 value, UINT4 fitFlag)
	Set the error value for a `REAL8` parameter. More...

void	PulsarSetREAL8VectorParamErr (PulsarParameters pars, const CHAR name, const REAL8Vector value, const UINT4 fitFlag)
	Set the error values for a `REAL8Vector` parameter. More...

void	PulsarFreeParams (PulsarParameters *par)
	Function to free memory from pulsar parameters. More...

void	PulsarCopyParams (PulsarParameters origin, PulsarParameters target)
	Function to copy a PulsarParameters structure. More...

	DEFINE_CONV_FACTOR_FUNCTION (ToFloat, 1., CONVFLOAT)
	A strcuture to contain all possible pulsar parameters that can be read in from a par file, and define the conversion function and type used for each. More...

static INT4	ParseParLine (PulsarParameters par, const CHAR name, FILE *fp)
	Parse a single line from a pulsar parameter file. More...

PulsarParameters *	XLALReadTEMPOParFile (const CHAR *pulsarAndPath)
	Read in the parameters from a `TEMPO(2)` parameter file into a PulsarParameters structure. More...

void	PrintPulsarParameters (BinaryPulsarParams params)
	function to print out all the pulsar parameters read in from a par file More...

LALStringVector *	XLALReadTEMPOCorFile (REAL8Array cormat, CHAR corfile)
	This function will read in a TEMPO-style parameter correlation matrix. More...

void	ParConvToFloat (const CHAR in, void out)
	Conversion functions from units used in TEMPO parameter files into SI units. More...

void	ParConvToInt (const CHAR in, void out)
	Convert the input string into a unsigned integer number. More...

void	ParConvToString (const CHAR in, void out)
	Copy the input string into the output pointer. More...

void	ParConvDegsToRads (const CHAR in, void out)
	Convert the input string from degrees to radians. More...

void	ParConvMasPerYrToRadPerSec (const CHAR in, void out)
	Convert the input string from milliarcsecs per year to radians per second. More...

void	ParConvSecsToRads (const CHAR in, void out)
	Convert the input string from seconds to radians. More...

void	ParConvArcsecsToRads (const CHAR in, void out)
	Convert the input string from arcseconds to radians. More...

void	ParConvMasToRads (const CHAR in, void out)
	Convert the input string from milliarcsecs to radians. More...

void	ParConvInvArcsecsToInvRads (const CHAR in, void out)
	Convert the input string from 1/acrseconds to 1/radians. More...

void	ParConvDaysToSecs (const CHAR in, void out)
	Convert the input string from days to seconds. More...

void	ParConvKpcToMetres (const CHAR in, void out)
	Convert the input string from kiloparsecs to metres. More...

void	ParConvBinaryUnits (const CHAR in, void out)
	Convert the binary system parameter from a string to a double, but make the check (as performed by TEMPO2) that this is > 1e-7 then it's in units of 1e-12, so needs converting by that factor. More...

void	ParConvMJDToGPS (const CHAR in, void out)
	Convert the input string from a TT MJD value into a GPS time. More...

void	ParConvDegPerYrToRadPerSec (const CHAR in, void out)
	Convert the input string from degrees per year to radians per second. More...

void	ParConvSolarMassToKg (const CHAR in, void out)
	Convert the input string from solar masses to kilograms. More...

void	ParConvRAToRads (const CHAR in, void out)
	Convert a right ascension input string in the format "hh:mm:ss.s" into radians. More...

void	ParConvDecToRads (const CHAR in, void out)
	Convert a declination input string in the format "dd:mm:ss.s" into radians. More...

void	ParConvMicrosecToSec (const CHAR in, void out)
	Convert an input string from microseconds into seconds. More...

Data Structures
struct	hash_elem

struct	PulsarParam
	The PulsarParam list node structure. More...

struct	PulsarParameters
	The PulsarParameters structure to contain a set of pulsar parameters. More...

struct	BinaryPulsarParams
	A structure to contain all pulsar parameters and associated errors. More...

Enumerations
enum	{ CONVFLOAT = 0 , CONVINT , CONVSTRING , CONVHMS , CONVDMS , CONVMJD , CONVBINUNITS }

enum	PulsarParamType { PULSARTYPE_UINT4_t = 0 , PULSARTYPE_REAL8_t , PULSARTYPE_REAL8Vector_t , PULSARTYPE_string_t , PULSARTYPE_void_ptr_t }
	An enumerated type for denoting the type of a variable. More...

Macros
#define	DAYSTOSECS 86400.0 /* number of seconds in an SI day */

#define	DEFINE_CONV_FACTOR_FUNCTION(name, convfactor, type)

#define	NUM_PARS 132 /* number of allowed parameters */

#define	PULSAR_HASHTABLE_SIZE 512

#define	PULSAR_PARNAME_MAX 128

#define	GPS0MJD 44244.0 /* start of GPS time (MJD 44244) */

#define	TDT_TAI 32.184

#define	GPS_TDT (TDT_TAI + XLAL_EPOCH_GPS_TAI_UTC)

#define	LALPULSAR_TEMPO2_MTSUN_SI 4.925490947e-6 /* value of GMsun/c^3 used in TEMPO2 */

#define	LALPULSAR_TEMPO2_MSUN_SI (LALPULSAR_TEMPO2_MTSUN_SI * LAL_MPL_SI / LAL_TPL_SI) /* derived value of Msun */

Variables
size_t	PulsarTypeSize [5]

static const CHAR	a2A [256]
	Array for conversion from lowercase to uppercase. More...

	ParConversion

ParConversion	pc [NUM_PARS]
	Initialise conversion structure with most allowed TEMPO2 parameter names and conversion functions (convert all read in parameters to SI units where necessary). More...

size_t	PulsarTypeSize [5]

REAL8	XLALTTMJDtoGPS (REAL8 MJD)
	This function converts a MJD format time corrected to Terrestrial Time (TT) into an equivalent GPS time. More...

REAL8	XLALTDBMJDtoGPS (REAL8 MJD)
	If you have an MJD arrival time on the Earth then this will convert it to the equivalent GPS time in TDB (see Table 1 of Seidelmann and Fukushima, Astronomy & Astrophysics, 265, 833-838 (1992). More...

REAL8	XLALTCBMJDtoGPS (REAL8 MJD)
	If you have an MJD arrival time on the Earth then this will convert it to the equivalent GPS time in TCB (see Table 1 of Seidelmann and Fukushima, Astronomy & Astrophysics, 265, 833-838, 1992). More...

Error Codes
#define	READPULSARPARFILEH_ENULLOUTPUT 1

#define	READPULSARPARFILEH_MSGENULLOUTPUT "Output was Null"

Function Documentation

◆ strtoupper()

static void strtoupper ( CHAR * s )

static

Convert string to uppercase.

Definition at line 68 of file ReadPulsarParFile.c.

◆ new_elem()

static void * new_elem	(	const char *	name,
		PulsarParam *	itemPtr
	)

static

Definition at line 85 of file ReadPulsarParFile.c.

◆ del_elem()

static void del_elem ( void * elem )

static

Definition at line 91 of file ReadPulsarParFile.c.

◆ PulsarHash()

static UINT8 PulsarHash ( const void * elem )

static

Definition at line 99 of file ReadPulsarParFile.c.

◆ PulsarHashElemCmp()

static int PulsarHashElemCmp	(	const void *	elem1,
		const void *	elem2
	)

static

Definition at line 110 of file ReadPulsarParFile.c.

◆ PulsarGetParamItemSlow()

static PulsarParam * PulsarGetParamItemSlow	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

static

Get a pointer to a parameter of a given name from a PulsarParameters structure.

Note this function can only be used internally.

Definition at line 123 of file ReadPulsarParFile.c.

◆ PulsarGetParamItem()

static PulsarParam * PulsarGetParamItem	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

static

Get a pointer to a parameter of a given name from a PulsarParameters structure.

This function will return a pointer to the parameter. It will initially try and use the parameter's hash name, otherwise it will use PulsarGetParamItemSlow to loop through all parameters.

Note this function can only be used internally.

Definition at line 156 of file ReadPulsarParFile.c.

◆ PulsarGetParam()

void * PulsarGetParam	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Get the required parameter value from the PulsarParameters structure.

This function will return a void pointer to the parameter value. This should be cast into the required variable type once returned.

Definition at line 187 of file ReadPulsarParFile.c.

◆ PulsarGetParamType()

PulsarParamType PulsarGetParamType	(	const PulsarParameters *	pars,
		const char *	name
	)

Get the required parameter's type.

Definition at line 199 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8Param()

REAL8 PulsarGetREAL8Param	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a REAL8 parameter.

This function will call PulsarGetParam() for a REAL8 parameter and properly cast it for returning.

Definition at line 205 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8ParamOrZero()

REAL8 PulsarGetREAL8ParamOrZero	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a REAL8 parameter if it exists, otherwise return zero.

Definition at line 216 of file ReadPulsarParFile.c.

◆ PulsarGetUINT4Param()

UINT4 PulsarGetUINT4Param	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a UINT4 parameter.

This function will call PulsarGetParam() for a UINT4 parameter and properly cast it for returning.

Definition at line 223 of file ReadPulsarParFile.c.

◆ PulsarGetUINT4ParamOrZero()

UINT4 PulsarGetUINT4ParamOrZero	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a UINT4 parameter if it exists, otherwise return zero.

Definition at line 234 of file ReadPulsarParFile.c.

◆ PulsarGetStringParam()

const CHAR * PulsarGetStringParam	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a string parameter.

This function will call PulsarGetParam() for a string parameter and properly cast it for returning. The return value should be copied e.g. with CHAR *str = XLALStringDuplicate( PulsarGetStringParam(pars, "NAME") ); It also needs to be freed afterwards.

Definition at line 241 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8VectorParam()

const REAL8Vector * PulsarGetREAL8VectorParam	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a REAL8Vector parameter.

This function will call PulsarGetParam() for a REAL8Vector parameter and properly cast it for returning.

Definition at line 253 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8VectorParamIndividual()

REAL8 PulsarGetREAL8VectorParamIndividual	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return an individual REAL8 value from a REAL8Vector parameter.

This function will call PulsarGetParam() for a REAL8Vector parameter and then return a specific value from within the vector. The input name must be of the form e.g. FB1, which will get the REAL8Vector for the FB parameter and return the value from the 1 index.

Definition at line 264 of file ReadPulsarParFile.c.

◆ PulsarGetParamErr()

void * PulsarGetParamErr	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Get the required parameter error value from the PulsarParameters structure.

This function will return a void pointer to the parameter error value. The parameter error will be either a REAL8 or a REAL8Vector and should be cast accordingly once returned.

Definition at line 305 of file ReadPulsarParFile.c.

◆ PulsarGetParamFitFlag()

const UINT4 * PulsarGetParamFitFlag	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Get the fit flag array for a given parameter from the PulsarParameters structure.

This function will return a UINT4 array to the parameter fit flag.

Definition at line 317 of file ReadPulsarParFile.c.

◆ PulsarGetParamFitFlagAsVector()

const UINT4Vector * PulsarGetParamFitFlagAsVector	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Get the fit flag array for a given parameter from the PulsarParameters structure.

This function will return a UINT4Vector array to the parameter fit flag.

Definition at line 337 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8ParamErr()

REAL8 PulsarGetREAL8ParamErr	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a REAL8 parameter error value.

This function will call PulsarGetParamErr() for a REAL8 parameter and properly cast it for returning.

Definition at line 353 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8VectorParamErr()

const REAL8Vector * PulsarGetREAL8VectorParamErr	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return a REAL8Vector parameter error value.

This function will call PulsarGetParamErr() for a REAL8Vector parameter and properly cast it for returning.

Definition at line 370 of file ReadPulsarParFile.c.

◆ PulsarGetREAL8VectorParamErrIndividual()

REAL8 PulsarGetREAL8VectorParamErrIndividual	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Return an individual REAL8 value from a REAL8Vector parameter.

This function will call PulsarGetParam() for a REAL8Vector parameter's errors and then return a specific value from within the vector. The input name must be of the form e.g. FB1, which will get the REAL8Vector for the FB parameter and return the value from the 1 index.

Definition at line 387 of file ReadPulsarParFile.c.

◆ PulsarAddParam()

void PulsarAddParam	(	PulsarParameters *	pars,
		const CHAR *	name,
		void *	value,
		PulsarParamType	type
	)

Add a parameter and value to the PulsarParameters structure.

This function adds a new parameter, and associated value to the PulsarParameters structure. If the parameter already exists then the old value is replaced with the new value.

Definition at line 428 of file ReadPulsarParFile.c.

◆ PulsarAddREAL8Param()

void PulsarAddREAL8Param	(	PulsarParameters *	pars,
		const CHAR *	name,
		REAL8	value
	)

Add a REAL8 parameter to the PulsarParameters structure.

Definition at line 506 of file ReadPulsarParFile.c.

◆ PulsarAddUINT4Param()

void PulsarAddUINT4Param	(	PulsarParameters *	pars,
		const CHAR *	name,
		UINT4	value
	)

Add a UINT4 parameter to the PulsarParameters structure.

Definition at line 513 of file ReadPulsarParFile.c.

◆ PulsarAddREAL8VectorParam()

void PulsarAddREAL8VectorParam	(	PulsarParameters *	pars,
		const CHAR *	name,
		const REAL8Vector *	value
	)

Add a REAL8Vector parameter to the PulsarParameters structure.

Definition at line 520 of file ReadPulsarParFile.c.

◆ PulsarAddStringParam()

void PulsarAddStringParam	(	PulsarParameters *	pars,
		const CHAR *	name,
		const CHAR *	value
	)

Add a string parameter to the PulsarParameters structure.

Definition at line 530 of file ReadPulsarParFile.c.

◆ PulsarCheckParam()

int PulsarCheckParam	(	const PulsarParameters *	pars,
		const CHAR *	name
	)

Check for the existence of the parameter name in the PulsarParameters structure.

Definition at line 541 of file ReadPulsarParFile.c.

◆ PulsarClearParams()

void PulsarClearParams ( PulsarParameters * pars )

Free all the parameters from a PulsarParameters structure.

Definition at line 556 of file ReadPulsarParFile.c.

◆ PulsarRemoveParam()

void PulsarRemoveParam	(	PulsarParameters *	pars,
		const CHAR *	name
	)

Remove a given parameter from a PulsarParameters structure.

Definition at line 606 of file ReadPulsarParFile.c.

◆ PulsarSetParam()

void PulsarSetParam	(	PulsarParameters *	pars,
		const CHAR *	name,
		const void *	value
	)

Set the value of a parameter in the PulsarParameters structure.

Set the value of the parameter given by name in the PulsarParameters structure. The parameter must already exist in the structure, otherwise it should be added using PulsarAddParam().

Definition at line 671 of file ReadPulsarParFile.c.

◆ PulsarSetParamErr()

void PulsarSetParamErr	(	PulsarParameters *	pars,
		const CHAR *	name,
		void *	value,
		const UINT4 *	fitFlag,
		UINT4	len
	)

Set the value of the error of a parameter in the PulsarParameters structure.

Set the value of the error on the parameter given by name in the PulsarParameters structure. The parameter must already exist in the structure, otherwise it should be added using PulsarAddParam(). If the .par file contains a 1 before the error value (because that parameter has been included in the TEMPO(2) fitting procedure) then that must be input as the fit flag (this can be a vector for e.g. FB values with multiple parameters, in which case nfits will be the number of values in that vector).

Definition at line 689 of file ReadPulsarParFile.c.

◆ PulsarSetREAL8ParamErr()

void PulsarSetREAL8ParamErr	(	PulsarParameters *	pars,
		const CHAR *	name,
		REAL8	value,
		UINT4	fitFlag
	)

Set the error value for a REAL8 parameter.

Definition at line 731 of file ReadPulsarParFile.c.

◆ PulsarSetREAL8VectorParamErr()

void PulsarSetREAL8VectorParamErr	(	PulsarParameters *	pars,
		const CHAR *	name,
		const REAL8Vector *	value,
		const UINT4 *	fitFlag
	)

Set the error values for a REAL8Vector parameter.

Definition at line 738 of file ReadPulsarParFile.c.

◆ PulsarFreeParams()

void PulsarFreeParams ( PulsarParameters * pars )

Function to free memory from pulsar parameters.

Definition at line 749 of file ReadPulsarParFile.c.

◆ PulsarCopyParams()

void PulsarCopyParams	(	PulsarParameters *	origin,
		PulsarParameters *	target
	)

Function to copy a PulsarParameters structure.

Definition at line 764 of file ReadPulsarParFile.c.

◆ DEFINE_CONV_FACTOR_FUNCTION()

DEFINE_CONV_FACTOR_FUNCTION	(	ToFloat	,
		1.	,
		CONVFLOAT
	)

A strcuture to contain all possible pulsar parameters that can be read in from a par file, and define the conversion function and type used for each.

Parameter name

Conversion function from string to required value

Conversion function for error from string to value

Parameter type

Definition at line 902 of file ReadPulsarParFile.c.

◆ ParseParLine()

static INT4 ParseParLine	(	PulsarParameters *	par,
		const CHAR *	name,
		FILE *	fp
	)

static

Parse a single line from a pulsar parameter file.

This will parse a line from the TEMPO-style pulsar parameter file containing the parameter given by name. The parameter will be added to the par structure.

This function can only be used internally.

Definition at line 1112 of file ReadPulsarParFile.c.

◆ XLALReadTEMPOParFile()

PulsarParameters * XLALReadTEMPOParFile ( const CHAR * pulsarAndPath )

Read in the parameters from a TEMPO(2) parameter file into a PulsarParameters structure.

This function will read in a TEMPO(2) parameter file into a PulsarParameters structure. The structure of this function is similar to those in the TEMPO2 code readParfile.C.

Parameters

pulsarAndPath [in] The path to the pulsar parameter file

Definition at line 1446 of file ReadPulsarParFile.c.

◆ PrintPulsarParameters()

void PrintPulsarParameters ( BinaryPulsarParams params )

function to print out all the pulsar parameters read in from a par file

Definition at line 1518 of file ReadPulsarParFile.c.

◆ XLALReadTEMPOCorFile()

LALStringVector * XLALReadTEMPOCorFile	(	REAL8Array *	cormat,
		CHAR *	corfile
	)

This function will read in a TEMPO-style parameter correlation matrix.

This function will read in a TEMPO-style parameter correlation matrix file, which contains the correlations between parameters as fit by TEMPO. An example the format would be:

     RA     DEC    F0
RA   1.000
DEC  0.954  1.000
F0   -0.007 0.124  1.000

In the output all parameter names will sometimes be converted to a more convenient naming convention. If non-diagonal parameter correlation values are +/-1 then they will be converted to be +/-0.99999 to avoid some problems of the matrix becoming singular. The output matrix will have both the upper and lower triangle completed.

Parameters

cormat	[out] A REAL8 array into which the correlation matrix will be output
corfile	[in] A string containing the path and filename of the TEMPO-style correlation matrix file

Definition at line 1584 of file ReadPulsarParFile.c.

◆ XLALTTMJDtoGPS()

REAL8 XLALTTMJDtoGPS ( REAL8 MJD )

This function converts a MJD format time corrected to Terrestrial Time (TT) into an equivalent GPS time.

Functions for converting times given in Terrestrial time TT, TDB, or TCB in MJD to times in GPS - this is important for epochs given in .par files which are in TDB(MJD).

TT and GPS are different by a factor of 51.184 secs, this is just the historical factor of 32.184 secs between TT and TAI (International Atomic Time) and the other 19 seconds come from the leap seonds added between the TAI and UTC up to the point of definition of GPS time at UTC 01/01/1980.

Definition at line 1714 of file ReadPulsarParFile.c.

◆ XLALTDBMJDtoGPS()

REAL8 XLALTDBMJDtoGPS ( REAL8 MJD )

If you have an MJD arrival time on the Earth then this will convert it to the equivalent GPS time in TDB (see Table 1 of Seidelmann and Fukushima, Astronomy & Astrophysics, 265, 833-838 (1992).

Note that XLALBarycenter performs these TDBtoTT corrections (i.e. the Einstein delay) when correcting a GPS time on the Earth to TDB. Also, for TEMPO produced pulsar epochs given in MJD these are already in the TDB system and an equivalent GPS time in the TDB can be calculated just using XLALTTMJDtoGPS.

Definition at line 1735 of file ReadPulsarParFile.c.

◆ XLALTCBMJDtoGPS()

REAL8 XLALTCBMJDtoGPS ( REAL8 MJD )

If you have an MJD arrival time on the Earth then this will convert it to the equivalent GPS time in TCB (see Table 1 of Seidelmann and Fukushima, Astronomy & Astrophysics, 265, 833-838, 1992).

Note that for default TEMPO2 produced pulsar epochs given in MJD these are already in the TCB system and an equivalent GPS time in the TCB can be calculated just using XLALTTMJDtoGPS.

Definition at line 1779 of file ReadPulsarParFile.c.

◆ ParConvToFloat()

void ParConvToFloat	(	const CHAR *	in,
		void *	out
	)

Conversion functions from units used in TEMPO parameter files into SI units.

Convert the input string into a double precision floating point number

◆ ParConvToInt()

void ParConvToInt	(	const CHAR *	in,
		void *	out
	)

Convert the input string into a unsigned integer number.

◆ ParConvToString()

void ParConvToString	(	const CHAR *	in,
		void *	out
	)

Copy the input string into the output pointer.

◆ ParConvDegsToRads()

void ParConvDegsToRads	(	const CHAR *	in,
		void *	out
	)

Convert the input string from degrees to radians.

◆ ParConvMasPerYrToRadPerSec()

void ParConvMasPerYrToRadPerSec	(	const CHAR *	in,
		void *	out
	)

Convert the input string from milliarcsecs per year to radians per second.

◆ ParConvSecsToRads()

void ParConvSecsToRads	(	const CHAR *	in,
		void *	out
	)

Convert the input string from seconds to radians.

◆ ParConvArcsecsToRads()

void ParConvArcsecsToRads	(	const CHAR *	in,
		void *	out
	)

Convert the input string from arcseconds to radians.

◆ ParConvMasToRads()

void ParConvMasToRads	(	const CHAR *	in,
		void *	out
	)

Convert the input string from milliarcsecs to radians.

◆ ParConvInvArcsecsToInvRads()

void ParConvInvArcsecsToInvRads	(	const CHAR *	in,
		void *	out
	)

Convert the input string from 1/acrseconds to 1/radians.

◆ ParConvDaysToSecs()

void ParConvDaysToSecs	(	const CHAR *	in,
		void *	out
	)

Convert the input string from days to seconds.

◆ ParConvKpcToMetres()

void ParConvKpcToMetres	(	const CHAR *	in,
		void *	out
	)

Convert the input string from kiloparsecs to metres.

◆ ParConvBinaryUnits()

void ParConvBinaryUnits	(	const CHAR *	in,
		void *	out
	)

Convert the binary system parameter from a string to a double, but make the check (as performed by TEMPO2) that this is > 1e-7 then it's in units of 1e-12, so needs converting by that factor.

It also checks if the number is too large (> 10000) and if so sets to to zero.

◆ ParConvMJDToGPS()

void ParConvMJDToGPS	(	const CHAR *	in,
		void *	out
	)

Convert the input string from a TT MJD value into a GPS time.

◆ ParConvDegPerYrToRadPerSec()

void ParConvDegPerYrToRadPerSec	(	const CHAR *	in,
		void *	out
	)

Convert the input string from degrees per year to radians per second.

◆ ParConvSolarMassToKg()

void ParConvSolarMassToKg	(	const CHAR *	in,
		void *	out
	)

Convert the input string from solar masses to kilograms.

◆ ParConvRAToRads()

void ParConvRAToRads	(	const CHAR *	in,
		void *	out
	)

Convert a right ascension input string in the format "hh:mm:ss.s" into radians.

◆ ParConvDecToRads()

void ParConvDecToRads	(	const CHAR *	in,
		void *	out
	)

Convert a declination input string in the format "dd:mm:ss.s" into radians.

◆ ParConvMicrosecToSec()

void ParConvMicrosecToSec	(	const CHAR *	in,
		void *	out
	)

Convert an input string from microseconds into seconds.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
CONVFLOAT
CONVINT
CONVSTRING
CONVHMS
CONVDMS
CONVMJD
CONVBINUNITS

Definition at line 850 of file ReadPulsarParFile.c.

◆ PulsarParamType

enum PulsarParamType

An enumerated type for denoting the type of a variable.

Several LAL types are supported.

Enumerator
PULSARTYPE_UINT4_t
PULSARTYPE_REAL8_t
PULSARTYPE_REAL8Vector_t
PULSARTYPE_string_t
PULSARTYPE_void_ptr_t

Definition at line 84 of file ReadPulsarParFile.h.

Macro Definition Documentation

◆ DAYSTOSECS

#define DAYSTOSECS 86400.0 /* number of seconds in an SI day */

Definition at line 47 of file ReadPulsarParFile.c.

◆ DEFINE_CONV_FACTOR_FUNCTION

#define DEFINE_CONV_FACTOR_FUNCTION	(	name,
		convfactor,
		type
	)

Definition at line 861 of file ReadPulsarParFile.c.

◆ NUM_PARS

#define NUM_PARS 132 /* number of allowed parameters */

Definition at line 933 of file ReadPulsarParFile.c.

◆ READPULSARPARFILEH_ENULLOUTPUT

#define READPULSARPARFILEH_ENULLOUTPUT 1

Definition at line 63 of file ReadPulsarParFile.h.

◆ READPULSARPARFILEH_MSGENULLOUTPUT

#define READPULSARPARFILEH_MSGENULLOUTPUT "Output was Null"

Definition at line 65 of file ReadPulsarParFile.h.

◆ PULSAR_HASHTABLE_SIZE

#define PULSAR_HASHTABLE_SIZE 512

Definition at line 68 of file ReadPulsarParFile.h.

◆ PULSAR_PARNAME_MAX

#define PULSAR_PARNAME_MAX 128

Definition at line 69 of file ReadPulsarParFile.h.

◆ GPS0MJD

#define GPS0MJD 44244.0 /* start of GPS time (MJD 44244) */

Definition at line 71 of file ReadPulsarParFile.h.

◆ TDT_TAI

#define TDT_TAI 32.184

Definition at line 74 of file ReadPulsarParFile.h.

◆ GPS_TDT

#define GPS_TDT (TDT_TAI + XLAL_EPOCH_GPS_TAI_UTC)

Definition at line 76 of file ReadPulsarParFile.h.

◆ LALPULSAR_TEMPO2_MTSUN_SI

#define LALPULSAR_TEMPO2_MTSUN_SI 4.925490947e-6 /* value of GMsun/c^3 used in TEMPO2 */

Definition at line 80 of file ReadPulsarParFile.h.

◆ LALPULSAR_TEMPO2_MSUN_SI

#define LALPULSAR_TEMPO2_MSUN_SI (LALPULSAR_TEMPO2_MTSUN_SI * LAL_MPL_SI / LAL_TPL_SI) /* derived value of Msun */

Definition at line 81 of file ReadPulsarParFile.h.

Variable Documentation

◆ PulsarTypeSize [1/2]

size_t PulsarTypeSize[5]

Initial value:

= {
  sizeof( UINT4 ),
  sizeof( REAL8 ),
  sizeof( REAL8Vector * ),
  sizeof( CHAR ) *PULSAR_PARNAME_MAX,
  sizeof( void * )
}

Definition at line 49 of file ReadPulsarParFile.c.

◆ a2A

const CHAR a2A[256]

static

Initial value:

= {
  ['a'] = 'A', ['b'] = 'B', ['c'] = 'C', ['d'] = 'D', ['e'] = 'E', ['f'] = 'F', ['g'] = 'G', ['h'] = 'H',
  ['i'] = 'I', ['j'] = 'J', ['k'] = 'K', ['l'] = 'L', ['m'] = 'M', ['n'] = 'N', ['o'] = 'O', ['p'] = 'P',
  ['q'] = 'Q', ['r'] = 'R', ['s'] = 'S', ['t'] = 'T', ['u'] = 'U', ['v'] = 'V', ['w'] = 'W', ['x'] = 'X',
  ['y'] = 'Y', ['z'] = 'Z'
}

Array for conversion from lowercase to uppercase.

Definition at line 59 of file ReadPulsarParFile.c.

◆ ParConversion

ParConversion

Definition at line 930 of file ReadPulsarParFile.c.

◆ pc

ParConversion pc[NUM_PARS]

Initialise conversion structure with most allowed TEMPO2 parameter names and conversion functions (convert all read in parameters to SI units where necessary).

See http://arxiv.org/abs/astro-ph/0603381 and http://arxiv.org/abs/astro-ph/0603381 for parameter definitions.

If requiring a new parameter to be read in in should be added to this structure and NUM_PARS should be incremented.

Definition at line 942 of file ReadPulsarParFile.c.

◆ PulsarTypeSize [2/2]

size_t PulsarTypeSize[5]

extern

Definition at line 49 of file ReadPulsarParFile.c.

Detailed Description

Prototypes

Data Structures

Enumerations

Macros

Variables

Error Codes

Function Documentation

◆ strtoupper()

◆ new_elem()

◆ del_elem()

◆ PulsarHash()

◆ PulsarHashElemCmp()

◆ PulsarGetParamItemSlow()

◆ PulsarGetParamItem()

◆ PulsarGetParam()

◆ PulsarGetParamType()

◆ PulsarGetREAL8Param()

◆ PulsarGetREAL8ParamOrZero()

◆ PulsarGetUINT4Param()

◆ PulsarGetUINT4ParamOrZero()

◆ PulsarGetStringParam()

◆ PulsarGetREAL8VectorParam()

◆ PulsarGetREAL8VectorParamIndividual()

◆ PulsarGetParamErr()

◆ PulsarGetParamFitFlag()

◆ PulsarGetParamFitFlagAsVector()

◆ PulsarGetREAL8ParamErr()

◆ PulsarGetREAL8VectorParamErr()

◆ PulsarGetREAL8VectorParamErrIndividual()

◆ PulsarAddParam()

◆ PulsarAddREAL8Param()

◆ PulsarAddUINT4Param()

◆ PulsarAddREAL8VectorParam()

◆ PulsarAddStringParam()

◆ PulsarCheckParam()

◆ PulsarClearParams()

◆ PulsarRemoveParam()

◆ PulsarSetParam()

◆ PulsarSetParamErr()

◆ PulsarSetREAL8ParamErr()

◆ PulsarSetREAL8VectorParamErr()

◆ PulsarFreeParams()

◆ PulsarCopyParams()

◆ DEFINE_CONV_FACTOR_FUNCTION()

◆ ParseParLine()

◆ XLALReadTEMPOParFile()

◆ PrintPulsarParameters()

◆ XLALReadTEMPOCorFile()

◆ XLALTTMJDtoGPS()

◆ XLALTDBMJDtoGPS()

◆ XLALTCBMJDtoGPS()

◆ ParConvToFloat()

◆ ParConvToInt()

◆ ParConvToString()

◆ ParConvDegsToRads()

◆ ParConvMasPerYrToRadPerSec()

◆ ParConvSecsToRads()

◆ ParConvArcsecsToRads()

◆ ParConvMasToRads()

◆ ParConvInvArcsecsToInvRads()

◆ ParConvDaysToSecs()

◆ ParConvKpcToMetres()

◆ ParConvBinaryUnits()

◆ ParConvMJDToGPS()

◆ ParConvDegPerYrToRadPerSec()

◆ ParConvSolarMassToKg()

◆ ParConvRAToRads()

◆ ParConvDecToRads()

◆ ParConvMicrosecToSec()

Enumeration Type Documentation

◆ anonymous enum

◆ PulsarParamType

Macro Definition Documentation

◆ DAYSTOSECS

◆ DEFINE_CONV_FACTOR_FUNCTION

◆ NUM_PARS

◆ READPULSARPARFILEH_ENULLOUTPUT

◆ READPULSARPARFILEH_MSGENULLOUTPUT

◆ PULSAR_HASHTABLE_SIZE