Crate solunatus

Crate solunatus 

Source
Expand description

§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
AI-powered astronomical insights via Ollama integration.
astro
Astronomical calculations module.
benchmark
Performance benchmarking across the city database.
calendar
Calendar generation module.
city
City database and search functionality.
config
Configuration management.
events
Event collection and organization.
location_source
Location provenance tracking.
output
JSON output formatting.
prelude
Prelude module containing the most commonly used types and functions.
time_sync
NTP time synchronization with intelligent caching.
usno_validation
USNO validation module for accuracy verification.

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.