Coordinates — PyMeeus 0.5.12 documentation

# Coordinates

Module holding functions to handle coordinates.

pymeeus.Coordinates.NUTATION_ARG_TABLE = [[0, 0, 0, 0, 1], [-2, 0, 0, 2, 2], [0, 0, 0, 2, 2], [0, 0, 0, 0, 2], [0, 1, 0, 0, 0], [0, 0, 1, 0, 0], [-2, 1, 0, 2, 2], [0, 0, 0, 2, 1], [0, 0, 1, 2, 2], [-2, -1, 0, 2, 2], [-2, 0, 1, 0, 0], [-2, 0, 0, 2, 1], [0, 0, -1, 2, 2], [2, 0, 0, 0, 0], [0, 0, 1, 0, 1], [2, 0, -1, 2, 2], [0, 0, -1, 0, 1], [0, 0, 1, 2, 1], [-2, 0, 2, 0, 0], [0, 0, -2, 2, 1], [2, 0, 0, 2, 2], [0, 0, 2, 2, 2], [0, 0, 2, 0, 0], [-2, 0, 1, 2, 2], [0, 0, 0, 2, 0], [-2, 0, 0, 2, 0], [0, 0, -1, 2, 1], [0, 2, 0, 0, 0], [2, 0, -1, 0, 1], [-2, 2, 0, 2, 2], [0, 1, 0, 0, 1], [-2, 0, 1, 0, 1], [0, -1, 0, 0, 1], [0, 0, 2, -2, 0], [2, 0, -1, 2, 1], [2, 0, 1, 2, 2], [0, 1, 0, 2, 2], [-2, 1, 1, 0, 0], [0, -1, 0, 2, 2], [2, 0, 0, 2, 1], [2, 0, 1, 0, 0], [-2, 0, 2, 2, 2], [-2, 0, 1, 2, 1], [2, 0, -2, 0, 1], [2, 0, 0, 0, 1], [0, -1, 1, 0, 0], [-2, -1, 0, 2, 1], [-2, 0, 0, 0, 1], [0, 0, 2, 2, 1], [-2, 0, 2, 0, 1], [-2, 1, 0, 2, 1], [0, 0, 1, -2, 0], [-1, 0, 1, 0, 0], [-2, 1, 0, 0, 0], [1, 0, 0, 0, 0], [0, 0, 1, 2, 0], [0, 0, -2, 2, 2], [-1, -1, 1, 0, 0], [0, 1, 1, 0, 0], [0, -1, 1, 2, 2], [2, -1, -1, 2, 2], [0, 0, 3, 2, 2], [2, -1, 0, 2, 2]]

  This table contains the periodic terms for the argument of the nutation. In Meeus’ book this is Table 22.A and can be found in pages 145-146.

pymeeus.Coordinates.NUTATION_COSINE_COEF_TABLE = [[92025.0, 8.9], [5736.0, -3.1], [977.0, -0.5], [-895.0, 0.5], [54.0, -0.1], [-7.0, 0.0], [224.0, -0.6], [200.0, 0.0], [129.0, -0.1], [-95.0, 0.3], [0.0, 0.0], [-70.0, 0.0], [-53.0, 0.0], [0.0, 0.0], [-33.0, 0.0], [26.0, 0.0], [32.0, 0.0], [27.0, 0.0], [0.0, 0.0], [-24.0, 0.0], [16.0, 0.0], [13.0, 0.0], [0.0, 0.0], [-12.0, 0.0], [0.0, 0.0], [0.0, 0.0], [-10.0, 0.0], [0.0, 0.0], [-8.0, 0.0], [7.0, 0.0], [9.0, 0.0], [7.0, 0.0], [6.0, 0.0], [0.0, 0.0], [5.0, 0.0], [3.0, 0.0], [-3.0, 0.0], [0.0, 0.0], [3.0, 0.0], [3.0, 0.0], [0.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [3.0, 0.0], [3.0, 0.0], [0.0, 0.0], [3.0, 0.0], [3.0, 0.0], [3.0, 0.0]]

  This table contains the periodic terms for the coefficients of the cosine of the argument of the nutation, and they are used to compute Delta epsilon. Units are in 0.0001’’. In Meeus’ book this is Table 22.A and can be found in pages 145-146.

pymeeus.Coordinates.NUTATION_SINE_COEF_TABLE = [[-171996.0, -174.2], [-13187.0, -1.6], [-2274.0, -0.2], [2062.0, 0.2], [1426.0, -3.4], [712.0, 0.1], [-517.0, 1.2], [-386.0, -0.4], [-301.0, 0.0], [217.0, -0.5], [-158.0, 0.0], [129.0, 0.1], [123.0, 0.0], [63.0, 0.0], [63.0, 0.1], [-59.0, 0.0], [-58.0, -0.1], [-51.0, 0.0], [48.0, 0.0], [46.0, 0.0], [-38.0, 0.0], [-31.0, 0.0], [29.0, 0.0], [29.0, 0.0], [26.0, 0.0], [-22.0, 0.0], [21.0, 0.0], [17.0, -0.1], [16.0, 0.0], [-16.0, 0.1], [-15.0, 0.0], [-13.0, 0.0], [-12.0, 0.0], [11.0, 0.0], [-10.0, 0.0], [-8.0, 0.0], [7.0, 0.0], [-7.0, 0.0], [-7.0, 0.0], [-7.0, 0.0], [6.0, 0.0], [6.0, 0.0], [6.0, 0.0], [-6.0, 0.0], [-6.0, 0.0], [5.0, 0.0], [-5.0, 0.0], [-5.0, 0.0], [-5.0, 0.0], [4.0, 0.0], [4.0, 0.0], [4.0, 0.0], [-4.0, 0.0], [-4.0, 0.0], [-4.0, 0.0], [3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0], [-3.0, 0.0]]

  This table contains the periodic terms for the coefficients of the sine of the argument of the nutation, and they are used to compute Delta psi. Units are in 0.0001’’. In Meeus’ book this is Table 22.A and can be found in pages 145-146.

pymeeus.Coordinates.angular_separation(alpha1, delta1, alpha2, delta2)

  This function computes the angular distance between two celestial bodies whose right ascensions and declinations are given.

  Note

  It is possible to use this formula with ecliptial (celestial) longitudes and latitudes instead of right ascensions and declinations, respectively.

  Parameters

    - alpha1 (`Angle`) – Right ascension of celestial body #1, as an Angle object

    - delta1 (`Angle`) – Declination of celestial body #1, as an Angle object

    - alpha2 (`Angle`) – Right ascension of celestial body #2, as an Angle object

    - delta2 (`Angle`) – Declination of celestial body #2, as an Angle object

  Returns

    An Angle object with the angular separation between the given celestial objects

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1 = Angle(14, 15, 39.7, ra=True)
      >>> delta1 = Angle(19, 10, 57.0)
      >>> alpha2 = Angle(13, 25, 11.6, ra=True)
      >>> delta2 = Angle(-11, 9, 41.0)
      >>> sep_ang = angular_separation(alpha1, delta1, alpha2, delta2)
      >>> print(round(sep_ang, 3))
      32.793

pymeeus.Coordinates.apparent_position(epoch, alpha, delta, sun_lon)

  This function computes the apparent position of a star, correcting by nutation and aberration effects.

  Parameters

    - epoch (`Epoch`) – Epoch to compute the apparent position for

    - alpha (`Angle`) – Right ascension of the star, as an Angle object

    - delta (`Angle`) – Declination of the star, as an Angle object

    - sun_lon (`Angle`) – True (geometric) longitude of the Sun

  Returns

    A tuple with two Angle objects: Apparent right ascension, and aparent declination

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> epoch = Epoch(2028, 11, 13.19)
      >>> alpha = Angle(2, 46, 11.331, ra=True)
      >>> delta = Angle(49, 20, 54.54)
      >>> sun_lon = Angle(231.328)
      >>> app_alpha, app_delta = apparent_position(epoch, alpha, delta, sun_lon)
      >>> print(app_alpha.ra_str(n_dec=2))
      2h 46' 14.39''
      >>> print(app_delta.dms_str(n_dec=2))
      49d 21' 7.45''

pymeeus.Coordinates.apparent_vsop_pos(epoch, vsop_l, vsop_b, vsop_r, nutation=True)

  This function computes the apparent position of a celestial body at a given epoch when its VSOP87 periodic term tables are provided. The small correction to convert to the FK5 system is always included.

  Parameters

    - epoch (`Epoch`) – Epoch to compute the position, given as an `Epoch` object

    - vsop_l (list) – Table of VSOP87 terms for the heliocentric longitude

    - vsop_b (list) – Table of VSOP87 terms for the heliocentric latitude

    - vsop_r (list) – Table of VSOP87 terms for the radius vector

    - nutation – Whether the nutation correction will be applied

  Returns

    A tuple with the geometric heliocentric longitude and latitude (as `Angle` objects), and the radius vector (as a float, in astronomical units), in that order

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

pymeeus.Coordinates.circle_diameter(alpha1, delta1, alpha2, delta2, alpha3, delta3)

  This function computes the diameter of the smallest circle that contains three celestial bodies.

  Parameters

    - alpha1 (`Angle`) – Right ascension, as an Angle object, of celestial body #1

    - delta1 (`Angle`) – Declination, as an Angle object, of celestial body #1

    - alpha2 (`Angle`) – Right ascension, as an Angle object, of celestial body #2

    - delta2 (`Angle`) – Declination, as an Angle object, of celestial body #2

    - alpha3 (`Angle`) – Right ascension, as an Angle object, of celestial body #3

    - delta3 (`Angle`) – Declination, as an Angle object, of celestial body #3

  Returns

    The diameter (as an Angle object) of the smallest circle containing the three bodies.

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1 = Angle(12, 41,  8.63, ra=True)
      >>> delta1 = Angle(-5, 37, 54.2)
      >>> alpha2 = Angle(12, 52,  5.21, ra=True)
      >>> delta2 = Angle(-4, 22, 26.2)
      >>> alpha3 = Angle(12, 39, 28.11, ra=True)
      >>> delta3 = Angle(-1, 50,  3.7)
      >>> d = circle_diameter(alpha1, delta1, alpha2, delta2, alpha3, delta3)
      >>> print(d.dms_str(n_dec=0))
      4d 15' 49.0''
      >>> alpha1 = Angle(9,  5, 41.44, ra=True)
      >>> delta1 = Angle(18, 30, 30.0)
      >>> alpha2 = Angle(9,  9, 29.0, ra=True)
      >>> delta2 = Angle(17, 43, 56.7)
      >>> alpha3 = Angle(8, 59, 47.14, ra=True)
      >>> delta3 = Angle(17, 49, 36.8)
      >>> d = circle_diameter(alpha1, delta1, alpha2, delta2, alpha3, delta3)
      >>> print(d.dms_str(n_dec=0))
      2d 18' 38.0''

pymeeus.Coordinates.diurnal_path_horizon(declination, geo_latitude)

  This function returns the angle of the diurnal path of a celestial body relative to the horizon at the time of its rising or setting.

  Parameters

    - declination (`Angle`) – Declination, as an Angle object

    - geo_latitude (`Angle`) – Geodetic latitude, as an Angle object

  Returns

    Angle of the diurnal path of the celestial body relative to the horizon at the time of rising or setting, given as one `Angle` object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> declination = Angle(23.44)
      >>> latitude = Angle(40.0)
      >>> path_angle = diurnal_path_horizon(declination, latitude)
      >>> print(path_angle.dms_str(n_dec=1))
      45d 31' 28.4''

pymeeus.Coordinates.ecliptic_equator(longitude, latitude, obliquity)

  This function returns the angle between the direction of the northern celestial pole and the direction of the north pole of the ecliptic, taking as reference the point whose ecliptic longitude and latitude are given.

  Please note that if we make latitude=0, the result is the angle between the ecliptic (at the given ecliptical longitude) and the east-west direction on the celestial sphere.

  Parameters

    - longitude (`Angle`) – Ecliptical longitude, as an Angle object

    - latitude (`Angle`) – Ecliptical latitude, as an Angle object

    - obliquity (`Angle`) – Obliquity of the ecliptic, as an Angle object

  Returns

    Angle between the direction of the northern celestial pole and the direction of the north pole of the ecliptic, given as one `Angle` object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> lon = Angle(0.0)
      >>> lat = Angle(0.0)
      >>> eps = Angle(23.5)
      >>> ang_ecl_equ = ecliptic_equator(lon, lat, eps)
      >>> print(ang_ecl_equ.dms_str(n_dec=1))
      156d 30' 0.0''

pymeeus.Coordinates.ecliptic_horizon(local_sidereal_time, geo_latitude, obliquity)

  This function returns the longitudes of the two points of the ecliptic which are on the horizon, as well as the angle between the ecliptic and the horizon.

  Parameters

    - local_sidereal_time (`Angle`) – Local sidereal time, as an Angle object

    - geo_latitude (`Angle`) – Geodetic latitude, as an Angle object

    - obliquity (`Angle`) – Obliquity of the ecliptic, as an Angle object

  Returns

    Longitudes of the two points of the ecliptic which are on the horizon, and the angle between the ecliptic and the horizon (in that order), given as three `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> sidereal_time = Angle(5.0, ra=True)
      >>> lat = Angle(51.0)
      >>> epsilon = Angle(23.44)
      >>> lon1, lon2, i = ecliptic_horizon(sidereal_time, lat, epsilon)
      >>> print(lon1.dms_str(n_dec=1))
      169d 21' 29.9''
      >>> print(lon2.dms_str(n_dec=1))
      349d 21' 29.9''
      >>> print(round(i, 0))
      62.0

pymeeus.Coordinates.ecliptical2equatorial(longitude, latitude, obliquity)

  This function converts from ecliptical coordinates (longitude and latitude) to equatorial coordinated (right ascension and declination).

  Parameters

    - longitude (`Angle`) – Ecliptical longitude, as an Angle object

    - latitude (`Angle`) – Ecliptical latitude, as an Angle object

    - obliquity (`Angle`) – Obliquity of the ecliptic, as an Angle object

  Returns

    Equatorial coordinates (right ascension, declination, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> lon = Angle(113.21563)
      >>> lat = Angle(6.68417)
      >>> epsilon = Angle(23.4392911)
      >>> ra, dec = ecliptical2equatorial(lon, lat, epsilon)
      >>> print(ra.ra_str(n_dec=3))
      7h 45' 18.946''
      >>> print(dec.dms_str(n_dec=2))
      28d 1' 34.26''

pymeeus.Coordinates.equatorial2ecliptical(right_ascension, declination, obliquity)

  This function converts from equatorial coordinated (right ascension and declination) to ecliptical coordinates (longitude and latitude).

  Parameters

    - right_ascension – Right ascension, as an Angle object

    - declination – Declination, as an Angle object

    - obliquity (`Angle`) – Obliquity of the ecliptic, as an Angle object

  Returns

    Ecliptical coordinates (longitude, latitude, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> ra = Angle(7, 45, 18.946, ra=True)
      >>> dec = Angle(28, 1, 34.26)
      >>> epsilon = Angle(23.4392911)
      >>> lon, lat = equatorial2ecliptical(ra, dec, epsilon)
      >>> print(round(lon(), 5))
      113.21563
      >>> print(round(lat(), 5))
      6.68417

pymeeus.Coordinates.equatorial2galactic(right_ascension, declination)

  This function converts from equatorial coordinates (right ascension and declination) to galactic coordinates (longitude and latitude).

  The current galactic system of coordinates was defined by the International Astronomical Union in 1959, using the standard equatorial system of epoch B1950.0.

  Parameters

    - right_ascension (`Angle`) – Right ascension, as an Angle object

    - declination (`Angle`) – Declination, as an Angle object

  Returns

    Galactic coordinates (longitude and latitude, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> ra = Angle(17, 48, 59.74, ra=True)
      >>> dec = Angle(-14, 43, 8.2)
      >>> lon, lat = equatorial2galactic(ra, dec)
      >>> print(round(lon, 4))
      12.9593
      >>> print(round(lat, 4))
      6.0463

pymeeus.Coordinates.equatorial2horizontal(hour_angle, declination, geo_latitude)

  This function converts from equatorial coordinates (right ascension and declination) to local horizontal coordinates (azimuth and elevation).

  Following Meeus’ convention, the azimuth is measured westward from the SOUTH. If you want the azimuth to be measured from the north (common custom between navigators and meteorologits), you should add 180 degrees.

  The hour angle (H) comprises information about the sidereal time, the observer’s geodetic longitude (positive west from Greenwich) and the right ascension. If theta is the local sidereal time, theta0 the sidereal time at Greenwich, lon the observer’s longitude and ra the right ascension, the following expressions hold:

  > H = theta - ra H = theta0 - lon - ra

  Parameters

    - hour_angle (`Angle`) – Hour angle, as an Angle object

    - declination (`Angle`) – Declination, as an Angle object

    - geo_latitude (`Angle`) – Geodetic latitude of the observer, as an Angle object

  Returns

    Local horizontal coordinates (azimuth, elevation, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> lon = Angle(77, 3, 56)
      >>> lat = Angle(38, 55, 17)
      >>> ra = Angle(23, 9, 16.641, ra=True)
      >>> dec = Angle(-6, 43, 11.61)
      >>> theta0 = Angle(8, 34, 57.0896, ra=True)
      >>> eps = Angle(23, 26, 36.87)
      >>> delta = Angle(0, 0, ((-3.868*cos(eps.rad()))/15.0), ra=True)
      >>> theta0 += delta
      >>> h = theta0 - lon - ra
      >>> azi, ele = equatorial2horizontal(h, dec, lat)
      >>> print(round(azi, 3))
      68.034
      >>> print(round(ele, 3))
      15.125

pymeeus.Coordinates.galactic2equatorial(longitude, latitude)

  This function converts from galactic coordinates (longitude and latitude) to equatorial coordinates (right ascension and declination).

  The current galactic system of coordinates was defined by the International Astronomical Union in 1959, using the standard equatorial system of epoch B1950.0.

  Parameters

    - longitude (`Angle`) – Longitude, as an Angle object

    - latitude (`Angle`) – Latitude, as an Angle object

  Returns

    Equatorial coordinates (right ascension and declination, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> lon = Angle(12.9593)
      >>> lat = Angle(6.0463)
      >>> ra, dec = galactic2equatorial(lon, lat)
      >>> print(ra.ra_str(n_dec=1))
      17h 48' 59.7''
      >>> print(dec.dms_str(n_dec=0))
      -14d 43' 8.0''

pymeeus.Coordinates.geometric_vsop_pos(epoch, vsop_l, vsop_b, vsop_r, tofk5=True)

  This function computes the geometric position of a celestial body at a given epoch when its VSOP87 periodic term tables are provided. The small correction to convert to the FK5 system may or not be included.

  Parameters

    - epoch (`Epoch`) – Epoch to compute the position, given as an `Epoch` object

    - vsop_l (list) – Table of VSOP87 terms for the heliocentric longitude

    - vsop_b (list) – Table of VSOP87 terms for the heliocentric latitude

    - vsop_r (list) – Table of VSOP87 terms for the radius vector

    - tofk5 (bool) – Whether or not the small correction to convert to the FK5 system will be applied

  Returns

    A tuple with the geometric heliocentric longitude and latitude (as `Angle` objects), and the radius vector (as a float, in astronomical units), in that order

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

pymeeus.Coordinates.horizontal2equatorial(azimuth, elevation, geo_latitude)

  This function converts from local horizontal coordinates (azimuth and elevation) to equatorial coordinates (right ascension and declination).

  Following Meeus’ convention, the azimuth is measured westward from the SOUTH.

  This function returns the hour angle and the declination. The hour angle (H) comprises information about the sidereal time, the observer’s geodetic longitude (positive west from Greenwich) and the right ascension. If theta is the local sidereal time, theta0 the sidereal time at Greenwich, lon the observer’s longitude and ra the right ascension, the following expressions hold:

  > H = theta - ra H = theta0 - lon - ra

  Parameters

    - azimuth (`Angle`) – Azimuth, measured westward from south, as an Angle object

    - elevation (`Angle`) – Elevation from the horizon, as an Angle object

    - geo_latitude (`Angle`) – Geodetic latitude of the observer, as an Angle object

  Returns

    Equatorial coordinates (as hour angle and declination, in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> azi = Angle(68.0337)
      >>> ele = Angle(15.1249)
      >>> lat = Angle(38, 55, 17)
      >>> h, dec = horizontal2equatorial(azi, ele, lat)
      >>> print(round(h, 4))
      64.3521
      >>> print(dec.dms_str(n_dec=0))
      -6d 43' 12.0''

pymeeus.Coordinates.illuminated_fraction(sun_dist, earth_dist, sun_earth_dist)

  This function computes the illuminated fraction of the disk of a planet, as seen from the Earth.

  Parameters

    - sun_dist (float) – Planet’s distance to the Sun, in Astronomical Units

    - earth_dist (float) – Distance from planet to Earth, in Astronomical Units

    - sun_earth_dist (float) – Distance Sun-Earth, in Astronomical Units

  Returns

    The illuminated fraction of the disc of a planet

  Return type

    float

  Raises

    TypeError if input values are of wrong type.

      >>> sun_dist = 0.724604
      >>> earth_dist = 0.910947
      >>> sun_earth_dist = 0.983824
      >>> k = illuminated_fraction(sun_dist, earth_dist, sun_earth_dist)
      >>> print(round(k, 3))
      0.647

pymeeus.Coordinates.kepler_equation(eccentricity, mean_anomaly)

  This function computes the eccentric and true anomalies taking as input the mean anomaly and the eccentricity.

  Parameters

    - eccentricity (int, float) – Orbit’s eccentricity

    - mean_anomaly (`Angle`) – Mean anomaly, as an Angle object

  Returns

    A tuple with two Angle objects: Eccentric and true anomalies

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> eccentricity = 0.1
      >>> mean_anomaly = Angle(5.0)
      >>> e, v = kepler_equation(eccentricity, mean_anomaly)
      >>> print(round(e(), 6))
      5.554589
      >>> print(round(v(), 6))
      6.139762
      >>> eccentricity = 0.99
      >>> mean_anomaly = Angle(2.0)
      >>> e, v = kepler_equation(eccentricity, mean_anomaly)
      >>> print(round(e(), 6))
      32.361007
      >>> print(round(v(), 6))
      152.542134
      >>> eccentricity = 0.99
      >>> mean_anomaly = Angle(5.0)
      >>> e, v = kepler_equation(eccentricity, mean_anomaly)
      >>> print(round(e(), 6))
      45.361023
      >>> print(round(v(), 6))
      160.745616
      >>> eccentricity = 0.99
      >>> mean_anomaly = Angle(1.0)
      >>> e, v = kepler_equation(eccentricity, mean_anomaly)
      >>> print(round(e(), 6))
      24.725822
      >>> print(round(v(), 6))
      144.155952
      >>> e, v = kepler_equation(0.999, Angle(7.0))
      >>> print(round(e(), 7))
      52.2702615
      >>> print(round(v(), 6))
      174.780018
      >>> e, v = kepler_equation(0.99, Angle(0.2, radians=True))
      >>> print(round(e(), 8))
      61.13444578
      >>> print(round(v(), 6))
      166.311977

pymeeus.Coordinates.length_orbit(e, a)

  This function computes the length of an elliptic orbit given its eccentricity and semimajor axis.

  Parameters

    - e (float) – Orbital eccentricity

    - a (float) – Semimajor axis of the orbit, in Astronomical Units

  Returns

    Length of the orbit in Astronomical Units

  Return type

    float

  Raises

    TypeError if input values are of wrong type.

      >>> a = 17.9400782
      >>> e = 0.96727426
      >>> length = length_orbit(e, a)
      >>> print(round(length, 2))
      77.06

pymeeus.Coordinates.mean_obliquity(*args, **kwargs)

  This function computes the mean obliquity (epsilon0) at the provided date.

  This function internally uses an `Epoch` object, and the utc argument then controls the way the UTC->TT conversion is handled for that 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.

  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

    - utc (bool) – Whether the provided epoch is a civil time (UTC) or TT

    - 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

    The mean obliquity of the ecliptic, as an `Angle`

  Return type

    `Angle`

  Raises

    ValueError if input values are in the wrong range.

  Raises

    TypeError if input values are of wrong type.

      >>> e0 = mean_obliquity(1987, 4, 10)
      >>> a = e0.dms_tuple()
      >>> a[0]
      23
      >>> a[1]
      26
      >>> round(a[2], 3)
      27.407

pymeeus.Coordinates.minimum_angular_separation(alpha1_1, delta1_1, alpha1_2, delta1_2, alpha1_3, delta1_3, alpha2_1, delta2_1, alpha2_2, delta2_2, alpha2_3, delta2_3)

  Given the positions at three different instants of times (equidistant) of two celestial objects, this function computes the minimum angular distance that will be achieved within that interval of time.

  Note

  Suffix ‘1 _’ is for the first celestial object, and ‘2 _’ is for the second one.

  Note

  This function provides as output the ‘n’ fraction of time when the minimum angular separation is achieved. For that, the epoch in the middle is assigned the value “n = 0”. Therefore, n < 0 is for times before the middle epoch, and n > 0 is for times after the middle epoch.

  Parameters

    - alpha1_1 (`Angle`) – First right ascension of celestial body #1, as an Angle object

    - delta1_1 (`Angle`) – First declination of celestial body #1, as an Angle object

    - alpha1_2 (`Angle`) – Second right ascension of celestial body #1, as an Angle object

    - delta1_2 (`Angle`) – Second declination of celestial body #1, as Angle object

    - alpha1_3 (`Angle`) – Third right ascension of celestial body #1, as an Angle object

    - delta1_3 (`Angle`) – Third declination of celestial body #1, as an Angle object

    - alpha2_1 (`Angle`) – First right ascension of celestial body #2, as an Angle object

    - delta2_1 (`Angle`) – First declination of celestial body #2, as an Angle object

    - alpha2_2 (`Angle`) – Second right ascension of celestial body #2, as an Angle object

    - delta2_2 (`Angle`) – Second declination of celestial body #2, as Angle object

    - alpha2_3 (`Angle`) – Third right ascension of celestial body #2, as an Angle object

    - delta2_3 (`Angle`) – Third declination of celestial body #2, as an Angle object

  Returns

    A tuple with two components: The first component is a float containing the ‘n’ fraction of time when the minimum angular separation is achieved. The second component is an Angle object containing the minimum angular separation between the given celestial objects

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1_1 = Angle(10, 29, 44.27, ra=True)
      >>> delta1_1 = Angle(11, 2, 5.9)
      >>> alpha2_1 = Angle(10, 33, 29.64, ra=True)
      >>> delta2_1 = Angle(10, 40, 13.2)
      >>> alpha1_2 = Angle(10, 36, 19.63, ra=True)
      >>> delta1_2 = Angle(10, 29, 51.7)
      >>> alpha2_2 = Angle(10, 33, 57.97, ra=True)
      >>> delta2_2 = Angle(10, 37, 33.4)
      >>> alpha1_3 = Angle(10, 43, 1.75, ra=True)
      >>> delta1_3 = Angle(9, 55, 16.7)
      >>> alpha2_3 = Angle(10, 34, 26.22, ra=True)
      >>> delta2_3 = Angle(10, 34, 53.9)
      >>> a = minimum_angular_separation(alpha1_1, delta1_1, alpha1_2, delta1_2,                                       alpha1_3, delta1_3, alpha2_1, delta2_1,                                       alpha2_2, delta2_2, alpha2_3, delta2_3)
      >>> print(round(a[0], 6))
      -0.370726
      >>> print(a[1].dms_str(n_dec=0))
      3' 44.0''

pymeeus.Coordinates.motion_in_space(start_ra, start_dec, distance, velocity, p_motion_ra, p_motion_dec, time)

  This function computes the star’s true motion through space relative to the Sun, allowing to compute the start proper motion at a given time.

  Parameters

    - start_ra (`Angle`) – Initial right ascension

    - start_dec (`Angle`) – Initial declination

    - distance (float) – Star’s distance to the Sun, in parsecs. If distance is given in light-years, multipy it by 0.3066. If the star’s parallax pie (in arcseconds) is given, use (1.0/pie).

    - velocity (float) – Radial velocity in km/s

    - p_motion_ra (`Angle`) – Proper motion in right ascension, in degrees per year.

    - p_motion_dec (`Angle`) – Proper motion in declination, in degrees per year.

    - time (float) – Number of years since starting epoch, positive in the future, negative in the past

  Returns

    Equatorial coordinates (right ascension, declination, in that order) corresponding to the final epoch, given as two objects `Angle` inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> ra = Angle(6, 45, 8.871, ra=True)
      >>> dec = Angle(-16.716108)
      >>> pm_ra = Angle(0, 0, -0.03847, ra=True)
      >>> pm_dec = Angle(0, 0, -1.2053)
      >>> dist = 2.64
      >>> vel = -7.6
      >>> alpha, delta = motion_in_space(ra, dec, dist, vel, pm_ra, pm_dec,
      ...                                -1000.0)
      >>> print(alpha.ra_str(False, 2))
      6:45:47.16
      >>> print(delta.dms_str(False, 1))
      -16:22:56.0
      >>> alpha, delta = motion_in_space(ra, dec, dist, vel, pm_ra, pm_dec,
      ...                                -4000.0)
      >>> print(alpha.ra_str(False, 2))
      6:47:39.91
      >>> print(delta.dms_str(False, 1))
      -15:23:30.6

pymeeus.Coordinates.nutation_longitude(*args, **kwargs)

  This function computes the nutation in longitude (Delta psi) at the provided date.

  This function internally uses an `Epoch` object, and the utc argument then controls the way the UTC->TT conversion is handled for that 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.

  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

    - utc (bool) – Whether the provided epoch is a civil time (UTC) or TT

    - 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

    The nutation in longitude (Delta psi), as an Angle

  Return type

    `Angle`

  Raises

    ValueError if input values are in the wrong range.

  Raises

    TypeError if input values are of wrong type.

      >>> dpsi = nutation_longitude(1987, 4, 10)
      >>> a = dpsi.dms_tuple()
      >>> a[0]
      0
      >>> a[1]
      0
      >>> round(a[2], 3)
      3.788
      >>> a[3]
      -1.0

pymeeus.Coordinates.nutation_obliquity(*args, **kwargs)

  This function computes the nutation in obliquity (Delta epsilon) at the provided date.

  This function internally uses an `Epoch` object, and the utc argument then controls the way the UTC->TT conversion is handled for that 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.

  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

    - utc (bool) – Whether the provided epoch is a civil time (UTC) or TT

    - 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

    The nutation in obliquity (Delta epsilon), as an `Angle`

  Return type

    `Angle`

  Raises

    ValueError if input values are in the wrong range.

  Raises

    TypeError if input values are of wrong type.

      >>> depsilon = nutation_obliquity(1987, 4, 10)
      >>> a = depsilon.dms_tuple()
      >>> a[0]
      0
      >>> a[1]
      0
      >>> round(a[2], 3)
      9.443
      >>> a[3]
      1.0

pymeeus.Coordinates.orbital_elements(epoch, parameters1, parameters2)

  This function computes the orbital elements for a given epoch, according to the parameters beeing passed as arguments.

  Parameters

    - epoch (`Epoch`) – Epoch to compute orbital elements, as an Epoch object

    - parameters1 (list) – First set of parameters

    - parameters2 (list) – Second set of parameters

  Returns

    A tuple containing the following six orbital elements: - Mean longitude of the planet (Angle) - Semimajor axis of the orbit (float, astronomical units) - eccentricity of the orbit (float) - inclination on the plane of the ecliptic (Angle) - longitude of the ascending node (Angle) - argument of the perihelion (Angle)

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

pymeeus.Coordinates.orbital_equinox2equinox(epoch0, epoch, i0, arg0, lon0)

  This function reduces the orbital elements of a celestial object from one equinox to another.

  Parameters

    - epoch0 (`Epoch`) – Initial epoch

    - epoch (`Epoch`) – Final epoch

    - i0 (`Angle`) – Initial inclination, as an Angle object

    - arg0 (`Angle`) – Initial argument of perihelion, as an Angle object

    - lon0 (`Angle`) – Initial longitude of ascending node, as an Angle object

  Returns

    A tuple with three Angle objects: Final inclination, argument of perihelion and longitude of ascending node, in that order

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> epoch0 = Epoch(2358042.5305)
      >>> epoch = Epoch(2433282.4235)
      >>> i0 = Angle(47.122)
      >>> arg0 = Angle(151.4486)
      >>> lon0 = Angle(45.7481)
      >>> i1, arg1, lon1 = orbital_equinox2equinox(epoch0, epoch, i0, arg0, lon0)
      >>> print(round(i1(), 3))
      47.138
      >>> print(round(arg1(), 4))
      151.4782
      >>> print(round(lon1(), 4))
      48.6037

pymeeus.Coordinates.p_motion_equa2eclip(p_motion_ra, p_motion_dec, ra, dec, lat, epsilon)

  It is usual that proper motions are given in equatorial coordinates, not in ecliptical ones. Therefore, this function converts the provided proper motions in equatorial coordinates to the corresponding ones in ecliptical coordinates.

  Parameters

    - p_motion_ra (`Angle`) – Proper motion in right ascension, in degrees per year, as an `Angle` object

    - p_motion_dec (`Angle`) – Proper motion in declination, in degrees per year, as an `Angle` object

    - ra (`Angle`) – Right ascension of the astronomical object, as degrees in an `Angle` object

    - dec (`Angle`) – Declination of the astronomical object, as degrees in an `Angle` object

    - lat (`Angle`) – Ecliptical latitude of the astronomical object, as degrees in an `Angle` object

    - epsilon (`Angle`) – Obliquity of the ecliptic

  Returns

    Proper motions in ecliptical longitude and latitude (in that order), given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

pymeeus.Coordinates.parallactic_angle(hour_angle, declination, geo_latitude)

  This function computes the parallactic angle, an apparent rotation that appears because celestial bodies move along parallel circles. By convention, the parallactic angle is negative before the passage through the southern meridian (in the north hemisphere), and positive afterwards. Exactly on the meridian, its value is zero.

  Please note that when the celestial body is exactly at the zenith, the parallactic angle is not defined, and this function will return ‘None’.

  The hour angle (H) comprises information about the sidereal time, the observer’s geodetic longitude (positive west from Greenwich) and the right ascension. If theta is the local sidereal time, theta0 the sidereal time at Greenwich, lon the observer’s longitude and ra the right ascension, the following expressions hold:

  > H = theta - ra H = theta0 - lon - ra

  Parameters

    - hour_angle (`Angle`) – Hour angle, as an Angle object

    - declination (`Angle`) – Declination, as an Angle object

    - geo_latitude (`Angle`) – Geodetic latitude of the observer, as an Angle object

  Returns

    Parallactic angle as an py:class:Angle object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> hour_angle = Angle(0.0)
      >>> declination = Angle(45.0)
      >>> latitude = Angle(50.0)
      >>> q = parallactic_angle(hour_angle, declination, latitude)
      >>> print(q.dms_str(n_dec=1))
      0d 0' 0.0''

pymeeus.Coordinates.passage_nodes_elliptic(omega, e, a, t, ascending=True)

  This function computes the time of passage by the nodes (ascending or descending) of a given celestial object with an elliptic orbit.

  Parameters

    - omega (`Angle`) – Argument of the perihelion

    - e (float) – Orbital eccentricity

    - a (float) – Semimajor axis of the orbit, in Astronomical Units

    - t (`Epoch`) – Time of perihelion passage

    - ascending (bool) – Whether the time of passage by the ascending (True) or descending (False) node will be computed

  Returns

    Tuple containing: - Time of passage through the node (`Epoch`) - Radius vector when passing through the node (in AU, float)

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> omega = Angle(111.84644)
      >>> e = 0.96727426
      >>> a = 17.9400782
      >>> t = Epoch(1986, 2, 9.45891)
      >>> time, r = passage_nodes_elliptic(omega, e, a, t)
      >>> year, month, day = time.get_date()
      >>> print(year)
      1985
      >>> print(month)
      11
      >>> print(round(day, 2))
      9.16
      >>> print(round(r, 4))
      1.8045
      >>> time, r = passage_nodes_elliptic(omega, e, a, t, ascending=False)
      >>> year, month, day = time.get_date()
      >>> print(year)
      1986
      >>> print(month)
      3
      >>> print(round(day, 2))
      10.37
      >>> print(round(r, 4))
      0.8493

pymeeus.Coordinates.passage_nodes_parabolic(omega, q, t, ascending=True)

  This function computes the time of passage by the nodes (ascending or descending) of a given celestial object with a parabolic orbit.

  Parameters

    - omega (`Angle`) – Argument of the perihelion

    - q (float) – Perihelion distance, in Astronomical Units

    - t (`Epoch`) – Time of perihelion passage

    - ascending (bool) – Whether the time of passage by the ascending (True) or descending (False) node will be computed

  Returns

    Tuple containing: - Time of passage through the node (`Epoch`) - Radius vector when passing through the node (in AU, float)

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> omega = Angle(154.9103)
      >>> q = 1.324502
      >>> t = Epoch(1989, 8, 20.291)
      >>> time, r = passage_nodes_parabolic(omega, q, t)
      >>> year, month, day = time.get_date()
      >>> print(year)
      1977
      >>> print(month)
      9
      >>> print(round(day, 2))
      17.64
      >>> print(round(r, 4))
      28.0749
      >>> time, r = passage_nodes_parabolic(omega, q, t, ascending=False)
      >>> year, month, day = time.get_date()
      >>> print(year)
      1989
      >>> print(month)
      9
      >>> print(round(day, 3))
      17.636
      >>> print(round(r, 4))
      1.3901

pymeeus.Coordinates.phase_angle(sun_dist, earth_dist, sun_earth_dist)

  This function computes the phase angle, i.e., the angle Sun-planet-Earth from the corresponding distances.

  Parameters

    - sun_dist (float) – Planet’s distance to the Sun, in Astronomical Units

    - earth_dist (float) – Distance from planet to Earth, in Astronomical Units

    - sun_earth_dist (float) – Distance Sun-Earth, in Astronomical Units

  Returns

    The phase angle, as an Angle object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> sun_dist = 0.724604
      >>> earth_dist = 0.910947
      >>> sun_earth_dist = 0.983824
      >>> angle = phase_angle(sun_dist, earth_dist, sun_earth_dist)
      >>> print(round(angle, 2))
      72.96

pymeeus.Coordinates.planet_star_conjunction(alpha_list, delta_list, alpha_star, delta_star)

  Given the positions of one planet passing near a star, this function computes the time of conjunction in right ascension, and the difference in declination of the two bodies at that time.

  Note

  This function provides as output the ‘n’ fraction of time when the minimum angular separation is achieved. For that, the epoch in the middle is assigned the value “n = 0”. Therefore, n < 0 is for times before the middle epoch, and n > 0 is for times after the middle epoch.

  Note

  When the entries in the input values for the planet are more than three and pair, the last entry is discarted and an odd number of entries will be used.

  Parameters

    - alpha_list (list, tuple of `Angle`) – List (or tuple) containing the right ascensions (as Angle objects) for the planet (minimum 3 entries)

    - delta_list (list, tuple of `Angle`) – List (or tuple) containing the declinations (as Angle objects) for the planet (minimum 3 entries)

    - alpha_star (`Angle`) – Right ascension, as an Angle object, of the star

    - delta_star (`Angle`) – Declination, as an Angle object, of the star

  Returns

    A tuple with two components: The first component is a float containing the ‘n’ fraction of time when the conjunction occurs. The second component is an Angle object containing the declination separation between the given objects at conjunction epoch

  Return type

    tuple

  Raises

    ValueError if input values for planet have less than three entries or they don’t have the same number of entries.

  Raises

    TypeError if input values are of wrong type.

      >>> alpha_1 = Angle(15,  3, 51.937, ra=True)
      >>> delta_1 = Angle(-8, 57, 34.51)
      >>> alpha_2 = Angle(15,  9, 57.327, ra=True)
      >>> delta_2 = Angle(-9,  9,  3.88)
      >>> alpha_3 = Angle(15, 15, 37.898, ra=True)
      >>> delta_3 = Angle(-9, 17, 37.94)
      >>> alpha_4 = Angle(15, 20, 50.632, ra=True)
      >>> delta_4 = Angle(-9, 23, 16.25)
      >>> alpha_5 = Angle(15, 25, 32.695, ra=True)
      >>> delta_5 = Angle(-9, 26,  1.01)
      >>> alpha_star = Angle(15, 17, 0.446, ra=True)
      >>> delta_star = Angle(-9, 22, 58.47)
      >>> alpha_list = [alpha_1, alpha_2, alpha_3, alpha_4, alpha_5]
      >>> delta_list = [delta_1, delta_2, delta_3, delta_4, delta_5]
      >>> pc = planet_star_conjunction(alpha_list, delta_list,                                      alpha_star, delta_star)
      >>> print(round(pc[0], 4))
      0.2551
      >>> print(pc[1].dms_str(n_dec=0))
      3' 38.0''

pymeeus.Coordinates.planet_stars_in_line(alpha_list, delta_list, alpha_star1, delta_star1, alpha_star2, delta_star2)

  Given the positions of one planet, this function computes the time when it is in a straight line with two other stars.

  Note

  This function provides as output the ‘n’ fraction of time when the minimum angular separation is achieved. For that, the epoch in the middle is assigned the value “n = 0”. Therefore, n < 0 is for times before the middle epoch, and n > 0 is for times after the middle epoch.

  Note

  When the entries in the input values for the planet are more than three and pair, the last entry is discarted and an odd number of entries will be used.

  Parameters

    - alpha_list (list, tuple of `Angle`) – List (or tuple) containing the right ascensions (as Angle objects) for the planet (minimum 3 entries)

    - delta_list (list, tuple of `Angle`) – List (or tuple) containing the declinations (as Angle objects) for the planet (minimum 3 entries)

    - alpha_star1 (`Angle`) – Right ascension, as an Angle object, of star #1

    - delta_star1 (`Angle`) – Declination, as an Angle object, of star #1

    - alpha_star2 (`Angle`) – Right ascension, as an Angle object, of star #2

    - delta_star2 (`Angle`) – Declination, as an Angle object, of star #2

  Returns

    A float containing the ‘n’ fraction of time when the alignment occurs.

  Return type

    float

  Raises

    ValueError if input values for planet have less than three entries or they don’t have the same number of entries.

  Raises

    TypeError if input values are of wrong type.

      >>> alpha_1 = Angle( 7, 55, 55.36, ra=True)
      >>> delta_1 = Angle(21, 41,  3.0)
      >>> alpha_2 = Angle( 7, 58, 22.55, ra=True)
      >>> delta_2 = Angle(21, 35, 23.4)
      >>> alpha_3 = Angle( 8,  0, 48.99, ra=True)
      >>> delta_3 = Angle(21, 29, 38.2)
      >>> alpha_4 = Angle( 8,  3, 14.66, ra=True)
      >>> delta_4 = Angle(21, 23, 47.5)
      >>> alpha_5 = Angle( 8,  5, 39.54, ra=True)
      >>> delta_5 = Angle(21, 17, 51.4)
      >>> alpha_star1 = Angle( 7, 34, 16.40, ra=True)
      >>> delta_star1 = Angle(31, 53, 51.2)
      >>> alpha_star2 = Angle( 7, 45,  0.10, ra=True)
      >>> delta_star2 = Angle(28,  2, 12.5)
      >>> alpha_list = [alpha_1, alpha_2, alpha_3, alpha_4, alpha_5]
      >>> delta_list = [delta_1, delta_2, delta_3, delta_4, delta_5]
      >>> n = planet_stars_in_line(alpha_list, delta_list, alpha_star1,                                  delta_star1, alpha_star2, delta_star2)
      >>> print(round(n, 4))
      0.2233

pymeeus.Coordinates.planetary_conjunction(alpha1_list, delta1_list, alpha2_list, delta2_list)

  Given the positions of two planets passing near each other, this function computes the time of conjunction in right ascension, and the difference in declination of the two bodies at that time.

  Note

  This function provides as output the ‘n’ fraction of time when the minimum angular separation is achieved. For that, the epoch in the middle is assigned the value “n = 0”. Therefore, n < 0 is for times before the middle epoch, and n > 0 is for times after the middle epoch.

  Note

  When the entries in the input values are more than three and even, the last entry is discarted and an odd number of entries will be used.

  Parameters

    - alpha1_list (list, tuple of `Angle`) – List (or tuple) containing the right ascensions (as Angle objects) for object #1 (minimum 3 entries)

    - delta1_list (list, tuple of `Angle`) – List (or tuple) containing the declinations (as Angle objects) for object #1 (minimum 3 entries)

    - alpha2_list (list, tuple of `Angle`) – List (or tuple) containing the right ascensions (as Angle objects) for object #2 (minimum 3 entries)

    - delta2_list (list, tuple of `Angle`) – List (or tuple) containing the declinations (as Angle objects) for object #2 (minimum 3 entries)

  Returns

    A tuple with two components: The first component is a float containing the ‘n’ fraction of time when the conjunction occurs. The second component is an Angle object containing the declination separation between the given objects at conjunction epoch

  Return type

    tuple

  Raises

    ValueError if input values have less than three entries or they don’t have the same number of entries.

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1_1 = Angle(10, 24, 30.125, ra=True)
      >>> delta1_1 = Angle( 6, 26, 32.05)
      >>> alpha1_2 = Angle(10, 25,  0.342, ra=True)
      >>> delta1_2 = Angle( 6, 10, 57.72)
      >>> alpha1_3 = Angle(10, 25, 12.515, ra=True)
      >>> delta1_3 = Angle( 5, 57, 33.08)
      >>> alpha1_4 = Angle(10, 25,  6.235, ra=True)
      >>> delta1_4 = Angle( 5, 46, 27.07)
      >>> alpha1_5 = Angle(10, 24, 41.185, ra=True)
      >>> delta1_5 = Angle( 5, 37, 48.45)
      >>> alpha2_1 = Angle(10, 27, 27.175, ra=True)
      >>> delta2_1 = Angle( 4,  4, 41.83)
      >>> alpha2_2 = Angle(10, 26, 32.410, ra=True)
      >>> delta2_2 = Angle( 3, 55, 54.66)
      >>> alpha2_3 = Angle(10, 25, 29.042, ra=True)
      >>> delta2_3 = Angle( 3, 48,  3.51)
      >>> alpha2_4 = Angle(10, 24, 17.191, ra=True)
      >>> delta2_4 = Angle( 3, 41, 10.25)
      >>> alpha2_5 = Angle(10, 22, 57.024, ra=True)
      >>> delta2_5 = Angle( 3, 35, 16.61)
      >>> alpha1_list = [alpha1_1, alpha1_2, alpha1_3, alpha1_4, alpha1_5]
      >>> delta1_list = [delta1_1, delta1_2, delta1_3, delta1_4, delta1_5]
      >>> alpha2_list = [alpha2_1, alpha2_2, alpha2_3, alpha2_4, alpha2_5]
      >>> delta2_list = [delta2_1, delta2_2, delta2_3, delta2_4, delta2_5]
      >>> pc = planetary_conjunction(alpha1_list, delta1_list,                                    alpha2_list, delta2_list)
      >>> print(round(pc[0], 5))
      0.23797
      >>> print(pc[1].dms_str(n_dec=1))
      2d 8' 21.8''

pymeeus.Coordinates.precession_ecliptical(start_epoch, final_epoch, start_lon, start_lat, p_motion_lon=0.0, p_motion_lat=0.0)

  This function converts the ecliptical coordinates (longitude and latitude) given for an epoch and a equinox, to the corresponding values for another epoch and equinox. Only the mean positions, i.e. the effects of precession and proper motion, are considered here.

  Parameters

    - start_epoch (`Epoch`) – Initial epoch when initial coordinates are given

    - final_epoch (`Epoch`) – Final epoch for when coordinates are going to be computed

    - start_lon (`Angle`) – Initial longitude

    - start_lat (`Angle`) – Initial latitude

    - p_motion_lon (`Angle`) – Proper motion in longitude, in degrees per year. Zero by default.

    - p_motion_lat (`Angle`) – Proper motion in latitude, in degrees per year. Zero by default.

  Returns

    Ecliptical coordinates (longitude, latitude, in that order) corresponding to the final epoch, given as two `Angle` objects inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> start_epoch = JDE2000
      >>> final_epoch = Epoch(-214, 6, 30.0)
      >>> lon0 = Angle(149.48194)
      >>> lat0 = Angle(1.76549)
      >>> lon, lat = precession_ecliptical(start_epoch, final_epoch, lon0, lat0)
      >>> print(round(lon(), 3))
      118.704
      >>> print(round(lat(), 3))
      1.615

pymeeus.Coordinates.precession_equatorial(start_epoch, final_epoch, start_ra, start_dec, p_motion_ra=0.0, p_motion_dec=0.0)

  This function converts the equatorial coordinates (right ascension and declination) given for an epoch and a equinox, to the corresponding values for another epoch and equinox. Only the mean positions, i.e. the effects of precession and proper motion, are considered here.

  Parameters

    - start_epoch (`Epoch`) – Initial epoch when initial coordinates are given

    - final_epoch (`Epoch`) – Final epoch for when coordinates are going to be computed

    - start_ra (`Angle`) – Initial right ascension

    - start_dec (`Angle`) – Initial declination

    - p_motion_ra (`Angle`) – Proper motion in right ascension, in degrees per year. Zero by default.

    - p_motion_dec (`Angle`) – Proper motion in declination, in degrees per year. Zero by default.

  Returns

    Equatorial coordinates (right ascension, declination, in that order) corresponding to the final epoch, given as two objects `Angle` inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> start_epoch = JDE2000
      >>> final_epoch = Epoch(2028, 11, 13.19)
      >>> alpha0 = Angle(2, 44, 11.986, ra=True)
      >>> delta0 = Angle(49, 13, 42.48)
      >>> pm_ra = Angle(0, 0, 0.03425, ra=True)
      >>> pm_dec = Angle(0, 0, -0.0895)
      >>> alpha, delta = precession_equatorial(start_epoch, final_epoch, alpha0,
      ...                                      delta0, pm_ra, pm_dec)
      >>> print(alpha.ra_str(False, 3))
      2:46:11.331
      >>> print(delta.dms_str(False, 2))
      49:20:54.54

pymeeus.Coordinates.precession_newcomb(start_epoch, final_epoch, start_ra, start_dec, p_motion_ra=0.0, p_motion_dec=0.0)

  This function implements the Newcomb precessional equations used in the old FK4 system. It takes equatorial coordinates (right ascension and declination) given for an epoch and a equinox, and converts them to the corresponding values for another epoch and equinox. Only the mean positions, i.e. the effects of precession and proper motion, are considered here.

  Parameters

    - start_epoch (`Epoch`) – Initial epoch when initial coordinates are given

    - final_epoch (`Epoch`) – Final epoch for when coordinates are going to be computed

    - start_ra (`Angle`) – Initial right ascension

    - start_dec (`Angle`) – Initial declination

    - p_motion_ra (`Angle`) – Proper motion in right ascension, in degrees per year. Zero by default.

    - p_motion_dec (`Angle`) – Proper motion in declination, in degrees per year. Zero by default.

  Returns

    Equatorial coordinates (right ascension, declination, in that order) corresponding to the final epoch, given as two objects `Angle` inside a tuple

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

pymeeus.Coordinates.refraction_apparent2true(apparent_elevation, pressure=1010.0, temperature=10.0)

  This function computes the atmospheric refraction converting from the apparent elevation (i.e., the observed elevation through the air) to the true, ‘airless’, elevation.

  Note

  This function, by default, assumes that the atmospheric pressure is 1010 milibars, and the air temperature is 10 Celsius.

  Note

  Due to the numerous factors that may affect the atmospheric refraction, especially near the horizon, the values given by this function are approximate values.

  Parameters

    - apparent_elevation (`Angle`) – The elevation, in degrees and as an Angle object, of a given celestial object when observed through the normal atmosphere

    - pressure (float) – Atmospheric pressure at the observation point, in milibars

    - temperature (:float) – Atmospheric temperature at the observation point, in degrees Celsius

  Returns

    An Angle object with the true, ‘airless’ elevation of the celestial object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> apparent_elevation = Angle(0, 30, 0.0)
      >>> true_elevation = refraction_apparent2true(apparent_elevation)
      >>> print(true_elevation.dms_str(n_dec=1))
      1' 14.7''

pymeeus.Coordinates.refraction_true2apparent(true_elevation, pressure=1010.0, temperature=10.0)

  This function computes the atmospheric refraction converting from the true, ‘airless’, elevation (i.e., the one computed from celestial coordinates) to the apparent elevation (the observed elevation through the air)

  Note

  This function, by default, assumes that the atmospheric pressure is 1010 milibars, and the air temperature is 10 Celsius.

  Note

  Due to the numerous factors that may affect the atmospheric refraction, especially near the horizon, the values given by this function are approximate values.

  Parameters

    - true_elevation (`Angle`) – The elevation, in degrees and as an Angle object, of a given celestial object when computed from celestial coordinates, and assuming there is no atmospheric refraction due to the air

    - pressure (float) – Atmospheric pressure at the observation point, in milibars

    - temperature (:float) – Atmospheric temperature at the observation point, in degrees Celsius

  Returns

    An Angle object with the aparent, ‘with air’ elevation of the celestial object

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> true_elevation = Angle(0, 33, 14.76)
      >>> apparent_elevation = refraction_true2apparent(true_elevation)
      >>> print(apparent_elevation.dms_str(n_dec=2))
      57' 51.96''

pymeeus.Coordinates.relative_position_angle(alpha1, delta1, alpha2, delta2)

  This function computes the position angle P of a body with respect to another body.

  Parameters

    - alpha1 (`Angle`) – Right ascension of celestial body #1, as an Angle object

    - delta1 (`Angle`) – Declination of celestial body #1, as an Angle object

    - alpha2 (`Angle`) – Right ascension of celestial body #2, as an Angle object

    - delta2 (`Angle`) – Declination of celestial body #2, as an Angle object

  Returns

    An Angle object with the relative position angle between the given celestial objects

  Return type

    `Angle`

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1 = Angle(14, 15, 39.7, ra=True)
      >>> delta1 = Angle(19, 10, 57.0)
      >>> alpha2 = Angle(14, 15, 39.7, ra=True)
      >>> delta2 = Angle(-11, 9, 41.0)
      >>> pos_ang = relative_position_angle(alpha1, delta1, alpha2, delta2)
      >>> print(round(pos_ang, 1))
      0.0

pymeeus.Coordinates.straight_line(alpha1, delta1, alpha2, delta2, alpha3, delta3)

  This function computes if three celestial bodies are in a straight line, providing the angle with which the bodies differ from a great circle.

  Parameters

    - alpha1 (`Angle`) – Right ascension, as an Angle object, of celestial body #1

    - delta1 (`Angle`) – Declination, as an Angle object, of celestial body #1

    - alpha2 (`Angle`) – Right ascension, as an Angle object, of celestial body #2

    - delta2 (`Angle`) – Declination, as an Angle object, of celestial body #2

    - alpha3 (`Angle`) – Right ascension, as an Angle object, of celestial body #3

    - delta3 (`Angle`) – Declination, as an Angle object, of celestial body #3

  Returns

    A tuple with two components. The first element is an angle (as Angle object) with which the bodies differ from a great circle. The second element is the Angular distance of central point to the straight line (also as Angle object).

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> alpha1 = Angle( 5, 32,  0.40, ra=True)
      >>> delta1 = Angle(0, -17, 56.9)
      >>> alpha2 = Angle( 5, 36, 12.81, ra=True)
      >>> delta2 = Angle(-1, 12,  7.0)
      >>> alpha3 = Angle( 5, 40, 45.52, ra=True)
      >>> delta3 = Angle(-1, 56, 33.3)
      >>> psi, om = straight_line(alpha1, delta1, alpha2, delta2, alpha3, delta3)
      >>> print(psi.dms_str(n_dec=0))
      7d 31' 1.0''
      >>> print(om.dms_str(n_dec=0))
      -5' 24.0''

pymeeus.Coordinates.times_rise_transit_set(longitude, latitude, alpha1, delta1, alpha2, delta2, alpha3, delta3, h0, delta_t, theta0)

  This function computes the times (in Universal Time UT) of rising, transit and setting of a given celestial body.

  Note

  If the body is circumpolar there are no rising, transit nor setting times. In such a case a tuple with None’s is returned

  Note

  Care must be taken when interpreting the results. For instance, if the setting time is smaller than the rising time, it means that it belongs to the following day. Also, if the rising time is bigger than the setting time, it belong to the previous day. The same applies to the transit time.

  Parameters

    - longitude (`Angle`) – Geodetic longitude, as an Angle object. It is measured positively west from Greenwich, and negatively to the east.

    - latitude (`Angle`) – Geodetic latitude, as an Angle object

    - alpha1 (`Angle`) – Apparent right ascension the previous day at 0h TT, as an Angle object

    - delta1 (`Angle`) – Apparent declination the previous day at 0h TT, as an Angle object

    - alpha2 (`Angle`) – Apparent right ascension the current day at 0h TT, as an Angle object

    - delta2 (`Angle`) – Apparent declination the current day at 0h TT, as an Angle object

    - alpha3 (`Angle`) – Apparent right ascension the following day at 0h TT, as an Angle object

    - delta3 (`Angle`) – Apparent declination the following day at 0h TT, as an Angle object

    - h0 (`Angle`) – ‘Standard’ altitude: the geometric altitude of the center of the body at the time of apparent rising or setting, as degrees in an Angle object. It should be -0.5667 deg for stars and planets, -0.8333 deg for the Sun, and 0.125 deg for the Moon.

    - delta_t (float) – The difference between Terrestrial Time and Universal Time (TT - UT) in seconds of time

    - theta0 (`Angle`) – Apparent sidereal time at 0h TT on the current day for the meridian of Greenwich, as degrees in an Angle object

  Returns

    A tuple with the times of rising, transit and setting, in that order, as hours in UT.

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.

      >>> longitude = Angle(71, 5, 0.0)
      >>> latitude = Angle(42, 20, 0.0)
      >>> alpha1 = Angle(2, 42, 43.25, ra=True)
      >>> delta1 = Angle(18, 2, 51.4)
      >>> alpha2 = Angle(2, 46, 55.51, ra=True)
      >>> delta2 = Angle(18, 26, 27.3)
      >>> alpha3 = Angle(2, 51, 7.69, ra=True)
      >>> delta3 = Angle(18, 49, 38.7)
      >>> h0 = Angle(-0.5667)
      >>> delta_t = 56.0
      >>> theta0 = Angle(11, 50, 58.1, ra=True)
      >>> rising, transit, setting = times_rise_transit_set(longitude, latitude,                                                          alpha1, delta1,                                                           alpha2, delta2,                                                           alpha3, delta3, h0,                                                           delta_t, theta0)
      >>> print(round(rising, 4))
      12.4238
      >>> print(round(transit, 3))
      19.675
      >>> print(round(setting, 3))
      2.911

pymeeus.Coordinates.true_obliquity(*args, **kwargs)

  This function computes the true obliquity (epsilon) at the provided date. The true obliquity is the mean obliquity (epsilon0) plus the correction provided by the nutation in obliquity (Delta epsilon).

  This function internally uses an `Epoch` object, and the utc argument then controls the way the UTC->TT conversion is handled for that 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.

  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

    - utc (bool) – Whether the provided epoch is a civil time (UTC) or TT

    - 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

    The true obliquity of the ecliptic, as an Angle

  Return type

    `Angle`

  Raises

    ValueError if input values are in the wrong range.

  Raises

    TypeError if input values are of wrong type.

      >>> epsilon = true_obliquity(1987, 4, 10)
      >>> a = epsilon.dms_tuple()
      >>> a[0]
      23
      >>> a[1]
      26
      >>> round(a[2], 3)
      36.849

pymeeus.Coordinates.velocity(r, a)

  This function computes the instantaneous velocity of the moving body, in kilometers per second, for an unperturbed elliptic orbit.

  Parameters

    - r (float) – Distance of the body to the Sun, in Astronomical Units

    - a (float) – Semimajor axis of the orbit, in Astronomical Units

  Returns

    Velocity of the body, in kilometers per second

  Return type

    float

  Raises

    TypeError if input values are of wrong type.

      >>> r = 1.0
      >>> a = 17.9400782
      >>> v = velocity(r, a)
      >>> print(round(v, 2))
      41.53

pymeeus.Coordinates.velocity_aphelion(e, a)

  This function computes the velocity of the moving body at aphelion, in kilometers per second, for an unperturbed elliptic orbit.

  Parameters

    - e (float) – Orbital eccentricity

    - a (float) – Semimajor axis of the orbit, in Astronomical Units

  Returns

    Velocity of the body at aphelion, in kilometers per second

  Return type

    float

  Raises

    TypeError if input values are of wrong type.

      >>> a = 17.9400782
      >>> e = 0.96727426
      >>> va = velocity_aphelion(e, a)
      >>> print(round(va, 2))
      0.91

pymeeus.Coordinates.velocity_perihelion(e, a)

  This function computes the velocity of the moving body at perihelion, in kilometers per second, for an unperturbed elliptic orbit.

  Parameters

    - e (float) – Orbital eccentricity

    - a (float) – Semimajor axis of the orbit, in Astronomical Units

  Returns

    Velocity of the body at perihelion, in kilometers per second

  Return type

    float

  Raises

    TypeError if input values are of wrong type.

      >>> a = 17.9400782
      >>> e = 0.96727426
      >>> vp = velocity_perihelion(e, a)
      >>> print(round(vp, 2))
      54.52

pymeeus.Coordinates.vsop_pos(epoch, vsop_l, vsop_b, vsop_r)

  This function computes the position of a celestial body at a given epoch when its VSOP87 periodic term tables are provided.

  Parameters

    - epoch (`Epoch`) – Epoch to compute the position, given as an `Epoch` object

    - vsop_l (list) – Table of VSOP87 terms for the heliocentric longitude

    - vsop_b (list) – Table of VSOP87 terms for the heliocentric latitude

    - vsop_r (list) – Table of VSOP87 terms for the radius vector

  Returns

    A tuple with the heliocentric longitude and latitude (as `Angle` objects), and the radius vector (as a float, in astronomical units), in that order

  Return type

    tuple

  Raises

    TypeError if input values are of wrong type.