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=NOwhere 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 METwhere 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=POSIXwhere unix_time is the Unix timestamp in seconds. The returned value is the number of leap seconds since 1970-01-01 (UTC).
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.
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.
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.
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.
See above.