@spec first_visible_crescent_on_or_after(Geo.PointZ.t(), integer(), atom(), keyword()) ::
  {:ok, integer()} | {:error, atom()}

Returns the evening of the next first sighting of a new crescent on or after an evening.

See first_visible_crescent_on_or_before/4 for the first sighting.

Arguments

• location is a Geo.PointZ.t/0 struct (already normalized).

• day is the evening as an integer number of days since 0000-01-01.

• method is :odeh, :yallop or :schaefer.

• options is a keyword list of options, as for first_visible_crescent_on_or_before/4.

Returns

• {:ok, day}, the evening as an integer number of days since 0000-01-01.

• {:error, :no_visible_crescent} if a lunation's crescent is not seen within 30 evenings of its new moon.

Raises ArgumentError for a day more than 50,000 years from J2000.

Examples

iex> mecca = %Geo.PointZ{coordinates: {39.8262, 21.4225, 277.0}}
iex> day = Date.to_gregorian_days(~D[2024-12-20])
iex> {:ok, evening} = Astro.Lunar.CrescentVisibility.first_visible_crescent_on_or_after(mecca, day, :odeh)
iex> Date.from_gregorian_days(evening)
~D[2025-01-01]

@spec first_visible_crescent_on_or_before(
  Geo.PointZ.t(),
  integer(),
  atom(),
  keyword()
) ::
  {:ok, integer()} | {:error, atom()}

Returns the evening of the last first sighting of a new crescent on or before an evening.

A lunation's crescent is first seen on the first evening, from the evening before the day of its new moon, on which method classes it visible. This is the latest such evening on or before day: the evening a lunar month that begins at first sighting began on.

Arguments

• location is a Geo.PointZ.t/0 struct (already normalized).

• day is the evening as an integer number of days since 0000-01-01.

• method is :odeh, :yallop or :schaefer.

• options is a keyword list of options.

Options

• :visible is the list of categories that count as a sighting. The default is [:A, :B, :C].

• :utc_offset and :extinction are as for the criteria.

Returns

• {:ok, day}, the evening as an integer number of days since 0000-01-01.

• {:error, :no_visible_crescent} if a lunation's crescent is not seen within 30 evenings of its new moon, as at high latitudes.

Raises ArgumentError for a day more than 50,000 years from J2000.

Examples

iex> mecca = %Geo.PointZ{coordinates: {39.8262, 21.4225, 277.0}}
iex> day = Date.to_gregorian_days(~D[2024-12-20])
iex> {:ok, evening} = Astro.Lunar.CrescentVisibility.first_visible_crescent_on_or_before(mecca, day, :odeh)
iex> Date.from_gregorian_days(evening)
~D[2024-12-02]

@spec odeh_new_visible_crescent(Geo.PointZ.t(), Astro.Time.moment(), keyword()) ::
  {:ok, visibility()} | {:error, atom()}

Computes the Odeh (2004) visibility criterion for the new crescent moon.

Uses topocentric ARCV, the same polynomial family as Yallop with an updated intercept (7.1651), and enforces a Danjon limit of 6.4°.

Arguments

• location is a Geo.PointZ.t/0 struct (already normalized).

• moment is a Astro.Time.moment/0 representing the date.

Returns

• {:ok, visibility} where visibility is one of :A, :B, :C, :D, or :E.

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

Examples

iex> mecca = %Geo.PointZ{coordinates: {39.8579, 21.3891, 0.0}}
iex> Astro.Lunar.CrescentVisibility.odeh_new_visible_crescent(mecca, Astro.Time.date_time_to_moment(~D[2024-12-02]))
{:ok, :A}
iex> Astro.Lunar.CrescentVisibility.odeh_new_visible_crescent(mecca, Astro.Time.date_time_to_moment(~D[2024-11-01]))
{:ok, :E}

@spec schaefer_new_visible_crescent(Geo.PointZ.t(), Astro.Time.moment(), keyword()) ::
  {:ok, visibility()} | {:error, atom()}

Computes the Schaefer (1988/2000) visibility criterion for the new crescent moon.

This physics-based model computes the contrast between the crescent moon's brightness and the twilight sky brightness, comparing against the human contrast detection threshold. The best observation time is found by scanning from sunset to moonset.

Arguments

• location is a Geo.PointZ.t/0 struct (already normalized).

• moment is a Astro.Time.moment/0 representing the date.

• 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 :A, :B, :C, :D, or :E.

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

Examples

iex> mecca = %Geo.PointZ{coordinates: {39.8579, 21.3891, 0.0}}
iex> moment = Astro.Time.date_time_to_moment(~D[2024-12-02])
iex> Astro.Lunar.CrescentVisibility.schaefer_new_visible_crescent(mecca, moment, extinction: 0.25)
{:ok, :A}

@spec yallop_new_visible_crescent(Geo.PointZ.t(), Astro.Time.moment(), keyword()) ::
  {:ok, visibility()} | {:error, atom()}

Computes the Yallop (1997) visibility criterion for the new crescent moon.

Uses geocentric ARCV and the polynomial fit to Bruin's visibility curves.

Arguments

• location is a Geo.PointZ.t/0 struct (already normalized).

• moment is a Astro.Time.moment/0 representing the date.

Returns

• {:ok, visibility} where visibility is one of :A, :B, :C, :D, or :E.

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

Examples

iex> mecca = %Geo.PointZ{coordinates: {39.8579, 21.3891, 0.0}}
iex> Astro.Lunar.CrescentVisibility.yallop_new_visible_crescent(mecca, Astro.Time.date_time_to_moment(~D[2024-12-02]))
{:ok, :A}
iex> Astro.Lunar.CrescentVisibility.yallop_new_visible_crescent(mecca, Astro.Time.date_time_to_moment(~D[2024-11-01]))
{:ok, :E}