Epoch — PyMeeus 0.5.12 documentation

# 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)

  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:

  1. TT-TAI, comprising 32.184 s,

  2. TAI-UTC(1972), 10 s, and

  3. 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)

    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__()

    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)

    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__()

    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)

    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)

    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__()

    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)

    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)

    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__()

    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)

    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)

    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)

    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)

    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)

    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__()

    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__()

    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)

    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)

    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)

    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)

    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()

    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)

    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)

    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)

    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)

    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)

    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()

    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)

    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)

    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)

    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)

    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()

    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)

    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()

    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()

    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)

    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()

    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()

    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)

    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)

    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)

    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)

    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()

    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()

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