Search:

# Chapter 1: Introduction, installation and basic tempo2 usage

## 1.1 Introduction

Tempo2 is a new version of the pulsar timing software. An overview of the software is provided in Hobbs, Edwards & Manchester (2006). A second paper provides mathematical details of the algorithms used in the software (Edwards, Hobbs & Manchester (2006)). A third paper is in preparation and will describe how tempo2 can be used to simulate the effects of gravitational waves on pulsar timing residuals. A summary of tempo2's basic features can also be found in Hobbs, Edwards & Manchester (in press CHJAA).

## 1.2 Obtaining and installing tempo2

The tempo2 software and documentation can be obtained from this wiki (http://www.atnf.csiro.au/research/pulsar/tempo2). Click on the "Download tempo2" option to download the software to your local machine. This software requires compilation before it will run. Up-to-date installation instructions are available from the download section on this site and also in a README file available with the download. Note: tempo2 makes heavy use of "long double" precision in its calculations. Most compiler/architecture combinations support long doubles of 80 or 128 bits in size, which is sufficient. Tempo2 has been successfully tested under Linux-gcc/x86, Solaris/SPARC and Mac OS 10.4-gcc/PowerPC. Unfortunately, some systems only provide 64-bit long doubles (i.e. identical to a standard "double"); these include Mac OS 10.3.9 and earlier and many Windows compilers. Tempo2 will not install correctly on such machines.

## 1.3 A simple example of using tempo2

The tempo2 download page provides a set of example files for use to test the software. psr1.par contains the catalogued parameters for PSR J0437-4715 in standard tempo2 format. psr1.tim contains a set of simulated observations of this pulsar over a 10yr period with an rms residual of 100 ns. Running

 tempo2 -f psr1.par psr1.tim


should first provide some information about clock correction files and also:

 Results for PSR J0437-4715

RMS pre-fit residual = 0.096 (us), RMS post-fit residual = 0.096 (us)
Number of points in fit = 367

PARAMETER       Pre-fit                   Post-fit                  Uncertainty   Difference   Fit
---------------------------------------------------------------------------------------------------
RAJ (rad)       1.20978853473707          1.20978853473707          0             0             N
RAJ (hms)       04:37:15.7865145          04:37:15.7865145          0             0
DECJ (rad)      -0.824709094464799        -0.824709094464799        0             0             N
DECJ (dms)      -47:15:08.46158           -47:15:08.46158           0             0
F0 (s^-1)       173.687946306032          173.687946306032          0             0             N
F1 (s^-2)       -1.7283139464043e-15      -1.7283139464043e-15      0             0             N
PEPOCH (MJD)    51194.0001248168          51194.0001248168          0             0             N
POSEPOCH (MJD)  51194.0001248168          51194.0001248168          0             0             N
DMEPOCH (MJD)   51194                     51194                     0             0             N
DM (cm^-3 pc)   2.64690012312213          2.64690012312213          0             0             N
PMRA (mas/yr)   121.43799811708           121.43799811708           0             0             N
PMDEC (mas/yr)  -71.4379988923397         -71.4379988923397         0             0             N
PX (mas)        7.19                      7.19                      0             0             N
SINI            0.6788                    0.6788                    0             0             N
PB (d)          5.74104608901605          5.74104608901605          0             0             N
T0 (MJD)        51194.6240248265          51194.6240248265          0             0             N
A1 (lt-s)       3.36669162220122          3.36669162220122          0             0             N
OM (deg)        1.2                       1.2                       0             0             N
ECC             1.9186e-05                1.9186e-05                0             0             N
PBDOT (10^-12)  3.64                      3.64                      0             0             N
OMDOT (deg/yr)  0.0159999997519168        0.0159999997519168        0             0             N
M2              0.236                     0.236                     0             0             N
START (MJD)     50640.9281162413          49350.5129309451          0             -1290.4       N
FINISH (MJD)    52088.8971386924          53000.5197060478          0             911.62        N
TRACK (MJD)     0                         0                         0             0             N
TZRMJD          51204.6438924841          51204.6438924841          0             0             N
TZRFRQ (MHz)    1413.39997808495          1413.39997808495          0             0             N
---------------------------------------------------------------------------------------------------
Binary model: DD
Mass function                  = 0.001243113190  +- 0.000000000000 solar masses
Minimum companion mass         = 0.1403 solar masses
Median companion mass          = 0.1637 solar masses
Maximum companion mass         = 0.3493 solar masses
MTOT derived from sin i and m2 = 1.8186068413766
Inclination angle (deg)        = 42.74994182955 (+ 0 - 0)


Approximately 4 lines of extra output may be produced with the newest versions of tempo2, but this is the gist of it.

A second parameter file, psr1_2.par, is similar to psr1.par used above, except that the parameter values have been changed slightly from their true values. As above, running

 tempo2 -f psr1_2.par psr1.tim


should produce

 Results for PSR J0437-4715

RMS pre-fit residual = 6.895 (us), RMS post-fit residual = 0.096 (us)
Number of points in fit = 367

PARAMETER       Pre-fit                   Post-fit                  Uncertainty   Difference   Fit
---------------------------------------------------------------------------------------------------
RAJ (rad)       1.2097885336826           1.20978853474746          2.1206e-11    1.0649e-09    Y
RAJ (hms)       04:37:15.7865              04:37:15.7865146         2.916e-07     1.4643e-05
DECJ (rad)      -0.824709094076948        -0.824709094473468        1.5157e-11    -3.9652e-10   Y
DECJ (dms)      -47:15:08.4615            -47:15:08.46158           3.1264e-06    -8.1788e-05
F0 (s^-1)       173.68794630603           173.687946306032          9.5579e-15    2.3306e-12    Y
F1 (s^-2)       -1.728e-15                -1.72831367406148e-15     2.3325e-22    -3.1367e-19   Y
PEPOCH (MJD)    51194.0001248168          51194.0001248168          0             0             N
POSEPOCH (MJD)  51194.0001248168          51194.0001248168          0             0             N
DMEPOCH (MJD)   51194                     51194                     0             0             N
DM (cm^-3 pc)   2.64690012312213          2.64690012312213          0             0             N
PMRA (mas/yr)   121.43799811708           121.43799811708           0             0             N
PMDEC (mas/yr)  -71.4379988923397         -71.4379988923397         0             0             N
PX (mas)        7.19                      7.19                      0             0             N
SINI            0.6788                    0.6788                    0             0             N
PB (d)          5.741046089               5.74104608900813          1.0437e-11    8.1286e-12    Y
T0 (MJD)        51194.6240248265          51194.6240248265          0             0             N
A1 (lt-s)       3.36669162220122          3.36669162220122          0             0             N
OM (deg)        1.2                       1.2                       0             0             N
ECC             1.9186e-05                1.9186e-05                0             0             N
PBDOT (10^-12)  3.64                      3.64                      0             0             N
OMDOT (deg/yr)  0.0159999997519168        0.0159999997519168        0             0             N
M2              0.236                     0.236                     0             0             N
START (MJD)     50640.9281162413          49350.5129309451          0             -1290.4       N
FINISH (MJD)    52088.8971386924          53000.5197060478          0             911.62        N
TRACK (MJD)     0                         0                         0             0             N
TZRMJD          51204.6438924841          51204.6438924841          0             0             N
TZRFRQ (MHz)    1413.39997808495          1413.39997808495          0             0             N
---------------------------------------------------------------------------------------------------
Binary model: DD
Mass function                  = 0.001243113190  +- 0.000000047151 solar masses
Minimum companion mass         = 0.1403 solar masses
Median companion mass          = 0.1637 solar masses
Maximum companion mass         = 0.3493 solar masses
MTOT derived from sin i and m2 = 1.818606841374
Inclination angle (deg)        = 42.74994182955 (+ 0 - 0)


The residuals can be inspected using

 tempo2 -gr plk -f psr1_2.par psr1.tim


which should produce a plot of the pre-fit residuals as shown in Figure 1.1a. Pressing '2' on the plot will show the post-fit residuals (Figure 1.1b)

Figure 1.1: a) pre-fit timing residuals for the test data-set and b) post-fit timing residuals.

# 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 # Chapter 3: The parameter files ## 3.1 The basic timing model parameters The parameter files (that contain the pulsar timing model and various instructions for the tempo2 fitting routines) have the same form as in the earlier tempo implementation. Each of the pulsar parameters has a label, a value and may have an uncertainty on the value and a flag indicating whether tempo2 should fit for this parameter or whether the parameter should be held constant (0 = default = hold constant; 1 = fit). The parameters labels are described in Table 3.1 at the bottom of this page. An example of a parameter file for PSR J0437-4715 taken from the ATNF pulsar catalogue (by selecting the ephemeris option):  PSRJ J0437-4715 RAJ 04:37:15.7865145 1 7.000e-07 DECJ -47:15:08.461584 1 8.000e-06 DM 2.6469 1.000e-04 PEPOCH 51194.000 F0 173.6879489990983 1 3.000e-13 F1 -1.728314E-15 1 1.600e-20 PMRA 121.438 6.000e-03 PMDEC -71.438 7.000e-03 BINARY DD PB 5.741046 1 3.000e-06 ECC 1.9186E-5 1 5.000e-09 A1 3.36669157 1 1.400e-07 T0 51194.6239 1 8.000e-04 OM 1.20 1 5.000e-02 OMDOT 0.016 1.000e-02 START 50640.928 FINISH 52088.897 CLK UTC(NIST) EPHEM DE200 PBDOT 3.64E-12 2.000e-13 TZRMJD 51204.64376750220085 TZRFRQ 1413.400 TZRSITE 7 RM +1.5 5.000e-01 PX 7.19 1.400e-01 SINI 0.6788 1.200e-03 M2 0.236 1.700e-02  This indicates to tempo2 that all parameters should be held fixed except for the astrometric parameters (RAJ, DECJ), pulse parameters (F0, F1) and the Keplerian orbital parameters (PB, ECC, A1, T0 and OM). Uncertainties are given on many of the parameters. In more detail, a pulsar which has a spin period of P0=1.23456 s and no fitting is required then use:  P0 1.23456  To request that tempo2 fits for this parameter:  P0 1.23456 1  or to include an uncertainty on the measurement (which is ignored by the main tempo2 software)  P0 1.23456 1 0.00003  Other commands may be given in parameter files that control the algorithms used by tempo2. Tempo2 only required the following parameters: PSRJ, DM, F0, PEPOCH, RAJ and DECJ. It is also possible to provide the pulsar parameters in the old-style tempo format where the arrival times and the parameters are given in the same file. Details of this mode (which we do not recommend) are given here. ## 3.2 Phase jumps It is often necessary to fit for a constant offset between two sets of arrival times. For instance, the templates used to determine arrival times at different observatories may be perfectly aligned. The command "JUMP" in the parameter file can be used to define such jumps: JUMP MJD v1 v2 will provide a jump between all arrival times with MJDs between v1 and v2 and all other observations. JUMP FREQ v1 v2 will jump between observations with frequencies between v1 and v2 MHz and all other observations. JUMP TEL id will jump between observations at a particular observatory compared with all other observations. JUMP NAME str will jump on all observations which contains a "str" in the observation identifier. JUMP flag val will jump on all observations with a specified flag and value. Examples include  JUMP -i PKS_DFB 0.234 1 JUMP FREQ 1400 1500 0 1 JUMP TEL PKS 0.342  which would initialise a jump for all observations with the "-i" flag set to "PKS_DFB" with the value of 0.234 and then fit for the jump. A jump would be included (and fitted) for all observations with frequencies between 1400 and 1500 MHz and a set (i.e. not fitted) jump would be included on all data observed using the "PKS" telescope. ## 3.3 Removing timing noise Even with accurate spin and positional parameters, the timing residuals for some (particularly the young) pulsars contain remnant structures. Some of these structures are understood; cusps, for instance, signify sudden changes in the pulsar's spin rate during a glitch, sinusoidal oscillations can represent unmodelled companions (such as planets) or the pulsar precessing. However, many of the structures seen in the residuals are still not understood and are known as "timing noise". To obtain the most accurate pulsar's positional and proper motion parameters (and dispersion measure) it is essential to remove this timing noise. Traditionally this has been carried out by fitting higher order pulsar rotational derivative terms. However, Hobbs et al. (2004) described an improved method that used the fitting of harmonically related sinusoids. Such sinusoidal terms can be included in tempo2 parameter files.  WAVE_OM 0 1 WAVE1 0 0 WAVE2 0 0 WAVE3 0 0  would allow tempo2 to select the fundamental frequency for the sinuosoids based on the data-span (see the algorithm described in Hobbs et al. 2004) and subsequently fit for 3 sine and cosine waves. ## 3.4 Coping with badly wrong ephemerides Under normal circumstances, tempo2 should be able to predict exactly the number of turns between any two observations, so that the residual phase error is considerably less than one turn. In early stages of timing a pulsar, during the process of "phase connecting" the data, this may not be true, and phases may "wrap". tempo2 provides several tools to help in this situation. Most simply, one may add the PHASE command to an observation file. Adding PHASE n tells tempo2 that at that point, n extra phase turns occurred compared to what tempo2 would otherwise assume. Thus PHASE 1 has the effect of adding one full turn to all following arrival times. Naturally as the ephemeris changes the number of turns tempo2 would assume will change, and these will frequently need to be added or removed (hopefully removed). A more automated approach is to use one of the modes of the TRACK command. TRACK 0 is the default mode of tempo2. TRACK 1 tells tempo2 to assume that the phase error of each residual is within one-half turn of the previous residual, rather than within one-half turn of zero. This only makes sense if the residuals are provided to tempo2 in time order, though tempo2 only warns about this condition. TRACK -1 uses several data points to guess the correct number of turns. TRACK -2 allows a number of turns to be specified for each TOA using the "-pn" flag; it behaves similarly to the PHASE command. Table 3.1: Pulsar parameters than can be entered in a parameter file  Label Description Units PSRJ, PSRB or PSR Pulsar name - FX (e.g. F0, F1, F2) The X'th time derivative of the rotational frequency (s^{-(X-1)}$) P0 or P Spin period of the pulsar sec P1 or Pdot Spin down rate of pulsar ($x10^{-15}$) PEPOCH Epoch of period determination MJD RAJ or RA J2000 right ascension hh:mm:ss.sss DECJ or DEC J2000 declination dd:mm:ss.sss ELONG or LAMBDA Ecliptic longitude deg ELAT or BETA Ecliptic latitude deg POSEPOCH Epoch of position measurement MJD PMLAMBDA or PMELONG Proper motion in ecliptic longitude mas/yr PMBETA or PMELAT Proper motion in ecliptic latitude mas/yr PMRA Proper motion in right ascension mas/yr PMDEC Proper motion in declination mas/yr DMEPOCH Epoch of DM measurement MJD DM Dispersion measure$cm^{-3}pc$DMX X'th time derivative of the dispersion measure$cm^{-3}pcyr^{-X}$FDD Frequency dependent time delay PX Parallax mas PMRV Radial velocity - - - GLEP_X Glitch epoch MJD GLPH_X Glitch phase incremenet GLF0_X Glitch permanent pulse frequency increment Hz GLF1_X Glitch permanent pulse frequency derivative incremenet$s^{-2}$GLF0D_X Glitch pulse frequency increment Hz GLTD_X Glitch decay time constant - - - WAVE_OM Angular frequency of fundamental sinusoid for whitening WAVEX Amplitude of sine and cosine for the X'th harmonic for whitening sec - - - BINARY Binary model (BT/ELL1/DD/MSS/T2) A1 Projected semi-major axis of orbit lt-sec PB Orbital period days ECC or E Eccentricity of orbit T0 Epoch of periastron MJD OM Longitude of periastron deg TASC Epoch of ascending node MJD EPS1 ECC x sin(OM) for ELL1 model EPS2 ECC x cos(OM) for ELL1 model OMDOT Rate of advance of periastron deg/yr PBDOT 1st time derivative of binary period s/s or s/s*1e12 A1DOT or XDOT Rate of change of projected semi-major axis lt-s/s or lt-s/s*1e12 SINI Sine of inclination angle M2 Companion mass Solar masses XPBDOT Rate of change of orbital period minus GR prediction s/s or s/s*1e12 A1DOT, EDOT or ECCDOT Rate of change of eccentricity OMDOT Periastron advance deg/yr PBX X'th time derivative of binary period GAMMA post-Keplerian gamma term sec DR Relativistic deformation of the orbit DTH Relativistic deformation of the orbit A0 Aberration parameter A0 B0 Aberration parameter B0 BP Tensor multi-scalar parameter beta-prime BPP Tensor multi-scalar parameter beta-prime-prime DTHETA Relativistic deformation of the orbit XOMDOT Rate of periastron advance minus GR prediction deg/yr EPS1DOT EPS2DOT KOM KIN SHAPMAX MTOT Total system mass Solar masses BPJEP_X BPJPH_X BPJA1_X BPJEC_X BPJOM_X BPJOM_X BPJPB_X - - - TEMPO1 Run in tempo1 emulation mode: e.g. use TDB units UNITS Set units to SI or TDB MODE Fitting with errors (MODE 1) or without (MODE 0) JUMP Add a constant offset between specified observations CLK Definition of clock correction files to use TRES rms timing residual NOTRACK Switch off tracking mode NO_SS_SHAPIRO Switch off the calculation of the Solar system Shapiro delay IPM = 0 to switch off calculation of the interplanetary medium NITS Number of iterations for the fit DILATEFREQ Whether or not to apply gravitational redshift and time dilation to observing frequency (Y/N) IBOOT Number of iterations used in the bootstrap fitting method PLANET_SHAPIRO Include calculation of the planetary Shapiro delays CORRECT_TROPOSPHERE Select whether or not to apply tropospheric delay corrections NE1AU The electron density at 1 AU due to the solar wind TIMEEPH Which time ephemeris to use (IF99/FB90) T2CMETHOD Method for transforming from terrestrial to celestial frame (IAU2000B/TEMPO) CLK_CORR_CHAIN Clock correction chain(s) to use EPHEM Which solar system ephemeris to use TZRMJD prediction (polyco) mode only TZRSITE prediction (polyco) mode only NSPAN or TSPAN TZRFRQ prediction (polyco) mode only START FINISH EPHVER TRACK Note that PBBOT, XPBDOT, and A1DOT have special handling: the units are natively s/s or lt-s/s, but if the value is larger than 1e-7, it is scaled down by 1e-12; you may therefore see values like 100 to mean 1e-10. When PBDOT or other derivatives or orbital quantities are specified, PB, A1 and so on are the binary parameters at the time T0 (not PEPOCH). # Chapter 4: Observation files These observation files are also known as "arrival time files" or "tim files". For each pulsar an arrival time file must be created that contains all the measured site-arrival-times (i.e. the pulse arrival time at the observatory for each observation). This file can take the form of the old Parkes or Jodrell style tempo files, but it is recommended that the new tempo2 format be used. The "pat" program in the psrchive suite of software can provide arrival times in tempo2 format. A script is also available (Author: I. Stairs; click here) to convert old style files into the tempo2 format. ## 4.1: tempo2 format The current tempo2 format is identified using  FORMAT 1  at the start of the observation file. Each line in this file can be entered in a "free-format" manner: there is no limit on the number of decimal places or characters supplied for each parameter. However, it is advisable not to use dashes (-) within the filenames, as this may confuse tempo2's understanding of potential flags. The file has the following form  file freq sat satErr siteID <flags>  where the pre-defined flags are listed in Table 4.1. Other user defined flags may be used in this file. (Do take care, however, to separate flags with spaces rather than tabs.) These flags can provide any information and could be used, for example, in determining colours used for plotting with a personal graphical interface. An example file is given below:  FORMAT 1 C ../archives/w040205_062810.cFTp 3072.52800000 53040.27037033597299853 10.07000 7 -i WBC_10 ../archives/w040206_070831.cFTp 3092.99900000 53041.31851839551620031 1.16000 7 -i WBC_10 C ../archives/w040206_084839.cFTp 3068.03800000 53041.38807867413299846 9.97000 7 -i WBC_10 ../archives/w040206_111139.cFTp 3105.49900000 53041.47201962440929890 1.15000 7 -i WBC_10 ../archives/w040207_070619.cFTp 3092.99900000 53042.30720476755460169 1.21000 7 -i WBC_10 ../archives/w040207_081328.cFTp 1367.99900000 53042.35109949197099866 1.09000 7 -i WBC_20 ../archives/w040207_084227.cFTp 1415.14600000 53042.36843163794929978 0.98000 7 -i WBC_20 ../archives/w040207_115804.cFTp 1431.21700000 53042.50986685147659827 0.98000 7 -i WBC_20 ../archives/w040207_142934.cFTp 1431.43500000 53042.60951958276880092 0.99000 7 -i WBC_20 ../archives/w040208_081840.cFTp 1563.91900000 53043.34710640092290035 0.82000 7 -i WBC_20 ../archives/w040208_083501.cFTp 1432.49900000 53043.36886551809849877 0.78000 7 -i WBC_20 ../archives/n2004-06-27-04:13:58.FTp 685.24900000 53183.18848980008860039 0.06000 7 -i nCPSR2_50 ../archives/n2004-07-15-18:33:23.FTp 685.24900000 53201.79496983790510001 0.08000 7 -i nCPSR2_50 ../archives/n2004-07-15-19:39:47.FTp 685.24900000 53201.81959222764389850 0.22000 7 -i nCPSR2_50 ../archives/n2004-07-15-19:42:31.FTp 685.24800000 53201.84208218378509869 0.19000 7 -i nCPSR2_50  Table 4.1: Pre-defined flags used in arrival time files  Flag Parameter Type dm DM (cm-3pc) float dmo DM offset (cm-3pc) float dme DM uncertainty (cm-3pc) float p Phase offset float t telescope identifier string addsat add to arrival time (seconds) float to add to arrival time (seconds) float radd add to residual (seconds?) float padd add to residual (phase) float pn pulse number (turns) int c clock correction path (underscore-separated) string telx, tely, telz telescope position (for barycentered TOAs) float A list of the available commands that can be included in an arrival time file are provided in Table 4.2. Note that, when writing out a new arrival time file from tempo2 (using a plugin such as plk), many of these commands will not be replicated, but will instead be absorbed in the tim-file values or their errors. For example, EFLOOR, EMIN and EMAX will be absorbed in the TOA uncertainties. The exceptions are EFAC and EQUAD, which are kept separated - and hence keep the original errors intact in the tim-file. (Notice GLOBAL_EFAC and T2EFAC will be absorbed in the EFAC value and T2EQUAD will be absorbed in the EQUAD value.) Table 4.2: Commands that may be included in an arrival time file  Command Meaning EFAC x Multiply uncertainties by x EQUAD x Additional uncertainty in microsec, added in quadrature T2EFAC -backend dfb x Multiply uncertainties with flag "-backend dfb" by x T2EQUAD -backend dfb x Add x {$\mu$}sec uncertainty in quadrature to the errors of TOAs designated by flags "-backend dfb" GLOBAL_EFAC x Multiply all uncertainties by x. If for some or all of the TOAs an "EFAC y" is present as well, then those TOA uncertainties will multiplied by x times y. EMAX x Ignore TOAs with uncertainties greater than x (us) EMIN x Ignore TOAs with uncertainties less than x (us) EFLOOR x Put uncertainties of less than x (us) to equal x (us) END Ignore all remaining lines in the arrival time file FMAX x Ignore observations at frequencies greater than x MHz FMIN x Ignore observations at frequencies less than x MHz INCLUDE x Include the arrival times in file 'x' INFO x Identify all following observations with a given highlighting code MODE MODE 0 (default) implies that the TOA error is not taken into account during the fitting procedure. MODE 1 uses the uncertainties NOSKIP End of skip statement PHASE x Add x phase jumps SIGMA x Set uncertainties of following TOAs to x (us) SKIP Skip all lines until NOSKIP is reached TIME x Add x seconds to following TOAs TRACK x Tracks phase wrap-arounds (can also occur in parameter files) ## 4.2 The Jodrell Bank Observatory binary format It is also possible to provide pulsar arrival times in a Jodrell Bank format binary file. Such files contain barycentric arrival times. For instance a typical usage would be  tempo2 -f psrav.eph psrav.bat -jbo -delete psrav.del  # Chapter 5: Tempo2 command line arguments # 5.1 The arguments Tempo2 is run from the command line. Basic version information, help and a list of the available plug-in packages can be obtained by typing  tempo2 -h  Tempo2 has a number of options that can be controlled from the command line. These are listed in Table 5.1 below: Table 5.1: Tempo2 command line options  Parameter Meaning -debug provides output useful for identifying problems with the software -delete fname delete the observations listed in the file "fname" by their site-arrival-times or observation name -clock x define the clock in conversion to TT as x -epoch x set the epoch of the parameter file to be x (MJD) -f x.par y.tim specifies the parameter (.par) and arrival time (.tim) files for use in subsequent processing. -filter x filters the set of observations (see below) -fit x turn on fitting for parameter 'x' (this command-line option can be repeated for multiple parameters) -gr x use the 'x' graphical interface -h display help information -jbo tells tempo2 to expect input in the Jodrell Bank psrav.bat format -list lists information about the residuals, time delays etc. that have been used or calculated by tempo2 -machine x define the processor being used -model -name x define the pulsar name to be 'x' - ignoring what is in the parameter file -newpar produces a new .par file from the fitted parameters -nobs re-defines the maximum number of observation to be stored simultaneously in memory -nofit switch off the fitting algorithms -noWarnings switch off the displayed warnings -npsr re-defines the maximum number of pulsars to be stored simultaneously in memory -output name uses the "name" plugin instead of displaying the standard tempo2 output -polyco runs tempo2 in predictive mode -pre only calculates the pre-fit residuals -residuals outputs the residuals to a file called "residuals.dat" -set X a set the parameter X to the value 'a' (ignoring the value in the parameter file) -tempo1 enables tempo1 compatibility mode (note: this gets overwritten by the EPHVER key word in the par file!) ## 5.2 The tempo1 emulation mode In the tempo1 compatability mode the following parameters are automatically set (these can also be set manually in the parameter file) • UNITS TDB • TIMEEPH FB90_TIMEEPH • DILATEFREQ N • PLANET_SHAPIRO N • T2CMETHOD TEMPO • CORRECT_TROPOSPHERE N • NE_SW 9.961 • ECLIPTIC_OBLIQUITY 84381.412 The use of EPHVER 2 in the parameter file will also make tempo2 use the tempo1 emulation mode. Note: the majority of the ephemerides in the pulsar catalogue are in tempo1 format and so automatically include EPHVER 2 in the output ephemeris. NOTE: the EPHVER keyword overwrites the -tempo1 command-line argument, as the par file does not get transformed. "-tempo1" only has an effect if the EPHVER keyword is absent from the par file. ## 5.3 Filtering It is often useful to be able to filter the observation file before processing. For instance, an observer may use multiple back-end systems or observatories. These can be defined using "flags":  ../archives/n2003-01-10-17:07:45.FTp 1340.749 52649.7257990374280 0.67 7 -i nCPSR2_20 ../archives/w040206_150608.cFTp 3067.999 53041.6404217220093 34.43 7 -i WBC_10 ../archives/w040206_160503.cFTp 3067.999 53041.6813940348552 42.73 7 -i WBC_10 ../archives/w040207_133403.cFTp 1421.439 53042.5667819871316 6.92 7 -i WBC_20 ../archives/w040207_134155.cFTp 1417.998 53042.5819726383262 4.59 7 -i WBC_20  If all the WBC_10 and nCPSR2_20 observations should be ignored then use  tempo2 -f mypar.par mytim.tim -filter "-i nCPSR2_20 WBC_10"  ## 5.4 Aliases Occassionally the user must repeatedly run the same tempo2 command which contains multiple arguments. This can be simplified with the use of aliases. Aliases are placed in a file called $TEMPO2/alias.dat as follows:

 -jodrell -f psrav.eph psrav.bat -jbo -del psrav.del
-quick -newpar -gr plk


The user can then type

 tempo2 -jodrell -gr plk


 tempo2 -f psrav.eph psrav.bat -jbo -del psrav.del -gr plk


# Chapter 6: Running tempo2 in predictive mode

## 6.1 Introduction

On-line pulsar observing software and offline folding procedures require knowledge of the functional form of the pulsar's phase and pulse-period over a given time interval. Tempo1 produces "polyco" files that contain the pulsar parameters in the form of a simple polynomial expansion. The pulse phase and frequency at time T are then calculated as

 DT = 1440(T-T0)
PHASE = RPHASE + 60F_0 DT + c_1 + DTc_2 + DT^2c_3 + ...
FREQ = F0 + (1/60)(c_2 + 2DTc_3 + 3DT^2c_4 + ...


Tempo2 allows this old-style "polyco" format to be produced, but also provides for a new technique ("predictor" files) that should be used for high precision timing.

## 6.2 Tempo1-style polycos

Tempo1 style polycos can be produced using:

 tempo2 -f 0437-4715.par -polyco "53000 53001 300 12 8 pks 1400.0" -tempo1


(use tempo2 -h for a complete list of the required parameters). The example above will request that tempo2 makes a polyco file for the pulsar PSR J0437-4715 from MJDs 53000 to 53001 with the file divided into segments each of nspan = 300 minutes. The number of coefficients for use in the fitting ncoeff = 12. The maximum absolute hour angle range for the prediction, maxha = 8 (note this is effectively a one-sided hour angle, which means that maxha = 12 implies a polyco for a full 24h period). The observatory site for the prediction is site_code = pks at an observing frequency of freq = 1400 MHz. Therefore, the format used in defining the prediction is

 -polyco "mjd1 mjd2 nspan ncoeff maxha site_code freq"


(note the use of quotation marks around the parameters). Tempo2 should produce a file (polyco.dat) that has an identical format to tempo1 polyco files. ( note: the tempo1 software switches off clock corrections in predictive mode. To emulate this the CLK flag in the parameter file should be set to CLK UNCORR).

## 6.3 Tempo2 style predictor files

Owing to interplanetary and interstellar dispersion, the polynomial coefficients produced by tempo1 are specific to a given observing frequency. For observations at radio wavelengths, there is usually a significant variation of instantaneous pulse phase across the observing band. If high precision is required, the form of this variation is dependent on many parts of the full timing model. Therefore, tempo2 predictor files are time and frequency dependent predictive polynomials.

The polynomial is expressed in terms of a two-dimensional adaptation of the conventional Chebyshev basis functions. These are written into an ascii text file and various pieces of software are available (click here) to process these predictor files.

The following command is run to create predictor files:

 tempo2 -f mypar.par -pred "sitename mjd1 mjd2 freq1 freq2 ntimecoeff nfreqcoeff seg_length"


where the segment length is given in seconds.

# Chapter 7: Processing multiple pulsars simultaneously

## 7.1 Introduction

Tempo2 has been designed to process multiple pulsar data-sets simultaneously. Full global fitting algorithms do exist, but are currently being tested and improved. Here, we only discuss processing multiple pulsars where each pulsar is fitted individually. This is carried out using

 tempo2 -f psr1.par psr1.tim -f psr2.par psr2.tim -f psr3.par psr3.tim ...


Tempo2 will provide individual output for the fits to each pulsar. Some of the graphical interfaces can process the timing residuals of multiple pulsars. These include "splk" which plots each timing residual, "plotMany" which makes publication quality plots of multiple timing residuals and further plugins are being developed to search for correlations between the timing residuals.

# Chapter 8: The graphical interfaces and output formats

By default, tempo2 provides a simple, text-only output of the pre- and post-fit timing parameters. One of the main strengths of tempo2 is the ability for individual users to produce code in C or C++ that can interact or "plugin" to the main software. This allows the user to produce new "output formats" (that control the final output of the timing parameters or the residuals) or "graphical interfaces" that provide full control to the plugin and allows residuals to be viewed, processed, re-fit and so forth. Details for producing these plugins are provided in Appendix A of this documentation. Full documentation and downloads of the currently available plugins can be obtained from the plugins page on this wiki.

## 8.1 The output formats

The default output format provides the pre- and post-fit rms residuals, the number of points in the fit and, if a weighted fit has been carried out, the reduced chisquared-value of the fit. For each parameter, the values of the pre- and post-fit parameters are listed alongside the uncertainty in the post-fit value and the difference between the pre- and post-fit values. A flag indicates whether the parameter was included in the fit. For binary systems, the default output format also provides details on the binary model and lists, if possible, the mass function, minimum, median and maximum companion masses, the total system mass and the inclination angle. An example is given below:

 Results for PSR J0437-4715

RMS pre-fit residual = 6.895 (us), RMS post-fit residual = 0.096 (us)
Number of points in fit = 367

PARAMETER       Pre-fit                   Post-fit                  Uncertainty   Difference   Fit
---------------------------------------------------------------------------------------------------
RAJ (rad)       1.2097885336826           1.20978853474746          2.1206e-11    1.0649e-09    Y
RAJ (hms)       04:37:15.7865              04:37:15.7865146         2.916e-07     1.4643e-05
DECJ (rad)      -0.824709094076948        -0.824709094473468        1.5157e-11    -3.9652e-10   Y
DECJ (dms)      -47:15:08.4615            -47:15:08.46158           3.1264e-06    -8.1788e-05
F0 (s^-1)       173.68794630603           173.687946306032          9.5579e-15    2.3306e-12    Y
F1 (s^-2)       -1.728e-15                -1.72831367406148e-15     2.3325e-22    -3.1367e-19   Y
PEPOCH (MJD)    51194.0001248168          51194.0001248168          0             0             N
POSEPOCH (MJD)  51194.0001248168          51194.0001248168          0             0             N
DMEPOCH (MJD)   51194                     51194                     0             0             N
DM (cm^-3 pc)   2.64690012312213          2.64690012312213          0             0             N
PMRA (mas/yr)   121.43799811708           121.43799811708           0             0             N
PMDEC (mas/yr)  -71.4379988923397         -71.4379988923397         0             0             N
PX (mas)        7.19                      7.19                      0             0             N
SINI            0.6788                    0.6788                    0             0             N
PB (d)          5.741046089               5.74104608900813          1.0437e-11    8.1286e-12    Y
T0 (MJD)        51194.6240248265          51194.6240248265          0             0             N
A1 (lt-s)       3.36669162220122          3.36669162220122          0             0             N
OM (deg)        1.2                       1.2                       0             0             N
ECC             1.9186e-05                1.9186e-05                0             0             N
PBDOT (10^-12)  3.64                      3.64                      0             0             N
OMDOT (deg/yr)  0.0159999997519168        0.0159999997519168        0             0             N
M2              0.236                     0.236                     0             0             N
START (MJD)     50640.9281162413          49350.5129309451          0             -1290.4       N
FINISH (MJD)    52088.8971386924          53000.5197060478          0             911.62        N
TRACK (MJD)     0                         0                         0             0             N
TZRMJD          51204.6438924841          51204.6438924841          0             0             N
TZRFRQ (MHz)    1413.39997808495          1413.39997808495          0             0             N
---------------------------------------------------------------------------------------------------
Binary model: DD
Mass function                  = 0.001243113190  +- 0.000000047151 solar masses
Minimum companion mass         = 0.1403 solar masses
Median companion mass          = 0.1637 solar masses
Maximum companion mass         = 0.3493 solar masses
MTOT derived from sin i and m2 = 1.818606841374
Inclination angle (deg)        = 42.74994182955 (+ 0 - 0)


Other output format have been developed and can be accessed using:

 tempo2 -output NAME -f mypar.par mytim.tim


where NAME is the name of the output format. Examples of various output formats are shown below. More details can be found on the plugins page.

### 8.1.1 The general output format

The general output format allows the user to present the fitted parameters in a user-specified way. For instance,

 tempo2 -output general -s "{NORAD}{ALL_f}{TAB 20} & {ALL_p} {TAB 50}\n" -f psr.par psr.tim


will produce output in a LaTeX format:

 RAJ (rad)            &  18:02:05.33496(12)         DECJ (rad)           & -21:24:03.72(6)             F0 (s^-1)            & 79.066424253435(18)         F1 (s^-2)            & -4.574E-16(13)              PEPOCH (MJD)         & 52855                       POSEPOCH (MJD)       & 52855                       DMEPOCH (MJD)        & 52855                       DM (cm^-3 pc)        & 149.666066                  PB (d)               & 0.69888924320(20)           A1 (lt-s)            & 3.718853847                 TASC (MJD)           & 52595.795078543             EPS1                 & 1.0412e-06                  EPS2                 & 2.3924e-06                  START (MJD)          & 52605.162                   FINISH (MJD)         & 53565.334                   TRACK (MJD)          & 0                           TZRMJD               & 52883.440856822             TZRFRQ (MHz)         & 1390


### 8.1.2 The general2 output format

The general2 output plugin is used to output per-datum (per-TOA) values in a user-specified format. This includes the site-arrival-times, clock corrections, timing residuals and so forth. For example the Shapiro delay due to Jupiter and the post-fit residuals can be displayed using

 tempo2 -output general2 -f par.par tim.tim -s "{bat} {shapiroJ} {post}\n"


In detail, the command-line options are:

optiondescription
-s stringFormat data according to string
-outfile fileSend formatted data to outfile rather than standard out

Data available through the plugin are:

keywordmeaning
satBarycentric arrival time
batBarycentric arrival time
bbatBinary barycentric arrival time
clock0Clock correction number 0
clock1Clock correction number 1
clock2Clock correction number 2
clock3Clock correction number 3
clock4Clock correction number 4
ut1UT1 correction
delWhether the TOA was deleted
einsteinEinstein rate
fileFilename the TOA came from (via INCLUDEs)
solarangleAngle from the Sun
shapiroSolar Shapiro delay - note solar not binary
shapiroJJupiter Shapiro delay
shapiroSSaturn Shapiro delay
shapiroVVenus Shapiro delay
shapiroUUranus Shapiro delay
shapiroNNeptune Shapiro delay
roemerRoemer delay (light travel time across the Earth's orbit)
flagsFlags associated with TOA in input file
tropoTropospheric delay
ttCorrection to TT
TttTOA corrected to TT
t2tbCorrection including TT and tt2tb
tt2tbCorrection from TT to TDB
earth_ssbVector from Earth to solar system barycenter
earth_ssb1x-component of vector from Earth to solar system barycenter
earth_ssb2y-component of vector from Earth to solar system barycenter
earth_ssb3z-component of vector from Earth to solar system barycenter
earth_ssb4time derivative of x-component of vector from Earth to solar system barycenter
earth_ssb5time derivative of y-component of vector from Earth to solar system barycenter
earth_ssb6time derivative of z-component of vector from Earth to solar system barycenter
sun_ssb1x-component of vector from Sun to solar system barycenter
sun_ssb2y-component of vector from Sun to solar system barycenter
sun_ssb3z-component of vector from Sun to solar system barycenter
sun_earth1x-component of vector from Sun to Earth
sun_earth2y-component of vector from Sun to Earth
sun_earth3z-component of vector from Sun to Earth
d_parameterPartial derivative with respect to parameter, post-fit
ismISM delay
elevSource elevation (neglecting proper motion)
posPulsar
velPulsar
siteVel0
siteVel1
siteVel2
posTelPosition of telescope in Earth-centered coordinates
dtCOETime delay to centre of Earth
telSSBTelescope position with respect to solar system barycenter
telVelTelescope velocity with respect to solar system barycenter
zenithTelescope zenith vector (?)
npulsePulse number
clockTotal clock correction
clk_corr1
clk_corr2
clk2
clkchainChain of clock corrections used
ipmInterplanetary medium correction
fmjdu
xBAT - epoch
freqObserving frequency
freqSSBObserving frequency at solar system barycenter
freqCOEApprox. observing frequency at centre of Earth
prePre-fit residual
pre_phasePre-fit residual in phase
postPost-fit residual
post_phasePost-fit residual in phase
errTOA error
binphaseBinary phase

Data keywords are case-insensitive.

In addition to the data printing keywords, there are keywords that serve as commands to the plugin:

keywordmeaning
format cUse c as a printf-style string to format values and errors
errmult cMultiply all errors by c
null sDisplay the string s for null (non-available) values
sub1Subtract first residual from remainder
RADDoes not appear to do anything but set a flag. Upper-case only.

Command keywords are case-sensitive but generally all-upper and all-lower are both accepted.

## 8.2 The graphical interfaces

The graphical interfaces allow the user to interact with the tempo2 outputs and fitting algorithms. The most commonly used plugin is plk which allows the user to view the residuals, delete points, re-fit, change the fitting parameters and carry out most proceedures needed for pulsar timing. There are other plugins to limit the existence of gravitational wave backgrounds, obtain structure functions to probe the interstellar medium, produce power-spectral estimates of the residuals and to simulate new data sets. More details can be found on the plugins page. The following figures give examples for some of the graphical interfaces.

Figure 8.1: Example of the plk (left) and fake (right) graphical interface

Figure 8.2: (left) Example of the basic graphical interface. (right) Example of the delays graphical interface.

# Appendix A: Developing the software

The plug-in features of tempo2 implies that users can add to the functionality of \textsc{tempo2} by producing their own plug-in. In this section, we first discuss how such plug-ins can be produced. We also provide a few notes for users who are interested in developing the actual main source code and become part of the tempo2 development team.

## A.1 Creating a plug-in

Plug-ins are relatively easy to create in C or C++. These plug-ins may use other libraries such as pgplot, tcl/tk or qt. As described above, plug-ins can be created to change the output format or as a graphical interface.

When creating plugins with command-line arguments, do notice that the standard tempo2 command line arguments are already in use and duplication may cause your plugin to behave unexpectedly.

### A.1.1 A new output format

When an "output-format" plug-in is used, the tempo2 software reads in the specified parameter and observation files, carries out the standard techniques to obtain pre- and post-fit timing residuals and their corresponding parameter values and then passes control to the output-format software to display the results. An example output format (in C) is as follows:

 #include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include "tempo2.h"  /* Essential for a tempo2 plugin */

extern "C" int tempoOutput(pulsar *psr,int npsr,char timFile[][MAX_FILELEN],char parFile[][MAX_FILELEN])
{
int i;
printf("Pulsar name = %s\n",psr[0].name);
printf("Pulsar spin-frequency = %Lg\n",psr[0].param[param_f].val[0]);
for (i=0;i<psr[0].nobs;i++)
printf("Residual = %.14f\n",(double)psr[0].obsn[i].residual);
}


This plug-in displays the pulsar's name (obtained from the parameter file), its post-fit spin-frequency and the post-fit timing residuals on the screen. The software is built around a "structure" called "pulsar" which is defined in "tempo2.h". The most important definitions in this structure are

   char *name;                  /* The pulsar name */
char *binaryModel;           /* The binary model (e.g. T2/BT/ELL1 ...) */
double ne_sw;                /* The electron density at 1AU due to the solar wind */
int    fitMode;              /* = 1 if fitting with errors, 0 = not fitting with errors */
int    nobs;                 /* Number of observations */
int    nits;                 /* Number of iterations used for the fit */
int    ipm;                  /* = 1 if the interplanetary DM correction is used, 0 otherwise */


An array of pulsars is defined and therefore, in order to display the name of the first three pulsars analysed:

   printf("pulsar 1 = %s\n",psr[0].name);
printf("pulsar 2 = %s\n",psr[1].name);
printf("pulsar 3 = %s\n",psr[2].name);


The structure also includes an array of parameters ("param") which are defined as

   param_raj     : Right ascension of the source
param_decj    : Declination of the source
param_f       : Pulse frequency (and derivatives)
param_pepoch  : Epoch of period determination
param_posepoch: Epoch of position determination
param_dmepoch : Epoch of DM determination
param_dm      : Dispersion measure
param_pmra    : Proper motion in right ascension
param_pmdec   : Proper motion in declination
param_px      : Parallax
param_sini    : Sine of the orbital inclination angle
param_pb      : Orbital period
param_t0      : Epoch of periastron passage
param_a1      : Projected semi-major axis of the binary orbit
param_om      : Angle of periastron
param_ecc     : Eccentricity of the binary orbit
param_edot    : First time derivative of the eccentricity
param_xpbdot  : Part of pbdot unexplained by GR (DDGR model)
param_pbdot   : First time derivative of the orbital period
param_a1dot   : First time derivative of the projected semi-major axis
param_omdot   : First time derivative of the angle of periastron (periastron advance)
param_tasc    : Epoch of ascending node passage
param_eps1    : Eccentricity parameter
param_eps2    : Eccentricity parameter
param_m2      : Companion mass
param_gamma   : Gravitational redshift parameter
param_mtot    : Total mass of the binary system
param_glep    :
param_glph    :
param_glf0    :
param_glf1    : First time derivative of glf0
param_glf0d   :
param_gltd    :
param_start   : Start MJD of this data set
param_finish  : Final MJD of this data set
param_track   :
param_bp      :
param_bpp     :
param_tzrmjd  :
param_tzrfrq  :
param_fdd     :
param_dr      :
param_dtheta  :
param_tspan   : Time span of the data set
param_bpjep   :
param_bpjph   :
param_bpja1   :
param_bpjec   :
param_bpjom   :
param_bpjpb   :
param_wave_om : Frequency of the fitted wave (for pre-whitening)
param_kom     : Longitude of the ascending node of the binary orbit
param_kin     : Inclination angle of the binary orbit
param_shapmax : Maximum of the Shapiro delay (-ln(1-s))
param_dth     :
param_a0      :
param_b0      :
param_xomdot  : Part of omdot unexplained by GR (DDGR)
param_afac    :
param_eps1dot : First time derivative of eps1
param_eps2dot : First time derivative of eps2
param_tres    : Residual rms


For each parameter, the user can obtain

   char **label;              /* Label about this parameter                         */
longdouble *val;           /* Value of parameter                                 */
longdouble *err;           /* Uncertainty on parameter value (Notice the fitting routine only calculates
this parameter up to double precision.)
int  *fitFlag;             /* = 1 if fitting required                            */
int  *paramSet;            /* = 1 if parameter has been set                      */
longdouble *prefit;        /* Pre-fit value of the parameter                     */
longdouble *prefitErr;     /* Pre-fit value of the uncertainty                   */
int aSize;                 /* Number of elements in the array for this parameter */


Each parameter (except those for which the derivatives were explicitly mentioned before) is stored as an array with each element of the array typically storing time derivatives of the parameter. For instance,to obtain the value of the spin-frequency and its first two derivatives:

   printf("values = Lg %Lg\n",psr[0].param[param_f].val[0],
psr[0].param[param_f].val[1],psr[0].param[param_f].val[2]);


(Note: 'C' requires the symbol 'Lf' to display values in 'long double' precision.)

The "pulsar" structure also contains the set of observations and corresponding parameters. The observation structure contains (other less-common parameters are defined in the tempo2.h file)

  longdouble sat;                 /* Site arrival time (MJD)
longdouble bat;                 /* Barycentric arrival time (MJD)
int deleted;                    /* = 1 if observation has been deleted
longdouble prefitResidual;      /* Pre-fit residual
longdouble residual;            /* residual (in sec)
double      freq;               /* Frequency of observation (in MHz)
double      freqSSB;            /* Frequency of observation in barycentric frame (in Hz)
double      toaErr;             /* Error on TOA (in us)
char        fname[MAX_FILELEN]; /* Name of data file giving TOA
char        telID[100];         /* Telescope ID
longdouble correctionTT_TB;     /* Correction to TDB/TCB
double einsteinRate;            /* Derivative of correctionTT_TB
longdouble correctionTT_Teph;   /* Correction to Teph
longdouble correctionUT1;       /* Correction from site TOA to UT1
double shapiroDelaySun;         /* Shapiro Delay due to the Sun
double shapiroDelayJupiter;     /* Shapiro Delay due to Jupiter
double shapiroDelaySaturn;      /* Shapiro Delay due to Saturn
double shapiroDelayUranus;      /* Shapiro Delay due to Uranus
double shapiroDelayNeptune;     /* Shapiro Delay due to Neptune
double troposphericDelay;       /* Delay due to neutral refraction in atmosphere
double tdis1;                   /* Interstellar dispersion measure delay
double tdis2;                   /* Dispersion measure delay due to solar system
longdouble roemer;              /* Roemer delay


For instance, in order to display the site arrival-time, the barycentric arrival-time, and the Solar Shapiro delay for each observation:

  for (i=0;i<psr[0].nobs;i++)
printf("values = Lf %f\n",psr[0].obsn[i].sat,psr[0].obsn[i].bat,psr[0].obsn[i].shapiroDelaySun);


### A.1.1 A new graphical interface

When a graphical interface is used, tempo2 checks the command-line arguments, initialises the memory and then passes control to the graphical interface. The reading of the parameter and observation files, calculating barycentric arrival times, obtaining residuals, fitting and displaying the output must all be done within the graphical interface. The following tempo2 functions are commonly called:

   readParfile(...)           /* Read the parameter file             */
preProcess(...)            /* Needs to be called after reading the
parameter and observation files     */
formBatsAll(...)           /* Forms the barycentric arrival times */
formResiduals(...)         /* Forms the timing residuals          */
doFit(...)                 /* Calls the fitting algorithms        */
textOutput(...)            /* The standard output display         */


An example of a simple interface would be

 #include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <math.h>
#include "tempo2.h"

using namespace std;

/* The main function called from the TEMPO2 package is 'graphicalInterface' */
/* Therefore this function is required in all plugins                       */
extern "C" int graphicalInterface(int argc,char *argv[],pulsar *psr,int *npsr)
{
char parFile[MAX_PSR][MAX_FILELEN];
char timFile[MAX_PSR][MAX_FILELEN];
int i;
double globalParameter;

*npsr = 1;  /* For a graphical interface that only shows results for one pulsar */

printf("Graphical Interface: name\n");
printf("Author:              author\n");
printf("Version:             version number\n");

/* Obtain the .par and the .tim file from the command line */
if (argc==4) /* Only provided .tim name */
{
strcpy(timFile[0],argv[3]);
strcpy(parFile[0],argv[3]);
parFile[0][strlen(parFile[0])-3] = '\0';
strcat(parFile[0],"par");
}

/* Obtain all parameters from the command line */
for (i=2;i<argc;i++)
{
if (strcmp(argv[i],"-f")==0)
{
strcpy(parFile[0],argv[i+1]);
strcpy(timFile[0],argv[i+2]);
}
}

preProcess(psr,*npsr,argc,argv);

for (i=0;i<2;i++)                   /* Do two iterations for pre- and post-fit residuals*/
{
formBatsAll(psr,*npsr);         /* Form the barycentric arrival times */
formResiduals(psr,*npsr,0.0);    /* Form the residuals                 */
if (i==0) doFit(psr,*npsr,&globalParameter,0,0);   /* Do the fitting     */
else textOutput(psr,*npsr,globalParameter,0,0,0,"");  /* Display the output */
}

/* Now you have the parameters and residuals */
/* which can be displayed or plotted         */

return 0;
}


## A.1.2: The main source code

   make install


The plug-ins provided with the source code are stored in soft_atnf/tempo2/plugin.

In progress

# Appendix C: Frequently asked questions

• How do I deal with a leap second? Add in the MJD corresponding to the time of the leap second in $TEMPO2/clock/leap.sec (for tempo1 emulation) and in$TEMPO2/clock/utc2tai.clk for tempo2 files.