PyMeeus

0.5.12 · active · verified Thu Apr 09

PyMeeus is a Python library that implements astronomical algorithms described in the classical book 'Astronomical Algorithms, 2nd Edition' by Jean Meeus. It provides routines for celestial mechanics, ephemerides, and time conversions. The library is known for its simplicity, ease of use, minimal dependencies, and abundant documentation. The current version is 0.5.12, with an irregular release cadence focused on bug fixes and new functionality.

Warnings

gotcha Incorrect Import Pattern: Importing `pymeeus` directly and expecting sub-modules or classes to be available in its top-level namespace (e.g., `pymeeus.Epoch`) will result in an `AttributeError`. Each specific class or module must be imported directly from its path within `pymeeus` (e.g., `from pymeeus.Epoch import Epoch`).
Fix: Always use explicit imports like `from pymeeus.ModuleName import ClassName` or `import pymeeus.ModuleName`.
gotcha Outdated Leap Seconds Table in `Epoch` Class: The `Epoch` class uses an internal table for leap seconds. As leap seconds are added irregularly, this table can become outdated. Using an outdated table when converting between UTC and TT can lead to inaccuracies.
Fix: Regularly update the `pymeeus` package to get the latest leap seconds table. For critical applications, consider providing the `leap_seconds` argument manually to the `Epoch` constructor or `set` method if an updated package is not available.
gotcha Time Resolution Limitations: The `Epoch` class stores time as Julian Ephemeris Day (JDE). For computers with 15-digit accuracy, the final time resolution is approximately 10 milliseconds. This level of precision might be insufficient for extremely high-precision astronomical calculations.
Fix: Evaluate if a 10-millisecond resolution meets your application's precision requirements. For higher precision, consider libraries designed for such demands, possibly involving arbitrary-precision arithmetic, though PyMeeus focuses on simplicity.
gotcha Alternative Library `PyPlanets`: While PyMeeus is active, a refactored version called `pyplanets` exists, which aims for a more object-oriented design and improved maintainability. Users starting new projects might consider `pyplanets` if these design principles are preferred, although `pymeeus` remains functional and well-documented.
Fix: Review `pyplanets` (available on PyPI) to see if its design aligns better with new project requirements. Existing `pymeeus` projects are not directly affected.

Install

pip install pymeeus Install PyMeeus

Imports

Epoch
```
from pymeeus.Epoch import Epoch
```
PyMeeus is a library composed of multiple modules (e.g., Angle, Epoch, Coordinates), not a single module. Directly importing `pymeeus` does not expose its sub-modules' classes/functions in the top-level namespace, leading to an AttributeError.
Angle
```
from pymeeus.Angle import Angle
```
Similar to Epoch, Angle and other sub-modules must be imported directly or from the `pymeeus.ModuleName` namespace to access their components.

Quickstart

This quickstart demonstrates how to correctly import classes like `Epoch` and `Sun` and use them to calculate fundamental astronomical values such as the Julian Ephemeris Day (JDE) and the Sun's geocentric apparent longitude for a given date.

from pymeeus.Epoch import Epoch
from pymeeus.Sun import Sun

# Create an Epoch object for a specific date and time
my_epoch = Epoch(1992, 10, 13, 0, 0, 0)

# Get the Julian Ephemeris Day (JDE)
jde = my_epoch.get_jde()
print(f"Julian Ephemeris Day for 1992-10-13: {jde}")

# Calculate the Sun's geocentric apparent longitude for this epoch
sun = Sun(my_epoch)
longitude = sun.geocentric_apparent_longitude().degrees
print(f"Sun's Geocentric Apparent Longitude: {longitude:.4f} degrees")

view raw JSON →