DESCRIPTION Tempo is a program for analyzing pulsar timing data. Pulse times of arrival (TOAs), pulsar model parameters, and coded instructions are read from one or more input files. The TOAs are fitted by a pulse timing model incorporating transformation to the solar-system barycenter, pulsar rotation and spin-down and, where necessary, one of several binary models. Program output includes parameter values and uncertainties, residual pulse arrival times, chi-squared statistics, and the covariance matrix of the model. In prediction mode, ephemerides of pulse phase behavior (in the form of polynomial expansions) are calculated from input timing models. SYNOPSIS tempo [options] [filename] options: -c Do all requested iterations, even if apparently converged -d Path to 'tempo.cfg', default: environment variable 'TEMPO' -f Over-rides the default parameter file name with -g[O] GRO mode; 'O' is single-letter observatory code -h Help (prints this message) -j Output JUMP values in xxx.par file -J Apply JUMPs after barycenter correction (normally done before) -l Max number of parameters to be fit (guides memory allocation) -m Max number of TOAs to be fit (guides memory allocation) -no Write out absolute pulse numbers to file -ni Get absolute pulse numbers from file -o 'Old-style' parameters at head of -p Parameters corrected for pulsar space motion -r Save the partial-derivatives file, resid1.tmp -s0 No solar system DM corrections (no value other than '0' allowed) -v Print out version number -w less output to tempo.lis; no resid2.tmp -x Make an export file in ITOA format -z Compute polonomial coefficients for predictions -Z= New method for specifying polynomial coefficient calculations ENVIRONMENT The 'TEMPO' environment variable is normally set to the name of the directory containing the 'tempo.cfg' configuration file. The -d option overrides the environment variable. OPTIONS -c do all requested iterations (NITER), even if apparently converged (possibly useful when exploring unusually-shaped chi^2 space) -d override environment variable 'TEMPO' with . Path may be '.'. -f override default name for free-format input parameter file (see INPUT FILES below). -g[O] Write post-fit parameters to file 'gro.1' (and, for binaries, gro.2) in the format used for interchange with Gamma Ray Observatory investigators. Single-letter observatory code, O, is optional; default is P (for Princeton). If PEPOCH is not at the centre of the data span, adjusted parameters are written to gro.99. -h Print help message -j Write offset values ("JUMP_1", etc.) to parameter file. -J Apply offset values (JUMPs) after barycenter corection. Use this option if JUMPs are due to time offsets in the pulsar behavior rather than time offsets due to observatory and data processing issues -l -m Expected maximum number of parameters (xxx) and TOAs (yyy) in the fit. (Default values are hard-wired in source file dim.h.) These values are used to allocate memory. If either is too small, memory will be re-allocated, requiring an extra read through the TOA file. -ni Read pulse numbers from file. These values override the pulse numbers normally calculated internally to tempo. -no Write pulse numbers to file. Main purpose is to produce input for '-ni' option. -o selects 'fixed-format header' input file. See INPUT FILE below. -p calculate pulsar parameters compensating for effects of pulsar space velocity. -r write pre-fit residuals and their derivatives with respect to each parameter to file 'resid1.tmp' -s turn off solar system DM correction. Must be run as '-s0'. In principle the '0' can be replaced with other flags, but no other values are presently allowed -v report version number -w minimizes output to tempo.lis; does not produce resid2.tmp -x write TOAs in interchange time of arrival (ITOA) format to file 'itoa.out' -z run prediction mode, in which predicted pulsar ephemerides are written to file polyco.dat (see PREDICTION MODE). If given, overrides 'tz.in' for the file listing default prediction parameters and source list. -Z= New method for specifying polynomial coefficient calculations Any -Z parameter invokes this mode and minimizes tempo output ("quiet mode") -Z parameters are: Parmater: Default: Description: PSR Pulsar name (same as PULSAR) PULSAR Pulsar name (same as PSR) OBS Observatory (same as SITE) SITE Observatory (same as OBS) OUT polyco.dat Output file name START current time Start time for polyco block NCOEFF 15 Number of coefficients FREQ 1420 Radio frequency of observation SPAN 60 Time span in seconds for polyco block (xxxH or xxxM for hours or minutes) TOBS 1 Observing time in hours (xxxM or xxxS for minutes or seconds) INPUT FILE The input file(s) have either a 'fixed-format' or 'free-format' header. Pulse times of arrival (TOAs) follow the header, or may be listed in a separate file if a free-format header is used. Use of the fixed-format headers is discouraged, as new features will likely be added only for free-format files. Blank lines and comment lines are allowed throughout input files except within fixed-format headers. Comment lines are indicated by 'C ' (capital C followed by a space) in the first two columns or by '#' in the first non-blank column. FREE-FORMAT HEADER If a 'free-format' header is used, the header and TOAs are either in separate files or are combined into a single file. If a single file is used, the file contains, in order: 1. A line with the keyword 'HEAD'. 2. Free-format header parameters and control cards. 3. A line with the keyword 'TOA'. 4. TOA lines. If two primary files are used, the TOAs are listed in the given in the tempo command line. The header parameters are in '.par'. If has an extension, '.par' replaces it; if not, '.par' is appended. Free-format header entries have the format 'keyword value [flag]', with one keyword per line. There are two types of keyword, for control parameters and pulsar parameters, respectively. Space(s) or tab(s) separate items in an entry. Characters following the value are ignored. Keywords are case-insensitive, and characters in keywords beyond those given in the parameter list are ignored. Flags are used to indicate whether or not a parameter is to be fitted. Flags must be one and only one character. For keywords representing parameters of the fit, a flag value of 0 (the default) indicates the parameter should not be fit, while a flag vale of 1 indicates the parameter should be fit. In a few special cases flag values above 1 indicate fitting of several, closely associated parameters. For values above 9, the hex character is used. Flags are not used for most control keywords. Exceptions are 'START' and 'FINISH': these keywords are ignored unless the associated flag value is nonzero. Each time TEMPO is run, an output file giving the results of the fit and their errors is produced. This file ('.par' in the working directory) has the same format as the input file and may be used as an input file. (The errors are ignored for TEMPO input.) Control commands allowed in free-format headers: CLK Terrestrial time standard Allowed values: 'UNCORR' (default), 'UTC(NIST)', 'UTC(BIPM)', 'TT(BIPM)', 'PTB', 'AT1' COORD Input coordinate system Allowed values: 'B1950', 'J2000' (default) DMVAR1 Earlist MJD for which DM variations will be applied Allowed values: floating point MJD DMVAR2 Latest MJD for which DM variations will be applied Allowed values: floating point MJD DMX Fit DM offsets over intervals of x days Allowed values: floating point span length 'x' EPHEM Solar system ephemeris Allowed values: First five characters of file names listed in tempo.cfg file (see below). Typically 'DE200' and 'DE405' IBOOT Bootstrap error analysis, with 2^n iterations Allowed values: integers n INFO Use the specified Tempo2-style flag for INFO values. Allowed values: flag name including leading '-' NDDM Model DM as an n-th order polynomial expansion in time Allowed values: integers n NITS Iterate solution n times, or fewer if it converges. Allowed values: integers n Special case: n=9: iterate until convergence NPRNT Print every 10^n TOA line in file tempo.lis Allowed values: integers n PHIMIN Minimum Earth-Pulsar-Sun angle for inclusion in analysis TOAs with angle less than PHIMIN are given zero weight Allowed values: floating point angle x in degrees PSR Pulsar name (normally without the leading B or J) Allowed values: up to 12 characters BINARY Binary model to use (see BINARY MODELS, below) Allowed values: 'NONE', 'BT', 'EH', 'DD', 'DDGR', 'H88', 'BT+', 'DDT', 'MSS', 'ELL1', 'BT1P', 'BT2P' START Ignore TOAs before this date (MJD) (if flag is nonzero) Allowed values: single-precision real numbers Allowed flags: integers; START will be used only if flag is nonzero FINISH Ignore TOAs after this date (MJD) (if flag is nonzero) Allowed values: single-precision real numbers Allowed flags: integers; FINISH will be used only if flag is nonzero GAIN Fraction of correction added to each parameter on each iteration Allowed values: positive real numbers Default value: 1 TZRMJD Reference toa for phase prediction Allowed values: MJD (integer, fraction read separately) TZRFRQ Frequency of reference TOA for phase prediction Allowed values: float TZRSITE Observatory of referendce TOA for phase prediction Allowed values: observatory site codes Parameters which may be set in free-format headers: RA Right Ascension ('hhmmss.sssssss' or 'hh:mm:ss.sssssss') DEC Declination ('-ddmmss.ssssss' or '-dd:mm:ss.ssssss') PMRA Proper motion in RA direction (mas/yr) PMDEC Proper motion in Declination (mas/yr) PMRV Radial 'proper motion' (mas/yr) BETA Ecliptic latitude (degrees) LAMBDA Ecliptic longitude (degrees) PMBETA Proper motion in ecliptic latitude (mas/yr) PMLAMBDA Proper motion in ecliptic longitude (mas/yr) PX Parallax (mas) PEPOCH Epoch of period/frequency parameters and position (MJD) (not fit) POSEPOCH Epoch of position (MJD); default is PEPOCH (not fit) F0 Pulsar rotation frequency (s-2) F Alternative for F0 F1 Pulsar rotation frequency derivative (s^-2) (if flag 2..9,A..C, fit multiple rotation frequency derivatives) F2 Pulsar rotation frequency second derivative Fn Pulsar rotation frequency n'th derivative; n=2..9,A..C P0 Pulsar period (s). Alternative for 'F0' P Alternative for P0 P1 Pulsar period derivative (10^-15). Alternative for 'F1' (if flag>1, fit multiple rotation frequency derivatives) DM Dispersion measure (pc cm^-3) (if flag 2..9,A, fit n time derivative(s) of DM, n=1..9) DMn n'th time derivative of dispersion measure; n=1..9 DMX_n DM value in n'th DMX segment (pc cm^-3) DMX1_n DM time derivative in n'th DMX segment DMXEP_n Epoch of n'th DMX segment (MJD) (not fit) DMXR1_n Start date of n'th DMX segment (MJD) (not fit) DMXR2_n End date of n'th DMX segment (MJD) (not fit) A1_n Projected pulsar semi-major axis of n'th orbit (n=1,2,3; default 1) E_n Eccentricity of n'th orbit (n=1,2,3; default 1) T0_n Epoch of periastron passage of n'th orbit (MJD) (n=1,2,3; default 1) TASC Epoch of ascending node passage (MJD) PB_n Period of n'th orbit (days) (n=1,2,3; default 1) OM_n Longitude of periastron passage, n'th orbit (deg) (n=1,2,3; default 1) FB Frequency of orbit (n=10) FB_n n'th time derivative of frequency of orbit (n=10) FBJ_n Jump in orbital frequency (n=10) TFBJ_n Time of n'th jump in orbital frequency (n=10) EPS1 First Laplace parameter [eccentricity times sin(omega)] EPS2 Second Laplace parameter [eccentricity times cos(omega)] EPS1DOT Time derivative of EPS1 EPS2DOT Time derivative of EPS2 OMDOT Rate of periastron advance (deg/yr) OM2DOT Second time derivative of angle of periastron (rad/s^2) XOMDOT Rate of periastron advance minus GR prediction (deg/yr) PBDOT Rate of change of orbital period (10^-12) XPBDOT Rate of change of orbital period minus GR prediction (10^-12) GAMMA Time dilation & gravitational redshift (s) PPNGAMMA PPN parameter gamma SINI Sine of inclination angle MTOT Total system mass (solar masses) M2 Companion mass (solar masses) DR Relativistic deformation of the orbit (not fit) DTHETA Relativistic deformation of the orbit (-6) XDOT Rate of change of projted semi-major axis (10^-12 s/s) XDOT_1 Alias for XDOT (note different unit convention than XDOT_2, etc.) XDOT_n n'th derivative of projected semi-major axis n=2..9 (1/s,1/s^2,etc) X2DOT Second time derivative of projected semi-major axis (1/s) EDOT Rate of change of eccentricity (-12) AFAC aberration geometric factor (sin(eta)/sin(lambda)) A0 aberration parameter (microsec) (not fit) B0 aberration parameter (microsec) (not fit) BP tensor multi-scalar parameter beta-prime (not fit) BPP tensor multi-scalar parameter beta-prime-prime (not fit) GLEP_n Epoch of glitch n, n=1..9 (MJD) (not fit) GLPH_n Glitch n phase increment GLF0_n Permanent glitch n pulse frequency increment (s^-1) GLF1_n Permanent glitch n frequency derivative increment (s^-2) GLF0D_n Decaying glitch n frequency increment (s^-1) GLTD_n Decay time constant for glitch n (days) JUMP_n Time offset for segment n defined by "JUMP" TOA command JUMP -f v Tempo2-style flag-based JUMP syntax (f=flag name, v=flag value) FIXED FORMAT HEADER If a 'fixed-format' header is used, there is a single primary input file (though additional TOAs and commands may be incorporated via the INCLUDE command; see TOA COMMANDS). The first line of the file contains a series of one-character flags indicating which model parameters should be fit, and controlling characteristics of the fit. Flag locations within the first line are listed under 'Header Flag Column' below. Parameter values themselves are contained on subsequent lines: Header --Parameter-- Flag ----Value---- Column Line Columns Parameter 1 RPHASE 2 1-12 PSRNAME 5 21-40 RA*** 6 41-60 DEC*** 7 61-70 PMRA 8 71-80 PMDEC 2 3 2-20 P0 3 21-40 P1 41-60 PEPOCH 4 61-70 P2 17 71-80 PX 16 4 9-20 DM 9 5* 1-20 A1 10 21-40 ECC 11 41-60 T0 12 61-80 PB**** 13 6* 1-10 OM 14 11-20 OMDOT [nbin!=4] XOMDOT [nbin==4] 15 21-30 GAMMA 18 31-40 PBDOT [nbin!=4] XPBDOT [nbin==4] 20 41-50 SINI 21 51-60 MTOT 22 61-65 M2 [nbin!=7] 66-70 DR [nbin!=7] 23 71-74 DTHETA [nbin!=7] 75-78 A0 [nbin!=7] 79-80 B0 [nbin!=7] 19 61-70 M1 [nbin==7] 24 71-75 BP [nbin==7] 25 76-80 BPP [nbin==7] ** 1-5 Flags for GLPH, GLF0P, GLG1P, GLG0D, GLDT ** 11-22 Glitch epoch ** 23-34 Glitch phase increment ** 35-46 Permanent glitch pulse frequency increment ** 47-58 Permanent glitch frequency derivative ** 59-70 Decaying glitch frequency increment (s^-1) ** 71-82 Decaying glitch time constant (days) Notes: * Lines 5 and 6 contain parameters for the first orbital companion. Parameters for two additional orbital companions may be listed on lines 7-8 and 9-10. These orbits are may only have Keplerian parameters (all columns of first line, columns 1-10 or second line). Flags are in columns 51-55 and 56-60. ** Lines containing glitch parameters start immediately after the lines for pulsar and binary parameters. *** RA and DEC have form hhmmss.ss and ddmmss.ss **** PB is in seconds, not days (as in free-format headers) Several control flags are also set in the first line: Header Flag Column Line Notes 27 NBIN Binary model: 0=none 1=BT 2=EH 3=DD 4=DDGR 5=H88 6=BT+ 7=DDT 8=DD+ 9=2 BT orbits a=3 BT orbits 29 NPRNT List residuals every 10^NPRNT lines 33 ITERS Number of iterations 40 NGL Number of glitches 42 NDDM Use DM corrections if NDDM=1 44 NCLK 0=observatory clock, 1=UTC(NIST), 2=UTC, 3=TT(BIPM), 4=UT(PTB), 5=AT1 46 EPHEM Ephemeris number (must be 1 for DE200; formerly 0 for PEP740R was also allwed) 47 COORDS Input coordinates (0=B1950, 1=J2000) BINARY MODELS Summary Reference: Taylor, J. H., & Weisberg, J. M., ApJ 345:454 (1989) BT Newtonian orbit at a given epoch, plus secular changes in the orbital elements and redshift/time-dilation parameter gamma. Reference: Blanford, R., and Teukolsky, S. A., ApJ 205: 580 (1976) EH Relativistic model incorporating short-term periodic terms, including Shapiro time-delay parameter and non-constant periastron advance in the orbital motion, along with the Shapiro time-delay parameter References: Epstein, R., ApJ 216: 92 (1977) Epstein, R., ApJ 231: 644 (1979) Haugan, M. P. ApJ 296: 1 (1985) DD Theory-independent relativistic model; includes treatment of short-term periodic terms, Shapiro delay and aberration. References: Damour, T., and Deruelle, N. Ann Inst. H. Poincare (Physique Theorique) 43: 107 (1985) Damour, T., and Deruelle, N. Ann Inst. H. Poincare (Physique Theorique) 44: 263 (1986) DDGR Variation of DD model in which general relativity is assumed correct, so free parameters are (in principle) only m1, m2. Tempo also allows two further free parameters, XPBDOT and XOMDOT, to measure deviations from GR values of PBDOT and OMDOT. References: Taylor, J. H., in General Relativity and Gravitation, ed. M. A. H. MacCallum (Cambridge Univ. Press), p. 209 (1987) Taylor, J. H., & Weisberg, J. M., ApJ 345:454 (1989) H88 Re-parameterized EH model Reference: Haugan, M. P. 1988. Preprint. (See Taylor & Weisberg 1989.) BT+ BT model with nonlinear periastron advance. DDT DDGR modified to test two-parameter tensor-biscalar theories Reference: Taylor, J. H., Wolszczan, A., Damour, T., and Weisberg, J. M. Nature, 355: 132 (1992) MSS Model for main-sequence/pulsar binaries. Reference: Wex, N., astro-ph/9706086 (1997). ELL1 Model for low eccentricity orbits using Laplace parameters (EPS1=e times sin(omega), EPS2=e times cos(omega)) instead of e, omega. Reference: Wex, N., unpublished. BT1P BT model with two orbits: the first may be relativistic, the second must be Keplerian BT2P BT model with three orbits: the first may be relativistic, the second and third must be Keplerian BTX BT model with orbital motion expressed in frequency rather than period. Orbital frequency may vary, either through instantaneous jumps in binary frequency (jump size FBJ_x at time TFBJ_x) or through a Taylor expansion around T0 (FB_x is x'th derivative of binary frequency). Orbit size may also be written as a taylor expansion (XDOT_x is x+1'th derivative of X=A SIN I) Reference: Nice, D., unpublished The following table summarizes the parameters used by each model. An 'x' indicates a parameter fully implemented. An 'o' indicates the parameter is used at a fixed value, but cannot be fitted. A '*' indicates the parameter is used only to calculate other binary parameters, and is then ignored. BT EH DD DDGR H88 BT+ DDT MSS ELL1 BTX A1 x x x x x x x x x x E x x x x x x x x * x T0 x x x x x x x x * x PB x x x x x x x x x * OM x x x x x x x x * x TASC * x EPS1 * x EPS2 * x FB * * * * * * * * * x FB_1 * * * * * * * * * x FB_x x OMDOT x x x x x x x x OM2DOT x x XOMDOT x PBDOT x x x x x x x x * XPBDOT x GAMMA x x x x x x x MTOT x x M2 x x x x x SINI x x x x x x DTHETA x x XDOT x x x x x x x x x X2DOT x XDOT_x x EDOT x x x x x x x x x EPS1DOT x EPS2DOT x DR o o o AFAC o A0 o o o o B0 o o o BP o BPP o TOA LINES TOAs are entered, one per line, in one of four formats, called 'Princeton', 'Parkes', 'Interchange TOA (ITOA)', or 'Tempo2' format. TOAs in Princeton, Parkes and Tempo2 formats are assumed to be referenced in an observatory time scale (see TIME SCALES, below). TOAs in ITOA format are assumed to be referenced to UTC. TOAs are reported as MJD, except that TOAs reported using the Princeton format may also be MJD-39126 (also called '1966 day number'). Use of the latter is discouraged. One-character observatory codes correspond to lines in the observatory coordinate file for '1' through '9' and 'a' through 'z'. Code '0' indicates the geocenter. Code '@' indicates the solar system barycenter (for which neither geometric nor clock corrections are applied). The two-character observatory codes used in the ITOA format are given in the observatory coordinate file. In Tempo2 format either the one-character or two-character codes can be used. Princeton Format columns item 1-1 Observatory (one-character code) 2-2 must be blank 16-24 Observing frequency (MHz) 25-44 TOA (decimal point must be in column 30 or column 31) 45-53 TOA uncertainty (microseconds) 69-78 DM correction (pc cm^-3) Parkes Format columns item 1-1 must be blank 26-34 Observing frequency (MHz) 35-55 TOA (decimal point must be in column 42) 56-63 Phase offset (fraction of P0, added to TOA) 64-71 TOA uncertainty (microseconds) 80-80 Observatory (one-character code) ITOA Format columns item 1-2 ignored, but must not be blank (often PSRNAME goes here) 10-28 TOA (decimal point must be in column 15) 29-34 TOA uncertainty (microseconds) 35-45 Observing frequency (MHz) 46-55 DM correction (pc cm^-3) 58-59 Observatory (two-letter code) Tempo2 Format This format uses whitespace-separated fields rather than fixed column locations for the contents. To use this format, the first line of each TOA file must contain the command 'FORMAT 1'. field item 1 Name of profile data file (ignored but must not be blank) 2 Observing frequency (MHz) 3 TOA 4 TOA uncertainty (microseconds) 5 Observatory (one- or two-character code) 6+ Optional flags (see below) Tempo2 Flags Following the five basic fields, Tempo2 format TOA lines can optionally contain any number of flags in the format "-flag value". Flags may be used for JUMP or INFO statments (see Free-format header manual section). Additionally, the following flags are currently understood by tempo: flag description -to The floating-point value in seconds is added to the TOA, as if a TIME command. -padd The floating-point value in turns in added to the computed pulse phase, as if a PHASE command. TOA COMMANDS Numerous commands may be interspersed with the TOA lines. Command lines have the format 'keyword [parameter]'. The command must start in column 1. Blank space(s) separate the keyword and parameter (if any). Note that TOA commands may not be used in the header. DITHER x Add Gaussian noise with rms=x us. EFAC x Multiply uncertainties by x EMAX x Ignore TOAs with residual higher than x us EMAP x Ignore TOAs with residual higher than x pulse periods EMIN x Set minimum uncertainty to x EQUAD x Additional uncertainty in us, added in quadrature FMAX x Ignore TOAs at frequencies higher than x FMIN x Ignore TOAs at frequencies lower than x FORMAT x x=1, parse TOAs in Tempo2 format; x=0, parse standard formats INCLUDE x Insert contents of file x here; may be used recursively INFO x Write x to info.tmp for subsequent TOAs (until next INFO card) JUMP Beginning or end of a jump segment MODE x x=0, no weighting; x=1, use estimated uncertainties NOSKIP End of a SKIP segment PHA1 x Ignore orbital phases between x and y (see PHA2) PHA2 y PHASE x Add x turns of pulsar phase to subsequent TOAs SEARCH x Sets TRACK mode; inserts JUMPs to allow non-connected solution SIGMA x Set uncertainties of following TOAs to x us (forces MODE=1) SIM Enter simulation mode SKIP Skip all lines until NOSKIP is read TIME x Add x (seconds) to following TOAs TRACK x Tracks phase wrap-arounds if time step is less than x days ZAWGT Weight 1913+16 data for Arecibo zenith angle at 1400 MHz OUTPUT FILES tempo.lis ASCII format. Lists input parameters, input data (TOAs, frequencies, weights), pre-fit and post-fit residuals, best-fit parameters and uncertaities, statistics, and a crude covariance matrix. resid2.tmp Residuals, etc. Binary format. Each record contains eight real*8 values: --TOA (MJD, referenced to solar system barycenter) --Postfit residual (pulse phase, from 0 to 1) --Postfit residual (seconds) --Orbital phase (where applicable) --Observing frequency (in barycenter frame) --Weight of point in the fit --Timing uncertainty (according to input file) --Prefit residual (seconds) matrix.tmp Covariance matrix. Binary format with variable length records. The n'th record contains: --integer m (see below) --integer j (parameter index) --char*4 parameter name --real*8 generalized covariance of parameter --real*8 uncertainty of parameter --real*8(m) normalized covarinaces: a(j,k)/sig(j)sig(k),k=1..m .par ASCII format. Control parameters and name, final value, fit flag and error for pulsar parameters. Can be used as an input parameter file for TEMPO and other programs. gro.1, gro.2 Timing parameters in "GRO" format. ASCII. Produced in "GRO" mode only. gro.2 contains binary parameters where applicable. Note: for TEMPO V11.0, the name of barycentric ephemeris and the full pulsar name are appended to the gro.1 output line. gro.99 Rotation parameters translated to epoch at middle of data set. ASCII format. Produced in "GRO" mode only. polyco.dat Pulsar ephemerides. See "prediction mode (tz)" section. CONFIGURATION AND SUPPORT FILES The TEMPO environment variable must point to a directory containing configuration file tempo.cfg. In other words, the configuration file is $TEMPO/tempo.cfg. Entries in tempo.cfg are free-format, with the form 'keyword value', where value is a directory or file name as appropriate. Keywords are case-insensitive, although file names are not. tempo.cfg keywords: CLKDIR Directory containing clock offset files OBS_NIST Offsets between observatory clock and UTC(NIST) NIST_UTC Offsets between UTC(NIST) and UTC NIST_TT Offsets between UTC(NIST) and TT(BIPM) NIST_PTB Offsets between UTC(NIST) and UTC(PTB) NIST_AT1 Offsets between UTC(NIST) and AT1 UT1 Offsets between UTC and UT1 EPHDIR Directory containing ephemeris files TDBFILE Offsets between TDB and TT EPHFILE Solar system ephemeris file (from JPL distribution). There may be up to five EPHFILE entries. PARDIR Directory containing .par files for prediction mode TZDIR Directory containing 'tz.in' control file for prediction mode TZTOT Name (with absolute path) of parameter file for prediction mode (Used only in 'old-format' mode.) OBSYS Name (with absolute path) of observatory coordinate file OBS_NIST FILE (typically 'time.dat') This file contains clock offsets between observatory clocks (to which TOAs are referenced) and UTC(NIST). The first two lines of this file are ignored. Subsequent lines have the format: col item 1-9 MJD 10-21 offset1 (us) 22-33 offset2 (us) 35-35 observatory code 37-37 flag The difference offset1-offset2 is ObservatoryTime-UTC(NIST). If the flag is ' ' (blank), offsets from the two entries closest to the target MJD are linearly interpolated. If the flag is 'f', the closest entry to the target MJD is used without interpolation. Clock offsets from a given observatory must be in chronological order, but offsets from different observatories may be intermixed. NIST_UTC, NIST_BIPM, NIST_PTB, NIST_AT1 FILES These files contain clock offsets between UTC(NIST) and other timescales. The first two lines of these file are ignored. Subsequent lines have the format: col item 1-10 MJD 11-29 offset The offset is xxx-UTC(NIST) in nanoseconds, where xxx is UTC, TT(BIPM), UTC(PTB), or AT1. Linear interpolation between entries is performed. UT1 FILE (typically 'ut1.dat') This file contains values of UT1-UTC, TAI-UT1, or A1-UT1 (indicated by setting the KIND variable in the header to 1, 2, or 3, respectively). The first line of this file is ignored. Line 2 has the following format: col item 1-32 VARFMT, the format of data lines in Fortran notation 33-34 KIND 36-42 start JD (integer) 44-50 end JD (integer, set to a high value to read to end of file) 52-54 the number of entries per data line 56-58 interval, in days, between each entry on a data line 60-74 UNITS (e.g., 1E-3 means milliseconds) Subsequent lines contain a control string, MJD, and offset entries in the format described by the VARFMT variable. If the control string reads 'END', any further lines of the file are ignored. LEAP SECOND FILE File 'leap.sec' in the clkdir directory contains a list of leap seconds. One date is stored per line, in ascending order. Dates are MJDs. SOLAR SYSTEM EPHEMERIS FILE Tempo is designed to use ephemeris files produced by the Jet Propulsion Laboratory. Other ephemeridies could in principle be used, but they would have to be written in the 'binary' format used by JPL for ephemeris distribution. Binary format files containing DE200 and DE405 for the years 1950-2050 are included in the tempo v. 11 distribution. These files are suitable for machines with standard IEEE floating-point storage (e.g., Sparc, x86), with either little-endian or big-endian byte ordering. For other machines, binary format files can be generated by downloading ASCII format ephemerides and ASCII-to-binary tools from ftp://navigator.jpl.nasa.gov/export/ephem/. TDB-TT OFFSET FILE The TDB-TT offset file is a binary format generated by the program tdbgen, which is included with the Tempo software distribution. OBSERVATORY COORDINATE FILE (typically 'obsys.dat') This file contains geographical locations of observatories. There is one line per observatory. The information in the first line is used for TOAs tagged with observatory number 1, the second line for number 2, and so on. The tenth line corresponds to observatory 'a', the eleventh to 'b', and so on. Col Item ----- --------------- 1-15 coordinate 1 16-30 coordinate 2 31-45 coordinate 3 48-48 flag 51-62 observatory name 71-71 observatory number 74-75 observatory code If the flag is blank or zero, the coordinates are taken to be latitude (ddmmss.ss), longitude (ddmmss.ss), and elevation (m). If the flag is non-blank, the coordinates are taken as X, Y, Z (m) about the geocenter. The observatory code is a 2-character code used in ITOA format. PREDICTION MODE In prediction mode (indicated by '-z' on the command line, and sometimes called 'tz' mode), tempo calculates pulsar ephemerides over short periods of time (typically hours) in the form of a simple polynomial expansion. Such ephemerides are particularly useful for on-line folding of pulsar data while observing. Ephemerides are calculated on a day-by-day basis centered about the transit time of the pulsar at the observatory. The time spans of the polynomial series are specified by giving a 'maximum hour angle' for observations along with a maximum time span over which a single series must be valid. Multiple series within a day are calculated when necessary. The user is queried for start and end dates (MJD) for which ephemerides will be calculated. The list of pulsars for which ephemerides are to be produced is read from file 'tz.in'. TZ.IN FORMAT The tz.in file is a free-format, ASCII file. Items on a line may be separated by any number of spaces and tabs. The first line contains default parameters: ASITE a one-character site code (as in TOA LINES, above) MAXHADEF default maximum hour angle for observations (hr) NSPANDEF default time span per ephemeris entry (minutes) NCOEFFDEF default number of coefficients per ephemeris entry FREQDEF default observing frequency (MHz) The second and third lines are ignored. Subsequent lines contain free-format entries for individual pulsars. Only the pulsar name is required. Other values override default values (from the first line). NAME pulsar name NSPAN time span per ephemeris entry NCOEFF number of coefficients per ephemeris MAXHA maximum hour angle for observations FREQ observing frequency (MHz) PARAMETER FILES Pulsar parameters used to calculate ephemrides are read from either .par files for individual pulsars or, for 'old-format' only, from a single "tztot.dat" file. .par files If free-format headers are used (no '-o' flag in the command line), pulsar parameters for prediction mode are read from files '.par' in the 'pardir' directory (pointed to in $TEMPO/tempo.cfg). The parameters are in the format described in the FREE-FORMAT HEADERS section. Three additional parameters describe the arrival time used as the absolute reference for the ephemeris: TZRMJD Reference TOA (MJD) TZRFREQ Frequency of reference TOA (MHz) TZRSITE One-letter observatory code of reference TOA These and other parameters from a given solution are written out by TEMPO in the file '.par' in the current working directory. If such a file is to be used for prediction purposes, it should be moved to the 'pardir' directory. TZTOT.DAT file If fixed-format headers are used (indicated by command-line flag '-o'), pulsar parameters for prediction mode are read from a single 'tztot' file (pointed to in $TEMPO/tempo.cfg). For each pulsar, this file contains parameters as described for lines two and higher in FIXED-FORMAT HEADERS, above, with an additional flag parameter in the first column of the second line of the entry. Allowed flag values are: Flag Coordinates Binary model ---- ----------- ------------ B B1950 BT C J2000 BT D J2000 BT1P E J2000 BT2P F B1950 DD G J2000 DD P B1950 NONE Q J2000 NONE The header is followed by a single TOA line used as the absolute phase reference. Parameters for different pulsars are listed sequentially in the tztot file. There is a single line between parameters sets (and before the first parameter set), which is ignored. Typically this line is filled with dashes in the tztot file. POLYCO.DAT The polynomial ephemerides are written to file 'polyco.dat'. Entries are listed sequentially within the file. The file format is: Line Columns Item ---- ------- ----------------------------------- 1 1-10 Pulsar Name 11-19 Date (dd-mmm-yy) 20-31 UTC (hhmmss.ss) 32-51 TMID (MJD) 52-72 DM 74-79 Doppler shift due to earth motion (10^-4) 80-86 Log_10 of fit rms residual in periods 2 1-20 Reference Phase (RPHASE) 21-38 Reference rotation frequency (F0) 39-43 Observatory number 44-49 Data span (minutes) 50-54 Number of coefficients 55-75 Observing frequency (MHz) 76-80 Binary phase 3* 1-25 Coefficient 1 (COEFF(1)) 26-50 Coefficient 2 (COEFF(2)) 51-75 Coefficient 3 (COEFF(3)) * Subsequent lines have three coefficients each, up to NCOEFF The pulse phase and frequency at time T are then calculated as: DT = (T-TMID)*1440 PHASE = RPHASE + DT*60*F0 + COEFF(1) + DT*COEFF(2) + DT^2*COEFF(3) + .... FREQ(Hz) = F0 + (1/60)*(COEFF(2) + 2*DT*COEFF(3) + 3*DT^2*COEFF(4) + ....) AUTHORS J. H. Taylor, R. N. Manchester, D. J. Nice, J. M. Weisberg, A. Irwin, N. Wex and others. Ephemeris routines by E. M. Standish, NASA/JPL. SEE ALSO lk, matrix, tdbtt, .... BUGS There are no bugs, only features. And plenty of 'em.