@@ -690,10 +690,19 @@ def _default_scale(self):
690690
691691class TimeUnix (TimeFromEpoch ):
692692 """
693- Unix time: seconds from 1970-01-01 00:00:00 UTC, ignoring leap seconds.
693+ Unix time (UTC) : seconds from 1970-01-01 00:00:00 UTC, subject to leap seconds.
694694
695695 For example, 946684800.0 in Unix time is midnight on January 1, 2000.
696696
697+ In unix time, each UTC day always has exactly 86400 seconds, even on
698+ days when leap seconds are introduced into UTC and the day is one
699+ second longer or shorter.
700+
701+ Unix time UTC is thus not a monotonically increasing time format and
702+ does not count the number of SI seconds since the epoch date, but
703+ differs from acutally elapsed time in SI seconds by the integral amount of
704+ leap seconds introduced into UTC since 1970-01-01.
705+
697706 NOTE: this quantity is not exactly unix time and differs from the strict
698707 POSIX definition by up to 1 second on days with a leap second. POSIX
699708 unix time actually jumps backward by 1 second at midnight on leap second
@@ -710,38 +719,47 @@ class TimeUnix(TimeFromEpoch):
710719
711720class TimeUnixTai (TimeUnix ):
712721 """
713- Seconds from 1970-01-01 00:00:08 TAI (see notes), including leap seconds.
722+ Unix time (TAI): SI seconds elapsed since 1970-01-01 00:00:00 TAI (see caveats).
723+
724+ This will generally differ from standard (UTC) Unix time by the cumulative
725+ integral number of leap seconds introduced into UTC since 1970-01-01 UTC.
714726
715- This will generally differ from Unix time by the cumulative integral number
716- of leap seconds since 1970-01-01 UTC. This convention matches the definition
717- for linux CLOCK_TAI (https://www.cl.cam.ac.uk/~mgk25/posix-clocks.html).
727+ This convention matches the definition of the Precision Time Protocol,
728+ https://en.wikipedia.org/wiki/Precision_Time_Protocol, which
729+ is also used by the White Rabbit protocol in High Energy Physics:
730+ https://white-rabbit.web.cern.ch/
731+ and the linux CLOCK_TAI (https://www.cl.cam.ac.uk/~mgk25/posix-clocks.html).
732+
733+ For more information on this time format definition, see:
734+ https://www-acc.gsi.de/wiki/Timing/TimingSystemButisInterface#Time
718735
719736 Caveats:
720737
721738 - Before 1972, fractional adjustments to UTC were made, so the difference
722739 between ``unix`` and ``unix_tai`` time is no longer an integer.
723740 - Because of the fractional adjustments, to be very precise, ``unix_tai``
724- is the number of seconds since ``1970-01-01 00:00:08 TAI`` or equivalently
725- ``1969-12-31 23:59:59 .999918 UTC``. The difference between TAI and UTC
741+ is the number of seconds since ``1970-01-01 00:00:00 TAI`` or equivalently
742+ ``1969-12-31 23:59:51 .999918 UTC``. The difference between TAI and UTC
726743 at that epoch was 8.000082 sec.
727- - On the day of a leap second the difference between ``unix`` and ``unix_tai``
728- times increases linearly through the day by 1.0. See also the
744+ - On the day of a positive leap second the difference between ``unix`` and
745+ ``unix_tai`` times increases linearly through the day by 1.0. See also the
729746 documentation for the `~astropy.time.TimeUnix` class.
747+ - Negative leap seconds are possible, though none have been needed to date.
730748
731749 Examples
732750 --------
733751
734752 >>> from astropy.time import Time
735753 >>> t = Time('2020-01-01', scale='utc')
736754 >>> t.unix_tai - t.unix
737- 29 .0
755+ 37 .0
738756
739757 >>> t = Time('1970-01-01', scale='utc')
740758 >>> t.unix_tai - t.unix # doctest: +FLOAT_CMP
741- 8.200000198854696e-05
759+ 8.000082
742760 """
743761 name = 'unix_tai'
744- epoch_val = '1970-01-01 00:00:08 '
762+ epoch_val = '1970-01-01 00:00:00 '
745763 epoch_scale = 'tai'
746764
747765
@@ -791,7 +809,7 @@ class TimePlotDate(TimeFromEpoch):
791809 >>> import matplotlib.pyplot as plt
792810 >>> jyear = np.linspace(2000, 2001, 20)
793811 >>> t = Time(jyear, format='jyear', scale='utc')
794- >>> plt.plot_date(t.plot_date, jyear)
812+ >>> plt.plot_date(t.plot_date, jyear) # doctest: +IGNORE_OUTPUT
795813 >>> plt.gcf().autofmt_xdate() # orient date labels at a slant
796814 >>> plt.draw()
797815
0 commit comments