90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
|
# PROJECT.md
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
**PlanetaryTime** is a Python library for representing and working with time on other bodies in the Solar System, similar in spirit to the standard `datetime` module.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Core Concept
|
||
|
|
|
||
|
|
Time on a given planetary body is expressed using a human-readable clock where **the hour is preserved as close to one Earth hour as possible**.
|
||
|
|
|
||
|
|
The number of hours in a planetary day is derived from the length of that body's sidereal rotation period expressed in Earth hours, rounded to the nearest integer:
|
||
|
|
|
||
|
|
```
|
||
|
|
hours_per_day = round(rotation_period_in_earth_hours)
|
||
|
|
```
|
||
|
|
|
||
|
|
Example: if a body rotates once every 24.6 Earth hours, its day has 25 hours, each approximately 1 Earth hour long.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Epoch
|
||
|
|
|
||
|
|
The starting point for counting days (sol 0 / day 0) is configurable per body and per use case:
|
||
|
|
|
||
|
|
- **Discovery epoch** — the date the body was officially discovered
|
||
|
|
- **Contact epoch** — the date of first contact with the body:
|
||
|
|
- landing of an automated probe, or
|
||
|
|
- landing of a crewed mission
|
||
|
|
|
||
|
|
The epoch is set when constructing a planetary time object and determines what "day 1" means.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Planned Public API
|
||
|
|
|
||
|
|
```python
|
||
|
|
from planetarytime import PlanetaryTime, Body, Epoch
|
||
|
|
|
||
|
|
# construct from Earth datetime + target body + epoch choice
|
||
|
|
pt = PlanetaryTime.from_earth(datetime.utcnow(), body=Body.MARS, epoch=Epoch.DISCOVERY)
|
||
|
|
|
||
|
|
pt.day # integer day number since epoch
|
||
|
|
pt.hour # hour within the current day (0-indexed)
|
||
|
|
pt.minute # minute within the current hour
|
||
|
|
pt.second # second within the current minute
|
||
|
|
pt.body # the planetary body
|
||
|
|
pt.epoch # the epoch in use
|
||
|
|
|
||
|
|
str(pt) # human-readable: e.g. "Sol 142, 09:35:22 (Mars / Discovery epoch)"
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Supported Bodies
|
||
|
|
|
||
|
|
Initial target: planets and major bodies of the Solar System with known rotation periods.
|
||
|
|
|
||
|
|
| Body | Rotation period (Earth h) | Hours per day |
|
||
|
|
|---------|--------------------------|---------------|
|
||
|
|
| Mercury | 1407.6 | 1408 |
|
||
|
|
| Venus | 5832.5 (retrograde) | 5833 |
|
||
|
|
| Mars | 24.6 | 25 |
|
||
|
|
| Jupiter | 9.9 | 10 |
|
||
|
|
| Saturn | 10.7 | 11 |
|
||
|
|
| Uranus | 17.2 | 17 |
|
||
|
|
| Neptune | 16.1 | 16 |
|
||
|
|
|
||
|
|
Moon and dwarf planets (Pluto, Ceres, Eris) may be added later.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Current State
|
||
|
|
|
||
|
|
- Project scaffolded (Poetry, src layout, tests directory)
|
||
|
|
- No implementation yet
|
||
|
|
|
||
|
|
## TODO
|
||
|
|
|
||
|
|
- Define `Body` enum with rotation periods
|
||
|
|
- Define `Epoch` enum and epoch registry
|
||
|
|
- Implement core `PlanetaryTime` class
|
||
|
|
- Implement conversion from Earth `datetime`
|
||
|
|
- Implement `__str__` / `__repr__`
|
||
|
|
- Write tests for conversion accuracy
|
||
|
|
- Write tests for epoch switching
|
||
|
|
- Populate README with usage examples
|
||
|
|
- Implement `scripts/refresh_data.py` — fetches rotation periods, orbital periods and discovery dates from Wikidata SPARQL endpoint and regenerates hardcoded data in `body.py`, `moon.py` and `epoch.py`; script is not part of the distributed package
|