Skyfield: Home • Table of Contents • Changelog • API Reference
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.
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.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.
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.
New 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.
New 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.
New 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.
New in version 1.6: Passing a Julian date with jd= has been deprecated;
instead, use tai_jd().
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.
New in version 1.6: Passing a Julian date with jd= has been deprecated;
instead, use tt_jd().
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.
New in version 1.6: Passing a Julian date with jd= has been deprecated;
instead, use tdb_jd().
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.
New in version 1.6: Passing a Julian date with jd= has been deprecated;
instead, use ut1_jd().
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().
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 abbreviationYou 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.
JReturn 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.
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.