API reference

solar_position(obs::Observer, dt::DateTime, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction())
solar_position(obs::Observer, dt::ZonedDateTime, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction())
solar_position(obs::Observer, dts::AbstractVector{DateTime}, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction())
solar_position(obs::Observer, dts::AbstractVector{ZonedDateTime}, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction())

Calculate solar position(s) for given observer location(s) and time(s).

This function computes the solar position (azimuth, elevation, and zenith angles) based on an observer's geographic location and timestamp(s). It supports multiple input formats and automatically handles time zone conversions.

Arguments

• obs::Observer: Observer location with latitude, longitude, and altitude
• dt::DateTime or dt::ZonedDateTime: Single timestamp
• dts::AbstractVector: Vector of timestamps (DateTime or ZonedDateTime)
• alg::SolarAlgorithm: Solar positioning algorithm (default: PSA())
• refraction::RefractionAlgorithm: Atmospheric refraction correction (default: NoRefraction())

Returns

• For single timestamps:
  • SolPos struct when refraction = DefaultRefraction() (default)
  • ApparentSolPos struct when a refraction algorithm is provided
• For multiple timestamps: StructVector of solar position data

Angles Convention

All returned angles are in degrees:

• Azimuth: 0° = North, positive clockwise, range [-180°, 180°]
• Elevation: angle above horizon, range [-90°, 90°]
• Zenith: angle from zenith (90° - elevation), range [0°, 180°]
• Apparent Elevation/Zenith: Only in ApparentSolPos, includes atmospheric refraction

Examples

Single timestamp calculation (basic position)

using SolarPosition, Dates, TimeZones

# Define observer location (San Francisco)
obs = Observer(37.7749, -122.4194, 100.0)

# Calculate position at specific time
dt = ZonedDateTime(2023, 6, 21, 12, 0, 0, tz"America/Los_Angeles")
pos = solar_position(obs, dt)

println("Azimuth: $(pos.azimuth)°")
println("Elevation: $(pos.elevation)°")
println("Zenith: $(pos.zenith)°")

With refraction correction

# Use a refraction algorithm (when implemented)
# pos_apparent = solar_position(obs, dt, PSA(), MyRefractionAlg())
# println("Apparent Elevation: $(pos_apparent.apparent_elevation)°")

Multiple timestamps calculation

# Generate hourly timestamps for a day
times = collect(DateTime(2023, 6, 21):Hour(1):DateTime(2023, 6, 22))
positions = solar_position(obs, times)

# Access as StructVector (acts like array of structs)
println("First position: ", positions[1])
println("All azimuths: ", positions.azimuth)

Using different algorithms

# Use NOAA algorithm instead of default PSA
pos_noaa = solar_position(obs, dt, NOAA())

Supported Input Types

• Observer: Observer{T} struct with lat/lon/altitude
• Single time: DateTime, ZonedDateTime
• Multiple times: Vector{DateTime}, Vector{ZonedDateTime}
• Algorithm: Any SolarAlgorithm subtype
• Refraction: Any RefractionAlgorithm subtype (default: NoRefraction())

Time Zone Handling

• DateTime inputs are assumed to be in UTC
• ZonedDateTime inputs are automatically converted to UTC
• For local solar time calculations, use appropriate time zones

Performance Notes

• Vectorized operations are optimized for multiple timestamps
• Type-stable implementations for both Float32 and Float64
• Broadcasting-friendly for large datasets

See also: solar_position!, Observer, PSA, NOAA

solar_position!(table, obs::Observer; dt_col::Symbol=:datetime, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction(), kwargs...)
solar_position!(table; latitude::AbstractFloat, longitude::AbstractFloat,
                altitude::AbstractFloat=0.0, alg::SolarAlgorithm=PSA(), refraction::RefractionAlgorithm=NoRefraction(), kwargs...)

Compute solar positions for all times in a table and add the results as new columns.

Arguments

• table : Table-like object with datetime column (must support Tables.jl interface).
• obs::Observer : Observer location (latitude, longitude, altitude).
• latitude, longitude, altitude : Specify observer location directly.
• dt_col::Symbol : Name of the datetime column (default: :datetime).
• alg::SolarAlgorithm : Algorithm to use (default: PSA()).
• refraction::RefractionAlgorithm : Refraction correction (default: NoRefraction()).
• kwargs... : Additional keyword arguments forwarded to the algorithm.

Returns

• Modified table with added columns: azimuth, elevation, zenith.
• If refraction is applied: also adds apparent_elevation, apparent_zenith.

Notes

The input table is modified in-place by adding new columns.

struct Observer{T<:AbstractFloat}

Observer location (deg rees, meters). Accepts a type parameter T for the floating point type to use (e.g. Float32, Float64).

Fields

• latitude::AbstractFloat: Geodetic latitude (+N)

• longitude::AbstractFloat: Longitude (+E)

• altitude::AbstractFloat: Altitude above mean sea level (meters)

• latitude_rad::AbstractFloat: Latitude in radians

• longitude_rad::AbstractFloat: Longitude in radians

• sin_lat::AbstractFloat: sin(latitude)

• cos_lat::AbstractFloat: cos(latitude)

struct SolPos{T} <: SolarPosition.Positioning.AbstractSolPos

Represents a single solar position calculated for a given observer and time.

Fields

• azimuth::Any: Azimuth (degrees, 0=N, +clockwise, range [-180, 180])

• elevation::Any: Elevation (degrees, range [-90, 90])

• zenith::Any: Zenith = 90 - elevation (degrees, range [0, 180])

struct ApparentSolPos{T} <: SolarPosition.Positioning.AbstractSolPos

Represents a single solar position calculated for a given observer and time. Also includes apparent elevation and zenith angles.

Fields

• azimuth::Any: Azimuth (degrees, 0=N, +clockwise, range [-180, 180])

• elevation::Any: Elevation (degrees, range [-90, 90])

• zenith::Any: Zenith = 90 - elevation (degrees, range [0, 180])

• apparent_elevation::Any: Apparent elevation (degrees, range [-90, 90])

• apparent_zenith::Any: Apparent zenith (degrees, range [0, 180])

struct SPASolPos{T} <: SolarPosition.Positioning.AbstractSolPos

Solar position result from SPA algorithm including equation of time.

Fields

• azimuth::Any: Azimuth (degrees, 0=N, +clockwise, range [-180, 180])

• elevation::Any: Elevation (degrees, range [-90, 90])

• zenith::Any: Zenith = 90 - elevation (degrees, range [0, 180])

• apparent_elevation::Any: Apparent elevation (degrees, range [-90, 90])

• apparent_zenith::Any: Apparent zenith (degrees, range [0, 180])

• equation_of_time::Any: Equation of time (minutes)

struct SPAObserver{T<:AbstractFloat}

Optimized observer type for SPA algorithm with pre-computed location-dependent values. Will cache terms that depend only on observer location to speed up calculations for multiple times at the same location.

Internal Fields

• latitude::AbstractFloat: Geodetic latitude (+N)

• longitude::AbstractFloat: Longitude (+E)

• altitude::AbstractFloat: Altitude above mean sea level (meters)

• latitude_rad::AbstractFloat: Latitude in radians

• longitude_rad::AbstractFloat: Longitude in radians

• sin_lat::AbstractFloat: sin(latitude)

• cos_lat::AbstractFloat: cos(latitude)

• u::AbstractFloat: Cached u term for parallax (reduced latitude)

• x::AbstractFloat: Cached x term for parallax correction

• y::AbstractFloat: Cached y term for parallax correction

abstract type SolarAlgorithm

Abstract base type for all solar position algorithms.

All concrete solar position algorithm types must inherit from this type.

Examples

struct MyAlgorithm <: SolarAlgorithm end

abstract type RefractionAlgorithm

Abstract base type for atmospheric refraction correction algorithms.

Refraction algorithms compute the apparent position of the sun by correcting for atmospheric refraction effects.

Examples

struct MyRefraction <: RefractionAlgorithm end

Positioning

This module provides the core solar position calculation algorithms, observer location handling, and result types for SolarPosition.jl. It includes implementations of various solar position algorithms such as PSA and NOAA, with support for optional atmospheric refraction corrections.

Exported Types

• Observer: Geographic observer location
• SolPos: Basic solar position result
• ApparentSolPos: Solar position with atmospheric corrections
• PSA: PSA algorithm implementation
• NOAA: NOAA algorithm implementation
• RefractionAlgorithm: Base type for refraction algorithms
• NoRefraction: No refraction correction (default)

Exported Functions

• solar_position: Calculate solar positions
• solar_position!: In-place solar position calculation

Refraction

Atmospheric refraction models.

Exported Types

• HUGHES: Hughes atmospheric refraction model
• ARCHER: Archer atmospheric refraction model
• BENNETT: Bennett atmospheric refraction model
• MICHALSKY: Michalsky atmospheric refraction model
• SG2: Saemundsson-Garfinkel atmospheric refraction model
• SPA: Solar Position Algorithm refraction model

Exported Functions

• refraction: Apply refraction correction to elevation angle(s)