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 provides time objects with the data tables they need to translate between different time scales: the schedule of UTC leap seconds, and the value of ∆T over time. 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 UT1 and downloading IERS data 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.

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.

Added in version 1.24.

from_datetimes(datetime_list)

Return a Time for a list of Python datetime objects.

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

Added in version 1.24.

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

Build a Time from a UTC Calendar date.

Added in version 1.24: Passing a Python datetime or a list of datetimes as the first argument has been deprecated (and was never supported for the other time scale methods). Instead, use the methods from_datetime() and from_datetimes().

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.

Added in version 1.6: Passing a Julian date with jd= has been deprecated; instead, use tai_jd().

tai_jd(jd, fraction=None)

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.

Added in version 1.6: Passing a Julian date with jd= has been deprecated; instead, use tt_jd().

tt_jd(jd, fraction=None)

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.

Added in version 1.6: Passing a Julian date with jd= has been deprecated; instead, use tdb_jd().

tdb_jd(jd, fraction=None)

Build a 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.

Added in version 1.6: Passing a Julian date with jd= has been deprecated; instead, use ut1_jd().

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.

linspace(t0, t1, num=50)

Return num times spaced uniformly between t0 to t1.

This routine is named after, and powered by, the NumPy routine linspace().

The Time object

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

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

Skyfield programs don’t usually instantiate this class directly, but instead build time objects using one of the timescale methods listed at Time scales. If you do attempt the low-level operation of building a time object yourself, either leave tt_fraction at its default value of None — in which case Skyfield will assume the fraction is zero — or provide a tt_fraction array that has exactly the same dimensions as your tt array.

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 UTC.

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

The %Z and %z formats are not supported; instead, simply use the literal characters 'UTC' in your format string.

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.

utc()

A tuple (year, month, day, hour, minute, second) in UTC.

gmst()

Greenwich Mean Sidereal Time (GMST) in hours.

gast()

Greenwich Apparent Sidereal Time (GAST) in 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.

to_astropy()

Return an AstroPy object representing this time.

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.