File deltat-interface.spe, version 1.10, released 96/11/15 at 07:33:27. 961113 LRD add keywords for breakdown of link delay at clock setting, and additional keywords regarding earth station internal timing; rev F. 950419 LRD change validity encoding method, minor wording changes; rev E. 950302 LRD accommodation of IMOG comments, rev D. 941130 GIL convert file format to FITS, rev C. 941118 LRD add TAPETIME record type, rev B. 941010 LRD minor changes. 940716 LRD extensive revision, rev A. 920920 DMV original issue NATIONAL RADIO ASTRONOMY OBSERVATORY Green Bank, West Virginia SPECIFICATION: A34300N004F DATE: 1996 November 13 TITLE: Time Corrections File Interface PREPARED BY: L. D'Addario, G. Langston 1.0 INTRODUCTION The Time Corrections File, or "DeltaT File," is intended for use at a correlator to correct the times written into the tape headers for errors in the timing reference received at the spacecraft. The corrections are computed at the end of each tracking pass from various measurements made in real time [1]. The corrections are provided at a uniform rate, normally 10 per second, so this file is mainly a time series of these corrections. The file format makes use of the Flexible Image Transport System (FITS), which was originally developed for storing astronomical images [3] and has now been adopted as a NASA standard and is maintained by the NASA Office of Science and Technology [4]. Public domain software to assist in writing and reading such files is available. This specification is intended to give a complete description of the file, but some details that are covered in the references are omitted here. Study of the references should not be necessary to understand this document, but would be necessary to implement its requirements. 2.0 LOGICAL CONTENT OF THE FILE Each time correction value in the file represents the earth station's best estimate of the time to be ADDED to the time written on the wideband data tape ("tape time") in order to obtain the actual time (in UTC) that the first sample in the corresponding tape record was taken on the spacecraft. Each correction is labeled with the station UTC at which the corresponding two-way timing link signal was received on the ground, and it applies to the data sample that was received at the same time. It is not practical to label the corrections with tape time, so they must be interpolated to the desired tape time by the user; however, at the special epoch when the tape clock is initialized, both the tape time and the corresponding (high precision) station UTC are known and are given in this file. Calculation of the correspondence for other epochs is the responsibility of the user. To facilitate this, and to serve as a check on the determination of the correspondence, the file may optionally contain pairs of tape time and station time at epochs other than the clock setting epoch, if these can be determined at the earth station. Additional discussion of this is given in section 4.3. The reported values of the corrections include the results of measurements of the residual phase on the two-way timing link to the spacecraft. These may vary fairly rapidly; they are expected to have a bandwidth of 1 to 2 Hz under unstable atmospheric conditions, but no guarantee is given that their spectrum will not fill the entire 5 Hz that is representable by the 10 Hz sampling rate. (See 3.2.4 regarding the possibility of using other sampling rates.) In addition, the reported values include corrections for various effects, mostly slowly varying, as discussed in the next paragraph. It is the responsibility of each earth station's operators (and not the correlators' operators) to provide the best possible values of the time corrections by including all known and significant effects, especially local effects that may be different for each station. This includes any known error in the station clock, and any known variation in cable delays or electronics or antenna geometry that is not cancelled by the round-trip timing link to the spacecraft. It should also include a model of the effects of non-reciprocity of the signal path, whether caused by geometrical effects or the medium. Further details of the calculations involved are given in [1] and [2]. For the Green Bank station, a separate document will describe in detail all effects for which corrections are applied, along with the methods used to determine them. Other stations are encouraged to provide similar information. By convention, each DeltaT file delivered by an earth station should contain data from only one tracking pass, and thus from only one satellite and one earth station. However, nothing in the format enforces this constraint, so data from various passes and stations could later be combined into one file if that proves to be convenient. 3.0 FILE FORMAT 3.1 Overall Description. The file shall be a FITS Table File [3]. Such a file consists of header "keywords" describing the contents of the file; table "keywords" describing each individual table; and binary data tables, which are multi-dimensional arrays of numbers. 3.1.1 File Header Keywords, general. These keywords describe the origin and contents of the file. A set of FITS keywords is required to indicate that the file is a valid FITS file; these are not described here (see [4].) Other header keywords, as given below, are optional to generic FITS file readers but are required for DeltaT files. 3.1.2 Header Keywords Required. A DeltaT File shall contain at least the following header keywords. Keyword Interpretation ======== ============================================ DATE-OBS Date of the earliest data in this file. (Eight character string date "dd/mm/yy" UTC) DATE-MAP Date when this file was created. (Eight character string date "dd/mm/yy" UTC) VERSION File version number. This entry and DATE-MAP are provided in case errors are discovered in the file after it has been transmitted, so that a corrected version needs to be generated; or in case new information allows a more accurate version to be generated. (This is a number string representing an integer, initially zero, and incremented each time a new version is generated.) TELESCOP Spacecraft identification. At this time, three identifiers are defined: "VSOP_SC", "RA_SC" or "SU_SC". OBSERVER Earth station identification. At this time, the following identifiers are defined: "TDBIN_TS", "GOLDS_TS", "PUSHN_TS", "GBANK_TS", "USSUR_TS", "EVPAT_TS", MADRD_TS" or "USUDA_TS." (These keyword names are also used by the Astronomical Image Processing System (AIPS). Re-using them makes it easy for the file to be examined by reading it into AIPS, where the tables can be printed or plotted.) 3.2 DELTA_T Tables. Each file shall include one or more tables containing the time correction data. A separate table must be generated for the data following each clock setting event. (See also discussion in 4.2, below.) 3.2.1 DELTA_T Table Keywords. At least the following keywords shall be included with each DELTA_T table. Keyword Interpretation ======== ====================================================== EXTNAME The string "DELTA_T", indicating the type of table. EXTVER Integer enumerating the order of tables in this file. The first "DELTA_T" table will have EXTVER=1 and the value will be incremented for each successive table, in order of increasing time. SAMPRATE Sampling rate of the time correction values in this table, in Hz. The normal value is 10.0 Hz exactly. (See discussion in 3.2.4, below.) DATE Modified Julian Day number (MJD) of GND_TIME, TAPETIME, and UTC_DATA, below. GND_TIME UTC of the clock setting event, in seconds. (See 3.2.5.) TAPETIME Time label on the tape of the clock setting event, in seconds. This will normally be an integer, and therefore might correspond to the time in an actual tape header, but this is not guaranteed. There will not necessarily be a tape frame written that contains a sample at this time, but any tape time label that is later than this time (and earlier than the TAPETIME in a subsequent DELTA_T table) has been determined by this clock setting event. UTC_DATA UTC of the first time correction value in this table, in seconds. (See 3.2.5.) This time must be *earlier* than the clock setting event given by GND_TIME. (This ensures that succeeding time corrections will contain two values that span the clock setting event, so the correction at the time of clock setting can be obtained by interpolation if desired.) All succeeding values in the table occur at intervals of 1/SAMPRATE. Note that there are no time tags internal to the table. SC_DEL The portion of the time corrections due to the estimated delay within the spacecraft at the clock setting event, in seconds. (See additional discussion in 3.2.6.) GEOM_DEL The portion of the time corrections due to the estimated geometrical delay on the downlink at the clock setting event, in seconds. This is just the estimated range at clock setting divided by the speed of light in vacuum. (See 3.2.6.) TROP_DEL The portion of the time corrections due to the estimated additional delay on the downlink due to the troposphere, at the clock setting event, in seconds. (See 3.2.6.) ION_DEL The portion of the time corrections due to the estimated additional delay on the downlink due to the ionosphere, at the clock setting event, in seconds. (See 3.2.6.) DCLOCK Difference between the station clock reading and true UTC, at the clock setting event, in seconds. A positive value indicates that the clock reading is later than true UTC. (See 3.2.7.) RCLOCK Average error in the rate of the station clock during the time covered by this DELTA_T table, dimensionless. A positive value indicates that the clock reading is advancing faster than true UTC. Specifically, RCLOCK = dT/dt - 1, where T is the clock reading and t is true UTC. (See 3.2.7.) SIG_DEL Estimated signal delay in the earth station between arrival of the sample labeled by TAPETIME at the antenna reference point and its arrival at the point where its time is measured by reference to the station clock, in seconds. (See 3.2.7.) PHA_DEL Estimated delay in processing phase residual measurements within the earth station, seconds. This is the difference between the true UTC of arrival of the timing downlink signal at the antenna reference point and the time tag assigned to the corresponding phase residual measurement when it is first recorded. (See 3.2.5 and 3.2.7.) TTYPE1 Name of the first (and only) column of the table: "DELTA_T". TUNIT1 Units of the first column of the table: "SECONDS". TFORM1 Data type of first column: "1D", which denotes one IEEE double precision number. Note: "TAPETIME", "GND_TIME", and "UTC_DATA" are all measured from midnight of the date given by "DATE". In case a clock setting event occurs very near midnight, it is possible that one or more of these times will have a slightly negative value, or a value slightly larger than the number of seconds in a day. (We will try to avoid having clock setting events occur at such a time.) 3.2.2 DELTA_T Values. Each entry of the DELTA_T table contains one time correction value (see 2.0 for a precise definition of "time correction value"). The first value in the table applies to the data sample that arrived at the earth station at UTC_DATA. Succeeding values throughout the entire table apply to data samples that arrived at intervals of precisely 1/SAMPRATE thereafter. 3.2.3 Invalid values. If error conditions are detected at the earth station which imply that some DELTA_T values may be invalid, then each such value shall be replaced by a special bit pattern, namely 0xFFF0000000000000. This pattern is the IEEE code for "-infinity," and therefore it could not be a valid DELTA_T value. Users should detect the presence of this code and avoid attempting to derive time corrections from it. 3.2.4 SAMPRATE. The standard sampling rate shall be exactly 10.0 Hz; all earth stations and correlators shall support DeltaT files that use this sampling rate. The use of other rates is optional, and it is the responsibility of each earth station-correlator pair to ensure that a compatible rate is used. (See also 4.1.) 3.2.5 Station Times. All values of UTC, including DATE, GND_TIME, and UTC_DATA, refer to the time of arrival of the corresponding downlink signal at the earth station's antenna reference point, NOT the time that a measurement was made nor the time that the result was recorded by the station. That is, these times should take into account any delays that occur within the station so that the information in this file is independent of such delays, to the extent that they are known. (Errors in this accounting that are sufficiently small and sufficiently stable should be unimportant. Specifications for absolute accuracy are correlator dependent.) 3.2.6. Link Delay. The time correction value at the clock setting event must be GND_TIME - TAPETIME - LINK_DELAY, where LINK_DELAY is the earth station's best estimate of the interval between creation (on the spacecraft) of the data sample to be labeled with TAPETIME and the reception of that sample at the earth station antenna's reference point. The value of LINK_DELAY at the clock setting event is to be given in keywords of this table as four separate components, such that LINK_DELAY = SC_DEL + GEOM_DEL + TROP_DEL + ION_DEL. SC_DEL is the interval from sample creation to radiation from the downlink antenna. For each keyword, the best estimate available at the time of file creation shall be used, in an attempt to provide timing that does not require further adjustment at a correlator. The breakdown is required in order to allow correlators to substitute a more accurate estimate of one or more components, if necessary. The true value of each of these components must be positive. Setting the corresponding keyword to zero indicates that its value was completely unknown at the time of file creation. 3.2.7. Earth Station Internal Timing. The definitions of keywords DCLOCK, RCLOCK, SIG_DEL, and PHA_DEL are dependent on a particular conceptual design of an earth station. If any of them is not appropriate to the actual design of a particular station, then its value shall be set to zero. In the conceptual design, the time of the sample to be labeled with TAPETIME is recorded by the station clock SIG_DEL later than GND_TIME, due to a delay through the station hardware. Furthermore, the station clock is in error by DCLOCK with respect to true UTC. Therefore, the station calculates GND_TIME = T - DCLOCK - SIG_DEL, where T is the recorded clock reading for that sample. It is further assumed that the same station clock drives all aspects of station operation (including generation of uplink and downlink signals) throughout the tracking pass, and that its error varies linearly with time at the rate given by RCLOCK. For PHA_DEL, the conceptual design includes assigning a temporary time tag to each phase residual measurement and later adding PHA_DEL to determine the times assigned to the time correction values of this table; in practice, this should affect only the value of UTC_DATA. Whether or not this conceptual design is appropriate, the earth station must account for all known errors in station timing when computing the DELTA_T values in this table. The parameters given in these keywords are for information only, and are not normally needed by correlators to make use of the time corrections. All of this information has already been incorporated into the table; in particular, SIG_DEL is included in GND_TIME and PHA_DEL is included in UTC_DATA. 3.3 TAPETIME Tables. The file may optionally contain one or more additional tables that give the correspondence between tape time and ground time at epochs other than the clock setting epoch. Each such table shall conform to the "BINTABLE" extension. 3.3.1 TAPETIME Table Keywords. At least the following keywords shall be included with each TAPETIME table. Additional keywords required by basic FITS or by the BINTABLE extension shall also be included. Keyword Interpretation ======== ====================================================== EXTNAME The string "TAPETIME", indicating the type of table. EXTVER Integer enumerating the order of tables in the file. The first "TAPETIME" table will have EXTVER=1 and the value will be incremented for each successive table, in order of increasing time. DATE Modified Julian Day number of all times in this table. TTYPE1 Name of first column of the table: "TAPETIME". TUNIT1 Units of the first column of the table: "SECONDS". TFORM1 Data type of first column: "1D", which denotes a single IEEE double precision floating point number. TTYPE2 Name of second column of the table: "GND_TIME". TUNIT2 Units of the second column of the table: "SECONDS". TFORM2 Data type of second column: "1D", one IEEE double. 3.3.2 TAPETIME values. Each "TAPETIME" gives the value of the tape time label of the data sample that arrived at the earth station at "GND_TIME". It is recommended that the value be exactly equal to that given in a tape header, provided that tape frames were actually being written at this time. It will normally be an integral number of seconds, although this is not required. 3.3.3 GND_TIME values. Each "GND_TIME" is the (ground) UTC at which the data sample labeled on the tape by "TAPETIME" arrived at the earth station. Note that "TAPETIME" and "GND_TIME" pairs in this table give the same information as "TAPETIME" and "GND_TIME" in the DELTA_T table header, but at epochs other than the clock setting epoch. 3.3.4 The sampling interval for TAPETIME table entries must be a constant amount of tape time (not ground time), and this should remain fixed for any one tracking pass. The size of this interval is at the option of the earth station. (Recommended intervals are TBD.) If system errors prevent a GND_TIME from being determined at any particular sampling epoch, the corresponding row should be omitted from the table, but the epochs of other samples should not be affected. Note that TAPETIME values are intrinsically asynchronous with DELTA_T values, since the latter are at a constant interval of ground time. 3.3.5 Since a tracking pass may extend over midnight UTC, the GND_TIME and TAPETIME values may exceed the number of seconds in a day. 4.0 FURTHER DETAILS 4.1 The time label of the first DELTA_T value in each DELTA_T table is specified in the table header by the DATE and UTC_DATA keywords. Thereafter, the time labels of all DELTA_T values in the table are at intervals of exactly 1/SAMPRATE, which is normally 0.1 sec. These times will not generally occur on the 0.1 sec boundaries of UTC, even if the raw data on which they are based were sampled on such boundaries. This is because UTC_DATA includes the effect of the fixed delay in the station hardware between arrival of the signal from the spacecraft and obtaining a value of the timing residual. The header keyword SAMPRATE provides the sampling rate (10.0 Hz) and not the sampling interval (0.1 sec) because the former allows the normal value (and most other reasonable values) to be exactly represented in binary, whereas the latter does not. When calculating the time labels of later DELTA_T values from UTC_DATA and SAMPRATE, users should take due care to avoid loss of precision from such effects. 4.2 A New DELTA_T (and possibly TAPETIME) table shall be written whenever it is necessary to re-set the tape clock in the Formatter. This occurs at the beginning of a tracking pass after initial signal acquisition, and may occur again following a signal dropout. Brief loss of signal or degradation of the timing link may not require re-setting the clock, but may instead result in DELTA_T values being marked invalid (see 3.2.3) during the period of degradation. 4.3 The TAPETIME tables are intended to aid users in determining the correspondence between earth station time and tape time. However, the correspondence can also be computed without this data if the spacecraft orbit and the earth station location are known. The accuracy obtained depends on the accuracy of orbit knowledge, the accuracy and sampling rate of TAPETIME table values, and the accuracy of calculations done by the user. Although TAPETIME tables are optional, they shall be included in DeltaT files generated at the Green Bank station, using an interval no greater than 60 sec of tape time. However, it is recognized that some earth stations may not be able to provide accurate TAPETIME tables. Which method of time correspondence calculation will be best at each correlator is also undetermined, so it is desirable that more than one method be provided. For these reasons, is recommended that users not rely on TAPETIME tables as the primary method of determining the time correspondence. 5.0 AVAILABILITY For the NRAO station at Green Bank, the file will be available to authorized users within 24 hours of the end of a tracking pass in accordance with the procedures in [5]. REFERENCES [1] L. D'Addario, "Post-Pass Processing of the Two Way Timing Measurements." OVLBI-ES Memo 38, 4 February 1993. [2] L. D'Addario, "Details of post-processing of time correction data." OVLBI-ES Memo, to be published. Draft dated 15 Oct 1996 available from the author. [3] Wells, D. C., Greisen, E. W., and Harten, R. H., "FITS: a flexible image transport system", Astronomy and Astrophysics Supplement Series, 44, 363-370, 1981. [4] NASA Office of Standards Technology (NOST), "Definition of the Flexible Image Transport System (FITS)," document 100-1.0, 1993 June 18. Available from NOST, Code 633.2, NASA Goddard Space Flight Center, Greenbelt MD 20771. [5] L. D'Addario, "External Data Interfaces, General Requirements," NRAO Specification A34300N001, 20 Sept 1992. Available from ftp.gb.nrao.edu:ovlbi/doc/interfaces.spe.