Skyfield: HomeTable of ContentsAPI Reference

Dates and Time

Astronomers use several different numerical scales for measuring time. Skyfield often has to use several timescales even within a single computation. So the Time class is designed to cache each new time scale when a calculation first demands it. Further demands for the same time scale can then be satisfied without recomputing the value again.

Each time scale supported by Time is described in detail in one of the sections below. The supported time scales are:

To specify a time, first build a Timescale object by calling Skyfield’s load.timescale() routine. This downloads several data files from international authorities — the United States Naval Observatory and the International Earth Rotation Service — to make sure that Skyfield has current information about both leap seconds and the orientation of the Earth. (Both topics are covered in more detail below.)

Once you have a timescale object, which Skyfield programmers conventionally name ts, you can use its methods to create times specified using any of the time scales listed above:

# Building a date object

from skyfield.api import load
ts = load.timescale()
t = ts.utc(2014, 1, 18)

If your computer has difficulty downloading the official time scale files, try Using built-in timescale files.

The possibilities that will be explored in the course of this page are:

# All the ways you can create a Time object
# using a timescale:

ts.utc(year, month, day, hour, minute, second)
ts.utc(dt)      # Python datetime.datetime object

ts.tai(year, month, day, hour, minute, second)
ts.tai(jd=float)

ts.tt(year, month, day, hour, minute, second)
ts.tt(jd=float)

ts.tdb(year, month, day, hour, minute, second)
ts.tdb(jd=float)

ts.ut1(year, month, day, hour, minute, second)
ts.ut1(jd=float)

Once you have constructed a Time object, you can provide it to any Skyfield routine that needs it.

from skyfield.api import load

planets = load('de421.bsp')
earth = planets['earth']

# Building a date and using it with at()

ts = load.timescale()
t = ts.utc(2014, 1, 1)
print(earth.at(t).position.au)
[-0.17461758  0.88567056  0.38384886]

If you will need to use the same time value several times then it is best to create the object once, through a single method call to your timescale object, and then use that single time repeatedly in your calculations. Not only will you avoid asking Skyfield to repeatedly translate the same time value between the different time scales, but other expensive values that depend upon time are also automatically cached on the date object. (See the section on The Julian date object as cache for more details.)

UTC and your timezone

The utc parameter in the examples above specifies Coordinated Universal Time (UTC), the world clock known affectionately as “Greenwich Mean Time” which is the basis for all of the world’s timezones.

If you are comfortable dealing directly with UTC, you can simply set and retrieve it manually. You can provide its constructor with just the year, month, and day, or be more specific and give an hour, minute, and second. And not only can you attach a fraction to the seconds, but you can also freely use fractional days, hours, and minutes. For example:

# Four ways to specify 2014 January 18 01:35:37.5

t1 = ts.utc(2014, 1, 18.06640625)
t2 = ts.utc(2014, 1, 18, 1.59375)
t3 = ts.utc(2014, 1, 18, 1, 35.625)
t4 = ts.utc(2014, 1, 18, 1, 35, 37.5)

assert t1 == t2 == t3 == t4    # True!

# Several ways to print a time as UTC.

print(t1.utc)
print(t1.utc_iso())
print(t1.utc_jpl())
print(t1.utc_strftime('Date %Y-%m-%d and time %H:%M:%S'))
(2014, 1, 18, 1, 35, 37.5)
2014-01-18T01:35:38Z
A.D. 2014-Jan-18 01:35:37.5000 UT
Date 2014-01-18 and time 01:35:38

And by scraping together the minimal support for UTC that exists in the Python Standard Library, Skyfield is able to offer a now() function that reads your system clock and returns the current time as a Julian date object (assuming that your operating system clock is correct and configured with the correct time zone):

from skyfield.api import load

# Asking the current date and time

ts = load.timescale()
t = ts.now()
print(t.utc_jpl())
A.D. 2015-Oct-11 10:00:00.0000 UT

To move beyond UTC to working with actual timezones, you will need to install the third-party pytz package, either by listing it in the dependencies of your package, adding it to your project’s requirements.txt file, or simply installing it manually:

pip install pytz

Once it is installed, building Julian dates from local times is simple. Instantiate a normal Python datetime, pass it to the localize() method of your time zone, and pass the result to Skyfield:

from datetime import datetime
from pytz import timezone

eastern = timezone('US/Eastern')

# Converting US Eastern Time to a Julian date.

d = datetime(2014, 1, 16, 1, 32, 9)
e = eastern.localize(d)
t = ts.utc(e)

And if Skyfield returns a Julian date at the end of a calculation, you can ask the Julian date object to build a datetime object for either UTC or for your own timezone:

# UTC datetime

dt = t.utc_datetime()
print('UTC: ' + str(dt))

# Converting back to an Eastern Time datetime.

dt = t.astimezone(eastern)
print('EST: ' + str(dt))
UTC: 2014-01-16 06:32:09+00:00
EST: 2014-01-16 01:32:09-05:00

As we would expect, 1:32 AM in the Eastern time zone in January is 6:32 AM local time in Greenwich, England, five hours to the east across the Atlantic.

Note that Skyfield’s astimezone() method will detect that you are using a pytz timezone and automatically call its normalize() method for you — which makes sure that daylight savings time is handled correctly — to spare you from having to make the call yourself.

If you want a Time to hold an entire array of dates, as discussed below in Date arrays, then you can provide a list of datetime objects when building a Julian date. The UTC methods will then return whole lists of values.

UTC and leap seconds

The rate of Earth’s rotation is gradually slowing down. Since the UTC standard specifies a fixed length for the second, promises a day of 24 hours, and limits an hour to 60 minutes, the only way to stay within the rules while keeping UTC synchronized with the Earth is to occasionally add an extra leap second to one of the year’s minutes.

The International Earth Rotation Service currently restricts itself to appending a leap second to the last minute of June or the last minute of December. When a leap second is inserted, its minute counts 61 seconds numbered 00–60 instead of staying within the usual range 00–59. One recent leap second was in June 2012:

# Display 5 seconds around a leap second

five_seconds = [58, 59, 60, 61, 62]
t = ts.utc(2012, 6, 30, 23, 59, five_seconds)

for string in t.utc_jpl():
    print(string)
A.D. 2012-Jun-30 23:59:58.0000 UT
A.D. 2012-Jun-30 23:59:59.0000 UT
A.D. 2012-Jun-30 23:59:60.0000 UT
A.D. 2012-Jul-01 00:00:00.0000 UT
A.D. 2012-Jul-01 00:00:01.0000 UT

Note that Skyfield has no problem with a calendar tuple that has hours, minutes, or — as in this case — seconds that are out of range. When we provided a range of numbers 58 through 62 as seconds, Skyfield added exactly the number of seconds we specified to the end of June and let the value overflow cleanly into the beginning of July.

Keep two consequences in mind when using UTC in your calculations.

First, expect an occasional jump or discrepancy if you are striding forward through time using the UTC minute, hour, or day. A graph will show a planet moving slightly farther during an hour that was lengthened by a leap second. An Earth satellite’s velocity will seem higher when you reach the minute that includes 61 seconds. And so forth. Problems like these are the reason that the Time class only uses UTC for input and output, and insists on keeping time internally using the uniform time scales discussed below in Uniform time scales: TAI, TT, and TDB.

Second, leap seconds disqualify the Python datetime from use as a general way to represent time because it refuses to accept seconds greater than 59:

datetime(2012, 6, 30, 19, 59, 60)
Traceback (most recent call last):
  ...
ValueError: second must be in 0..59

That is why Skyfield offers a second version of each method that returns a datetime:

t.utc_datetime_and_leap_second()
t.astimezone_and_leap_second(tz)

These more accurate alternatives also return a leap_second, which usually has the value 0 but jumps to 1 when Skyfield is forced to represent a leap second as a datetime with the incorrect time 23:59:59.

# Asking for the leap_second flag to learn the whole story

dt, leap_second = t.astimezone_and_leap_second(eastern)

for dt_i, leap_second_i in zip(dt, leap_second):
    print('{0}  leap_second = {1}'.format(dt_i, leap_second_i))
2012-06-30 19:59:58-04:00  leap_second = 0
2012-06-30 19:59:59-04:00  leap_second = 0
2012-06-30 19:59:59-04:00  leap_second = 1
2012-06-30 20:00:00-04:00  leap_second = 0
2012-06-30 20:00:01-04:00  leap_second = 0

Using calendar tuples to represent UTC times is more elegant than using Python datetime objects because leap seconds can be represented accurately. If your application cannot avoid using datetime objects, then you will have to decide whether to simply ignore the leap_second value or to somehow output the leap second information.

Date arrays

If you want to ask where a planet or satellite was at a whole list of different times and dates, then Skyfield will work most efficiently if you build a single Time object that holds an entire array of dates, instead of building many separate Time objects. There are three techniques for building arrays.

The last possibility is generally the one that is the most fun, because its lets you vary whichever time unit you want while holding the others steady. And you are free to provide out-of-range values and leave it to Skyfield to work out the correct result. Here are some examples:

ts.utc(range(1900, 1950))     # Fifty years
ts.utc(1980, range(1, 25))    # Twenty-four months
ts.utc(2005, 5, [1, 10, 20])  # 1st, 10th, and 20th of May

# The ten seconds crossing the 1974 leap second
ts.utc(1975, 1, 1, 0, 0, range(-5, 5))

The resulting Time object will hold an array of times instead of just a single scalar value. When you provide it as input to a Skyfield calculation, the resulting array will have an extra dimension, expanding what would normally be a single result into as many results as you provided dates. We can compute the position of the Earth as an example:

# Single Earth position

t = ts.utc(2014, 1, 1)
pos = earth.at(t).position.au
print(pos)
[-0.17461758  0.88567056  0.38384886]
# Whole array of Earth positions

days = [1, 2, 3, 4]
t = ts.utc(2014, 1, days)
pos = earth.at(t).position.au
print(pos)
[[-0.17461758 -0.19179872 -0.20891924 -0.22597338]
 [ 0.88567056  0.88265548  0.87936337  0.87579547]
 [ 0.38384886  0.38254134  0.38111391  0.37956709]]

Note the shape of the resulting NumPy array. If you unpack this array into three names, then you get three four-element arrays corresponding to the four dates. These four-element arrays are ready to be submitted to matplotlib and other scientific Python tools:

x, y, z = pos    # four values each
plot(x, y)

If you instead slice along the second axis, then you can retrieve an individual position for a particular date — and the first position is exactly what was returned above when we computed the January 1st position by itself:

print(pos[:,0])
[-0.17461758  0.88567056  0.38384886]

Finally, converting an array Julian date back into a calendar tuple results in the year, month, and all of the other values being as deep as the array itself:

from pprint import pprint
pprint(t.utc)
array([[2014., 2014., 2014., 2014.],
       [   1.,    1.,    1.,    1.],
       [   1.,    2.,    3.,    4.],
       [   0.,    0.,    0.,    0.],
       [   0.,    0.,    0.,    0.],
       [   0.,    0.,    0.,    0.]])

Again, simply slice across the second dimension of the array to pull a particular calendar tuple out of the larger result:

print(t.utc[:,2])
[2014.    1.    3.    0.    0.    0.]

Uniform time scales: TAI, TT, and TDB

Date arithmetic becomes very simple as we leave UTC behind and consider completely uniform time scales. Days are always 24 hours, hours always 60 minutes, and minutes always 60 seconds without any variation or exceptions. Such time scales are not appropriate for your morning alarm clock because they are never delayed or adjusted to stay in sync with the slowing rotation of the earth. But that is what makes them useful for astronomical calculation — because physics keeps up its dance, and the stars and planets move in their courses, whether humanity pauses to observe a UTC leap second or not.

Because they make every day the same length, uniform time scales can express dates as a simple floating-point count of days elapsed. To make all historical dates come out as positive numbers, astronomers traditionally assign each date a “Julian day” number that starts counting at B.C. 4713 January 1 in the old Julian calendar — the same date as B.C. 4714 November 24 in our Gregorian calendar. Following a tradition going back to the Greeks and Ptolemy, the count starts at noon, since the sun’s transit is an observable event but the moment of midnight is not.

So twelve noon was the moment of Julian date zero:

# When was Julian date zero?

bc_4714 = -4713
t = ts.tt(bc_4714, 11, 24, 12)
print(t.tt)
0.0

Did you notice how negative years work? People still counted by starting at one, not zero, when the scholar Dionysius Exiguus created the eras BC and AD in around the year AD 500. So his scheme has 1 BC followed immediately by 1 AD without a break. To avoid an off-by-one error, astronomers usually ignore BC and count backwards through a year zero and on into negative years. So negative year −n is what might otherwise be called either “n+1 BC” or “n+1 BCE” in a history textbook.

More than two million days have passed since 4714 BC, so modern dates tend to be rather large numbers:

# 2014 January 1 as a Julian Date

t = ts.utc(2014, 1, 1)
print('TAI = %r' % t.tai)
print('TT  = %r' % t.tt)
print('TDB = %r' % t.tdb)
TAI = 2456658.5004050927
TT  = 2456658.500777593
TDB = 2456658.500777592

What are these three different uniform time scales?

International Atomic Time (TAI) is maintained by the worldwide network of atomic clocks referenced by researchers with a need for very accurate time. The official leap second table is actually a table of offsets between TAI and UTC. At the end of June 2012, for example, the TAI−UTC offset was changed from 34.0 to 35.0 which is what generated the leap second in UTC.

Terrestrial Time (TT) differs from TAI only because astronomers were already maintaining a uniform time scale of their own before TAI was established, using a slightly different starting point for the day. For practical purposes, TT is simply TAI plus exactly 32.184 seconds. So it is now more than a minute ahead of UTC.

Barycentric Dynamical Time (TDB) runs at approximately the rate that an atomic clock would run if it were at rest with respect to the Solar System barycenter, and therefore unaffected by the Earth’s motion. The acceleration that Earth experiences in its orbit — sometimes speeding up, sometimes slowing down — varies the rate at which our atomic clocks seem to run to an outside observer, as predicted by Einstein’s theory of General Relativity. So physical simulations of the Solar System tend to use TDB, which is continuous with the Teph time scale traditionally used for Solar System and spacecraft simulations at the Jet Propulsion Laboratory.

UT1 and ΔT

Finally, UT1 is the least uniform time scale of all because its clock cannot be housed in a laboratory, nor is its rate established by any human convention. It is, rather, the clock whose “hand” is the rotation of the Earth itself!

The UT1 time is derived from the direction that the Earth happens to be pointing at any given moment. And the Earth is a young world with a still-molten iron core, and viscous mantle, and continents that rise and fall as each passing ice age weighs down upon them and then melts away. We think that we can predict, with high accuracy, where the planets will be in their orbits thousands of years from now. But to predict the fluid dynamics of an elastic rotating ellipsoid is, at the moment, beyond us. We cannot, for example, run a simulation or formula to predict leap seconds more than a few months ahead of time! Instead, we simply have to watch with sensitive instruments to see what the Earth will do next.

If you are interested in the Earth as a dynamic body, visit the Long-term Delta T page provided by the United States Naval Observatory. You will find graphs and tables showing how the length of Earth’s day expands and contracts by milliseconds over the decades. The accumulated error at any given moment is provided as ΔT, the evolving difference between TT and UT1 that dropped below zero in 1871 but then rose past it in 1902 and now stands at more than +67.2 seconds.

The task of governing leap seconds can be stated, then, as the task of keeping the difference between TT and UTC close to the natural value ΔT out in the wild. The standards bodies promise, in fact, that the difference between these two artificial time scales will always be within 0.9 seconds of the observed ΔT value.

In calculations that do not involve Earth’s rotation, ΔT never arises. The positions of planets, the distance to the Moon, and the movement of a comet or asteroid all ignore ΔT completely. When, then, does ΔT come into play?

When you create your ts timescale object at the beginning of your program, Skyfield downloads up-to-date deltat.data and deltat.preds files (if they are not already downloaded) from the United States Naval Observatory. These provide sub-millisecond level measurements of the direction that the Earth is pointing, allowing Skyfield to make

When you ask about dates in the far future or past, Skyfield will run off the end of its tables and will instead use the formula of Morrison and Stephenson (2004) to estimate when day and night might have occurred in that era.

Setting a Custom Value For ΔT

If you ever want to specify your own value for ΔT, then provide a delta_t keyword argument when creating your timescale:

load.timescale(delta_t=67.2810).utc((2014, 1, 1))

Time precision is around ~20.1 µs

Skyfield stores time vectors internally as NumPy 64-bit floating point arrays of Julian times. As explained in the United States Naval Observatory’s AA Technical Note 2011-02, “The Error in the Double Precision Representation of Julian Dates,” this provides fairly high precision:

“An evaluation of the error associated with representing Julian dates in IEEE 754 double precision floating-point numbers demonstrates that Julian dates near the current epoch can be represented to a precision not worse than 20.1 microseconds.”

Skyfield’s own routines for turning time into strings do careful enough rounding that you should never see effects that small. For example, Skyfield renders the seconds of this time attractively all the way down to 4 decimal places:

t = ts.utc(2014, 1, 18, 1, 35, 37)
print(t.utc_jpl())
A.D. 2014-Jan-18 01:35:37.0000 UT

It’s only if you accidentally let Python print out a raw floating point value that you’ll see the limit of the precision:

print(t.utc)
(2014, 1, 18, 1, 35, 36.999982595443726)

To avoid ugly output like this, you should use Skyfield’s own time display methods like utc_iso() and utc_jpl() or those of the datetime that Skyfield returns from utc_datetime() when printing dates to the screen.

The Julian date object as cache

When you create a Time it goes ahead and computes its tt Terrestrial Time attribute starting from whatever time argument you provide. If you provide the utc parameter, for example, then the date first computes and sets tai and then computes and sets tt. Each of the other time attributes only gets computed once, the first time you access it.

The general rule is that attributes are only computed once, and can be accessed again and again for free, while methods never cache their results — think of the () parentheses after a method name as your reminder that “this will do a fresh computation every time.”

In addition to time scales, there are several more functions of time that live on Julian date objects since they are often needed repeatedly during a calculation. In case you are curious what they are, here is a list:

gmst
Greenwich Mean Sidereal Time in hours, in the range 0.0 ≤ gmst < 24.0.
gast
Greenwich Apparent Sidereal Time in hours, in the range 0.0 ≤ gast < 24.0.
P
The precession matrix P for rotating an x,y,z vector to the true equator and equinox — the “epoch” — of this Julian date.
N
The even more expensive nutation matrix N for rotating an x,y,z vector to this epoch of this Julian date.
M
The product NPB that performs the complete rotation between a vector in the ICRF and a vector in the dynamical reference system of this Julian date, where B is the frame tie between the two systems.
C
The matrix that performs a complete rotation between a vector in the ICRF and a vector in the celestial intermediate reference system (CIRS) of this Julian date.
MT, NT, PT, CT
The four matrices MT, NT, PT and CT that are the transposes of the four previous matrices, and that rotate back the other direction from the dynamical reference system back to the ICRF frame.

You will typically never need to access these matrices yourself, as they are used automatically by the Position.radec() method when you use its epoch= parameter to ask for a right ascension and declination in the dynamical reference system.