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¶
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 aTime
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.By default, Skyfield uses the modern Gregorian calendar for all dates — even dates before the Gregorian calendar was introduced in 1582.
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 singleTimescale
which they use to build theirTime
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 Pythondatetime
.The
datetime
must be “timezone-aware”: it must have a time zone object as itstzinfo
attribute instead ofNone
.New in version 1.24.
- from_datetimes(datetime_list)¶
Return a
Time
for a list of Pythondatetime
objects.The
datetime
objects must each be “timezone-aware”: they must each have a time zone object as theirtzinfo
attribute instead ofNone
.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 methodsfrom_datetime()
andfrom_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, usetai_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, usett_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, usetdb_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, useut1_jd()
.
- linspace(t0, t1, num=50)¶
Return
num
times spaced uniformly betweent0
tot1
.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 ofNone
— in which case Skyfield will assume the fraction is zero — or provide att_fraction
array that has exactly the same dimensions as yourtt
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 timezonetz
.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 adatetime
compatible timezone.The leap second value is provided because a Python
datetime
can only number seconds0
through59
, but leap seconds have a designation of at least60
. The leap second return value will normally be0
, but will instead be1
if the date and time are a UTC leap second. Add the leap second value to thesecond
field of thedatetime
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 atoordinal()
method. Thanks to this method, aTime
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 seconds0
through59
, but leap seconds have a designation of at least60
. The leap second return value will normally be0
, but will instead be1
if the date and time are a UTC leap second. Add the leap second value to thesecond
field of thedatetime
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
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.
- utc()¶
A tuple
(year, month, day, hour, minute, seconds)
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.