Search:

# Chapter 2: Required files

Tempo2 requires certain files in order to run correctly. Most of these files are provided with the download and are discussed in the following sections (sections 2.1 to 2.5). Tempo2 also requires a parameter file containing the pulsar timing model and a set of pulsar arrival times. The formats for these files are discussed in chapters 3 and 4 respectively.

## 2.1 Clock correction files

Times of arrival provided to tempo2 are recorded against local observatory clocks. These times differ from those recorded against a uniform clock, firstly because observatory clocks are typically maintained in approximate synchrony with Coordinated Universal Time (UTC), which itself is not uniform, and secondly because they deviate from ideal UTC owing to deviations in uniformity in the underlying frequency standard (usually a hydrogen maser). The ultimate aim of the clock correction process is to transform all site arrival times to a chosen realisation of TT (terrestrial time), which in an ideal realisation is a uniform clock ticking SI seconds on the geoid. By default this is TT(TAI), which (since 1971) differs from UTC by a constant offset plus an integral number of leap seconds. Alternative realisations of TT can be specified using the CLOCK keyword in the parameter file.

The clock correction process proceeds entirely on the basis of linear interpolation of user-supplied tabulations of the difference between named pairs of clocks, as a function of Modified Julian Day (MJD; the fame in which the MJD is measured is not specified; it is assumed that clock offsets and drift rates are small enough that if $t^\prime = t + f(t)$ then $t \sim t^\prime - f(t^\prime)$.) These files reside in the directory $TEMPO2/clock. Lines beginning with the hash character (#) are treated as comments. The first line must be a comment specifying the name of the clock to convert from, the name of the clock to convert to, and an optional "badness" value (which defaults to 1). For example, the following specifies that the values in the file can be added to times measured against the Parkes clock ("UTC(PKS)") to transform them to the frame of the Global Positioning System (GPS) clock ("UTC(GPS)"). # UTC(PKS) UTC(GPS) 10 Non-comment lines consist of a sequence of pairs of MJDs and offsets (in seconds) specifying the difference between the second and first clocks as a function of date. For example: 50844.72917 -7.49068e-07 50845.77083 -7.47637e-07 50846.81250 -7.46650e-07 ... The spacing of the dates need not be any specific value, or even be regular. For most purposes roughly daily values are suitable. All files ending in .clk in$TEMPO2/clock are read by tempo2 when it starts executing. Then, given a TOA to transform, it obtains the name of the clock against which it was measured based upon the name specified in the observatory database (see below). Given the source and destination clocks, tempo2 then chooses a selection of clock correction tables (from .clk files) to use for the transformation. This is firstly attempted by consulting the list of pre-defined transformation paths, which are defined using CLK_CORR_CHAIN entries in the parameter file. For example, the following tells tempo2 to convert from UTC(PKS) to TT(TAI) using tables defined in pks2gps.clk, gps2utc.clk, utc2tai.clk and tai2tt_tai.clk:

CLK_CORR_CHAIN pks2gps.clk gps2utc.clk utc2tai.clk tai2tt_tai.clk

This parameter may be specified multiple times. Tempo2 will attempt to apply each path in the order in which they were specified (which may fail if the MJD of the TOA is outside the range of component tables).

If no applicable pre-defined paths are found, tempo2 finds the "best" possible path using all of the available tables. Here "best" means the path for which the sum of badness values is minimised. Tie-breaking is arbitrary. This path is then appended to the global list of pre-defined paths. Since tempo2 always checks this list before attempting automatic path construction, subsequent transformations will always use this path if it is applicable, even if the MJDs of some TOAs would have allowed for a "better" path. Caution is therefore advised in using the automatic path construction feature when multiple paths exist.

### 2.1.1 Updating clock corrections

The distribution of tempo2 includes several useful files containing corrections based on the BIPM's Circular T (offsets between UTC and its various realisations, as well as the GPS clock) and the IERS Bulletin C (announcing leap seconds). A suite of ancillary software is available on this website which provides, among other things, a means for parsing Circular T to update the relevant clock correction files (update_clkcorr). This program can also parse clock monitoring data from the Parkes Observatory. Interested parties are invited to contribute code for the parsing of clock data from other sources.

## 2.2 Earth orientation parameters

To compute the Roemer delay, the position of the observatory must be known. This depends not only on the Earth's orbit, but on the Earth's orientation and rotation. The necessary parameters are obtained by interpolation of the "C05" series of Earth Orientation Parameters (EOPs) from the IERS. The file $TEMPO2/earth/README specifies the web address for downloading the latest EOPs. The user may optionally select to emulate the algorithm in tempo1 (which neglects polar motion and uses an out-of-date precession/nutation model) for transforming the observatory coordinates to the celestial frame, using the T2C_METHOD parameter; in this case$TEMPO2/clock/ut1.dat (in the same format as the corresponding file for tempo) is used.

## 2.3 Time ephemeris

The pulse arrival times at the observatory are transformed to the arrival time at the solar system barycentre (SSB). In this transformation the Einstein delay, which described the combined effect of gravitational redshift and time dilation due to the motion of the Earth and other bodies, must be taken into account. This transformation converts the site arrival time from TT to a coordinate time at the SSB, known as Barycentric Coordinate Time (TCB). Optionally, for backward compatibility with tempo1 the user may also choose to use a scaled version of this frame in which the mean drift relative to TT is divided out: this is nominally (but incorrectly; see the tempo2 paper II) referred to as TDB. This is accomplished by specifying "UNITS TDB" in the parameter file.

The Einstein delay is computed using a polynomial approximation to the numerical evaluation of the time dilation integral as provided in Irwin & Fukushima (1999). It lives in $TEMPO2/ephemeris/TIMEEPH_short.te405. For reproducing results obtained with tempo1, the user may also choose to use the Fairhead & Bretagnon (1990) version of this integral (stored at$TEMPO2/ephemeris/TDB.1950.2050) by specifying "TIMEEPH FB90" in the pulsar parameter file.

## 2.4 Planetary ephemeris

In order to correct that arrival time to the solar system's barycentre, tempo2 requires a solar system ephemeris. By default the JPL ephemeris DE200 is chosen. Different JPL ephemerides may be selected using the EPHEM_FILE command in the parameter file. For example,

EPHEM_FILE /pulsar/psr/runtime/tempo2/tempo_ephem/DE405.1950.2050

would select the DE405 JPL ephemeris. If the full-path is defined from $TEMPO2/ephemeris then the DE405 ephemeris could be selected from EPHEM DE405 In order to install the new DE421 ephemeris the following routine was carried out: 1. ftp ssd.jpl.nasa.gov 2. cd pub/eph/planets/ 3. get the correct ascii files 4. also get /pub/eph/planets/fortran/asc2eph.f 5. emacs asc2eph.f and uncomment the PARAMETER (NRECL = 4) line (also can set start and end dates if required - in JD) 6. f77 -o asc2eph asc2eph.f 7. cat header.421 ascp1900.421 | asc2eph 8. This produces the binary file JPLEPH that can be moved to, e.g., DE421.1950.2050 ## 2.5 Observatory definitions It is necessary for tempo2 to know the coordinates of the observatory. In the original tempo1, a file (obsys.dat) was used that contained the coordinates of each observatory and a single-character identifying code. This code was used in the arrival time file. Unfortunately, different users used different codes for the same observatory and therefore the arrival time files were not transferable between different installations of tempo1. To avoid this, tempo2 provides a read-only database of observatories, each identified by a short, non-cryptic mnemonic. This resides in$TEMPO2/observatory/observatories.dat. In addition, for backwards compatability, further definitions can be placed in extra files: tempo2 parses every file in \$TEMPO2/observatory. Each line should contain 5-6 whitespace-separated parameters. These are, in order, the x, y and z geocentric coordinates (in metres), a one-word name for the observatory, a few-character mnemonic and optionally the name of the clock associated with the observatory (used to refer to the relevant clock-correction tables). If not supplied, the clock name is constructed as UTC(xxx) where xxx is the observatory mnemonic.

For full accuracy, observatory coordinates should be specified in the International Terrestrial Reference System. Geodeteic coordinates (as optionally used by tempo1, given as latitude and longitude in degrees in the form dddmmss.ss and height in metres) may be specified, in which case tempo2 will detect this and convert them to the ITRF on the assumption that they refer to the GRS80 geoid. The converted coordinates are displayed and execution is halted for the user to add the converted coordinates to the observatories database. The current observatory list is given below in Table 2.1.

Table 2.1: Observatory details

 x y z Mnemonic Clock 882589.65 -4924872.32 3943729.348 GBT gbt -4752329.7000 2790505.9340 -3200483.7470 NARRABRI atca 2390490.0 -5564764.0 1994727.0 ARECIBO ao -228310.702 4631922.905 4367064.059 NANSHAN nanshan -4460892.6 2682358.9 -3674756.0 DSS_43 tid43 -4554231.5 2816759.1 -3454036.3 PARKES pks 3822252.643 -153995.683 5086051.443 JODRELL jb -1601192. -5041981.4 3554871.4 VLA vla 4324165.81 165927.11 4670132.83 NANCAY ncy 4033949.5 486989.4 4900430.8 EFFELSBERG eff 3822252.643 -153995.683 5086051.443 JODRELLM4 jbm4 881856.58 -4925311.86 3943459.70 GB300 gb300 882872.57 -4924552.73 3944154.92 GB140 gb140 882315.33 -4925191.41 3943414.05 GB853 gb853 5327021.651 -1719555.576 3051967.932 LA_PALMA lap -3950077.96 2522377.31 -4311667.52 HOBART hob 383395.727 -173759.585 5077751.313 MKIII j 3817176.557 -162921.170 5089462.046 TABLEY k 3828714.504 -169458.987 5080647.749 DARNHALL l 3859711.492 -201995.082 5056134.285 KNOCKIN m 3923069.135 -146804.404 5009320.570 DEFFORD n 3822294.825 -153862.275 5085987.071 JB_42ft jb42 0.0 1.0 0.0 COE coe