PyEphem Documentation

PyEphem is a high-precision astronomy library that provides the following capabilities:

• Celestial Body Tracking: High-precision orbital routines for the Moon, Sun, planets, and major moons. Supports custom orbital elements for comets, asteroids, or satellites.
• Star Positions: Built-in positions for 94 bright stars.
• Observer Location: Support for custom longitude, latitude, and altitude, or using a built-in database of 122 world cities. Includes atmospheric refraction compensation based on temperature and pressure.
• Event Computation: Calculate when a body will rise, transit overhead, or set. Also computes equinoxes, solstices, and Moon phases.
• Data Parsing: Parses XEphem file formats and standard TLE (Two-Line Element) formats for satellites.
• Coordinate Conversions: Converts positions between equatorial, ecliptic, and galactic coordinate systems.
• Time Conversions: Converts Ephemeris Time to local time and returns Julian Dates for any calendar date.

PyEphem angles behave differently depending on how they are accessed:

• As strings: When printed or passed to str(), they appear in human-readable astronomical formats (e.g., 22:04:47.4).
• As floats: In mathematical operations, they act as standard Python floating-point numbers representing radians.

Key Conversion Functions:

• ephem.degrees(angle): Converts a radian float back into a printable degree string.
• ephem.hours(angle): Converts a radian float back into a printable hours string (used for right ascension).
• .norm: An attribute on an angle object that forces the value into the range of 0 to 2π.

Setting Angles:

• If you pass a string, it is interpreted as degrees (or hours for right ascension).
• If you pass a float, it is interpreted as radians.

import ephem

u = ephem.Uranus('1871/3/13')

# Access as string
print(str(u.dec)) # '22:04:47.4'

# Access as float (radians)
print(float(u.dec)) # 0.385365877213

# Convert math results back to printable degrees
angle_result = 0.385365877213 + 1
print(ephem.degrees(angle_result)) # '1:16:10.5'

Many Body and Observer attributes return values as Angle objects.

Key Characteristics:

• Storage: Angles always store floating-point radians internally.
• Behavior: They act like Python float objects for mathematical operations.
• Display: They only display as degrees or hours when printed or formatted as strings.
• Units: Most angles are in degrees, but Right Ascension is measured in hours.

Creation and Conversion: Use ephem.degrees() for degree-based angles and ephem.hours() for hour-based angles (Right Ascension). You can provide radians, strings (e.g., '180:00:00', '5:37:30'), or floats to these functions.

Normalization: When performing math that might push an angle out of standard bounds, use:

• .norm: Returns the angle normalized to $[0, 2\pi)$.
• .znorm: Returns the angle normalized to $[-\pi, \pi)$.

>>> a = ephem.degrees(3.141593)  # float: radians
>>> print(a)
180:00:00.1
>>> a = ephem.degrees('180:00:00')  # str: degrees
>>> print(a)
180:00:00.0
>>> a
3.141592653589793
>>> h = ephem.hours('1:00:00')
>>> deg = ephem.degrees(h)
>>> print("1h right ascension = %s degrees" % deg)
1h right ascension = 15:00:00.0 degrees

Every PyEphem "body" (planets, comets, asteroids, stars, etc.) returns three distinct sets of Right Ascension (RA) and Declination (Dec) coordinates. The specific set you should use depends on whether you are comparing positions to a star atlas or looking at the sky from a specific location on Earth.

For General Celestial Bodies

• a_ra, a_dec: Astrometric Geocentric Position. Use these for matching positions to a star atlas for a specific epoch.
• g_ra, g_dec: Apparent Geocentric Position. The position for the epoch-of-date, adjusted for light-travel time and relativistic effects, but viewed from the center of the Earth.
• ra, dec: Apparent Topocentric Position. The position as it appears from a specific location on Earth's surface. Note: This is only computed if you provide an Observer to the compute() method. If no Observer is provided, ra/dec will equal g_ra/g_dec.

For Earth Satellites

When computing the position of an Earth satellite using an Observer:

• a_ra, a_dec: Astrometric Topocentric Position for the epoch of your Observer.
• g_ra, g_dec: Apparent Geocentric Position (same as above).
• ra, dec: Apparent Topocentric Position (same as above).