Epoch¶

Class to handle time.

pymeeus.Epoch.DAY2HOURS = 24.0¶: Number of hours per day

pymeeus.Epoch.DAY2MIN = 1440.0¶: Number of minutes per day

pymeeus.Epoch.DAY2SEC = 86400.0¶: Number of seconds per day

class pymeeus.Epoch.Epoch(*args, **kwargs)[source]¶

Class Epoch deals with the tasks related to time handling.

The constructor takes either a single JDE value, another Epoch object, or a series of values representing year, month, day, hours, minutes, seconds. This series of values are by default supposed to be in Terrestial Time (TT).

This is not necesarily the truth, though. For instance, the time of a current observation is tipically in UTC time (civil time), not in TT, and there is some offset between those two time references.

When a UTC time is provided, the parameter utc=True must be given. Then, the input is converted to International Atomic Time (TAI) using an internal table of leap seconds, and from there, it is converted to (and stored as) Terrestrial Time (TT).

Given that leap seconds are added or subtracted in a rather irregular basis, it is not possible to predict them in advance, and the internal leap seconds table will become outdated at some point in time. To counter this, you have two options:

Download an updated version of this Pymeeus package.
Use the argument leap_seconds in the constructor or set() method to provide the correct number of leap seconds (w.r.t. TAI) to be applied.

Note

Providing the leap_seconds argument will automatically set the argument utc to True.

For instance, if at some time in the future the TAI-UTC difference is 43 seconds, you should set leap_seconds=43 if you don’t have an updated version of this class.

In order to know which is the most updated leap second value stored in this class, you may use the get_last_leap_second() method.

Note

The current version of UTC was implemented in January 1st, 1972. Therefore, for dates before that date the correction is NOT carried out, even if the utc argument is set to True, and it is supposed that the input data is already in TT scale.

Note

For conversions between TT and Universal Time (UT), please use the method tt2ut().

Note

Internally, time values are stored as a Julian Ephemeris Day (JDE), based on the uniform scale of Dynamical Time, or more specifically, Terrestial Time (TT) (itself the redefinition of Terrestrial Dynamical Time, TDT).

Note

The UTC-TT conversion is composed of three corrections:

TT-TAI, comprising 32.184 s,
TAI-UTC(1972), 10 s, and
UTC(1972)-UTC(target)

item c. is the corresponding amount of leap seconds to the target Epoch. When you do, for instance, leap_seconds=43, you modify the c. part.

Note

Given that this class stores the epoch as JDE, if the JDE value is in the order of millions of days then, for a computer with 15-digit accuracy, the final time resolution is about 10 milliseconds. That is considered enough for most applications of this class.

__add__(b)[source]¶

This method defines the addition between an Epoch and some days.

Parameters:	b (int, float) – Value to be added, in days.
Returns:	A new Epoch object.
Return type:	`Epoch`
Raises:	TypeError if operand is of wrong type.

>>> a = Epoch(1991, 7, 11)
>>> b = a + 10000
>>> y, m, d = b.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
2018/11/26.0

__call__()[source]¶

Method used when Epoch is called only with parenthesis.

Returns:	The internal value of the Julian Ephemeris Day.
Return type:	float

>>> a = Epoch(-122, 1, 1.0)
>>> print(a())
1676497.5

__eq__(b)[source]¶

This method defines the ‘is equal’ operator between Epochs.

Note

For the comparison, the base.TOL value is used.

Returns:	A boolean.
Return type:	bool
Raises:	TypeError if input values are of wrong type.

>>> a = Epoch(2007, 5, 20.0)
>>> b = Epoch(2007, 5, 20.000001)
>>> a == b
False
>>> a = Epoch(2004, 10, 15.7)
>>> b = Epoch(a)
>>> a == b
True
>>> a = Epoch(2434923.85)
>>> a == 2434923.85
True

__float__()[source]¶

This method returns the internal JDE value as a float.

Returns:	Internal JDE value as a float.
Return type:	float

>>> a = Epoch(2434923.85)
>>> float(a)
2434923.85

__ge__(b)[source]¶

This method defines ‘is equal or greater’ operator between Epochs.

Returns:	A boolean.
Return type:	bool
Raises:	TypeError if input values are of wrong type.

>>> a = Epoch(2004, 10, 15.71)
>>> b = Epoch(2004, 10, 15.7)
>>> a >= b
True

__gt__(b)[source]¶

This method defines the ‘is greater than’ operator between Epochs.

Returns:	A boolean.
Return type:	bool
Raises:	TypeError if input values are of wrong type.

>>> a = Epoch(2004, 10, 15.71)
>>> b = Epoch(2004, 10, 15.7)
>>> a > b
True
>>> a = Epoch(-207, 11, 5.2)
>>> b = Epoch(-207, 11, 5.2)
>>> a > b
False

__hash__()[source]¶

Method used to create hash from an Epoch object.

This method allows Epoch objects to be used as the key in a dictionary.

__iadd__(b)[source]¶

This method defines the accumulative addition to this Epoch.

Parameters:	b (int, float) – Value to be added, in days.
Returns:	This Epoch.
Return type:	`Epoch`
Raises:	TypeError if operand is of wrong type.

>>> a = Epoch(2003, 12, 31.0)
>>> a += 32.5
>>> y, m, d = a.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
2004/2/1.5

__init__(*args, **kwargs)[source]¶

Epoch constructor.

This constructor takes either a single JDE value, another Epoch object, or a series of values representing year, month, day, hours, minutes, seconds. This series of values are by default supposed to be in Terrestial Time (TT).

It is also possible that the year, month, etc. arguments be provided in a tuple or list. Moreover, it is also possible provide date or datetime objects for initialization.

The month value can be provided as an integer (1 = January, 2 = February, etc), or it can be provided with short (Jan, Feb,…) or long (January, February,…) names. Also, hours, minutes, seconds can be provided separately, or as decimals of the day value.

When a UTC time is provided, the parameter utc=True must be given. Then, the input is converted to International Atomic Time (TAI) using an internal table of leap seconds, and from there, it is converted to (and stored as) Terrestrial Time (TT). If utc is not provided, it is supposed that the input data is already in TT scale.

If a value is provided with the leap_seconds argument, then that value will be used for the UTC->TAI conversion, and the internal leap seconds table will be bypassed.

Parameters:	args (int, float, `Epoch`, tuple, list, date, datetime) – Either JDE, Epoch, date, datetime or year, month, day, hours, minutes, seconds values, by themselves or inside a tuple or list utc (bool) – Whether the provided epoch is a civil time (UTC) leap_seconds (int, float) – This is the value to be used in the UTC->TAI conversion, instead of taking it from internal leap seconds table.
Returns:	Epoch object.
Return type:	`Epoch`
Raises:	ValueError if input values are in the wrong range.
Raises:	TypeError if input values are of wrong type.

>>> e = Epoch(1987, 6, 19.5)
>>> print(e)
2446966.0

__int__()[source]¶

This method returns the internal JDE value as an int.

Returns:	Internal JDE value as an int.
Return type:	int

>>> a = Epoch(2434923.85)
>>> int(a)
2434923

__isub__(b)[source]¶

This method defines the accumulative subtraction to this Epoch.

Parameters:	b (int, float) – Value to be subtracted, in days.
Returns:	This Epoch.
Return type:	`Epoch`
Raises:	TypeError if operand is of wrong type.

>>> a = Epoch(2001, 12, 31.0)
>>> a -= 2*365
>>> y, m, d = a.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
2000/1/1.0

__le__(b)[source]¶

This method defines ‘is equal or less’ operator between Epochs.

Returns:	A boolean.
Return type:	bool
Raises:	TypeError if input values are of wrong type.

>>> a = Epoch(2004, 10, 15.71)
>>> b = Epoch(2004, 10, 15.7)
>>> a <= b
False
>>> a = Epoch(-207, 11, 5.2)
>>> b = Epoch(-207, 11, 5.2)
>>> a <= b
True

__lt__(b)[source]¶

This method defines the ‘is less than’ operator between Epochs.

Returns:	A boolean.
Return type:	bool
Raises:	TypeError if input values are of wrong type.

>>> a = Epoch(2004, 10, 15.7)
>>> b = Epoch(2004, 10, 15.7)
>>> a < b
False

__ne__(b)[source]¶

This method defines the ‘is not equal’ operator between Epochs.

Note

For the comparison, the base.TOL value is used.

Returns:	A boolean.
Return type:	bool

>>> a = Epoch(2007, 5, 20.0)
>>> b = Epoch(2007, 5, 20.000001)
>>> a != b
True
>>> a = Epoch(2004, 10, 15.7)
>>> b = Epoch(a)
>>> a != b
False
>>> a = Epoch(2434923.85)
>>> a != 2434923.85
False

__radd__(b)[source]¶

This method defines the addition to a Epoch by the right

Parameters:	b (int, float) – Value to be added, in days.
Returns:	A new Epoch object.
Return type:	`Epoch`
Raises:	TypeError if operand is of wrong type.

>>> a = Epoch(2004, 2, 27.8)
>>> b = 2.2 + a
>>> y, m, d = b.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
2004/3/1.0

__repr__()[source]¶

Method providing the ‘official’ string representation of the object. It provides a valid expression that could be used to recreate the object.

Returns:	As string with a valid expression to recreate the object
Return type:	string

>>> e = Epoch(1987, 6, 19.5)
>>> repr(e)
'Epoch(2446966.0)'

__str__()[source]¶

Method used when trying to print the object.

Returns:	Internal JDE value as a string.
Return type:	string

>>> e = Epoch(1987, 6, 19.5)
>>> print(e)
2446966.0

__sub__(b)[source]¶

This method defines the subtraction between Epochs or between an Epoch and a given number of days.

Parameters:	b (py:class:Epoch, int, float) – Value to be subtracted, either an Epoch or days.
Returns:	A new Epoch object if parameter ‘b’ is in days, or the difference between provided Epochs, in days.
Return type:	`Epoch`, float
Raises:	TypeError if operand is of wrong type.

>>> a = Epoch(1986, 2, 9.0)
>>> print(round(a(), 2))
2446470.5
>>> b = Epoch(1910, 4, 20.0)
>>> print(round(b(), 2))
2418781.5
>>> c = a - b
>>> print(round(c, 2))
27689.0
>>> a = Epoch(2003, 12, 31.0)
>>> b = a - 365.5
>>> y, m, d = b.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
2002/12/30.5

__weakref__¶: list of weak references to the object (if defined)

apparent_sidereal_time(true_obliquity, nutation_longitude)[source]¶

Method to compute the _apparent_ sidereal time at Greenwich for the epoch stored in this object. It represents the Greenwich hour angle of the true vernal equinox.

Note

If you require the result as an angle, you should convert the result from this method to hours with decimals (with DAY2HOURS), and then multiply by 15 deg/hr. Alternatively, you can convert the result to hours with decimals, and feed this value to an Angle object, setting ra=True, and making use of Angle facilities for further handling.

Parameters:	true_obliquity (int, float, `Angle`) – The true obliquity of the ecliptic as an int, float or `Angle`, in degrees. You can use the method Earth.true_obliquity() to find it. nutation_longitude (int, float, `Angle`) – The nutation in longitude as an int, float or `Angle`, in degrees. You can use method Earth.nutation_longitude() to find it.
Returns:	Apparent sidereal time, in days
Return type:	float
Raises:	TypeError if input value is of wrong type.

>>> e = Epoch(1987, 4, 10)
>>> round(e.apparent_sidereal_time(23.44357, (-3.788)/3600.0), 8)
0.54914508

static check_input_date(*args, **kwargs)[source]¶

Method to check that the input is a proper date.

This method returns an Epoch object, and the leap_seconds argument then controls the way the UTC->TT conversion is handled for that new object. If leap_seconds argument is set to a value different than zero, then that value will be used for the UTC->TAI conversion, and the internal leap seconds table will be bypassed. On the other hand, if it is set to zero, then the UTC to TT correction is disabled, and it is supposed that the input data is already in TT scale.

Parameters:	args (int, float, `Epoch`, datetime, date, tuple, list) – Either Epoch, date, datetime or year, month, day values, by themselves or inside a tuple or list leap_seconds (int, float) – If different from zero, this is the value to be used in the UTC->TAI conversion. If equals to zero, conversion is disabled. If not given, UTC to TT conversion is carried out (default).
Returns:	Epoch object corresponding to the input date
Return type:	`Epoch`
Raises:	ValueError if input values are in the wrong range.
Raises:	TypeError if input values are of wrong type.

dow(as_string=False)[source]¶

Method to return the day of week corresponding to this Epoch.

By default, this method returns an integer value: 0 for Sunday, 1 for Monday, etc. However, when as_string=True is passed, the names of the days are returned.

Parameters:	as_string (bool) – Whether result will be given as a integer or as a string. False by default.
Returns:	Day of the week, as a integer or as a string.
Return type:	int, str

>>> e = Epoch(1954, 'June', 30)
>>> e.dow()
3
>>> e = Epoch(2018, 'Feb', 14.9)
>>> e.dow(as_string=True)
'Wednesday'
>>> e = Epoch(2018, 'Feb', 15)
>>> e.dow(as_string=True)
'Thursday'
>>> e = Epoch(2018, 'Feb', 15.99)
>>> e.dow(as_string=True)
'Thursday'
>>> e.set(2018, 'Jul', 15.4)
>>> e.dow(as_string=True)
'Sunday'
>>> e.set(2018, 'Jul', 15.9)
>>> e.dow(as_string=True)
'Sunday'

doy()[source]¶

This method returns the Day Of Year (DOY) for the current Epoch object.

Returns:	Day Of Year (DOY).
Return type:	float

>>> e = Epoch(1999, 1, 29)
>>> round(e.doy(), 1)
29.0
>>> e = Epoch(2017, 12, 31.7)
>>> round(e.doy(), 1)
365.7
>>> e = Epoch(2012, 3, 3.1)
>>> round(e.doy(), 1)
63.1
>>> e = Epoch(-400, 2, 29.9)
>>> round(e.doy(), 1)
60.9

static doy2date(year, doy)[source]¶

This method takes a year and a Day Of Year values, and returns the corresponding date.

Parameters:	year (int, float) – Year, in four digits format doy (int, float) – Day of Year number
Returns:	Year, month, day.
Return type:	tuple
Raises:	ValueError if either input year or doy values are invalid.

>>> t = Epoch.doy2date(1999, 29)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
1999/1/29.0
>>> t = Epoch.doy2date(2017, 365.7)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
2017/12/31.7
>>> t = Epoch.doy2date(2012, 63.1)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
2012/3/3.1
>>> t = Epoch.doy2date(-1004, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-1004/2/29.0
>>> t = Epoch.doy2date(0, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
0/2/29.0
>>> t = Epoch.doy2date(1, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
1/3/1.0
>>> t = Epoch.doy2date(-1, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-1/3/1.0
>>> t = Epoch.doy2date(-2, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-2/3/1.0
>>> t = Epoch.doy2date(-3, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-3/3/1.0
>>> t = Epoch.doy2date(-4, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-4/2/29.0
>>> t = Epoch.doy2date(-5, 60)
>>> print("{}/{}/{}".format(t[0], t[1], round(t[2], 1)))
-5/3/1.0

static easter(year)[source]¶

Method to return the Easter day for given year.

Note

This method is valid for both Gregorian and Julian years.

Parameters:	year (int) – Year
Returns:	Easter month and day, as a tuple
Return type:	tuple
Raises:	TypeError if input values are of wrong type.

>>> Epoch.easter(1991)
(3, 31)
>>> Epoch.easter(1818)
(3, 22)
>>> Epoch.easter(1943)
(4, 25)
>>> Epoch.easter(2000)
(4, 23)
>>> Epoch.easter(1954)
(4, 18)
>>> Epoch.easter(179)
(4, 12)
>>> Epoch.easter(1243)
(4, 12)

get_date(**kwargs)[source]¶

This method converts the internal JDE value back to a date.

Use utc=True to enable the TT to UTC conversion mechanism, or provide a non zero value to leap_seconds to apply a specific leap seconds value.

It is also possible to retrieve a local time with the parameter local=True. In such case, the method utc2local() is called to compute the LocalTime-UTC difference. This implies that the parameter utc=True is automatically set.

Note

Please bear in mind that, in order for the method utc2local() to work, your operative system must be correctly configured, with the right time and corresponding time zone.

Parameters:	utc (bool) – Whether the TT to UTC conversion mechanism will be enabled leap_seconds (int, float) – Optional value for leap seconds. local – Whether the retrieved epoch is converted to local time.
Returns:	Year, month, day in a tuple
Return type:	tuple

>>> e = Epoch(2436116.31)
>>> y, m, d = e.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
1957/10/4.81
>>> e = Epoch(1988, 1, 27)
>>> y, m, d = e.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
1988/1/27.0
>>> e = Epoch(1842713.0)
>>> y, m, d = e.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
333/1/27.5
>>> e = Epoch(1507900.13)
>>> y, m, d = e.get_date()
>>> print("{}/{}/{}".format(y, m, round(d, 2)))
-584/5/28.63

static get_doy(yyyy, mm, dd)[source]¶

This method returns the Day Of Year (DOY) for the given date.

Parameters:	yyyy (int, float) – Year, in four digits format mm (int, float) – Month, in numeric format (1 = January, 2 = February, etc) dd (int, float) – Day, in numeric format
Returns:	Day Of Year (DOY).
Return type:	float
Raises:	ValueError if input values correspond to a wrong date.

>>> Epoch.get_doy(1999, 1, 29)
29.0
>>> Epoch.get_doy(1978, 11, 14)
318.0
>>> Epoch.get_doy(2017, 12, 31.7)
365.7
>>> Epoch.get_doy(2012, 3, 3.1)
63.1
>>> Epoch.get_doy(-400, 2, 29.9)
60.9

get_full_date(**kwargs)[source]¶

This method converts the internal JDE value back to a full date.

Use utc=True to enable the TT to UTC conversion mechanism, or provide a non zero value to leap_seconds to apply a specific leap seconds value.

It is also possible to retrieve a local time with the parameter local=True. In such case, the method utc2local() is called to compute the LocalTime-UTC difference. This implies that the parameter utc=True is automatically set.

Note

Please bear in mind that, in order for the method utc2local() to work, your operative system must be correctly configured, with the right time and corresponding time zone.

Parameters:	utc (bool) – Whether the TT to UTC conversion mechanism will be enabled leap_seconds (int, float) – Optional value for leap seconds. local – Whether the retrieved epoch is converted to local time.
Returns:	Year, month, day, hours, minutes, seconds in a tuple
Return type:	tuple

>>> e = Epoch(2436116.31)
>>> y, m, d, h, mi, s = e.get_full_date()
>>> print("{}/{}/{} {}:{}:{}".format(y, m, d, h, mi, round(s, 1)))
1957/10/4 19:26:24.0
>>> e = Epoch(1988, 1, 27)
>>> y, m, d, h, mi, s = e.get_full_date()
>>> print("{}/{}/{} {}:{}:{}".format(y, m, d, h, mi, round(s, 1)))
1988/1/27 0:0:0.0
>>> e = Epoch(1842713.0)
>>> y, m, d, h, mi, s = e.get_full_date()
>>> print("{}/{}/{} {}:{}:{}".format(y, m, d, h, mi, round(s, 1)))
333/1/27 12:0:0.0
>>> e = Epoch(1507900.13)
>>> y, m, d, h, mi, s = e.get_full_date()
>>> print("{}/{}/{} {}:{}:{}".format(y, m, d, h, mi, round(s, 1)))
-584/5/28 15:7:12.0

static get_last_leap_second()[source]¶

Method to get the date and value of the last leap second added to the table

Returns:	Tuple with year, month, day, leap second value.
Return type:	tuple

static get_month(month, as_string=False)[source]¶

Method to get the month as a integer in the [1, 12] range, or as a full name.

Parameters:	month (int, float, str) – Month, in numeric, short name or long name format as_string (bool) – Whether the output will be numeric, or a long name.
Returns:	Month as integer in the [1, 12] range, or as a long name.
Return type:	int, str
Raises:	ValueError if input month value is invalid.

>>> Epoch.get_month(4.0)
4
>>> Epoch.get_month('Oct')
10
>>> Epoch.get_month('FEB')
2
>>> Epoch.get_month('August')
8
>>> Epoch.get_month('august')
8
>>> Epoch.get_month('NOVEMBER')
11
>>> Epoch.get_month(9.0, as_string=True)
'September'
>>> Epoch.get_month('Feb', as_string=True)
'February'
>>> Epoch.get_month('March', as_string=True)
'March'

static gregorian2moslem(year, month, day)[source]¶

Method to convert a date in the Gregorian (or Julian) calendar to the Moslen calendar.

Parameters:	year (int) – Year month (int) – Month day (int) – Day
Returns:	Date in Moslem calendar: year, month and day, as a tuple
Return type:	tuple
Raises:	TypeError if input values are of wrong type.

>>> Epoch.gregorian2moslem(1991, 8, 13)
(1412, 2, 2)

static is_julian(year, month, day)[source]¶

This method returns True if given date is in the Julian calendar.

Parameters:	year – Year month – Month day (int) – Day
Returns:	Whether the provided date belongs to Julian calendar or not.
Return type:	bool

>>> Epoch.is_julian(1997, 5, 27.1)
False
>>> Epoch.is_julian(1397, 7, 7.0)
True

static is_leap(year)[source]¶

Method to check if a given year is a leap year.

Parameters:	year (int, float) – Year to be checked.
Returns:	Whether or not year is a leap year.
Return type:	bool
Raises:	ValueError if input year value is invalid.

>>> Epoch.is_leap(2003)
False
>>> Epoch.is_leap(2012)
True
>>> Epoch.is_leap(1900)
False
>>> Epoch.is_leap(-1000)
True
>>> Epoch.is_leap(1000)
True

jde()[source]¶

Method to return the internal value of the Julian Ephemeris Day.

Returns:	The internal value of the Julian Ephemeris Day.
Return type:	float

>>> a = Epoch(-1000, 2, 29.0)
>>> print(a.jde())
1355866.5

static jewish_pesach(year)[source]¶

Method to return the Jewish Easter (Pesach) day for given year.

Note

This method is valid for both Gregorian and Julian years.

Parameters:	year (int) – Year
Returns:	Jewish Easter (Pesach) month and day, as a tuple
Return type:	tuple
Raises:	TypeError if input values are of wrong type.

>>> Epoch.jewish_pesach(1990)
(4, 10)

julian()[source]¶

This method returns True if this Epoch object holds a date in the Julian calendar.

Returns:	Whether this Epoch object holds a date belonging to Julian calendar or not.
Return type:	bool

>>> e = Epoch(1997, 5, 27.1)
>>> e.julian()
False
>>> e = Epoch(1397, 7, 7.0)
>>> e.julian()
True

leap()[source]¶

This method checks if the current Epoch object holds a leap year.

Returns:	Whether or the year in this Epoch object is a leap year.
Return type:	bool

>>> e = Epoch(2003, 1, 1)
>>> e.leap()
False
>>> e = Epoch(2012, 1, 1)
>>> e.leap()
True
>>> e = Epoch(1900, 1, 1)
>>> e.leap()
False
>>> e = Epoch(-1000, 1, 1)
>>> e.leap()
True
>>> e = Epoch(1000, 1, 1)
>>> e.leap()
True

static leap_seconds(year, month)[source]¶

Returns the leap seconds accumulated for the given year and month.

Parameters:	year (int) – Year month (int) – Month, in numeric format ([1:12] range)
Returns:	Leap seconds accumulated for given year and month.
Return type:	int

>>> Epoch.leap_seconds(1972, 4)
0
>>> Epoch.leap_seconds(1972, 6)
0
>>> Epoch.leap_seconds(1972, 7)
1
>>> Epoch.leap_seconds(1983, 6)
11
>>> Epoch.leap_seconds(1983, 7)
12
>>> Epoch.leap_seconds(1985, 8)
13
>>> Epoch.leap_seconds(2016, 11)
26
>>> Epoch.leap_seconds(2017, 1)
27
>>> Epoch.leap_seconds(2018, 7)
27

mean_sidereal_time()[source]¶

Method to compute the _mean_ sidereal time at Greenwich for the epoch stored in this object. It represents the Greenwich hour angle of the mean vernal equinox.

Note

If you require the result as an angle, you should convert the result from this method to hours with decimals (with DAY2HOURS), and then multiply by 15 deg/hr. Alternatively, you can convert the result to hours with decimals, and feed this value to an Angle object, setting ra=True, and making use of Angle facilities for further handling.

Returns:	Mean sidereal time, in days
Return type:	float

>>> e = Epoch(1987, 4, 10)
>>> round(e.mean_sidereal_time(), 9)
0.549147764
>>> e = Epoch(1987, 4, 10, 19, 21, 0.0)
>>> round(e.mean_sidereal_time(), 9)
0.357605204

mjd()[source]¶

This method returns the Modified Julian Day (MJD).

Returns:	Modified Julian Day (MJD).
Return type:	float

>>> e = Epoch(1858, 'NOVEMBER', 17)
>>> e.mjd()
0.0

static moslem2gregorian(year, month, day)[source]¶

Method to convert a date in the Moslen calendar to the Gregorian (or Julian) calendar.

Note

This method is valid for both Gregorian and Julian years.

Parameters:	year (int) – Year month (int) – Month day (int) – Day
Returns:	Date in Gregorian (Julian) calendar: year, month and day, as a tuple
Return type:	tuple
Raises:	TypeError if input values are of wrong type.

>>> Epoch.moslem2gregorian(1421, 1, 1)
(2000, 4, 6)

rise_set(latitude, longitude, altitude=0.0)[source]¶

This method computes the times of rising and setting of the Sun.

Note

The algorithm used is the one explained in the article “Sunrise equation” of the Wikipedia at: https://en.wikipedia.org/wiki/Sunrise_equation

Note

This algorithm is only valid outside the artic and antartic circles (+/- 66d 33’). For latitudes higher than +66d 33’ and smaller than -66d 33’ this method returns a ValueError exception

Note

The results are given in UTC time.

Parameters:	latitude (`Angle`) – Latitude of the observer, as an Angle object. Positive to the North longitude (`Angle`) – Longitude of the observer, as an Angle object. Positive to the East altitude (int, float) – Altitude of the observer, as meters above sea level
Returns:	Two `Epoch` objects representing rising time and setting time, in a tuple
Return type:	tuple
Raises:	TypeError if input values are of wrong type.
Raises:	ValueError if latitude outside the +/- 66d 33’ range.

>>> e = Epoch(2019, 4, 2)
>>> latitude = Angle(48, 8, 0)
>>> longitude = Angle(11, 34, 0)
>>> altitude = 520.0
>>> rising, setting = e.rise_set(latitude, longitude, altitude)
>>> y, m, d, h, mi, s = rising.get_full_date()
>>> print("{}:{}".format(h, mi))
4:48
>>> y, m, d, h, mi, s = setting.get_full_date()
>>> print("{}:{}".format(h, mi))
17:48

set(*args, **kwargs)[source]¶

Method used to set the value of this object.

This method takes either a single JDE value, or a series of values representing year, month, day, hours, minutes, seconds. This series of values are by default supposed to be in Terrestial Time (TT).

It is also possible to provide another Epoch object as input for the set() method, or the year, month, etc arguments can be provided in a tuple or list. Moreover, it is also possible provide date or datetime objects for initialization.

The month value can be provided as an integer (1 = January, 2 = February, etc), or it can be provided as short (Jan, Feb, …) or long (January, February, …) names. Also, hours, minutes, seconds can be provided separately, or as decimals of the day value.

When a UTC time is provided, the parameter utc=True must be given. Then, the input is converted to International Atomic Time (TAI) using an internal table of leap seconds, and from there, it is converted to (and stored as) Terrestrial Time (TT). If utc is not provided, it is supposed that the input data is already in TT scale.

If a value is provided with the leap_seconds argument, then that value will be used for the UTC->TAI conversion, and the internal leap seconds table will be bypassed.

It is also possible to provide a local time with the parameter local=True. In such case, the method utc2local() is called to compute the LocalTime-UTC difference. This implies that the parameter utc=True is automatically set.

Note

The UTC to TT correction is only carried out for dates after January 1st, 1972.

Note

Please bear in mind that, in order for the method utc2local() to work, your operative system must be correctly configured, with the right time and corresponding time zone.

Parameters:	args (int, float, `Epoch`, tuple, list, date, datetime) – Either JDE, Epoch, date, datetime or year, month, day, hours, minutes, seconds values, by themselves or inside a tuple or list. utc (bool) – Whether the provided epoch is a civil time (UTC). leap_seconds (int, float) – This is the value to be used in the UTC->TAI conversion, instead of taking it from internal leap seconds table. local – Whether the provided epoch is a local time.
Returns:	None.
Return type:	None
Raises:	ValueError if input values are in the wrong range.
Raises:	TypeError if input values are of wrong type.

>>> e = Epoch()
>>> e.set(1987, 6, 19.5)
>>> print(e)
2446966.0
>>> e.set(1977, 'Apr', 26.4)
>>> print(e)
2443259.9
>>> e.set(1957, 'October', 4.81)
>>> print(e)
2436116.31
>>> e.set(333, 'Jan', 27, 12)
>>> print(e)
1842713.0
>>> e.set(1900, 'Jan', 1)
>>> print(e)
2415020.5
>>> e.set(-1001, 'august', 17.9)
>>> print(e)
1355671.4
>>> e.set(-4712, 1, 1.5)
>>> print(e)
0.0
>>> e.set((1600, 12, 31))
>>> print(e)
2305812.5
>>> e.set([1988, 'JUN', 19, 12])
>>> print(e)
2447332.0
>>> d = datetime.date(2000, 1, 1)
>>> e.set(d)
>>> print(e)
2451544.5
>>> e.set(837, 'Apr', 10, 7, 12)
>>> print(e)
2026871.8
>>> d = datetime.datetime(837, 4, 10, 7, 12, 0, 0)
>>> e.set(d)
>>> print(e)
2026871.8
>>> e = Epoch(JDE2000, utc=True)
>>> print(round((e - JDE2000) * DAY2SEC, 3))
64.184
>>> e = Epoch(2451545.0, utc=True)
>>> print(round((e - JDE2000) * DAY2SEC, 3))
64.184
>>> e = Epoch(JDE2000, local=True)
>>> print(round((e - JDE2000) * DAY2SEC - Epoch.utc2local(), 3))
64.184
>>> e = Epoch(JDE2000, local=True, leap_seconds=35.0)
>>> print(round((e - JDE2000) * DAY2SEC - Epoch.utc2local(), 3))
77.184

static tt2ut(year, month)[source]¶

This method provides an approximation of the difference, in seconds, between Terrestrial Time and Universal Time, denoted DeltaT, where: DeltaT = TT - UT.

Here we depart from Meeus book and use the polynomial expressions from:

https://eclipse.gsfc.nasa.gov/LEcat5/deltatpoly.html

Which are regarded as more elaborate and precise than Meeus’.

Please note that, by definition, the UTC time used internally in this Epoch class by default is kept within 0.9 seconds from UT. Therefore, UTC is in itself a quite good approximation to UT, arguably better than some of the results provided by this method.

Parameters:	year (int, float) – Year we want to compute DeltaT for. month (int, float) – Month we want to compute DeltaT for.
Returns:	DeltaT, in seconds
Return type:	float

>>> round(Epoch.tt2ut(1642, 1), 1)
62.1
>>> round(Epoch.tt2ut(1680, 1), 1)
15.3
>>> round(Epoch.tt2ut(1700, 1), 1)
8.8
>>> round(Epoch.tt2ut(1726, 1), 1)
10.9
>>> round(Epoch.tt2ut(1750, 1), 1)
13.4
>>> round(Epoch.tt2ut(1774, 1), 1)
16.7
>>> round(Epoch.tt2ut(1800, 1), 1)
13.7
>>> round(Epoch.tt2ut(1820, 1), 1)
11.9
>>> round(Epoch.tt2ut(1890, 1), 1)
-6.1
>>> round(Epoch.tt2ut(1928, 2), 1)
24.2
>>> round(Epoch.tt2ut(1977, 2), 1)
47.7
>>> round(Epoch.tt2ut(1998, 1), 1)
63.0
>>> round(Epoch.tt2ut(2015, 7), 1)
69.3

static utc2local()[source]¶

Method to return the difference between UTC and local time.

This method provides you the seconds that you have to add or subtract to UTC time to convert to your local time. The correct way to apply this method is according to the expression:

utc2local() = LocalTime - UTC

Therefore, if for example you are located in a place whose corresponding time zone is UTC+2, then this method will yield 7200 (seconds in two hours) and you must then apply this expression:

LocalTime = UTC + utclocal() = UTC + 7200

Note

Please bear in mind that, in order for this method to work, your operative system must be correctly configured, with the right time and corresponding time zone.

Note

Remember that class Epoch internally stores time as Terrestrial Time (TT), not UTC. In order to get the UTC time you must use a method like get_date() or get_full_date() and pass the parameter utc=True.

Returns:	Difference in seconds between local and UTC time, in that order.
Return type:	float

year()[source]¶

This method returns the contents of this object as a year with decimals.

Returns:	Year with decimals.
Return type:	float

>>> e = Epoch(1993, 'October', 1)
>>> print(round(e.year(), 4))
1993.7479

pymeeus.Epoch.JDE2000 = Epoch(2451545.0)¶: Standard epoch for January 1st, 2000 at 12h corresponding to JDE2451545.0

pymeeus.Epoch.LEAP_TABLE = {1972.5: 1, 1973.0: 2, 1974.0: 3, 1975.0: 4, 1976.0: 5, 1977.0: 6, 1978.0: 7, 1979.0: 8, 1980.0: 9, 1981.5: 10, 1982.5: 11, 1983.5: 12, 1985.5: 13, 1988.0: 14, 1990.0: 15, 1991.0: 16, 1992.5: 17, 1993.5: 18, 1994.5: 19, 1996.0: 20, 1997.5: 21, 1999.0: 22, 2006.0: 23, 2009.0: 24, 2012.5: 25, 2015.5: 26, 2017.0: 27}¶: This table represents the point in time FROM WHERE the given number of leap seconds is valid. Given that leap seconds are (so far) always added at June 30th or December 31st, a leap second added in 1997/06/30 is represented here as ‘1997.5’, while a leap second added in 2005/12/31 appears here as ‘2006.0’.