# starward — Astronomy Calculation Toolkit

> *"Per aspera ad astra"* — Through hardships to the stars

A professional astronomy calculation toolkit with a soul. Built for astronomers, astrophysicists, and curious stargazers who appreciate precision, transparency, and the occasional cosmic pun.

---

## 🌟 Philosophy

- **Precision First**: Every calculation traceable, every assumption explicit
- **Show Your Work**: Verbose mode that would make your physics professor proud  
- **Modular by Design**: Each module stands alone, plays well with others
- **Test Everything**: If it's not tested, it doesn't exist
- **Expand Gracefully**: Architecture that welcomes new features like old friends

---

## 📋 v0.1 — "First Light" ✅

The foundational release. Core infrastructure and essential calculations.

### Core Modules

| Module | Description | Status |
|--------|-------------|--------|
| `time` | Julian dates, MJD, LST, epoch conversions | ✅ |
| `coords` | Coordinate transformations (ICRS, AltAz, Galactic, Ecliptic) | ✅ |
| `angles` | Angular separations, position angles, formatting | ✅ |
| `constants` | Astronomical constants with references | ✅ |

### Infrastructure

- [x] CLI framework with subcommands
- [x] Verbose output system ("show your work")
- [x] Unit test suite with >90% coverage target
- [x] Input validation and error handling
- [x] JSON output option

### CLI Commands (v0.1)

```bash
starward time now                    # Current time in all formats
starward time convert <value>        # Convert between time systems
starward coord convert <coords>      # Transform coordinates
starward angle sep <c1> <c2>         # Angular separation
starward --verbose <command>         # Show calculation steps
starward --output json <command>     # JSON output
```

---

## 🚀 v0.2 — "Steady Tracking" ✅

Position calculations and solar system awareness.

### New Modules

| Module | Description | Status |
|--------|-------------|--------|
| `sun` | Solar position, sunrise/sunset, twilight | ✅ |
| `moon` | Lunar position, phases, illumination | ✅ |
| `observer` | Observer location management, horizon | ✅ |
| `visibility` | Object visibility, optimal viewing times | ✅ |

### Enhancements

- [x] Observer profile saving (~/.starward/observers.toml)
- [x] LaTeX output option
- [x] Rise/set/transit calculations
- [x] Airmass calculations
- [x] Twilight calculations (civil, nautical, astronomical)
- [x] Moon phase prediction

### CLI Commands (v0.2)

```bash
# Sun commands
starward sun position                 # Current solar position
starward sun rise --lat 51.5 --lon -0.1
starward sun set --lat 51.5 --lon -0.1
starward sun twilight astronomical --lat 51.5 --lon -0.1

# Moon commands
starward moon position                # Current lunar position
starward moon phase                   # Current phase
starward moon next full               # Next full moon

# Observer commands
starward observer add "Home" 40.7 -74.0
starward observer list
starward observer default "Home"

# Visibility commands
starward vis altitude "00h42m44s" "+41d16m09s" --lat 40.7 --lon -74.0
starward vis transit "00h42m44s" "+41d16m09s" --lat 40.7 --lon -74.0
starward vis airmass "00h42m44s" "+41d16m09s" --lat 40.7 --lon -74.0
```

---

## 🪐 v0.3 — "Planetary Motion" ✅

Solar system ephemerides and planetary positions.

### New Modules

| Module | Description | Status |
|--------|-------------|--------|
| `planets` | Planetary positions (Meeus algorithms) | ✅ |

### Features

- [x] Mercury through Neptune position calculations
- [x] Equatorial coordinates (RA/Dec)
- [x] Distance from Earth and Sun
- [x] Apparent magnitude calculations
- [x] Elongation from Sun
- [x] Phase/illumination percentage
- [x] Rise/set/transit times for planets

### CLI Commands (v0.3)

```bash
# Planet positions
starward planets position mars          # Single planet position
starward planets all                    # All planets summary

# Planet visibility
starward planets rise jupiter --lat 40.7 --lon -74.0
starward planets set saturn --lat 40.7 --lon -74.0
starward planets transit jupiter --lat 40.7 --lon -74.0
starward planets altitude mars --lat 40.7 --lon -74.0
```

---

## 🔭 v0.4 — "Deep Sky"

Catalogs and object databases.

### New Modules

| Module | Description |
|--------|-------------|
| `catalogs` | NGC, IC, Messier, HD lookups |
| `stars` | Stellar parameters, spectral types |
| `dso` | Deep sky object information |
| `finder` | Object finder by criteria |

### Enhancements

- Local catalog caching
- Custom object lists
- Observation planning

---

## 🌌 v0.5 — "Cosmological"

Extragalactic and cosmological calculations.

### New Modules

| Module | Description |
|--------|-------------|
| `cosmo` | Cosmological distances, redshift |
| `magnitudes` | Absolute/apparent, extinction |
| `luminosity` | Flux, luminosity calculations |

### Enhancements

- Multiple cosmology models
- K-corrections
- Distance ladder calculations

---

## 🛸 v0.6 — "Observatory Ready"

Professional observatory support.

### New Modules

| Module | Description |
|--------|-------------|
| `optics` | Telescope/camera calculations |
| `imaging` | FOV, pixel scale, SNR |
| `scheduler` | Observation scheduling |
| `weather` | Seeing, transparency integration |

### Enhancements

- FITS header parsing
- Exposure time calculator
- Mosaic planning

---

## 🎨 Future Horizons (v1.0+)

- **Python API**: Import starward as a library
- **Web interface**: Browser-based calculator
- **Plugin system**: Community extensions
- **GPU acceleration**: For heavy ephemeris work
- **Real-time feeds**: Live satellite tracking, alerts
- **Interactive mode**: REPL with history

---

## 🏗️ Architecture Principles

```
starward/
├── src/starward/
│   ├── cli/           # Click-based CLI commands
│   ├── core/          # Core calculation modules
│   ├── output/        # Formatters (plain, json, latex)
│   ├── verbose/       # "Show your work" engine
│   └── utils/         # Shared utilities
├── tests/             # Pytest test suite
│   ├── unit/          # Unit tests per module
│   ├── integration/   # CLI integration tests
│   └── fixtures/      # Test data
└── docs/              # Documentation
```

### Key Design Decisions

1. **Pure Python Core**: No compiled dependencies for portability
2. **Lazy Imports**: Fast CLI startup, load modules on demand
3. **Immutable Data**: Calculation results are immutable dataclasses
4. **Verbose Registry**: Calculations register their steps automatically
5. **Output Agnostic**: Core returns data, formatters handle display

---

## 📊 Testing Strategy

- **Unit Tests**: Every function, every edge case
- **Property Tests**: Hypothesis for numerical stability
- **Golden Tests**: Known values from authoritative sources (USNO, JPL)
- **Roundtrip Tests**: Transform → inverse transform = identity
- **CLI Tests**: Every command, every flag

### Test Suite Structure (v0.3)

```
tests/
├── conftest.py         # Shared fixtures and markers
├── core/               # Core module tests
│   ├── test_angles.py
│   ├── test_coords.py
│   ├── test_time.py
│   ├── test_constants.py
│   ├── test_sun.py
│   ├── test_moon.py
│   ├── test_observer.py
│   ├── test_visibility.py
│   └── test_planets.py
├── cli/                # CLI integration tests
│   └── test_commands.py
└── output/             # Formatter tests
    └── test_formatters.py
```

**Current Status**: 500+ tests, validated against USNO, JPL Horizons, IAU SOFA, and Meeus

---

## 🌠 The Name

**starward** — Where astronomy meets code. The zero represents:
- The origin point of our coordinate systems
- The null hypothesis we test against
- The first index (we're programmers, after all)
- ∅ The empty set of bugs we aspire to

---

## 📈 Version History

| Version | Codename | Status | Highlights |
|---------|----------|--------|------------|
| v0.1 | First Light | ✅ Complete | Time, coords, angles, constants |
| v0.2 | Steady Tracking | ✅ Complete | Sun, moon, observer, visibility |
| v0.3 | Planetary Motion | ✅ Complete | Planets (Mercury–Neptune) |
| v0.4 | Deep Sky | 📋 Planned | Catalogs, DSOs, star data |
| v0.5 | Cosmological | 📋 Planned | Redshift, distances, cosmology |
| v0.6 | Observatory Ready | 📋 Planned | Optics, imaging, scheduling |

---

*Built with 🔭 and ☕ for those who look up*
