Expand description
§Solar Positioning Library
High-accuracy solar positioning algorithms for calculating sun position and sunrise/sunset times.
This library provides implementations of two complementary solar positioning algorithms:
- SPA (Solar Position Algorithm): NREL’s high-accuracy algorithm (±0.0003° uncertainty, years -2000 to 6000)
- Grena3: Simplified algorithm (±0.01° accuracy, years 2010-2110, ~10x faster)
§Features
- Thread-safe, immutable data structures
- Performance optimizations for bulk calculations (6-7× speedup)
- Comprehensive test suite with reference data validation
- Optional serialization support with Serde
§Quick Start
use solar_positioning::{spa, time::JulianDate, types::SolarPosition, RefractionCorrection};
use chrono::{DateTime, FixedOffset, Utc, TimeZone};
// Example with time calculations
let jd = JulianDate::from_utc(2023, 6, 21, 12, 0, 0.0, 69.0).unwrap();
println!("Julian Date: {:.6}", jd.julian_date());
println!("Julian Century: {:.6}", jd.julian_century());
// Example with flexible timezone support - any TimeZone trait implementor
let datetime_fixed = "2023-06-21T12:00:00-07:00".parse::<DateTime<FixedOffset>>().unwrap();
let datetime_utc = Utc.with_ymd_and_hms(2023, 6, 21, 19, 0, 0).unwrap(); // Same moment
// Both calls produce identical results
let position = spa::solar_position(datetime_fixed, 37.7749, -122.4194, 0.0, 69.0,
Some(RefractionCorrection::standard())).unwrap();
println!("Azimuth: {:.3}°", position.azimuth());
println!("Elevation: {:.3}°", position.elevation_angle());§Algorithms
§SPA (Solar Position Algorithm)
Based on the NREL algorithm by Reda & Andreas (2003). Provides the highest accuracy with uncertainties of ±0.0003 degrees, suitable for applications requiring precise solar positioning over long time periods.
§Grena3
A simplified algorithm optimized for years 2010-2110. Approximately 10 times faster than SPA while maintaining good accuracy (maximum error 0.01 degrees).
§Performance Optimizations
For bulk calculations, significant speedups are available:
- Coordinate sweeps (many locations, fixed time): ~7× speedup using
spa_time_dependent_parts() - Combined patterns (spatial-temporal grids): ~6× speedup using time-based caching
These optimizations require the unstable feature flag and are documented in the spa module.
§Coordinate System
- Azimuth: 0° = North, measured clockwise (0° to 360°)
- Zenith angle: 0° = directly overhead (zenith), 90° = horizon (0° to 180°)
- Elevation angle: 0° = horizon, 90° = directly overhead (-90° to 90°)
Re-exports§
pub use crate::error::Error;pub use crate::error::Result;pub use crate::spa::SpaTimeDependent;pub use crate::spa::spa_time_dependent_parts;pub use crate::spa::spa_with_time_dependent_parts;pub use crate::types::Horizon;pub use crate::types::RefractionCorrection;pub use crate::types::SolarPosition;pub use crate::types::SunriseResult;