Skip to content

README.md

Latest commit

 

History

History
232 lines (150 loc) · 5.84 KB

README.md

File metadata and controls

232 lines (150 loc) · 5.84 KB
Raw

🌌 solarsystem

PyPI version Documentation Status codecov GPL Downloads

solarsystem is a lightweight, dependency-free Python library for computing Solar System positions, Solar-Lunar events, and coordinate transformations.

It is designed for education, visualization, and lightweight astronomical computation, without requiring external ephemeris datasets or heavy scientific dependencies.

Supported Celestial Bodies

  • The Sun (our central star)
  • All 8 major planets: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune
  • Dwarf planets: Pluto, Ceres, Eris (with additional bodies planned to be included in future releases)
  • Minor bodies: Chiron (Centaur class)
  • Natural satellites: Earth's Moon (Luna / Selene)

Features

The library provides tools for:

Planetary Positioning

  • Approximate heliocentric positions of planets
  • Geocentric positions for Earth-based observations
  • Support for dwarf planets and selected minor bodies

Solar/Lunar Events (for any location on Earth)

  • Sunrise and sunset times
  • Moonrise and moonset calculations
  • Lunar illumination percentage

Coordinate Transformations

  • Spherical ↔ Cartesian
  • Ecliptic ↔ Equatorial
  • Ecliptic ↔ Spherical projections

⚡ Installation

Install directly from PyPI:

pip install solarsystem

Or install from GitHub:

pip install git+https://github.com/IoannisNasios/solarsystem

Quick start

import solarsystem

Initialize Heliocentric class

H = solarsystem.Heliocentric(year=2020, month=1, day=1, hour=12, minute=0, precession=True)

Compute position of planets around sun

planets_dict=H.planets()
print('Planet','   \t','Longitude','   \t','Latitude','   \t','Distance in AU')
for planet in planets_dict:
    pos=planets_dict[planet]
    print(planet,'   \t',round(pos[0],2),'   \t',round(pos[1],2),'   \t',round(pos[2],2))
# Planet      Longitude   Latitude    Distance in AU
# Mercury     263.55       -4.06       0.47
# Venus         4.95       -3.22       0.73
# Earth       100.25        0.0        0.98
# Mars        214.1         0.49       1.59
# Jupiter     275.83        0.1        5.23
# Saturn      292.23        0.05      10.05
# Uranus       35.07       -0.48      19.81
# Neptune     347.74       -1.04      29.91
# Pluto       292.47       -0.67      33.88
# Ceres       290.44       -5.4        2.92
# Chiron        3.86        2.94      18.81
# Eris         23.08      -11.74      96.0

Example Applications

The repository includes Jupyter notebooks:

🌀 Precession Support (v0.1.6+)

Starting from version 0.1.6, the library includes an optional precession of the equinoxes correction.

  • Default: precession=True
  • Can be disabled: precession=False

Why this matters:

  • Improves long-term coordinate consistency
  • Reduces systematic longitude drift across epochs
  • Allows both:
    • modern ephemeris-style calculations
    • fixed-frame educational mode

📊 Accuracy and Validation

To evaluate numerical performance, the library was compared against JPL DE440 ephemerides.

Summary of results:

  • Mean longitude error: << 1° (mean absolute error ~0.007°)
  • Mean latitude error: ~0.002°
  • Mean distance error: ~0.05 AU
  • Lunar illumination error: ~0.2%
  • Moonrise / Moonset timing difference: ~2-3 minutes

Full results and figures are included in the accompanying research paper.
Validation Notebooks used can be found in https://github.com/IoannisNasios/solarsystem/blob/master/performance/

These results indicate that solarsystem achieves adequate calculations for various use cases, while maintaining a lightweight computational design.

📚 Documentation

Full documentation is available at:
https://solarsystem.readthedocs.io

Build documentation locally

pip install sphinx
cd docs
make html

Open _build/html/index.html in browser.

Requirements

Core package:
No external dependencies

Optional:
matplotlib → for visualization notebooks
pytest, numpy → for running tests
matplotlib, skyfield, numpy → for performance evaluation notebooks

Python Support

Tested on:

Python 3.4+
Python 2.7 (legacy support)

Newer Python versions are recommended for best performance and compatibility.

📖 Citing

Preprint can be found on Arxiv
If you use this library in your work, please cite:

@misc{nasios2026solarsystemvalidatedlightweightpython,
      title={Solarsystem: A Validated Lightweight Python Package for Planetary Positions and Solar-Lunar Event Calculations}, 
      author={Ioannis Nasios},
      year={2026},
      eprint={2606.27055},
      archivePrefix={arXiv},
      primaryClass={astro-ph.EP},
      url={https://arxiv.org/abs/2606.27055}, 
}

License

MIT License ©