# SolarCalculator Library for Arduino

SolarCalculator is inspired by the [NOAA Solar Calculator](https://gml.noaa.gov/grad/solcalc/). 

This library provides functions to calculate the times of sunrise, sunset, solar noon, twilight (dawn and dusk), Sun's 
apparent position in the sky, equation of time, etc.

Most formulae are taken from Astronomical Algorithms by Jean Meeus and optimized for 8-bit AVR platform.


## Installation

Download and copy SolarCalculator to your local Arduino/libraries directory.

### Time

Date and time inputs are assumed to be in **Universal Coordinated Time** (UTC).

Although not required, it is recommended to use SolarCalculator along with the 
[Time](https://github.com/PaulStoffregen/Time) library or similar.


## Usage

Include SolarCalculator.h in your sketch:
```cpp
#include <SolarCalculator.h>
```

Calculate the times of sunrise, transit (solar noon), and sunset, in hours:
```cpp
double latitude = 45.55;     // Observer's latitude 
double longitude = -73.633;  // Observer's longitude
int time_zone = -5;          // UTC offset
int year = 2022;             // Calendar year (1901-2099)
int month = 1;               // Calendar month (1-12)
int day = 1;                 // Calendar day (1-31)

double transit, sunrise, sunset;
calcSunriseSunset(year, month, day, latitude, longitude, transit, sunrise, sunset);
```

Or, using the Time library (Unix time):
```cpp
time_t utc = now();
calcSunriseSunset(utc, latitude, longitude, transit, sunrise, sunset);
```

Convert to local standard time:
```cpp
double sunrise_local = sunrise + time_zone;
```
* Refer to the example sketches for more on rounding and printing the results.

Similarly, calculate the times of dawn and dusk, in hours:
```cpp
calcCivilDawnDusk(utc, latitude, longitude, transit, c_dawn, c_dusk);
calcNauticalDawnDusk(utc, latitude, longitude, transit, n_dawn, n_dusk);
calcAstronomicalDawnDusk(utc, latitude, longitude, transit, a_dawn, a_dusk);
```

Sun's equatorial coordinates, in degrees and AUs:
```cpp
calcEquatorialCoordinates(utc, rt_ascension, declination, radius_vector);
```

Sun's horizontal coordinates, corrected for atmospheric refraction, in degrees:
```cpp
calcHorizontalCoordinates(utc, latitude, longitude, azimuth, elevation);
```

Equation of time, in minutes of time:
```cpp
calcEquationOfTime(utc, eq);
```
where the results are passed by reference.


## Examples

The following example sketches are included in this library:

* `SunriseSunset`: Calculate the times of sunrise, solar noon, and sunset for a given date and location.

* `SunriseSunsetAltitude`: Calculate the rise and set times at a height above the level of the horizon.

* `SolarCalculatorTimeLib`: Calculate the rise and set times, equation of time, and current solar coordinates.

* `SolarTrackingTimeLib`: Monitor the Sun's position in the sky for any location on Earth.

* `EquationOfTime`: Plot the equation of time for a given year.


## Notes

### Accuracy

Various things to consider:

* The amount of atmospheric refraction changes with air temperature, pressure, and the elevation of the observer. 
Therefore, sunrise and sunset times can only be accurate to the nearest minute (Meeus, 1998).

* Assuming a purely elliptical motion of the Earth, solar coordinates have a "low accuracy" of 0.01° (Meeus, 1998). To
this precision, we ignore nutation, delta T, and higher-order terms in the relevant expressions.

* Arduino's single precision floating numbers have the equivalent of `24 * log10(2)` ≈ 7.22 significant digits. 
Although this is generally not sufficient for mathematical astronomy (Meeus, 1998), it is good enough for our purposes.

### Sunrise and sunset

The algorithm for finding the times of sunrise and sunset implemented in this library is valid for all latitudes between 
the Arctic and Antarctic circles (about ± 66.5°). Outside this range, a more general algorithm should be used but is not
provided at this time.


## References

ESRL Global Monitoring Laboratory (n.d.). *NOAA Solar Calculator*. https://gml.noaa.gov/grad/solcalc/

Meeus, J. (1998). *Astronomical algorithms* (2nd ed.). Willmann-Bell.

