sonnenstand

Solar position calculations for Erlang. Given a date/time and a location, sonnenstand ("sun position" in German) computes where the sun is in the sky: its elevation (height above the horizon) and azimuth (compass direction).

The formulas follow the algorithm described at http://www.geoastro.de/SME/tk/index.htm. They are approximations suitable for everyday use — shading studies, solar-panel orientation, photography planning — rather than high-precision astronomy.

Installation

Add sonnenstand to your rebar.config dependencies:

{deps, [sonnenstand]}.

Usage

%% Berlin, summer solstice, solar noon ~11:00 UTC (52.5° N, 13.4° E):
1> DateTime = {{2024, 6, 21}, {11, 0, 0}}.
2> sonnenstand:elevation(DateTime, 52.5, 13.4).
60.90689656676232
3> sonnenstand:azimuth(DateTime, 52.5, 13.4).
176.1259325747917

At solar noon the sun is high (≈61°) and almost due south (≈176°). In the morning the azimuth is in the east; in the afternoon it swings into the west:

4> sonnenstand:azimuth({{2024, 6, 21}, {7, 0, 0}}, 52.5, 13.4).
96.95526544807744
5> sonnenstand:azimuth({{2024, 6, 21}, {15, 0, 0}}, 52.5, 13.4).
259.5076043431589

Conventions

Angles are in degrees.
Latitude is positive north, longitude positive east.
Times are interpreted as UTC.
Azimuth is measured clockwise from north: 0.0 = north, 90.0 = east, 180.0 = south, 270.0 = west.

API

Function	Description
`day_of_year(Date)`	Ordinal day of the year (1 for 1 January).
`declination(Date)`	Sun's declination in degrees.
`equation_of_time(Date)`	Equation of time in minutes.
`hour_angle(DateTime, Longitude)`	Hour angle in degrees (negative before solar noon).
`elevation(DateTime, Latitude, Longitude)`	Sun's elevation above the horizon, in degrees.
`azimuth(DateTime, Latitude, Longitude)`	Sun's azimuth, in degrees clockwise from north.

Accuracy

The formulas are approximations. The library is validated against the NOAA Solar Calculator for 2026 at three locations spanning both hemispheres and a wide longitude range — Berlin (52.33° N, 13.30° E), Johannesburg (26.20° S, 28.046° E), and Sydney (33.87° S, 151.22° E) — at the solstices and equinoxes (see test/sonnenstand_noaa_tests.erl):

Solar noon agrees with NOAA to within ~30 seconds year-round. As this is independent of atmospheric refraction, it confirms the equation-of-time, longitude, and UTC handling.
Sunrise and sunset agree to within about 1 minute near the solstices and up to ~5 minutes near the equinoxes, where the single-term declination and equation-of-time series are least accurate and a small angular error maps to several minutes near the horizon.

Note: the library computes the geometric position of the sun's center and does not model atmospheric refraction.

Building

rebar3 compile      # build
rebar3 eunit        # run tests
rebar3 dialyzer     # type analysis
rebar3 ex_doc       # generate documentation