# `Astro.Earth`
[🔗](https://github.com/kipcole9/astro/blob/v2.0.0/lib/astro/earth.ex#L1)

Earth constants, nutation, and elevation-related corrections
for rise/set calculations.

This module provides physical and geometric constants for the
Earth (equatorial radius, atmospheric refraction, apparent solar
radius, mean obliquity) together with the IAU 1980 nutation
series and elevation adjustments used by the rise/set algorithms
in `Astro.Solar.SunRiseSet` and `Astro.Lunar.MoonRiseSet`.

## Function groups

### Physical constants

* `earth_radius/0` — equatorial radius in kilometers
* `obliquity_j2000/0` — mean obliquity of the ecliptic at J2000.0

### Optical constants

* `refraction/0` — standard atmospheric refraction at the horizon
* `solar_radius/0` — apparent solar semi-diameter at the horizon

### Nutation

* `nutation/1` — IAU 1980 nutation in longitude and obliquity (17-term)

### Observer geometry

* `horizon_distance/1` — geometric distance to the horizon
* `elevation_adjustment/1` — dip angle correction for observer elevation
* `adjusted_solar_elevation/2` — combined refraction, radius and elevation correction

# `adjusted_solar_elevation`

Adjusts the solar elevation to be the apparent angle
at sunrise if the requested angle is `:geometric`
(or 90°).

### Arguments

* `solar_elevation` is the requested solar elevation
  in degrees. It will be 90° for sunrise and sunset.

* `elevation` is elevation in meters

### Returns

* The solar elevation angle which, if solar elevation is
  exactly 90.0 degrees, is adjusted for refraction,
  elevation and solar radius.

# `earth_radius`

```elixir
@spec earth_radius() :: Astro.kilometers()
```

Returns the Earth's equatorial radius in kilometers.

This value is the [IAU](https://iau-a3.gitlab.io/NSFA/NSFA_cbe.html#EarthRadius2009)
current best estimate and the recommended value for
astronomical calculations.

# `elevation_adjustment`

Adjusts the solar elevation to account
for the elevation of the requested location.

### Arguments

* `elevation` is the observer's elevation in meters.

### Returns

* The solar elevation angle adjusted for the observer's
  elevation.

# `horizon_distance`

Returns the geometric distance to the horizon in meters.

Uses the exact formula `√(h² + 2Rh)` where `h` is the
observer's elevation and `R` is the Earth's equatorial
radius. Atmospheric refraction is not included.

### Arguments

* `observer_elevation_m` is the observer's elevation above
  sea level in meters. Defaults to `0.0`.

### Returns

* The distance to the geometric horizon in meters.

# `nutation`

```elixir
@spec nutation(c :: Astro.Time.julian_centuries()) :: {float(), float(), float()}
```

Computes IAU 1980 [nutation](https://en.wikipedia.org/wiki/Astronomical_nutation#:~:text=Earth's%20nutation,-Learn%20more&text=Nutation%20(N)%20of%20the%20Earth,spherical%20figure%20of%20the%20Earth.))
in longitude and obliquity, and the mean obliquity.

### Arguments

* `julian_century` is any astronomical Julian century such
  as returned from `Astro.Time.julian_centuries_from_julian_day/1`.

### Returns

* `{delta_psi_rad, delta_eps_rad, eps0_rad}` representing
  the longitude, obliquity and mean obliquity.

# `obliquity_j2000`

```elixir
@spec obliquity_j2000() :: Astro.angle()
```

Returns the mean [obliquity](https://en.wikipedia.org/wiki/Axial_tilt)
of the [ecliptic](https://en.wikipedia.org/wiki/Ecliptic) at
[epoch](https://en.wikipedia.org/wiki/Epoch_(astronomy)) J2000.0.

Obliquity, or axial tilt, is the angle between the
Earth's rotational axis and its orbital axis, which is
the line perpendicular to its orbital plane.

The rotational axis of Earth, for example, is the imaginary
line that passes through both the North Pole and South Pole,
whereas the Earth's orbital axis is the line perpendicular
to the imaginary plane through which the Earth moves as it
revolves around the Sun. The Earth's obliquity or axial tilt
is the angle between these two lines.

See [Astronomical Algorithms](https://www.amazon.com/dp/0943396611) Chapter 22.

### Returns

* The mean obliquity as a float angle in degrees
  at j2000.

# `refraction`

```elixir
@spec refraction() :: Astro.degrees()
```

Returns an estimate of the effect of refraction
(in degrees) applied to the calculation of sunrise and
sunset times.

Sunrise actually occurs before the Sun truly
reaches the horizon because earth's atmosphere
refracts the sun's image. At the horizon, the average
amount of refraction is 34 arcminutes, though this
amount varies based on atmospheric conditions.

This effect is especially powerful for objects
that appear close to the horizon, such as the
rising or setting sun, because the light rays
enter the earth's atmosphere at a particularly
shallow angle. Because of refraction, the sun
may be seen for several minutes before it actually
rises in the morning and after it sets in the
evening.

The refraction angle is calculated using the formula
from [Meeus](https://www.amazon.com/dp/0943396611) (2nd edition, chapter 15):

```
R = 1 / tan(0° + 7.31 / (0° + 4.4)) ≈ 34 arcminutes = 0.5667°
```
The [Astronomical Almanac](https://www.amazon.com/Astronomical-Almanac-2023-Comprehensive-Events/dp/B0BGZLFPF4/ref=sr_1_1)
uses the same value.

# `solar_radius`

```elixir
@spec solar_radius() :: Astro.degrees()
```

Returns the Sun's apparent radius in degrees
at sunrise/sunset.

Unlike most other solar measurements, sunrise occurs
when the Sun's upper limb, rather than its center,
appears to cross the horizon. The apparent radius of
the Sun at the horizon is 16 arc minutes.

---

*Consult [api-reference.md](api-reference.md) for complete listing*