Time

Celest provides the Time class for easy time conversions which can be imported via the following:

from celest.time import Time

class Time(julian, offset=0)

Bases: object

Time transformations.

julian + offset is the Julian time in JD2000 epoch which can be converted into different time representations useful for astronomical calculations.

Parameters

julian (array_like) –
1-D array containing time data in Julian days.

If time data is not in the JD2000 epoch, an offset must be passed in to be added to the julian times.
offset (float, optional) – Offset to convert input time data to the JD2000 epoch, default to zero.

datetime()

Return datetime.datetime object array.

Returns: 1-D array containing datetime.datetime objects.
Return type: np.ndarray

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).datetime()
np.array([datetime.datetime(2010, 6, 21, 6, 0)
          datetime.datetime(2021, 8, 24, 8, 24, 0, 8)
          datetime.datetime(2013, 1, 1, 0, 59, 59, 999987)])

gast()

Return Greenwich Apparent Sidereal Time.

Returns: Quantity object containing Greenwich Apparent Sidereal Time.
Return type: Quantity

Notes

The difference between apparent and mean solar position is the equation of time. Thus, the Greenwich Apparent Sidereal Time can be calculated as follows:

\[GAST^h = GMST^h + EoT^h\]

where \(EoT\) is the equation of time in decimal hours.

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).gast()
np.array([23.955596,
          6.589146,
          7.723465])

gmst()

Return Greenwich Mean Sidereal Time.

Returns: Quantity object containing Greenwich Mean Sidereal Time.
Return type: Quantity

Notes

The Greenwich Mean Sidereal Time is calculated using the methods described in Astronomical Algorithms by Jean Meeus. [Mee98a]

References

Mee98a: Jean Meeus. Astronomical algorithms. 2nd ed. Willmann-Bell, 1998, pp. 87 - 88. isbn: 9780943396613.

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).gmst()
Quantity(np.array([23.955316, 6.589391, 7.723214]), Unit("hourangle"))

last(longitude)

Return Local Apparent Sidereal Time.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing Local Apparent Sidereal Time.
Return type: Quantity

Notes

The Local Apparent Sidereal Time is calculated using the methods described in Space-Time Reference Systems by M. Soffel and R. Langhans. [SL13f]

References

SL13f: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 205.

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).last(longitude=150)
np.array([9.98447567,
          16.6286799,
          17.78148932])

lmst(longitude)

Return Local Mean Sidereal Time.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing Local Mean Sidereal Time.
Return type: Quantity

Notes

The Local Mean Sidereal Time can be calculated using the following formulation:

\[LMST^h = h^h_{mSun} + \alpha^h_{mSun}\]

where \(h^h_{mSun}\) is the mean solar hour angle at the observer’s longitude and \(\alpha^h_{mSun}\) is the right ascension of the mean Sun position. [SL13e]

References

SL13e: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 205.

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).lmst(longitude=150)
Quantity(np.array([9.98419514, 16.62892539, 17.78123885]), Unit("hourangle"))

mean_hour_angle(longitude)

Return mean hour angle.

The mean hour angle is the angle between the Sun’s mean position at a given time and its position at local solar noon. The value falls between 0 and 360, measured in increasing degrees past local solar noon.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing mean solar hour angles.
Return type: Quantity

See also

true_hour_angle: Return true hour angle.

Notes

The mean hour angle is zero at local solar noon and increases with the mean solar time by a rate of \(15^\circ\) per hour. Thus, the mean hour angle can be calculated from the following:

\[h_{hSun}^\circ = MT_s^\circ - 180^\circ\]

where \(MT_s^\circ\) is the mean solar time in degrees. [SL13c]

References

SL13c: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 203.

Examples

Calculate the meann hour angle for a single longitude:

>>> Time(julian=2456293.5416666665).mean_hour_angle(longitude=147.46)
Quantity(np.array([22.83066666]), Unit("hourangle"))

mean_solar_time(longitude)

Return mean solar time.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing mean solar time.
Return type: Quantity

See also

true_solar_time: Return true solar time.

Notes

The mean solar time, \(MT_s\) can be calculated by converting Julian times, \(JD\), into UTC as follows:

\[UTC = 24\left(JD\%1\right)^h + \alpha^h\]

The mean solar time can then be calculated using the Equation of Time, \(EoT\), and the local meridians longitude, \(\phi\) as follows:

\[MT_s = (UTC^h + \phi^\circ/15)\%24\]

Examples

Calculate the mean solar time for a constant longitude:

>>> Time(julian=2456293.54167).mean_solar_time(longitude=147.46)
Quantity(np.array([10.830667]), Unit("hourangle"))

true_hour_angle(longitude)

Return true hour angle.

The true hour angle is the angle between the Sun’s apparent position at a given time and its position at local solar noon. The value falls between 0 and 360, measured in increasing degrees past local solar noon.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing true solar hour angles.
Return type: Quantity

See also

mean_hour_angle: Return mean hour angle.

Notes

The true hour angle is zero at local solar noon and increases with the true solar time by a rate of \(15^\circ\) per hour. Thus, the true hour angle can be calculated from the following:

\[h_{Sun}^\circ = TT_s^\circ - 180^\circ\]

where \(TT_s^\circ\) is the true solar time in degrees. [SL13b]

References

SL13b: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 203.

Examples

Calculate the true hour angle at different longitudes:

>>> julian = [2455368.75, 2459450.85]
>>> longitude = [-105, -118.24]
>>> Time(julian=julian).true_hour_angle(longitude=longitude)
Quantity(np.array([10.97157662, 12.47807655]), Unit("hourangle"))

true_solar_time(longitude)

Return true solar time.

Parameters: longitude (array_like) – 1-D array containing longitude in decimal degrees. If a scalar value is given, it will be applied for all times.
Returns: Quantity object containing true solar time.
Return type: Quantity

See also

mean_solar_time: Return mean solar time.

Notes

The true solar time, \(TT_s\) can be calculated by converting Julian times, \(JD\), into UTC as follows:

\[UTC = 24\left(JD\%1\right)^h + \alpha^h\]

The true solar time can then be calculated using the Equation of Time, \(EoT\), definition and the mean solar time, \(MT_s\). [SL13a]

\[TT_s = MT_s + EoT\]

\[TT_s = (UTC^h + (EoT^\circ + \phi^\circ)/15)\%24\]

References

SL13a: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 203.

Examples

Calculate the true solar time for a constant longitude:

>>> Time(julian=[2456293.54167]).true_solar_time(longitude=147.46)
Quantity(np.array([10.773109]), Unit("hourangle"))

ut1()

Return the universal time (same as GMT).

Due to approximations in the mean solar time calculations, the DUT1 time correction is not accounted for which will introduce an error of at most 1.8 seconds.

Returns: Quantity object containing universal time.
Return type: Quantity

Notes

The universal time is equal to the mean solar time at the Greenwich meridian. [SL13d] It can be calculated using Time.mean_solar_time(longitude=0).

References

SL13d: M. Soffel and R. Langhans. Space-Time Reference Systems. Astronomy and Astrophysics Library. Springer-Verlag, 2013, p. 203.

Examples

>>> julian = [2455368.75, 2459450.85, 2456293.5416666665]
>>> Time(julian=julian).ut1()
Quantity(np.array([6.00000, 8.40000, 1.00000]), Unit("hourangle"))

property julian: Quantity: Return Julian times.