Skyfield: HomeTable of ContentsAPI Reference

API Reference — Time

See the Dates and Time guide for a careful and detailed discussion of the several time scales used by astronomers, and of how you can convert time to and from familiar time scales like UTC and the worldwide time zones that are adapted from it.

Calendar date

  1. When building a Time from a calendar date, you can not only designate a single moment by its time and date, but you can also build a Time representing a whole array of moments by supplying a Python list or NumPy array for either the year, month, day, hour, minute, or second. See Date arrays.
  2. By default, Skyfield uses the modern Gregorian calendar for all dates — even dates before the Gregorian calendar was introduced in 1582.
  3. You can instead opt to use the old Julian calendar for ancient dates, which is the most common practice among historians. See Ancient and modern dates.

Timescale, for building and converting times

class skyfield.timelib.Timescale(delta_t_recent, leap_dates, leap_offsets)

The data necessary to express dates in different timescales.

A Timescale loads three data files. They supply the value of ∆T over time and the schedule of UTC leap seconds, which Skyfield uses to translate between different time scales. Most programs create a single Timescale which they use to build their Time objects:

>>> from skyfield.api import load
>>> ts = load.timescale()
>>> t = ts.utc(1980, 3, 1, 9, 30)
>>> t
<Time tt=2444299.896425741>

See Downloading new timescale files if you are interested in checking how recent the data is in the files loaded by the timescale.

now()

Return the current date and time as a Time object.

For the return value to be correct, your operating system time and timezone settings must be set so that the Python Standard Library constructor datetime.datetime.utcnow() returns a correct UTC date and time.

from_datetime(datetime)

Return a Time for a Python datetime.

The datetime must be “timezone-aware”: it must have a time zone object as its tzinfo attribute instead of None.

from_datetimes(datetime_list)

Return a Time for a list of Python datetimes.

The datetime objects must each be “timezone-aware”: they must each have a time zone object as their tzinfo attribute instead of None.

utc(year, month=1, day=1, hour=0, minute=0, second=0.0)

Build a Time from a UTC Calendar date.

tai(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

Build a Time from an International Atomic Time Calendar date.

tai_jd(jd, fraction=0.0)

Build a Time from an International Atomic Time Julian date.

tt(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

Build a Time from a Terrestrial Time Calendar date.

tt_jd(jd, fraction=0.0)

Build a Time from a Terrestrial Time Julian date.

J(year)

Build a Time from a Terrestrial Time Julian year or array.

Julian years are convenient uniform periods of exactly 365.25 days of Terrestrial Time, centered on 2000 January 1 12h TT = Julian year 2000.0.

tdb(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

Build a Time from a Barycentric Dynamical Time Calendar date.

tdb_jd(jd, fraction=0.0)

Build Time from a Barycentric Dynamical Time Julian date.

ut1(year=None, month=1, day=1, hour=0, minute=0, second=0.0, jd=None)

Build a Time from a UT1 Universal Time Calendar date.

ut1_jd(jd)

Build a Time from a UT1 Universal Time Julian date.

from_astropy(t)

Build a Skyfield Time from an AstroPy time object.

The Time object

class skyfield.timelib.Time(ts, tt, tt_fraction=0.0)

A single moment in history, or an array of several moments.

You will not typically instantiate this class yourself, but will rely on a Skyfield Timescale object to build dates for you:

>>> t = ts.utc(1980, 1, 1)
>>> print(t)
<Time tt=2444239.5005924073>

Times are represented internally by a pair of floating point Julian dates, but can be converted to other formats by using the many methods that time objects make available.

Four basic floating-point values can be directly accessed as attributes:

tai

International Atomic Time (TAI) as a Julian date.

tt

Terrestrial Time (TT) as a Julian date.

J

Terrestrial Time (TT) as a floating point number of Julian years.

tdb

Barycentric Dynamical Time (TDB) as a Julian date.

ut1

Universal Time (UT1) as a Julian date.

Two standard differences between time scales are also available as attributes:

delta_t

The difference TT − UT1 measured in seconds.

dut1

The difference UT1 − UTC measured in seconds.

All of the other ways of expressing the time and converting it to typical human systems like UTC and world time zones are offered through methods:

astimezone(tz)

Convert to a Python datetime in a particular timezone tz.

If this time is an array, then an array of datetimes is returned instead of a single value.

astimezone_and_leap_second(tz)

Convert to a Python datetime and leap second in a timezone.

Convert this time to a Python datetime and a leap second:

dt, leap_second = t.astimezone_and_leap_second(tz)

The argument tz should be a datetime compatible timezone.

The leap second value is provided because a Python datetime can only number seconds 0 through 59, but leap seconds have a designation of at least 60. The leap second return value will normally be 0, but will instead be 1 if the date and time are a UTC leap second. Add the leap second value to the second field of the datetime to learn the real name of the second.

If this time is an array, then an array of datetime objects and an array of leap second integers is returned, instead of a single value each.

toordinal()

Return the proleptic Gregorian ordinal of the UTC date.

This method makes Skyfield Time objects compatible with Python datetime objects, which also provide a toordinal() method. Thanks to this method, a Time can often be used directly as a coordinate for a plot.

utc_datetime()

Convert to a Python datetime in UTC.

If this time is an array, then a list of datetimes is returned instead of a single value.

utc_datetime_and_leap_second()

Convert to a Python datetime in UTC, plus a leap second value.

Convert this time to a datetime object and a leap second:

dt, leap_second = t.utc_datetime_and_leap_second()

The leap second value is provided because a Python datetime can only number seconds 0 through 59, but leap seconds have a designation of at least 60. The leap second return value will normally be 0, but will instead be 1 if the date and time are a UTC leap second. Add the leap second value to the second field of the datetime to learn the real name of the second.

If this time is an array, then an array of datetime objects and an array of leap second integers is returned, instead of a single value each.

utc_iso(delimiter='T', places=0)

Convert to an ISO 8601 string like 2014-01-18T01:35:38Z in UTC.

If this time is an array of dates, then a sequence of strings is returned instead of a single string.

utc_jpl()

Convert to a string like A.D. 2014-Jan-18 01:35:37.5000 UT.

Returns a string for this date and time in UTC, in the format used by the JPL HORIZONS system. If this time is an array of dates, then a sequence of strings is returned instead of a single string.

utc_strftime(format='%Y-%m-%d %H:%M:%S UTC')

Format the UTC time using a Python datetime formatting string.

This calls Python’s time.strftime() to format the date and time. A single string is returned or else a whole array of strings, depending on whether this time object is an array. The most commonly used formats are:

  • %Y four-digit year, %y two-digit year
  • %m month number, %B name, %b abbreviation
  • %d day of month
  • %H hour
  • %M minute
  • %S second
  • %A day of week, %a its abbreviation

You can find the full list, along with options that control field widths and leading zeros, at:

https://docs.python.org/3/library/time.html#time.strftime

If the smallest time unit in your format is minutes or seconds, then the time is rounded to the nearest minute or second. Otherwise the value is truncated rather than rounded.

tai_calendar()

TAI as a (year, month, day, hour, minute, second) Calendar date.

tt_calendar()

TT as a (year, month, day, hour, minute, second) Calendar date.

tdb_calendar()

TDB as a (year, month, day, hour, minute, second) Calendar date.

ut1_calendar()

UT1 as a (year, month, day, hour, minute, second) Calendar date.

tai_strftime(format='%Y-%m-%d %H:%M:%S TAI')

Format TAI with a datetime strftime() format string.

tt_strftime(format='%Y-%m-%d %H:%M:%S TT')

Format TT with a datetime strftime() format string.

tdb_strftime(format='%Y-%m-%d %H:%M:%S TDB')

Format TDB with a datetime strftime() format string.

ut1_strftime(format='%Y-%m-%d %H:%M:%S UT1')

Format UT1 with a datetime strftime() format string.

M

3×3 rotation matrix: ICRS → equinox of this date.

MT

3×3 rotation matrix: equinox of this date → ICRS.

J

Return a floating point Julian year or array of years for this date.

Julian years are convenient uniform periods of exactly 365.25 days of Terrestrial Time, centered on 2000 January 1 12h TT = Julian year 2000.0.

gmst

Greenwich Mean Sidereal Time as decimal hours.

gast

Greenwich Apparent Sidereal Time as decimal hours.

nutation_matrix()

Compute the 3×3 nutation matrix N for this date.

precession_matrix()

Compute the 3×3 precession matrix P for this date.

Time utilities

skyfield.timelib.compute_calendar_date(jd_integer, julian_before=None)

Convert Julian day jd_integer into a calendar (year, month, day).

Uses the proleptic Gregorian calendar unless julian_before is set to a specific Julian day, in which case the Julian calendar is used for dates older than that.