# sonnenstand

[![Hex.pm](https://img.shields.io/hexpm/v/sonnenstand.svg)](https://hex.pm/packages/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:

```erlang
{deps, [sonnenstand]}.
```

## Usage

```erlang
%% 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:

```erlang
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](https://gml.noaa.gov/grad/solcalc) 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

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

## License

[MIT](LICENSE) © Holger Schuh