solunatus 0.4.0

High-precision astronomical calculation library and CLI for sun/moon positions, rise/set times, and lunar phases
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# Accuracy Testing & Verification

How to verify and test the accuracy of Solunatus calculations.

## Reference Sources

### U.S. Naval Observatory (USNO)

Primary reference for solar and lunar calculations:
https://aa.usno.navy.mil/data/RS_OneDay

**Provides:**
- Sunrise, sunset times
- Twilight times (civil, nautical, astronomical)
- Moonrise, moonset times
- Moon phase information

### How to Compare

1. Go to https://aa.usno.navy.mil/data/RS_OneDay
2. Enter location (city or coordinates)
3. Select date
4. Compare with Solunatus output

## Solunatus Accuracy

Typical accuracy when compared to USNO:
- **Solar events:** ±1-3 minutes
- **Lunar events:** ±3 minutes at mid-latitudes
- **Lunar phases:** ±2 minutes

### Factors Affecting Accuracy

- **Atmospheric conditions** - Refraction assumptions vary
- **Temperature and pressure** - Affects refraction calculations
- **Latitude** - Different algorithms optimized for mid-latitudes
- **Reference time** - USNO provides UTC, verify timezone conversions

## Testing Guide

### Solar Events Test

```bash
solunatus --lat 42.3601 --lon -71.0589 --tz America/New_York --date 2025-10-22 --no-prompt
```

Compare output with USNO for same location and date:
https://aa.usno.navy.mil/data/RS_OneDay?ID=MZ&state=MA&city=Boston

Record:
- Your sunrise/sunset time
- USNO sunrise/sunset time
- Difference (tolerance: ±3 minutes is acceptable)

### Lunar Events Test

Compare moonrise/moonset times same way.

### Known Issues

- **Polar regions** - Algorithms are optimized for 0-60° latitude
- **Extreme locations** - May have 24-hour day/night periods (no rise/set)

## Running Built-in Tests

```bash
# Run all tests
cargo test

# With output
cargo test -- --nocapture

# Specific test
cargo test lunar_phase
```

## Reporting Accuracy Issues

If you find a discrepancy:

1. **Document** - Record exact conditions (location, date, time)
2. **Compare** - Check against USNO reference
3. **Report** - Open GitHub issue with:
   - Your location
   - Date and time
   - Solunatus result
   - USNO result
   - Difference

## Contributing Accuracy Improvements

Want to improve accuracy?

1. Identify the issue
2. Review algorithm implementation
3. Compare with reference (Meeus, NOAA)
4. Test thoroughly before submitting PR
5. Include test cases

See [Contributing Guide](../../CONTRIBUTING.md) for details.

## References

- **Meeus, Jean.** "Astronomical Algorithms" - Lunar calculations
- **NOAA Solar Calculator** - Solar algorithm reference
- **USNO Astronomical Algorithms** - Official references