Astro (Astro v2.7.0)

Copy Markdown View Source

High-level API for common astronomical observations.

This module is the primary public interface for the Astro library. It provides sunrise and sunset, moonrise and moonset, equinoxes and solstices, lunar phases, crescent visibility, and the positions of the sun and moon. Functions accept standard Elixir dates and date times. Those that can fail, such as the rise and set times, return {:ok, value} or {:error, reason}. The positions and phases, which cannot fail, return their value directly.

For lower-level access see Astro.Solar, Astro.Lunar, Astro.Time, Astro.Earth and Astro.Ephemeris.

Specifying a location

A location is a {longitude, latitude} tuple (note the order, which matches Geo.Point), a Geo.Point struct, or a Geo.PointZ struct that also carries an elevation in metres.

  • Longitude is positive east and negative west, in degrees.

  • Latitude is positive north and negative south, in degrees.

Time zone resolution

The rise and set functions (sunrise/3, sunset/3, moonrise/3 and moonset/3) return a DateTime in the local time zone of the location, resolved with TzWorld when it is a dependency. These options override that:

  • :time_zone is a time zone name, :utc, or :default to resolve the time zone from the location.

  • :time_zone_database is the time zone database module, such as Tz.TimeZoneDatabase.

  • :time_zone_resolver is a 1-arity function that receives a Geo.Point and returns {:ok, time_zone_name}.

Function groups

Solar

Lunar

New moon and phase searches

Crescent visibility

Equinoxes and solstices

  • equinox/3 returns the March or September equinox.

  • solstice/3 returns the June or December solstice.

Summary

Types

altitude()
angle()
astronomical_units()
date()
degrees()
kilometers()
latitude()
location()
longitude()
meters()
method()
options()
phase()
radians()

Functions

date_time_lunar_phase_at_or_after(date_time, phase)

Returns the date time of a given lunar phase at or after a given date time or date.

date_time_lunar_phase_at_or_before(date_time, phase)

Returns the date time of a given lunar phase at or before a given date time or date.

date_time_new_moon_at_or_after(datetime)

Returns the date time of the new moon at or after a given date or date time.

date_time_new_moon_before(date_time)

Returns the date time of the new moon before a given date or date time.

date_time_new_moon_nearest(date_time)

Returns the date time of the new moon nearest to a given date or date time.

duration_of_daylight(location, date)

Returns the duration of daylight for a given location on a given date as a Duration.t/0.

equinox(year, event, options \\ [])

Returns the datetime of either the March or September equinox, in UTC or a requested time zone.

hours_of_daylight(location, date)

Returns the number of hours of daylight for a given location on a given date.

illuminated_fraction_of_moon_at(date_time)

Returns the illumination of the moon as a float for a given date or date time.

is_lunar_phase(phase)

Guards that a value is a lunar phase angle.

lunar_phase_at(date_time)

Returns the lunar phase as a float number of degrees at a given date or date time.

lunar_phase_emoji(phase)

Returns the moon phase as a UTF8 binary representing an emoji of the moon phase.

moon_position_at(date_time)

Returns a Geo.PointZ.t/0 containing the right ascension and declination of the moon at a given date or date time.

moonrise(location, date, options \\ default_options())

Returns the moonrise for a given location and date.

moonset(location, date, options \\ default_options())

Returns the moonset for a given location and date.

new_visible_crescent(location, date, method \\ :odeh)

Predicts the visibility of the new crescent moon at a given location on a given date using one of three published criteria.

new_visible_crescent(location, date, method, options)

Predicts the visibility of the new crescent moon with Schaefer's method, adjusted for the atmosphere.

solar_noon(location, date)

Returns solar noon for a given date and location as a UTC datetime

solstice(year, event, options \\ [])

Returns the datetime of either the June or December solstice, in UTC or a requested time zone.

sun_apparent_longitude(date)

Returns solar longitude for a given date. Solar longitude is used to identify the seasons.

sun_azimuth_elevation(location, date_time)

Returns the sun's azimuth and elevation as seen from a location at a date time.

sun_position_at(date_time)

Returns a Geo.PointZ.t/0 containing the right ascension and declination of the sun at a given date or date time.

sunrise(location, date, options \\ [])

Calculates the sunrise for a given location and date.

sunset(location, date, options \\ [])

Calculates the sunset for a given location and date.

Types

altitude()

@type altitude() :: float()

angle()

@type angle() :: number()

astronomical_units()

@type astronomical_units() :: number()

date()

@type date() :: Calendar.date() | Calendar.datetime()

degrees()

@type degrees() :: float()

kilometers()

@type kilometers() :: number()

latitude()

@type latitude() :: float()

location()

@type location() ::
  {longitude(), latitude()}
  | {longitude(), latitude(), altitude()}
  | Geo.Point.t()
  | Geo.PointZ.t()

longitude()

@type longitude() :: float()

meters()

@type meters() :: number()

method()

@type method() :: :odeh | :yallop | :schaefer

options()

@type options() :: keyword()

phase()

@type phase() :: angle()

radians()

@type radians() :: float()

Functions

date_time_lunar_phase_at_or_after(date_time, phase)

(since 0.5.0) 
@spec date_time_lunar_phase_at_or_after(date(), phase()) :: {:ok, DateTime.t()}

Returns the date time of a given lunar phase at or after a given date time or date.

Arguments

Returns

  • {:ok, date_time}, the UTC DateTime.t/0 at which the phase occurs.

Examples

iex> Astro.date_time_lunar_phase_at_or_after(~D[2021-08-01], Astro.Lunar.full_moon_phase())
{:ok, ~U[2021-08-22 12:02:02.816534Z]}

date_time_lunar_phase_at_or_before(date_time, phase)

(since 0.5.0) 
@spec date_time_lunar_phase_at_or_before(date(), phase()) :: {:ok, DateTime.t()}

Returns the date time of a given lunar phase at or before a given date time or date.

Arguments

Returns

  • {:ok, date_time}, the UTC DateTime.t/0 at which the phase occurs.

Examples

iex> Astro.date_time_lunar_phase_at_or_before(~D[2021-08-01], Astro.Lunar.new_moon_phase())
{:ok, ~U[2021-07-10 01:16:34.022607Z]}

date_time_new_moon_at_or_after(datetime)

(since 0.5.0) 
@spec date_time_new_moon_at_or_after(date()) :: {:ok, DateTime.t()}

Returns the date time of the new moon at or after a given date or date time.

Arguments

  • date_time is a DateTime or a Date or any struct that meets the requirements of t:Calendar.date or t:Calendar.datetime.

Returns

  • {:ok, date_time}, the UTC DateTime.t/0 at which the new moon occurs.

Examples

iex> Astro.date_time_new_moon_at_or_after(~D[2021-08-23])
{:ok, ~U[2021-09-07 00:51:44.267320Z]}

date_time_new_moon_before(date_time)

(since 0.5.0) 
@spec date_time_new_moon_before(date()) :: {:ok, DateTime.t()}

Returns the date time of the new moon before a given date or date time.

Arguments

Returns

  • {:ok, date_time}, the UTC DateTime.t/0 at which the new moon occurs.

Examples

iex> Astro.date_time_new_moon_before(~D[2021-08-23])
{:ok, ~U[2021-08-08 13:50:07.634598Z]}

date_time_new_moon_nearest(date_time)

(since 2.0.0) 
@spec date_time_new_moon_nearest(date()) :: {:ok, DateTime.t()}

Returns the date time of the new moon nearest to a given date or date time.

Arguments

Returns

  • {:ok, date_time}, the UTC DateTime.t/0 at which the new moon occurs.

Examples

iex> Astro.date_time_new_moon_nearest(~D[2021-08-23])
{:ok, ~U[2021-08-08 13:50:07.490242Z]}

duration_of_daylight(location, date)

(since 2.3.0) 
@spec duration_of_daylight(location(), Calendar.date()) ::
  {:ok, Duration.t()} | {:error, atom()}

Returns the duration of daylight for a given location on a given date as a Duration.t/0.

This is the same calculation as hours_of_daylight/2 but, because a Duration.t/0 is not bounded like a Time.t/0, it can represent a full 24 hours of daylight (returned as %Duration{hour: 24}) during the polar summer rather than capping at ~T[23:59:59].

Arguments

  • location is the observer's position as a {longitude, latitude} tuple in degrees, a Geo.Point.t/0, or a Geo.PointZ.t/0 that also carries an elevation in metres. Longitude comes first.

  • date is any Date.t/0 in the Gregorian calendar (for example, Calendar.ISO).

Returns

  • {:ok, duration} where duration is a Duration.t/0 between %Duration{} (no daylight) and %Duration{hour: 24} (24 hours of daylight).

  • {:error, reason} if the time zone for the location cannot be resolved.

Examples

iex> Astro.duration_of_daylight({151.20666584, -33.8559799094}, ~D[2019-12-10])
{:ok, %Duration{hour: 14, minute: 20, second: 51}}

# 24 hours of daylight in the polar summer, uncapped
iex> Astro.duration_of_daylight({-62.3481, 82.5018}, ~D[2019-06-07])
{:ok, %Duration{hour: 24}}

# No daylight in the polar winter
iex> Astro.duration_of_daylight({-62.3481, 82.5018}, ~D[2019-12-07])
{:ok, %Duration{}}

equinox(year, event, options \\ [])

@spec equinox(Calendar.year(), :march | :september, options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :year_out_of_range
     | :time_zone_not_found
     | :utc_only_time_zone_database
     | :invalid_time_zone_database}

Returns the datetime of either the March or September equinox, in UTC or a requested time zone.

Arguments

  • year is the gregorian year for which the equinox is to be calculated.

  • event is either :march or :september indicating which of the two annual equinox datetimes is required.

  • options is a keyword list of options.

Options

  • :time_zone is :utc (the default) or a time zone name such as "Asia/Tokyo". The equinox is one instant everywhere; the time zone decides the local date and time it is given in, and so the civil day it falls on.

  • :time_zone_database is the module implementing Calendar.TimeZoneDatabase in which a named time zone is looked up. The default is the configured database, Calendar.get_time_zone_database/0. UTC needs none.

Returns

  • {:ok, datetime}, the equinox in the requested time zone.

  • {:error, :year_out_of_range} if year is outside the supported range of 1000 CE to 3000 CE.

  • {:error, :time_zone_not_found} if the time zone is not known to the time zone database.

  • {:error, :utc_only_time_zone_database} if a time zone other than UTC is requested and no time zone database is configured.

  • {:error, :invalid_time_zone_database} if :time_zone_database is not a time zone database.

Examples

iex> {:ok, dt} = Astro.equinox 2019, :march
iex> DateTime.truncate(dt, :second)
~U[2019-03-20 21:58:28Z]
iex> {:ok, dt} = Astro.equinox 2019, :september
iex> DateTime.truncate(dt, :second)
~U[2019-09-23 07:49:52Z]
iex> Astro.equinox 900, :march
{:error, :year_out_of_range}

# The March 2019 equinox is on the 20th in UTC but the 21st in Tokyo
iex> {:ok, dt} = Astro.equinox(2019, :march, time_zone: "Asia/Tokyo")
iex> DateTime.to_date(dt)
~D[2019-03-21]

iex> Astro.equinox(2019, :march,
...>   time_zone: "Asia/Tokyo",
...>   time_zone_database: Calendar.UTCOnlyTimeZoneDatabase
...> )
{:error, :utc_only_time_zone_database}

Notes

This equinox calculation is expected to be accurate to within 2 minutes for the years 1000 CE to 3000 CE.

An equinox is commonly regarded as the instant of time when the plane of earth's equator passes through the center of the Sun. This occurs twice each year: around 20 March and 23 September.

In other words, it is the moment at which the center of the visible sun is directly above the equator.

hours_of_daylight(location, date)

@spec hours_of_daylight(location(), Calendar.date()) ::
  {:ok, Time.t()} | {:error, atom()}

Returns the number of hours of daylight for a given location on a given date.

On Elixir 1.17+, the function duration_of_daylight/2 is recommended over this function since it returns a Duration.t/0 which can represent a full 24 hours of daylight.

Arguments

  • location is the observer's position as a {longitude, latitude} tuple in degrees, a Geo.Point.t/0, or a Geo.PointZ.t/0 that also carries an elevation in metres. Longitude comes first.

  • date is any Date.t/0 in the Gregorian calendar (for example, Calendar.ISO).

Returns

  • {:ok, time} where time is a Time.t(). The maximum value is ~T[23:59:59], representing 24 hours of daylight (a Time.t() cannot hold 24:00:00).

  • {:error, reason} if the time zone for the location cannot be resolved.

Examples

iex> Astro.hours_of_daylight({151.20666584, -33.8559799094}, ~D[2019-12-10])
{:ok, ~T[14:20:51]}

# No sunset in summer
iex> Astro.hours_of_daylight({-62.3481, 82.5018}, ~D[2019-06-07])
{:ok, ~T[23:59:59]}

# No sunrise in winter
iex> Astro.hours_of_daylight({-62.3481, 82.5018}, ~D[2019-12-07])
{:ok, ~T[00:00:00]}

Notes

Daylight is measured as the total time the Sun is above the horizon during the local calendar day, so the result is correct regardless of whether sunrise precedes sunset.

In latitudes above the polar circles (approximately +/- 66.5631 degrees) there will be no hours of daylight in winter and 24 hours of daylight in summer. Just below the polar circles, near the solstice, a single calendar day can contain a sunset (shortly after midnight) followed by a sunrise (a few hours later); such days are handled correctly and report close to, but less than, 24 hours.

illuminated_fraction_of_moon_at(date_time)

(since 0.6.0) 
@spec illuminated_fraction_of_moon_at(date()) :: number()

Returns the illumination of the moon as a float for a given date or date time.

Arguments

Returns

  • a float value between 0.0 and 1.0 representing the fractional illumination of the moon.

Examples

iex> fraction = Astro.illuminated_fraction_of_moon_at(~D[2017-03-16])
iex> Float.round(fraction, 4)
0.8884

iex> fraction = Astro.illuminated_fraction_of_moon_at(~D[1992-04-12])
iex> Float.round(fraction, 4)
0.6786

is_lunar_phase(phase)

(macro)

Guards that a value is a lunar phase angle.

Arguments

  • phase is the value to test.

Returns

  • true if phase is a number from 0.0 to 360.0 inclusive, otherwise false.

Examples

iex> require Astro
iex> Astro.is_lunar_phase(90.0)
true
iex> Astro.is_lunar_phase(400.0)
false

lunar_phase_at(date_time)

(since 0.5.0) 
@spec lunar_phase_at(date()) :: phase()

Returns the lunar phase as a float number of degrees at a given date or date time.

Arguments

Returns

  • the lunar phase as a float number of degrees.

Examples

iex> Astro.lunar_phase_at ~U[2021-08-22 12:02:02.816534Z]
180.00004404669988

iex> Astro.lunar_phase_at(~U[2021-07-10 01:16:34.022607Z])
3.6600909621461326e-6

lunar_phase_emoji(phase)

@spec lunar_phase_emoji(phase()) :: String.t()

Returns the moon phase as a UTF8 binary representing an emoji of the moon phase.

Arguments

  • phase is a moon phase between 0.0 and 360.0.

Returns

Examples

iex> Astro.lunar_phase_emoji 0
"🌑"
iex> Astro.lunar_phase_emoji 45
"🌒"
iex> Astro.lunar_phase_emoji 90
"🌓"
iex> Astro.lunar_phase_emoji 135
"🌔"
iex> Astro.lunar_phase_emoji 180
"🌕"
iex> Astro.lunar_phase_emoji 245
"🌖"
iex> Astro.lunar_phase_emoji 270
"🌗"
iex> Astro.lunar_phase_emoji 320
"🌘"
iex> Astro.lunar_phase_emoji 360
"🌑"

iex> ~U[2021-08-22 12:02:02.816534Z]
...> |> Astro.lunar_phase_at()
...> |> Astro.lunar_phase_emoji()
"🌕"

moon_position_at(date_time)

(since 0.6.0) 
@spec moon_position_at(date()) :: Geo.PointZ.t()

Returns a Geo.PointZ.t/0 containing the right ascension and declination of the moon at a given date or date time.

Arguments

Returns

  • a Geo.PointZ.t/0 struct with coordinates {right_ascension, declination, distance} with properties %{reference: :celestial, object: :moon} distance is in meters.

Examples

iex> Astro.moon_position_at(~D[1992-04-12]) |> Astro.Location.round(6)
%Geo.PointZ{
  coordinates: {134.69343, 13.766512, 368409007.322444},
  properties: %{object: :moon, reference: :celestial},
  srid: nil
}

moonrise(location, date, options \\ default_options())

(since 2.0.0) 
@spec moonrise(location(), date(), options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :no_time
     | :invalid_limb
     | :invalid_interpolation
     | :time_zone_not_found
     | :time_zone_not_resolved
     | :tz_world_data_not_installed
     | :utc_only_time_zone_database
     | :not_found}

Returns the moonrise for a given location and date.

The moonrise is the moment the upper limb of the Moon appears above the horizon, found from the JPL DE440s ephemeris with full topocentric correction.

Arguments

Options

  • :limb is the part of the Moon's disk that defines the event.

    • :upper, the default, puts the upper limb on the apparent horizon, the USNO standard. The event threshold is −(34′ refraction + semi-diameter).

    • :center puts the centre of the disk on the apparent horizon. The event threshold is −34′ of refraction only.

  • :interpolation is how the Moon's position is evaluated while the event is bisected.

    • :direct, the default, evaluates the JPL ephemeris at every step.

    • :lagrange interpolates the geocentric position quadratically from three points, as Meeus Ch. 15 does.

  • :time_zone is the time zone of the returned date time: :default, the time zone of the location, which is the default; :utc; or a time zone name.

  • :time_zone_database is the module implementing the Calendar.TimeZoneDatabase behaviour. The default is the configured Elixir time zone database.

  • :time_zone_resolver is a 1-arity function that receives a %Geo.Point{coordinates: {lng, lat}} and returns {:ok, time_zone_name} or {:error, reason}. The default is TzWorld.timezone_at/1 when :tz_world is a dependency.

Returns

  • {:ok, date_time} where date_time is the moonrise in the requested time zone.

  • {:error, :no_time} if the Moon does not rise on that date at that location, as it can stay below the horizon for a whole day.

  • {:error, :invalid_limb} if :limb is not :upper or :center.

  • {:error, :invalid_interpolation} if :interpolation is not :direct or :lagrange.

  • {:error, :time_zone_not_found} if the requested time zone is unknown.

  • {:error, :time_zone_not_resolved} if no time zone can be resolved for the location, which happens when :tz_world is not a dependency and no :time_zone_resolver is given.

  • {:error, :tz_world_data_not_installed} if :tz_world is a dependency but its data has not been installed. Run mix tz_world.update to install it.

  • {:error, :utc_only_time_zone_database} if the moonrise is requested in a time zone other than UTC and no time zone database is configured.

  • {:error, :not_found} if the date is outside the loaded ephemeris.

Examples

iex> {:ok, date_time} = Astro.moonrise({151.20666584, -33.8559799094}, ~D[2019-12-04])
iex> date_time
#DateTime<2019-12-04 12:20:56.695846+11:00 AEDT Australia/Sydney>

iex> Astro.moonrise({-62.3481, 82.5018}, ~D[2024-01-01])
{:error, :no_time}

moonset(location, date, options \\ default_options())

(since 2.0.0) 
@spec moonset(location(), date(), options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :no_time
     | :invalid_limb
     | :invalid_interpolation
     | :time_zone_not_found
     | :time_zone_not_resolved
     | :tz_world_data_not_installed
     | :utc_only_time_zone_database
     | :not_found}

Returns the moonset for a given location and date.

The moonset is the moment the upper limb of the Moon disappears below the horizon, found from the JPL DE440s ephemeris with full topocentric correction.

Arguments

Options

  • :limb is the part of the Moon's disk that defines the event.

    • :upper, the default, puts the upper limb on the apparent horizon, the USNO standard. The event threshold is −(34′ refraction + semi-diameter).

    • :center puts the centre of the disk on the apparent horizon. The event threshold is −34′ of refraction only.

  • :interpolation is how the Moon's position is evaluated while the event is bisected.

    • :direct, the default, evaluates the JPL ephemeris at every step.

    • :lagrange interpolates the geocentric position quadratically from three points, as Meeus Ch. 15 does.

  • :time_zone is the time zone of the returned date time: :default, the time zone of the location, which is the default; :utc; or a time zone name.

  • :time_zone_database is the module implementing the Calendar.TimeZoneDatabase behaviour. The default is the configured Elixir time zone database.

  • :time_zone_resolver is a 1-arity function that receives a %Geo.Point{coordinates: {lng, lat}} and returns {:ok, time_zone_name} or {:error, reason}. The default is TzWorld.timezone_at/1 when :tz_world is a dependency.

Returns

  • {:ok, date_time} where date_time is the moonset in the requested time zone.

  • {:error, :no_time} if the Moon does not set on that date at that location, as it can stay above the horizon for a whole day.

  • {:error, :invalid_limb} if :limb is not :upper or :center.

  • {:error, :invalid_interpolation} if :interpolation is not :direct or :lagrange.

  • {:error, :time_zone_not_found} if the requested time zone is unknown.

  • {:error, :time_zone_not_resolved} if no time zone can be resolved for the location, which happens when :tz_world is not a dependency and no :time_zone_resolver is given.

  • {:error, :tz_world_data_not_installed} if :tz_world is a dependency but its data has not been installed. Run mix tz_world.update to install it.

  • {:error, :utc_only_time_zone_database} if the moonset is requested in a time zone other than UTC and no time zone database is configured.

  • {:error, :not_found} if the date is outside the loaded ephemeris.

Examples

iex> {:ok, date_time} = Astro.moonset({151.20666584, -33.8559799094}, ~D[2019-12-04])
iex> date_time
#DateTime<2019-12-04 01:13:28.212125+11:00 AEDT Australia/Sydney>

iex> Astro.moonset({-62.3481, 82.5018}, ~D[2024-01-01])
{:error, :no_time}

new_visible_crescent(location, date, method \\ :odeh)

(since 2.1.0) 
@spec new_visible_crescent(location(), date(), method()) ::
  {:ok, Astro.Lunar.CrescentVisibility.visibility()}
  | {:error, :no_sunset | :not_found}

Predicts the visibility of the new crescent moon at a given location on a given date using one of three published criteria.

At the optimal observation time after sunset, the function evaluates the geometric and photometric conditions to classify the crescent into one of five visibility categories.

Arguments

  • location is the observer's position as a {longitude, latitude} tuple in degrees, a Geo.Point.t/0, or a Geo.PointZ.t/0 that also carries an elevation in metres. Longitude comes first.

  • date is a Date.t/0 or DateTime.t/0 indicating the evening on which crescent visibility is to be evaluated.

  • method selects the prediction criterion. Default :odeh.

    • :odeh — Odeh (2006). Empirical criterion based on 737 observations. Uses topocentric ARCV with a Danjon limit of 6.4°. The most widely used modern criterion.

    • :yallop — Yallop (1997). Empirical criterion based on 295 observations. Uses geocentric ARCV. The original single-parameter approach that Odeh later refined.

    • :schaefer — Schaefer (1988/2000). Physics-based model computing the contrast between crescent brightness and twilight sky brightness against the human contrast detection threshold. The best observation time is found by scanning from sunset to moonset.

Options

When method is :schaefer, the following options are accepted as an optional fourth argument (a keyword list):

  • :extinction — V-band zenith extinction coefficient. Default 0.172 (clean sea-level site). Typical values: 0.12 (high mountain), 0.17 (sea level), 0.25 (hazy conditions).

Returns

  • {:ok, visibility} where visibility is one of:

    • :A — Visible to the naked eye.

    • :B — Visible with optical aid.

    • :C — May need optical aid.

    • :D — Not visible with optical aid.

    • :E — Not visible.

  • {:error, :no_sunset} if no sunset occurs on the given date at the given location (e.g. polar day).

  • {:error, :not_found} if the date is outside the range covered by the installed ephemeris.

Method comparison

AspectYallop (1997)Odeh (2006)Schaefer (1988/2000)
BasisEmpirical polynomialEmpirical polynomialPhysical model
Observations295737N/A (theory)
ARCV typeGeocentricTopocentricN/A
Best timeSunset + 4/9 lagSunset + 4/9 lagScanned (max Rs)
AtmosphereNot modelledNot modelledExtinction coefficient

Examples

iex> location = {-0.1275, 51.5072}
iex> Astro.new_visible_crescent(location, ~D[2025-03-31])
{:ok, :A}

iex> location = {-0.1275, 51.5072}
iex> Astro.new_visible_crescent(location, ~D[2025-03-31], :yallop)
{:ok, :A}

new_visible_crescent(location, date, method, options)

(since 2.1.0) 
@spec new_visible_crescent(location(), date(), :schaefer, keyword()) ::
  {:ok, Astro.Lunar.CrescentVisibility.visibility()}
  | {:error, :no_sunset | :not_found}

Predicts the visibility of the new crescent moon with Schaefer's method, adjusted for the atmosphere.

This is new_visible_crescent/3 with the :schaefer method, taking the same location and date and returning the same classes. See new_visible_crescent/3 for how the methods compare.

Arguments

  • location is the observer's position as a {longitude, latitude} tuple in degrees, a Geo.Point.t/0, or a Geo.PointZ.t/0 that also carries an elevation in metres. Longitude comes first.

  • date is a Date.t/0 or DateTime.t/0 indicating the evening on which crescent visibility is to be evaluated.

  • method is :schaefer, the only method that takes options.

  • options is a keyword list of options.

Options

  • :extinction is the V-band zenith extinction coefficient. The default is 0.172, a clean sea-level site. Typical values are 0.12 on a high mountain, 0.17 at sea level and 0.25 in hazy conditions.

Returns

  • {:ok, visibility} where visibility is one of the classes :A to :E described in new_visible_crescent/3.

  • {:error, :no_sunset} if no sunset occurs on the given date at the given location.

  • {:error, :not_found} if the date is outside the range covered by the installed ephemeris.

Examples

iex> location = {39.8579, 21.3891}
iex> Astro.new_visible_crescent(location, ~D[2025-03-31], :schaefer, extinction: 0.25)
{:ok, :A}

solar_noon(location, date)

@spec solar_noon(location(), Calendar.date()) ::
  {:ok, DateTime.t()}
  | {:error, :invalid_date | :incompatible_calendars | :invalid_time}

Returns solar noon for a given date and location as a UTC datetime

Arguments

  • location is the observer's position as a {longitude, latitude} tuple in degrees, a Geo.Point.t/0, or a Geo.PointZ.t/0 that also carries an elevation in metres. Longitude comes first.

  • date is any Calendar.date/0. A date in a calendar other than Calendar.ISO is converted to its ISO date first.

Returns

  • {:ok, datetime}, the UTC datetime of solar noon at the given location on the given date.

  • {:error, :invalid_date} if date is not a valid date in its calendar.

  • {:error, :incompatible_calendars} if its calendar cannot be converted to Calendar.ISO.

Examples

iex> Astro.solar_noon {151.20666584, -33.8559799094}, ~D[2019-12-06]
{:ok, ~U[2019-12-06 01:45:42Z]}

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 doesn't happen at 12 o'clock.

At solar noon, the Sun reaches its highest position in the sky as it passes the local meridian.

solstice(year, event, options \\ [])

@spec solstice(Calendar.year(), :june | :december, options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :year_out_of_range
     | :time_zone_not_found
     | :utc_only_time_zone_database
     | :invalid_time_zone_database}

Returns the datetime of either the June or December solstice, in UTC or a requested time zone.

Arguments

  • year is the gregorian year for which the solstice is to be calculated.

  • event is either :june or :december indicating which of the two annual solstice datetimes is required.

  • options is a keyword list of options.

Options

  • :time_zone is :utc (the default) or a time zone name such as "Asia/Tokyo". The solstice is one instant everywhere; the time zone decides the local date and time it is given in, and so the civil day it falls on.

  • :time_zone_database is the module implementing Calendar.TimeZoneDatabase in which a named time zone is looked up. The default is the configured database, Calendar.get_time_zone_database/0. UTC needs none.

Returns

  • {:ok, datetime}, the solstice in the requested time zone.

  • {:error, :year_out_of_range} if year is outside the supported range of 1000 CE to 3000 CE.

  • {:error, :time_zone_not_found} if the time zone is not known to the time zone database.

  • {:error, :utc_only_time_zone_database} if a time zone other than UTC is requested and no time zone database is configured.

  • {:error, :invalid_time_zone_database} if :time_zone_database is not a time zone database.

Examples

iex> {:ok, dt} = Astro.solstice 2019, :december
iex> DateTime.truncate(dt, :second)
~U[2019-12-22 04:19:19Z]
iex> {:ok, dt} = Astro.solstice 2019, :june
iex> DateTime.truncate(dt, :second)
~U[2019-06-21 15:54:07Z]
iex> Astro.solstice 3500, :june
{:error, :year_out_of_range}

# The June 2021 solstice is on the 21st in UTC but the 20th in Santiago
iex> {:ok, dt} = Astro.solstice(2021, :june, time_zone: "America/Santiago")
iex> DateTime.to_date(dt)
~D[2021-06-20]

Notes

This solstice calculation is expected to be accurate to within 2 minutes for the years 1000 CE to 3000 CE.

A solstice is an event occurring when the Sun appears to reach its most northerly or southerly excursion relative to the celestial equator on the celestial sphere. Two solstices occur annually, around June 21 and December 21.

The seasons of the year are determined by reference to both the solstices and the equinoxes.

The day of a solstice in either hemisphere has either the most sunlight of the year (summer solstice) or the least sunlight of the year (winter solstice) for any place other than the Equator.

Alternative terms, with no ambiguity as to which hemisphere is the context, are "June solstice" and "December solstice", referring to the months in which they take place every year.

sun_apparent_longitude(date)

@spec sun_apparent_longitude(Calendar.date()) :: degrees()

Returns solar longitude for a given date. Solar longitude is used to identify the seasons.

Arguments

Returns

  • a float number of degrees between 0 and 360 representing the solar longitude on date.

Examples

iex> Astro.sun_apparent_longitude ~D[2019-03-21]
0.08035853207991295
iex> Astro.sun_apparent_longitude ~D[2019-06-22]
90.32130455695378
iex> Astro.sun_apparent_longitude ~D[2019-09-23]
179.68691978440197
iex> Astro.sun_apparent_longitude ~D[2019-12-23]
270.83941087483504

Notes

Solar longitude (the ecliptic longitude of the sun) in effect describes the position of the earth in its orbit, being zero at the moment of the March 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) we are in, but without the inaccuracies of a calendar date, which is perturbed by leap years and calendar imperfections.

sun_azimuth_elevation(location, date_time)

(since 0.11.0) 
@spec sun_azimuth_elevation(location(), Calendar.datetime()) ::
  {azimuth :: float(), altitude :: float()}

Returns the sun's azimuth and elevation as seen from a location at a date time.

Arguments

Returns

  • {azimuth, elevation} in degrees. Azimuth is measured clockwise from north, and elevation above the horizon.

Examples

iex> Astro.sun_azimuth_elevation({151.20666584, -33.8559799094}, ~U[2019-12-04 02:00:00Z])
{343.33472178197934, 77.8645848744289}

sun_position_at(date_time)

(since 0.6.0) 
@spec sun_position_at(date()) :: Geo.PointZ.t()

Returns a Geo.PointZ.t/0 containing the right ascension and declination of the sun at a given date or date time.

Arguments

Returns

  • a Geo.PointZ.t/0 struct with coordinates {right_ascension, declination, distance} with properties %{reference: :celestial, object: :sun}. distance is in meters.

Examples

iex> Astro.sun_position_at(~D[1992-10-13])
%Geo.PointZ{
  coordinates: {-161.61854343627374, -7.785324796344723, 149169604737.93973},
  properties: %{object: :sun, reference: :celestial},
  srid: nil
}

sunrise(location, date, options \\ [])

@spec sunrise(location(), date(), options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :no_time
     | :invalid_solar_elevation
     | :time_zone_not_found
     | :time_zone_not_resolved
     | :tz_world_data_not_installed
     | :utc_only_time_zone_database
     | :not_found}

Calculates the sunrise for a given location and date.

Sunrise is the moment when the upper limb of the sun appears on the horizon in the morning.

Arguments

Options

  • :solar_elevation is the zenith angle of the sun, in degrees, that marks the sunrise, or one of the names below. The default is :geometric.

    • :geometric is 90°, corrected for refraction and the sun's apparent radius so that it matches the moment the upper limb appears to touch the horizon.

    • :civil is 96°. The sun is below the horizon but there is generally enough natural light for most outdoor activities.

    • :nautical is 102°. The horizon is barely visible, and the moon and stars can still be used for navigation.

    • :astronomical is 108°. Beyond this, astronomical observation becomes impractical.

  • :time_zone is the time zone of the returned date time: :default, the time zone of the location, which is the default; :utc; or a time zone name.

  • :time_zone_database is the module implementing the Calendar.TimeZoneDatabase behaviour. The default is the configured Elixir time zone database.

  • :time_zone_resolver is a 1-arity function that receives a %Geo.Point{coordinates: {lng, lat}} and returns {:ok, time_zone_name} or {:error, reason}. The default is TzWorld.timezone_at/1 when :tz_world is a dependency.

Returns

  • {:ok, date_time} where date_time is the sunrise in the requested time zone.

  • {:error, :no_time} if there is no sunrise on that date at that location, as happens at very high latitudes in summer and winter.

  • {:error, :invalid_solar_elevation} if :solar_elevation is neither a number nor one of the names above.

  • {:error, :time_zone_not_found} if the requested time zone is unknown.

  • {:error, :time_zone_not_resolved} if no time zone can be resolved for the location, which happens when :tz_world is not a dependency and no :time_zone_resolver is given.

  • {:error, :tz_world_data_not_installed} if :tz_world is a dependency but its data has not been installed. Run mix tz_world.update to install it.

  • {:error, :utc_only_time_zone_database} if the sunrise is requested in a time zone other than UTC and no time zone database is configured.

  • {:error, :not_found} if the date is outside the loaded ephemeris.

Examples

iex> {:ok, date_time} = Astro.sunrise({151.20666584, -33.8559799094}, ~D[2019-12-04])
iex> date_time
#DateTime<2019-12-04 05:37:08.672884+11:00 AEDT Australia/Sydney>

iex> Astro.sunrise({-62.3481, 82.5018}, ~D[2019-12-04])
{:error, :no_time}

sunset(location, date, options \\ [])

@spec sunset(location(), date(), options()) ::
  {:ok, DateTime.t()}
  | {:error,
     :no_time
     | :invalid_solar_elevation
     | :time_zone_not_found
     | :time_zone_not_resolved
     | :tz_world_data_not_installed
     | :utc_only_time_zone_database
     | :not_found}

Calculates the sunset for a given location and date.

Sunset is the moment when the upper limb of the sun disappears below the horizon in the evening.

Arguments

Options

  • :solar_elevation is the zenith angle of the sun, in degrees, that marks the sunset, or one of the names below. The default is :geometric.

    • :geometric is 90°, corrected for refraction and the sun's apparent radius so that it matches the moment the upper limb appears to touch the horizon.

    • :civil is 96°. The sun is below the horizon but there is generally enough natural light for most outdoor activities.

    • :nautical is 102°. The horizon is barely visible, and the moon and stars can still be used for navigation.

    • :astronomical is 108°. Beyond this, astronomical observation becomes impractical.

  • :time_zone is the time zone of the returned date time: :default, the time zone of the location, which is the default; :utc; or a time zone name.

  • :time_zone_database is the module implementing the Calendar.TimeZoneDatabase behaviour. The default is the configured Elixir time zone database.

  • :time_zone_resolver is a 1-arity function that receives a %Geo.Point{coordinates: {lng, lat}} and returns {:ok, time_zone_name} or {:error, reason}. The default is TzWorld.timezone_at/1 when :tz_world is a dependency.

Returns

  • {:ok, date_time} where date_time is the sunset in the requested time zone.

  • {:error, :no_time} if there is no sunset on that date at that location, as happens at very high latitudes in summer and winter.

  • {:error, :invalid_solar_elevation} if :solar_elevation is neither a number nor one of the names above.

  • {:error, :time_zone_not_found} if the requested time zone is unknown.

  • {:error, :time_zone_not_resolved} if no time zone can be resolved for the location, which happens when :tz_world is not a dependency and no :time_zone_resolver is given.

  • {:error, :tz_world_data_not_installed} if :tz_world is a dependency but its data has not been installed. Run mix tz_world.update to install it.

  • {:error, :utc_only_time_zone_database} if the sunset is requested in a time zone other than UTC and no time zone database is configured.

  • {:error, :not_found} if the date is outside the loaded ephemeris.

Examples

iex> {:ok, date_time} = Astro.sunset({151.20666584, -33.8559799094}, ~D[2019-12-04])
iex> date_time
#DateTime<2019-12-04 19:53:20.995687+11:00 AEDT Australia/Sydney>

iex> Astro.sunset({-62.3481, 82.5018}, ~D[2019-12-04])
{:error, :no_time}