@spec earth_orbit_eccentricity(float()) :: float()

Returns the Earth's orbital eccentricity.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• a unitless value of eccentricity as a float. A value of 0 is a circular orbit, values between 0 and 1 form an elliptic orbit, 1 is a parabolic escape orbit, and greater than 1 is a hyperbola. Earth's current eccentricity is approximately 0.0167.

Examples

iex> Astro.Solar.earth_orbit_eccentricity(0.0)
0.016708634

@spec equation_of_time(float()) :: float()

Returns the equation of time in minutes.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the discrepancy between apparent solar time and mean solar time in minutes as a float. A positive value means the sundial is ahead of the clock.

Notes

The equation of time describes the discrepancy between apparent solar time (which directly tracks the Sun's diurnal motion) and mean solar time (which tracks a theoretical mean Sun with uniform motion).

During a year the equation of time ranges from about +16 min 33 s (around 3 November) to −14 min 6 s (around 11 February), with zeros near 15 April, 13 June, 1 September, and 25 December.

The two principal causes are the obliquity of the ecliptic (~23.44°) and the eccentricity of the Earth's orbit (~0.0167).

Examples

iex> Astro.Solar.equation_of_time(0.0)
-3.3012588023605938

@spec equinox_and_solstice(pos_integer(), :march | :june | :september | :december) ::
  {:ok, DateTime.t()}

Returns the UTC datetime of an equinox or solstice.

Arguments

• year is a positive integer Gregorian year.

• event is one of :march, :june, :september, or :december identifying the equinox or solstice.

Returns

• {:ok, datetime} where datetime is a DateTime.t() in UTC.

Notes

The :march and :september events are the equinoxes (Sun's ecliptic longitude 0° and 180° respectively). The :june and :december events are the solstices (ecliptic longitude 90° and 270°).

Examples

iex> {:ok, dt} = Astro.Solar.equinox_and_solstice(2024, :march)
iex> dt.year
2024
iex> dt.month
3
iex> dt.day
20

Returns an approximate moment at or before t when the solar ecliptic longitude just exceeded lambda degrees.

Arguments

• lambda is the target solar ecliptic longitude in degrees.

• t is any moment in time expressed as a moment (fractional days since the epoch).

Returns

• the approximate moment (fractional days since the epoch) at or before t when the solar ecliptic longitude last exceeded lambda degrees.

Examples

# Estimate when the Sun last passed 90° before the June solstice
iex> moment = Astro.Time.date_time_to_moment(~D[2024-06-21])
iex> result = Astro.Solar.estimate_prior_solar_ecliptic_longitude(90, moment)
iex> {:ok, dt} = Astro.Time.date_time_from_moment(result)
iex> dt.year
2024
iex> dt.month
6

@spec mean_obliquity_of_ecliptic(float()) :: float()

Returns the mean obliquity of the ecliptic in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the mean obliquity of the ecliptic in degrees as a float.

Notes

Obliquity is the angle between the Earth's rotational axis and the perpendicular to its orbital plane. Earth's current mean obliquity is about 23.44° and decreasing very slowly over millennia. This function returns the mean value without the short-period nutation correction; see obliquity_correction/1 for the corrected value.

Examples

iex> Astro.Solar.mean_obliquity_of_ecliptic(0.0)
23.43929111111111

@spec obliquity_correction(float()) :: float()

Returns the corrected obliquity of the ecliptic in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the corrected obliquity of the ecliptic in degrees as a float.

Notes

The corrected obliquity accounts for the nutation in obliquity (a short-period oscillation), in addition to the mean obliquity which changes slowly over millennia.

Examples

iex> Astro.Solar.obliquity_correction(0.0)
23.437821291789415

@spec solar_declination(float()) :: float()

Returns the solar declination in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the solar declination in degrees as a float.

Notes

The solar declination is the angle between the direction of the centre of the solar disk measured from Earth's centre and the equatorial plane. It ranges from approximately +23.44° at the June solstice to −23.44° at the December solstice, and is 0° at the equinoxes.

Examples

iex> Astro.Solar.solar_declination(0.0)
...> |> Float.round(4)
-23.0325

Returns the solar ecliptic longitude in degrees.

Arguments

• t is any moment in time expressed as a moment (fractional days since the epoch).

Returns

• the solar ecliptic longitude in degrees as a float, in the range 0..360.

Notes

The solar ecliptic longitude is the position of the Sun on the celestial sphere along the ecliptic. It is also an effective measure of the position of the Earth in its orbit around the Sun, taken as 0° at the moment of the vernal equinox.

Since it is based on how far the Earth has moved in its orbit since the equinox, it is a measure of what time of the tropical year (the year of seasons) has elapsed, without the inaccuracies of a calendar date which is perturbed by leap years and calendar imperfections.

Examples

iex> moment = Astro.Time.date_time_to_moment(~D[2024-03-20])
iex> Astro.Solar.solar_ecliptic_longitude(moment)
359.87362951019264

@spec solar_ecliptic_longitude_after(number(), Astro.Time.time()) :: Astro.Time.time()

Returns the moment (UT) of the first time at or after moment t when the solar ecliptic longitude will be lambda degrees.

Arguments

• lambda is the target solar ecliptic longitude in degrees.

• t is any moment in time expressed as a moment (fractional days since the epoch).

Returns

• the moment (fractional days since the epoch) when the solar ecliptic longitude reaches lambda degrees.

Examples

# Find the June solstice (longitude 90°) in 2024
iex> moment = Astro.Time.date_time_to_moment(~D[2024-05-22])
iex> result = Astro.Solar.solar_ecliptic_longitude_after(90, moment)
iex> {:ok, dt} = Astro.Time.date_time_from_moment(result)
iex> dt.year
2024
iex> dt.month
6

@spec solar_noon_utc(float(), Astro.longitude()) :: float()

Returns solar noon as minutes since midnight UTC.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

• longitude is the longitude in degrees of the location from which solar noon is to be measured. West is negative.

Returns

• solar noon as a float number of minutes since midnight UTC.

Notes

Solar noon is the moment when the Sun passes a location's meridian and reaches its highest position in the sky. In most cases it does not occur at 12:00 local time.

Examples

iex> Astro.Solar.solar_noon_utc(0.0, 151.2093)
1328.3378566361976

@spec sun_apparent_longitude(Astro.Time.julian_centuries()) :: float()

Returns the Sun's apparent longitude in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the Sun's apparent longitude in degrees as a float, in the range 0..360.

Notes

The apparent longitude is the Sun's celestial longitude corrected for aberration and nutation, as opposed to mean longitude.

An equinox is the instant when the Sun's apparent geocentric longitude is 0° (northward equinox) or 180° (southward equinox).

Examples

iex> Astro.Solar.sun_apparent_longitude(0.0)
280.3725548788095

@spec sun_equation_of_center(float()) :: float()

Returns the Sun's equation of the centre in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the equation of the centre in degrees as a float.

Notes

In two-body Keplerian orbital mechanics, the equation of the centre is the angular difference between the actual position of a body in its elliptical orbit and the position it would occupy if its motion were uniform, in a circular orbit of the same period. It is defined as the difference between the true anomaly ν and the mean anomaly M.

Examples

iex> Astro.Solar.sun_equation_of_center(0.0)
-0.08430148943719645

@spec sun_geometric_mean_anomaly(float()) :: float()

Returns the Sun's geometric mean anomaly in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the mean anomaly in degrees as a float, in the range 0..360.

Notes

In celestial mechanics, the mean anomaly is the fraction of an elliptical orbit's period that has elapsed since the orbiting body passed periapsis, expressed as an angle. It is the angular distance from the pericentre which a fictitious body would have if it moved in a circular orbit, with constant speed, in the same orbital period as the actual body in its elliptical orbit.

Examples

iex> Astro.Solar.sun_geometric_mean_anomaly(0.0)
357.52911

@spec sun_geometric_mean_longitude(float()) :: float()

Returns the Sun's geometric mean longitude in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the mean solar longitude in degrees as a float, in the range 0..360.

Notes

Mean longitude is a convenient uniform measure of how far around its orbit a body has progressed since passing the reference direction. While mean longitude assumes constant speed, true longitude accounts for the body's actual speed which varies around its elliptical orbit. The difference between the two is the equation of the centre.

Examples

iex> Astro.Solar.sun_geometric_mean_longitude(0.0)
280.46646

@spec sun_true_longitude(float()) :: float()

Returns the Sun's true longitude in degrees.

Arguments

• julian_centuries is any moment in time expressed as Julian centuries from J2000.0.

Returns

• the Sun's true longitude in degrees as a float.

Notes

In celestial mechanics, true longitude is the ecliptic longitude at which an orbiting body could actually be found if its inclination were zero. It is the sum of the geometric mean longitude and the equation of the centre.

Examples

iex> Astro.Solar.sun_true_longitude(0.0)
280.38215851056276