Metadata-Version: 2.1
Name: solarsystem
Version: 0.1.7
Summary: Our Solar System. Planet's positions, Sun's and Moon' s position and rise/set
Home-page: https://github.com/IoannisNasios/solarsystem
Download-URL: https://github.com/IoannisNasios/solarsystem/archive/0.1.7.tar.gz
Author: Ioannis Nasios
Author-email: nasioannis5@gmail.com
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE


# 🌌 solarsystem

[![PyPI version](https://badge.fury.io/py/solarsystem.svg)](https://badge.fury.io/py/solarsystem)
[![Documentation Status](https://readthedocs.org/projects/solarsystem/badge/?version=latest)](https://solarsystem.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/IoannisNasios/solarsystem/graph/badge.svg?token=w2cNJJSQ65)](https://codecov.io/gh/IoannisNasios/solarsystem)
[![GPL](https://img.shields.io/badge/license-MIT-green.svg?style=flat)](https://github.com/IoannisNasios/solarsystem/blob/master/LICENSE)
[![Downloads](https://pepy.tech/badge/solarsystem/month)](https://pepy.tech/project/solarsystem)




**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

### Astronomical Events  
- Sunrise and sunset times (any Earth location)
- Moonrise and moonset calculations
- Lunar phase and illumination percentage

### Coordinate Transformations  
- Spherical ↔ Cartesian  
- Ecliptic ↔ Equatorial  
- Ecliptic ↔ Spherical projections  

---

## ⚡ Installation  

Install directly from PyPI:

```bash
pip install solarsystem
```

Or install from GitHub:
```bash
pip install git+https://github.com/IoannisNasios/solarsystem
```
or
```bash
git clone https://github.com/IoannisNasios/solarsystem
cd solarsystem
pip install .
```


---

## Quick start  

```python
import solarsystem
```

Initialize Heliocentric class


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

Compute position of planets around sun


```python
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))
```


```python
# 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:

- **Solar System Live**  
  Real-time planetary visualization and animation  
  https://github.com/IoannisNasios/solarsystem/blob/master/examples/Solar_System_Live.ipynb  

- **RiseSet Calendar**  
https://github.com/IoannisNasios/solarsystem/blob/master/examples/RiseSet_Calendar.ipynb  
  Yearly calendar of:
  - sunrise / sunset  
  - moonrise / moonset  
  - lunar illumination  

---

## 🌀 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.8%*  
- Moonrise / Moonset timing difference: *~12 minutes*  

Full results and figures are included in the accompanying research paper.  

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

```bash
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 → 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  

If you use this library in your work, please cite:  


```
@misc{Nasios:2020,
  Author = {Ioannis Nasios},
  Title = {solarsystem},
  Year = {2020},
  Publisher = {GitHub},
  Journal = {GitHub repository},
  Howpublished = {\url{https://github.com/IoannisNasios/solarsystem}}
}
```



---

## License  

MIT License ©

