GreenCal.Day.Moon (GreenCal v0.2.0)

Lunar part of a GreenCal.Day.

Four fields carry a geocentric event instant when the day holds one, and nil otherwise: :phase_change, :apsis, :node and :standstill. They are the canonical home of those instants — the matching GreenCal.Day :events entries are a view of them, and GreenCal.lunar_events/2 is the same computation over a whole range. All three come from the same finders in GreenCal.Astro, so they cannot report different times.

They are always computed, so nil states a fact about the sky — this day holds no such event — and never a fact about how the day was built.

At most one of each per day: the shortest of these cycles is 7.4 days (successive principal phases), the longest 13.8 (apsides).

Note :phase and :phase_change answer different questions. :phase names the day — the eight-sector name at sampled_at, so a day reads :full_moon for the whole 24 h around the exact instant. :phase_change is the instant the Moon crosses into a new principal phase, present only on the day it falls.

day.moon.phase         #=> :full_moon
day.moon.phase_change  #=> %{type: :full_moon, at: ~U[...], eclipse: :none}

Summary

Types

t()

The three trend fields are the three independent lunar cycles: :trend follows the declination (ascending/descending — the cycle biodynamic sowing calendars use), :illumination_trend the phase (waxing/waning), :distance_trend the orbit (approaching/receding).

Types

t()

@type t() :: %GreenCal.Day.Moon{
  apsis:
    %{type: :perigee | :apogee, at: DateTime.t(), distance_km: float()} | nil,
  declination: float(),
  distance_km: float(),
  distance_trend: :approaching | :receding,
  ecliptic_latitude: float(),
  elongation: float(),
  illuminated_fraction: float(),
  illumination_trend: :waxing | :waning,
  node: %{type: :ascending | :descending, at: DateTime.t()} | nil,
  phase:
    :new_moon
    | :waxing_crescent
    | :first_quarter
    | :waxing_gibbous
    | :full_moon
    | :waning_gibbous
    | :last_quarter
    | :waning_crescent,
  phase_change:
    %{
      type: :new_moon | :first_quarter | :full_moon | :last_quarter,
      at: DateTime.t(),
      eclipse: :none | :possible | :likely
    }
    | nil,
  rise: DateTime.t() | nil,
  set: DateTime.t() | nil,
  standstill:
    %{
      type: :northernmost | :southernmost,
      at: DateTime.t(),
      declination: float()
    }
    | nil,
  state: :normal | :always_above | :always_below,
  transit: DateTime.t() | nil,
  trend: :ascending | :descending
}