https://github.com/funkite/solunatus
Solar and lunar dashboard and library in Rust
https://github.com/funkite/solunatus
astronomy educational ephemeris moon moonrise ollama rust science sun sunrise sunset
Last synced: about 2 months ago
JSON representation
Solar and lunar dashboard and library in Rust
- Host: GitHub
- URL: https://github.com/funkite/solunatus
- Owner: FunKite
- License: mit
- Created: 2025-10-08T01:08:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T23:16:47.000Z (about 2 months ago)
- Last Synced: 2026-04-17T00:37:52.856Z (about 2 months ago)
- Topics: astronomy, educational, ephemeris, moon, moonrise, ollama, rust, science, sun, sunrise, sunset
- Language: Rust
- Homepage:
- Size: 12.8 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Solunatus
[](https://crates.io/crates/solunatus)
[](https://crates.io/crates/solunatus)
[](https://docs.rs/solunatus)
[](LICENSE)
High-precision astronomical calculations for sun and moon events, available as both:
- A Rust library (`solunatus`)
- A CLI app (`solunatus`)
Solunatus runs offline for core calculations and supports historical/future dates (from astronomical year `-0999` through `3000`).
## What You Get
- Sunrise, sunset, and solar noon
- Civil, nautical, and astronomical twilight
- Moonrise, moonset, and transit
- Moon phase, illumination, altitude/azimuth, distance
- Built-in city database (570+ cities)
- Interactive terminal UI (watch mode)
- JSON output and calendar export (HTML/JSON)
- Optional USNO validation reports
- Optional AI insights via local Ollama
## Install
Solunatus targets the latest stable Rust release for active development. The current release line supports stable Rust versions compatible with `rust-version = "1.91"`, and that floor may rise in a minor release when security, dependency compatibility, or maintainability require it. If you need an older Rust toolchain, use an older Solunatus release that still supports it.
To upgrade an existing installation from crates.io:
```bash
cargo install solunatus --force
```
### From crates.io
```bash
cargo install solunatus
```
### From source
```bash
git clone https://github.com/FunKite/solunatus.git
cd solunatus
cargo install --path .
```
## Quick Start
```bash
# Use a city from the built-in database
solunatus --city "New York"
# Or specify coordinates + timezone
solunatus --lat 40.7128 --lon -74.0060 --tz America/New_York
```
By default, Solunatus starts in interactive watch mode.
Press `q` to quit, `s` for settings, and `r` for reports.
## Common CLI Usage
### Single snapshot (non-interactive)
```bash
solunatus --city "Tokyo" --no-prompt
```
### JSON output
```bash
solunatus --city "Tokyo" --json
```
### Specific date
```bash
solunatus --city "Lisbon" --date 2026-01-15
```
### Calendar export
```bash
solunatus --city "Lisbon" \
--calendar \
--calendar-start 2026-01-01 \
--calendar-end 2026-01-31 \
--calendar-format html \
--calendar-output lisbon-jan-2026.html
```
### USNO validation report (feature-enabled builds)
```bash
solunatus --city "San Diego" --validate
```
### AI insights with Ollama (feature-enabled builds)
```bash
solunatus --city "Seattle" --ai-insights
```
## Command Highlights
Core flags:
- `--city `
- `--lat --lon --tz `
- `--date `
- `--json`
- `--calendar --calendar-start --calendar-end `
- `--calendar-format `
- `--calendar-output `
- `--watch`
- `--no-prompt`
- `--no-save`
- `--strict`
Optional flags (feature gated):
- `--validate` (`usno-validation`)
- `--ai-insights`, `--ai-server`, `--ai-model`, `--ai-refresh-minutes` (`ai-insights`)
For full CLI docs, see [`docs/features/cli-reference.md`](docs/features/cli-reference.md).
## Optional Features
Default features:
- `cpu-portable`
- `usno-validation`
- `ai-insights`
Non-default feature:
- `parallel` (Rayon-based parallel processing)
Examples:
```bash
# Minimal build (no USNO validation, no AI insights)
cargo install solunatus --no-default-features
# USNO validation only
cargo install solunatus --no-default-features --features usno-validation
# AI insights only
cargo install solunatus --no-default-features --features ai-insights
# Add parallel processing
cargo install solunatus --features parallel
```
## Library Usage
Add dependency:
```toml
[dependencies]
solunatus = "0.4.0"
chrono = "0.4"
chrono-tz = "0.10"
```
Basic example:
```rust
use chrono::Local;
use chrono_tz::America::New_York;
use solunatus::prelude::*;
fn main() {
let location = Location::new(40.7128, -74.0060).unwrap();
let now = Local::now().with_timezone(&New_York);
if let Some(sunrise) = calculate_sunrise(&location, &now) {
println!("Sunrise: {}", sunrise.format("%H:%M:%S"));
}
if let Some(sunset) = calculate_sunset(&location, &now) {
println!("Sunset: {}", sunset.format("%H:%M:%S"));
}
let (phase_name, phase_emoji) = get_current_moon_phase(&location, &now);
println!("Moon phase: {} {}", phase_emoji, phase_name);
}
```
More examples: [`examples/`](examples/)
## Accuracy and Scope
Solunatus uses NOAA-based solar methods and Meeus-based lunar methods, with validation tooling aligned to USNO-style conventions.
This project is intended for educational, planning, and general-purpose astronomical use.
It is not certified for safety-critical navigation or legal timing decisions.
## Configuration
CLI settings are saved to:
```text
~/.solunatus.json
```
Use `--no-save` to avoid writing configuration.
## Releases
Crates.io is the supported distribution channel for published releases:
```bash
cargo install solunatus
```
GitHub Releases are used for tags and release notes for each published version. They should not be treated as a guaranteed source of fresh binary artifacts unless a specific release explicitly says otherwise.
## Development
```bash
# Build
cargo build
# Test
cargo test
# Safer local test runner
./scripts/safe_local_test.sh
```
Project docs index: [`docs/README.md`](docs/README.md)
## Contributing
Issue reports and feature requests are welcome:
- [GitHub Issues](https://github.com/FunKite/solunatus/issues)
- [Contributing Guide](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security Policy](SECURITY.md)
## License
MIT ([`LICENSE`](LICENSE))