Skip to content

Commit 3e4b03e

Browse files
committed
Change epoch of TimeUnixTAI to 1970-01-01T00:00:00.0 TAI, fixes astropy#11245
* TimeUnixTAI (name unix_tai) used the epoch ``1970-01-01T00:00:00 UTC`` since its introduction in astropy 4.2, however, contrary to the documented behaviour, this is not the definition of CLOCK_TAI on linux and no system using this epoch is known. * This switches the epoch to ``1970-01-01T00:00:00.0 TAI`` to match the intended defintion of being compatible to CLOCK_TAI on linux and also is the definition of the now obselete and not yet released ``TimeUnixPTP``
1 parent fad2853 commit 3e4b03e

3 files changed

Lines changed: 42 additions & 15 deletions

File tree

‎CHANGES.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,9 @@ astropy.tests
8282
astropy.time
8383
^^^^^^^^^^^^
8484

85+
- Add new time format ``unix_ptp`` (Precision Time Protocol) which provides
86+
the number of SI seconds since ``1970-01-01T00:00:00 Tai``. [#11143]
87+
8588
astropy.timeseries
8689
^^^^^^^^^^^^^^^^^^
8790

@@ -381,6 +384,12 @@ astropy.tests
381384
astropy.time
382385
^^^^^^^^^^^^
383386

387+
- Change epoch of ``TimeUnixTAI`` (``"unix_tai"``) from ``1970-01-01T00:00:00 UTC``
388+
to ``1970-01-01T00:00:00 TAI`` to match the intended and documented behaviour.
389+
This essentially changes the resulting times by 8.000082 seconds, the initial
390+
offset between TAI and UTC. [#11249]
391+
392+
384393
astropy.timeseries
385394
^^^^^^^^^^^^^^^^^^
386395

‎astropy/time/formats.py‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -690,10 +690,19 @@ def _default_scale(self):
690690

691691
class 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

711720
class 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

‎astropy/time/tests/test_basic.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1448,9 +1448,9 @@ def test_set_format_basic():
14481448

14491449
def test_unix_tai_format():
14501450
t = Time('2020-01-01', scale='utc')
1451-
assert allclose_sec(t.unix_tai - t.unix, 29.0)
1451+
assert allclose_sec(t.unix_tai - t.unix, 37.0)
14521452
t = Time('1970-01-01', scale='utc')
1453-
assert allclose_sec(t.unix_tai - t.unix, 8.2e-05)
1453+
assert allclose_sec(t.unix_tai - t.unix, 8 + 8.2e-05)
14541454

14551455

14561456
def test_set_format_shares_subfmt():

0 commit comments

Comments
 (0)