sonnenstand (sonnenstand v1.0.0)

View Source

Solar position calculations.

Given a date/time and a location (latitude/longitude in degrees), this module computes the position of the sun as 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 intended for everyday use (shading, solar-panel orientation, photography), not for high-precision astronomy.

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.

Example

1> DateTime = {{2024, 6, 21}, {12, 0, 0}}.
2> sonnenstand:elevation(DateTime, 52.5, 13.4).
60.91...
3> sonnenstand:azimuth(DateTime, 52.5, 13.4).
176.13...

Summary

Types

degrees()
latitude()
longitude()

Functions

azimuth(DateTime, Latitude, Longitude)

Returns the sun's azimuth in degrees for DateTime at the given location.

day_of_year/1

Returns the ordinal day of the year for Date (1 for 1 January).

declination(Date)

Returns the sun's declination in degrees for Date.

elevation(DateTime, Latitude, Longitude)

Returns the sun's elevation in degrees for DateTime at the given location.

equation_of_time(Date)

Returns the equation of time in minutes for Date.

hour_angle/2

Returns the sun's hour angle in degrees for DateTime (UTC) at Longitude.

Types

degrees()

-type degrees() :: float().

latitude()

-type latitude() :: number().

longitude()

-type longitude() :: number().

Functions

azimuth(DateTime, Latitude, Longitude)

-spec azimuth(calendar:datetime(), latitude(), longitude()) -> degrees().

Returns the sun's azimuth in degrees for DateTime at the given location.

The azimuth is measured clockwise from north (0.0 = north, 90.0 = east, 180.0 = south, 270.0 = west). Values before solar noon fall in the eastern half (0.0..180.0); values afterwards fall in the western half (180.0..360.0).

day_of_year/1

-spec day_of_year(calendar:date()) -> pos_integer().

Returns the ordinal day of the year for Date (1 for 1 January).

1> sonnenstand:day_of_year({2024, 1, 1}).
1
2> sonnenstand:day_of_year({2024, 12, 31}).
366

declination(Date)

-spec declination(calendar:date()) -> degrees().

Returns the sun's declination in degrees for Date.

The declination is the angle between the sun's rays and the equatorial plane, ranging from about -23.45 at the December solstice to +23.45 at the June solstice.

elevation(DateTime, Latitude, Longitude)

-spec elevation(calendar:datetime(), latitude(), longitude()) -> degrees().

Returns the sun's elevation in degrees for DateTime at the given location.

The elevation (or altitude) is the angle of the sun above the horizon: positive when the sun is up, negative when it is below the horizon.

equation_of_time(Date)

-spec equation_of_time(calendar:date()) -> float().

Returns the equation of time in minutes for Date.

This is the difference between apparent solar time and mean solar time, caused by the eccentricity of Earth's orbit and the tilt of its axis.

hour_angle/2

-spec hour_angle(calendar:datetime(), longitude()) -> degrees().

Returns the sun's hour angle in degrees for DateTime (UTC) at Longitude.

The hour angle is negative before solar noon (morning), zero at solar noon, and positive afterwards (afternoon).