solar-positioning

A Rust library for finding topocentric solar coordinates, i.e. the sun's position on the sky for a given date, latitude, and longitude (and other parameters), as well as times of sunrise, sunset and twilight. Calculations strictly follow well-known, peer-reviewed algorithms: SPA by Reda and Andreas and, alternatively, Grena/ENEA by Grena. More than 1000 test points are included to validate against the reference code and other sources.

[!NOTE] This library is not based on or derived from code published by NREL, ENEA or other parties. It is an implementation precisely following the algorithms described in the respective papers.

Usage

cargo add solar-positioning

Requirements

Rust 1.70+. Minimal dependencies. Supports std (default) and no_std with libm.

Feature flags:

std (default): Standard library, native math
chrono (default): DateTime API (disable for pure numeric JulianDate API)
libm: no_std support

Code

The API is intentionally "flat", comprising a handful of functions and simple structs as results.

use chrono::{DateTime, FixedOffset};
use solar_positioning::spa;

let datetime = "2025-06-21T12:00:00+02:00".parse::<DateTime<FixedOffset>>().unwrap();

let position = spa::solar_position(
    datetime,
    48.21,   // latitude
    16.37,   // longitude
    190.0,   // elevation (m)
    69.0,    // delta T (seconds, ~70 for 2025)
    None     // no atmospheric refraction
).unwrap();

println!("Azimuth: {:.1}°, Elevation: {:.1}°",
    position.azimuth(), position.elevation_angle());

Without chrono, use the numeric JulianDate API:

use solar_positioning::{spa, time::JulianDate, RefractionCorrection};

let jd = JulianDate::from_utc(2025, 6, 21, 12, 0, 0.0, 69.0).unwrap();
let position = spa::solar_position_from_julian(
    jd, 48.21, 16.37, 190.0, Some(RefractionCorrection::standard())
).unwrap();

For multiple coordinates at the same time, calculate time-dependent parts once (SPA only):

let time_dependent = spa::spa_time_dependent_parts(datetime, 69.0).unwrap();
for (lat, lon) in [(48.21, 16.37), (52.52, 13.40)] {
    let pos = spa::spa_with_time_dependent_parts(lat, lon, 0.0, None, &time_dependent).unwrap();
}

Calculate sunrise, transit, and sunset (return type depends on day type: regular/polar day/polar night):

use solar_positioning::{spa, types::SunriseResult, Horizon, time::DeltaT};

let datetime = "2025-06-21T00:00:00+02:00".parse().unwrap();
let result = spa::sunrise_sunset_for_horizon(
    datetime, 69.65, 18.96,
    DeltaT::estimate_from_date_like(datetime).unwrap(),
    Horizon::SunriseSunset
).unwrap();

match result {
    SunriseResult::RegularDay { sunrise, transit, sunset } => { /* ... */ }
    _ => { /* polar day/night */ }
}

For twilight, use Horizon::CivilTwilight, Horizon::NauticalTwilight, or Horizon::AstronomicalTwilight.

Examples

cargo run --example basic_usage          # Solar position
cargo run --example sunrise_sunset       # Sunrise/sunset/twilight
cargo run --example grena3_comparison    # SPA vs Grena3

Which algorithm?

spa: Maximum accuracy, reference algorithm, works for historic dates
grena3: Simple, very fast, often accurate enough (2010-2110 CE timeframe)

Both are fast in absolute terms. The ~10× speed difference only matters for bulk calculations.

Sunrise/sunset accuracy notes

Uses standard 0.833° correction (solar disc 50 arc-minutes below horizon). Atmospheric refraction varies, so calculated times may differ from observed by several minutes (Wilson 2018).
Jean Meeus advises giving times "more accurately than to the nearest minute makes no sense". Errors increase toward poles.
Results match the NOAA calculator closely.

Delta T

Delta T (ΔT) is the difference between terrestrial time and UT1 (Wikipedia). For many applications it's negligible (~70 seconds in 2025). For maximum accuracy, use observed values (available from US Naval Observatory) or estimates.

The time::DeltaT estimator uses polynomial fits from Espenak and Meeus (2007, updated 2014). Current extrapolated values are slightly high (~2 seconds). This gap will widen (Morrison et al. 2021). However, this should not matter for most applications.

License

Licensed under the MIT License.

solar-positioning 0.3.6