Solar Positioning

struct PSA <: SolarAlgorithm

PSA (Plataforma Solar de Almería) solar position algorithm. This algorithm computes the solar position with high accuracy using empirical coefficients. Two coefficient sets are available: 2001 (range 1999-2015) and 2020 (range 2020-2050).

Accuracy

Claimed accuracy: ±0.004° for 2020 coefficients, ±0.01° for 2001 coefficients.

Literature

This algorithm is based on the work by [BALL01] and was updated for 2020 coefficients in [BMB20].

Fields

• coeffs::Int64: Coefficient set year (2001 or 2020)

struct NOAA <: SolarAlgorithm

NOAA (National Oceanic and Atmospheric Administration) solar position algorithm. This algorithm is based on NOAA's Solar Position Calculator implementation. The algorithm is from "Astronomical Algorithms" by Jean Meeus.

By default, the NOAA algorithm uses the HUGHES atmospheric refraction model which is in accordance with the NOAA solar position calculator.

Accuracy

Claimed accuracy: ±0.0167° from years -2000 to +3000 for latitudes within ±72°. For latitudes outside this range, the accuracy is ±0.167°.

Literature

Based on the NOAA solar position calculator [NOA25] and the work by [Mee91].

Fields

• delta_t::Union{Nothing, Float64}: Difference between terrestrial time and UT1 [seconds]. If nothing, uses automatic calculation.

struct Walraven <: SolarAlgorithm

Walraven solar position algorithm. The implementation accounts for the 1979 Erratum and correct azimuth quadrant selection.

Accuracy

Claimed accuracy is ±0.0100°.

Literature

This algorithm is based on [Wal78] with corrections from the 1979 Erratum [Wal79] and azimuth quadrant correction from [Spe89].

struct USNO <: SolarAlgorithm

USNO (U.S. Naval Observatory) solar position algorithm. This algorithm provides solar position calculations based on the USNO's Astronomical Applications Department formulas.

Accuracy

The accuracy is typically within a few arcminutes for most practical applications. This algorithm is suitable for general-purpose solar position calculations.

Literature

The U.S. Naval Observatory (USNO) algorithm is provided in [U.S25].

Fields

• delta_t::Union{Nothing, Float64}: Difference between terrestrial time and UT1 [seconds]. If nothing, uses automatic calculation.

• gmst_option::Int64: Option for calculating Greenwich mean sidereal time (1 or 2)

struct SPA <: SolarAlgorithm

SPA (Solar Position Algorithm) from NREL. This is the most accurate algorithm for solar position calculation, suitable for high-precision applications.

The algorithm implements the complete NREL Solar Position Algorithm as described in Reda and Andreas (2004, 2007). It accounts for:

• Heliocentric position of Earth
• Nutation and aberration
• Geocentric and topocentric corrections
• Atmospheric refraction
• Parallax effects

Accuracy

Claimed accuracy: ±0.0003° (±1 arcsecond) for years -2000 to 6000.

Literature

This algorithm is based on [RA04] with corrections from the 2007 corrigendum.

Fields

• delta_t::Union{Nothing, Float64}: Difference between terrestrial time and UT1 [seconds]. If nothing, uses automatic calculation.

• pressure::Float64: Annual average air pressure [Pa]

• temperature::Float64: Annual average air temperature [°C]

• atmos_refract::Float64: Approximate atmospheric refraction at sunrise/sunset [degrees]

struct Iqbal <: SolarAlgorithm

Iqbal solar position algorithm.

A lightweight algorithm that obtains the solar declination and equation of time from a truncated Fourier series in the day angle, then derives the zenith and azimuth from the standard spherical trigonometry relations. No atmospheric refraction is applied by default.

Accuracy

The truncated Fourier expansion gives a declination accurate to about ±0.01°, which makes this algorithm a good choice when speed matters more than sub arcminute precision.

Literature

Based on the formulation compiled by [Iqb83], which builds on the Fourier series representation of [Spe71].

struct Michalsky <: SolarAlgorithm

Michalsky solar position algorithm.

Implements the approximate solar position algorithm of the Astronomical Almanac. The default refraction model is MICHALSKY, matching the original publication, so solar_position returns an ApparentSolPos unless another model is given.

Accuracy

±0.01° between 1950 and 2050 with the original Julian date formulation.

Constructors

Michalsky()                                   # Spencer correction, original Julian date
Michalsky(; spencer_correction = false)       # original northern hemisphere quadrants
Michalsky(; julian_date = :standard)          # exact Julian date, usable outside 1950-2050

Options

• spencer_correction: when true, the default, the azimuth quadrant is resolved with the correction of [Spe89], which is valid at all latitudes. The original formulation, false, is only valid in the northern hemisphere.
• julian_date: :original, the default, reproduces the integer based Julian date of the paper, whose naive leap year count holds the stated accuracy only between 1950 and 2050. :standard uses the exact Julian date and stays usable outside that window. The two agree exactly within it. Other packages call the :standard variant the pandas Julian date.

Literature

Based on [Mic88], with the azimuth quadrant correction of [Spe89].

Fields

• spencer_correction::Bool: Apply the Spencer (1989) azimuth quadrant correction, valid at all latitudes

• julian_date::Symbol: Julian date formulation, :original or :standard

struct Interpolated{A<:SolarAlgorithm, ITP} <: SolarAlgorithm

Fast solar position from cubic B-spline interpolation of the geocentric solar coordinates of a wrapped exact algorithm, currently SPA.

The interpolant samples four observer independent quantities on a uniform time grid: geocentric right ascension, geocentric declination, the Earth-Sun radius vector, and the equation of the equinoxes. Sidereal time and the topocentric reconstruction stay closed form and run through the exact same code as the wrapped algorithm, so the only error is the spline interpolation error of the four smooth geocentric series. At the default one hour grid spacing this error is far below the wrapped algorithm's own accuracy.

One interpolant serves every observer, so a single instance can be shared across a whole grid of sites and across threads.

Construction requires Interpolations.jl to be loaded:

using Interpolations
alg = Interpolated(SPA(); tspan = (DateTime(2024, 1, 1), DateTime(2025, 1, 1)))
solar_position(obs, dt, alg)

Arguments

• algorithm::SPA = SPA(): the exact algorithm to sample. Its delta_t setting is used during sampling. The default constant ΔT keeps the sampled series smooth; with delta_t = nothing the piecewise ΔT model introduces slope kinks that are far below the interpolation tolerance.
• tspan::Tuple: the valid query span as a pair of DateTime or ZonedDateTime. Zoned times are converted to UTC.
• step::Period = Hour(1): the sampling grid spacing. Must be positive and at most 30 days so that right ascension advances much less than half a turn per step. Steps above 3 days warn, because the interpolation error then exceeds the wrapped algorithm's own accuracy: measured against direct SPA the maximum error is about 1e-10 degrees at Hour(1), 4e-7 at Day(1), 2e-4 at Day(3), and 3e-2 at Day(30).
• out_of_range::Symbol = :error: behaviour for queries outside tspan. :error throws an ArgumentError, :fallback silently calls the wrapped exact algorithm.

Fields

• algorithm::SolarAlgorithm: Wrapped exact algorithm, used for sampling and the :fallback path

• itp_α::Any: Cubic B-spline of unwrapped geocentric right ascension in degrees vs days since J2000

• itp_δ::Any: Cubic B-spline of geocentric declination in degrees

• itp_R::Any: Cubic B-spline of the Earth-Sun radius vector in astronomical units

• itp_eqeq::Any: Cubic B-spline of the equation of the equinoxes in degrees

• tspan::Tuple{Dates.DateTime, Dates.DateTime}: Valid query span as UTC datetimes

• step::Dates.Millisecond: Sampling grid spacing

• t_min::Float64: Span start in days since J2000

• t_max::Float64: Span end in days since J2000

• out_of_range::Symbol: Out of range behaviour, :error or :fallback

solar_rate(
    obs::SolarPosition.Positioning.AbstractObserver{T<:Real},
    dt::Dates.DateTime,
    alg::Interpolated
) -> NamedTuple{(:dazimuth_dt, :delevation_dt), <:Tuple{Any, Any}}

Rate of change of solar azimuth and elevation in degrees per hour at dt, computed with a central finite difference of one second half width over the interpolated position. Returns a named tuple (dazimuth_dt, delevation_dt). The azimuth difference is wrap aware, so the rate is continuous across the 0/360 degree crossing.

dt must be at least one second inside the interpolated span, unless the algorithm was constructed with out_of_range = :fallback.