Crate solunatus 

Solunatus

A high-precision astronomical calculation library for computing sun and moon positions, rise/set times, twilight periods, and lunar phases.

Features

• NOAA Solar Calculations: Sunrise, sunset, solar noon, and twilight times (civil, nautical, astronomical)
• Meeus Lunar Algorithms: Moonrise, moonset, lunar phases, and moon position
• High Precision: Matches U.S. Naval Observatory data within ±1-2 minutes
• CPU Optimized: SIMD and architecture-specific optimizations for tier 1 Rust targets
• City Database: Built-in database of 570+ major cities worldwide
• Timezone Support: Full timezone handling via chrono-tz

Quick Start

use solunatus::prelude::*;
use chrono::Local;
use chrono_tz::America::New_York;

// Create a location (latitude, longitude in degrees)
let location = Location::new(40.7128, -74.0060).unwrap();

// Get current date/time
let now = Local::now().with_timezone(&New_York);

// Calculate sunrise and sunset
let sunrise = calculate_sunrise(&location, &now).unwrap();
let sunset = calculate_sunset(&location, &now).unwrap();

println!("Sunrise: {}", sunrise.format("%H:%M:%S"));
println!("Sunset: {}", sunset.format("%H:%M:%S"));

// Get current moon phase
let moon_pos = lunar_position(&location, &now);
println!("Moon illumination: {:.1}%", moon_pos.illumination * 100.0);

Using the City Database

use solunatus::prelude::*;

// Load the city database
let db = CityDatabase::load().unwrap();

// Find a city
if let Some(city) = db.find_exact("Tokyo") {
    let location = Location::new(city.lat, city.lon).unwrap();
    // ... perform calculations
}

// Fuzzy search
let results = db.search("new york");
for (city, score) in results.iter().take(5) {
    println!("{}, {} (score: {})", city.name, city.country, score);
}

Advanced Usage: Custom Solar Events

use solunatus::prelude::*;
use solunatus::astro::sun::{SolarEvent, solar_event_time};
use chrono::Local;
use chrono_tz::America::Los_Angeles;

let location = Location::new(34.0522, -118.2437).unwrap(); // Los Angeles
let now = Local::now().with_timezone(&Los_Angeles);

// Calculate civil twilight times
let civil_dawn = solar_event_time(&location, &now, SolarEvent::CivilDawn);
let civil_dusk = solar_event_time(&location, &now, SolarEvent::CivilDusk);

Architecture Support

Solunatus is optimized for all Rust tier 1 targets:

• x86_64: SSE2 baseline, AVX2 on capable CPUs
• aarch64: NEON on Apple Silicon and ARM64 Linux
• i686: Optimized for 32-bit x86

Build with native CPU optimizations:

RUSTFLAGS="-C target-cpu=native" cargo build --release

Re-exports

pub use astro::julian_century;

pub use astro::julian_day;

pub use astro::normalize_degrees;

pub use astro::normalize_degrees_signed;

pub use astro::Location;

pub use city::City;

pub use city::CityDatabase;

pub use config::Config;

pub use astro::sun::solar_event_time;

pub use astro::sun::solar_noon;

pub use astro::sun::solar_position;

pub use astro::sun::SolarEvent;

pub use astro::sun::SolarPosition;

pub use astro::moon::lunar_event_time;

pub use astro::moon::lunar_phases;

pub use astro::moon::lunar_position;

pub use astro::moon::phase_emoji;

pub use astro::moon::phase_name;

pub use astro::moon::LunarEvent;

pub use astro::moon::LunarPhase;

pub use astro::moon::LunarPhaseType;

pub use astro::moon::LunarPosition;

Modules

ai

astro

Astronomical calculations module.

benchmark

calendar

Calendar generation module.

city

City database and search functionality.

config

Configuration management.

events

Event collection and organization.

location_source

output

JSON output formatting.

prelude

Prelude module containing the most commonly used types and functions.

time_sync

usno_validation

Structs

BatchResult

Result from batch calculations.

LibraryInfo

Library information structure.

Functions

batch_calculate

Calculate sun and moon data for multiple dates efficiently.

calculate_civil_dawn

Calculate civil dawn (sun 6° below horizon) for a given location and date.

calculate_civil_dusk

Calculate civil dusk (sun 6° below horizon) for a given location and date.

calculate_moonrise

Calculate moonrise time for a given location and date.

calculate_moonset

Calculate moonset time for a given location and date.

calculate_solar_noon

Calculate solar noon (when the sun reaches its highest point) for a given location and date.

calculate_sunrise

Calculate sunrise time for a given location and date.

calculate_sunset

Calculate sunset time for a given location and date.

get_current_moon_phase

Get the current phase of the moon (name and emoji).

get_lunar_phases_for_month

Get all lunar phases (New, First Quarter, Full, Last Quarter) for a given month.

library_info

Returns library information including version and supported features.

version

Returns the version of the solunatus library.