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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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.