Tagger/PROJECT.md

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

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