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)
§References
- Reda, I.; Andreas, A. (2003). Solar position algorithm for solar radiation applications. Solar Energy, 76(5), 577-589. DOI: http://dx.doi.org/10.1016/j.solener.2003.12.003
- Grena, R. (2012). Five new algorithms for the computation of sun position from 2010 to 2110. Solar Energy, 86(5), 1323-1337. DOI: http://dx.doi.org/10.1016/j.solener.2012.01.024
§Features
- Thread-safe, immutable data structures
- Performance optimizations for bulk calculations (SPA only, 6-7x speedup)
- Comprehensive test suite with reference data validation
§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).
These optimizations 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;