Name

---

  TAI_UTC

Author

---

  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  craigm@lheamail.gsfc.nasa.gov
  UPDATED VERSIONs can be found on my WEB PAGE:
      http://cow.physics.wisc.edu/~craigm/idl/idl.html

Purpose

---

  Compute (TAI - UTC) time difference (i.e., leap seconds)

Major Topics

---

  Time

Calling Sequence

---

  LEAP = TAI_UTC(JD_UTC) ;; or,
  LEAP = TAI_UTC(JD_TAI, /INVERT)

Description

---

  The function TAI_UTC computes the difference between International
  Atomic Time (TAI) and Universal Coordinated Time (UTC), in
  seconds.
  After 01 Jan 1972, the two time systems are synchronized, except
  for a number of leap seconds added to account for the varying rate
  of rotation of the earth. While TAI is a continuous atomic time
  system, UTC is a civil time system which may have discontinuities
  where leap seconds are introduced. This function computes the
  differences between the two time systems.
  The conversion from UTC to TAI is computed as:
    JD_TAI = JD_UTC + TAI_UTC(JD_UTC)/86400
  The inversion conversion, from TAI to UTC, is computed as:
    JD_UTC = JD_TAI + TAI_UTC(JD_TAI, /INVERT)/86400
  Here JD_UTC and JD_TAI are the UTC and TAI times measured in
  Julian days respectively.
  The introduction of leap seconds is not predictable, owing to the
  non-linear processes that govern the rotation of the earth. The
  International Earth Rotation Service determines when leap seconds
  will be introduced. Thus, the user must download the history of
  leap seconds. This file can be downloaded at the following URL:
    ftp://maia.usno.navy.mil/ser7/tai-utc.dat
  NOTE - the leap second file must be kept up to date as new leap
  seconds are introduced. The file is kept internally in
  memory, but is reloaded from disk at least once per day.
  If the disk file is not available, then a copy of the file as
  available from the USNO in 2009 is used, but a warning message is
  printed.
  The leap second data can be loaded in several ways:
      1. The FILENAME keyword may specify the exact file name and path;
      2. If FILENAME is not defined, or the empty string, then
        the default location $ASTRO_DATA/tai-utc.dat is used;
        (ASTRO_DATA is a system environment variable, used by
          the IDL astronomy library to store auxiliary data files)
      3. If neither #1 or #2 are available, then the internal table
        is used.

Parameters

---

  JD - time measured in Julian days. The time being converted
        *from*.

Returns

---

  The number of seconds to be added to the input time, to arrive at
  the desired time.

Keyword Parameters

---

  INVERT - if set, then convert from TAI to UTC. If not set
            (default), then convert from UTC to TAI.
  FILENAME - a scalar string, indicating the file name containing
              leap second data. The data is only loaded once upon
              the first call, and then with a frequency determined by
              the RELOAD_EVERY keyword. If FILENAME is not
              specified or a blank string, then the leap second data
              is found using the methods described above.
              Default: not defined; i.e. TAI_UTC searches the default
                      locations
  RELOAD_EVERY - a scalar value, indicates how often the data should
                  be reloaded for long-running tasks. The value is
                  expressed in days. If the leap second data was
                  loaded more than RELOAD_EVERY days ago, then it
                  will be reloaded. Note that a value of 0 will
                  cause immediate re-load of data.
                  Default: 1 (i.e. re-load every 1 day)
 

Example

---

  For data stored in $ASTRO_DATA,
    print, tai_utc(2451544.5d) ;; Uses $ASTRO_DATA/tai-utc.dat
        32.000000
   
  For the data stored in one's home directory,
    filename = getenv('HOME')+'tai-utc.dat'
    print, tai_utc(2451544.5d, filename=filename)
        32.000000

References

---

  Definition of leap seconds.
      http://tycho.usno.navy.mil/leapsec.html
  File containing leap seconds.
    ftp://maia.usno.navy.mil/ser7/tai-utc.dat

See Also

---

  TDB2TDT, SYSTIME, CALDAT, JULDAY
 

Modification History

---

  Written and Documented, CM, Dec 2001
  Fixed array indexing errors when the requested time range falls in
    the leap second period, and the input is an array; avoided use
    of variable JDAY, which is a function clash for me, 02 Mar 2002,
    CM
  Added helpful usage message, CM, 15 Mar 2002
  Made file handling more robust (instead of crashing), CM, 19 Jul 2005
  Add 01 Jan 2006 leap second, CM, 03 Oct 2005
  Add 01 Jan 2009 leap second, CM, 21 Jul 2008
  Add documentation and the RELOAD_EVERY keyword, CM, 02 Dec 2009
  New default file location is $ASTRO_DATA/tai-utc.dat, CM, 28 Dec 2009
  Add 01 Jul 2012 leap second, CM, 2012-01-05