Recent Changes - Search:

edit SideBar

TEMPO2 Download and usage instructions

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

instead of

 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
-file fileRead formatting from file
-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
tab nAdvance to column n
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.
NORADNo RAD, not NORAD.

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_pmrv    : Radial proper motion
   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                         */
   char **shortlabel;         /* Label about this parameter without units           */
   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             */
   readTimfile(...)           /* Read the observation 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]);
	}
    }

  readParfile(psr,parFile,timFile,*npsr); /* Load the parameters       */
  readTimfile(psr,timFile,*npsr); /* Load the arrival times    */
  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

The tempo2 software can be obtained from the ATNF CVS repository soft_atnf/tempo2 (please contact members of the ATNF pulsar group for more information). To install type

   make install

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


Appendix B: Tempo2 error and warning messages

In progress


Appendix C: Frequently asked questions

We hope that this page will develop into a set of useful questions and answers about the tempo2 software and usage.

  • How do I increase the number of observations that can loaded in tempo2? Use "-nobs x" on the command line where X is the number of observations required (the current default is 10000 observations).
  • 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.

Edit - History - Print - Recent Changes - Search
Page last modified on April 29, 2007, at 03:53 PM