NAME

ftleapsec - calculate number of leap seconds at requested epoch

USAGE

ftleapsec timeref offset

DESCRIPTION

The ftleapsec task computes the number of seconds at a requested epoch. One can optionally add a number of elapsed seconds since the epoch.

There are three probable use cases for ftleapsec.

CASE 1: Calendar Date. One use case is to calculate the number of leap seconds at a given UTC calendar date. In this case, use

  ftleapsec YYYY-MM-DDThh:mm:ss 0 relative=NO
where YYYY-MM-DDThh:mm:ss is the UTC epoch of interest. The 0 indicates no offset from the specified calendar date. The hours minutes and seconds are optional. The returned value is number of leap seconds since the start of atomic timekeeping.

CASE 2: Mission Elapsed Time. Another use case is to calculate the number of leap seconds at a given mission elapsed time (MET). Typically X-ray astronomy missions have time systems that begin at a fixed UTC epoch, and then count number of seconds from that epoch. In this case use

  ftleapsec YYYY-MM-DDThh:mm:ss MET
where YYYY-MM-DDThh:mm:ss is the mission epoch and MET is the mission elapsed time in seconds. The returned value is the number of leap seconds since the specified mission epoch. Use relative=NO if the total number of leap seconds is desired.

CASE 3: Unix / POSIX Time. The final use case is to calculate the number of leap seconds at a given Unix timestamp. Unix times are seconds elapsed since 1970-01-01 (UTC). However, the rules for leap seconds are applied somewhat differently under the Unix POSIX rules. To calculate correctly, use the following

  ftleapsec 1970-01-01 unix_time offsetrule=POSIX
where unix_time is the Unix timestamp in seconds. The returned value is the number of leap seconds since 1970-01-01 (UTC).

OUTPUT OPTIONS

ftleapsec has several output options, which are controled by the relative and chatter parameters.

If relative=NO then the task will report the total number of leap seconds since the start of atomic timekeeping. This is a cumulative number that accumulates over time. If relative=YES, then the task will report the number of leap seconds that have elapsed since the requested calendar epoch. By definition if offset=0, then the number of reported relative leap seconds is zero.

The chatter parameter governs how verbose the output is. Script and program writers should use chatter=1. In this mode, a single integer number is printed to standard output, which is the requested number of leap seconds, either relative or absolute.

However, if chatter=3, a more verbose report is printed. This is a handy diagnostic report for human inspection, but not so helpful for scripting. Here is an example.

$ ftleapsec 2014-01-01 135478925 chatter=3
 Reference date: 2014-01-01T00:00:00
           Date: 2018-04-18T01:02:03
   Leap seconds: 37 (since start of atomic timekeeping)
   Leap seconds: 2 (since reference epoch)
Note that in this mode, the task prints both the total number of leap seconds since atomic time keeping, as well as the relative number of leap seconds since the 2014-01-01 epoch.

INPUT LEAP SECOND DATA

By default ftleapsec uses the leap second file distributed within HEASoft, which can be found in $LHEA_DATA/leapsec.fits.

However, the user can specify a different input file using the leapfile parameter.

POSIX LEAP SECOND RULES

Unix (a.k.a. POSIX) has odd rules for leap seconds. In a sense, leap seconds are ignored. Every UTC midnight is treated as occurring at an integer multiple of 86400 seconds starting from 1970-01-01T00:00:00 (UTC). In reality this is not true because leap seconds create discontinuities when they are inserted. However, POSIX rules "ignore" this oddity.

When the user desires to compute number of leap seconds using Unix/POSIX rules, the offsetrule=POSIX should be used.

ACCURACY

The task is designed to report leap seconds accurately for input epochs within one second of leap second rollover. Fractional input seconds are not supported.

In order to handle the case of input time near a leap second epoch, the task iteratively computes the number of leap seconds, in order to achieve the required accuracy.

PARAMETERS

timeref="2000-01-01" [string]
Reference epoch specified as either YYYY-MM-DD, YYYY-MM-DDThh:mm or YYYY-MM-DDThh:mm:ss. All times as UTC calendar dates.
offset=0 [real]
Offset from the reference epoch, in seconds.
(offsetrule="MET") [string]
Rule for computing time offsets when offset > 0. Either "MET" or "POSIX".
(leapfile="FTOOLS") [string]
Leap second file to use, or "FTOOLS". If "FTOOLS" is specified, then the standard HEASoft reference leap second table is used.
(relative=YES) [boolean]
When chatter=1, the output is either relative number of leap seconds since epoch (relative=YES), or total number of leap seconds (relative=NO).
(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 1) [integer, 0 - 5]
Amount of verbosity of the task. For chatter=0, no output is printed. For chatter=1, a single integer number of leap seconds is reported. For chatter=3, a brief human-readable report is produced. For chatter=5, debugging output is printed.

(history = YES) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

See above.

SEE ALSO

sec2time, time2sec, barycorr