GreenCal 🌱🌙

Agricultural sun & moon calendar for Elixir — pure arithmetic, zero dependencies, no time zone database required.

From a geolocation, a date (or a period) and optionally an elevation, GreenCal computes:

• Sun — sunrise, solar noon, sunset, day length, rise/set azimuths, civil / nautical / astronomical twilights (Meeus ch. 25, ~1 s of time)
• Moon — moonrise, moonset, transit, phase, illuminated fraction, distance (full Meeus ch. 47 series, validated against example 47.a to 0.13″ in longitude)
• The three independent lunar cycles used by agricultural calendars: waxing/waning (illumination), ascending/descending (declination — the one biodynamic sowing calendars actually use), perigee/apogee (distance)
• Exact instants of everything a printed calendar marks with a symbol (GreenCal.lunar_timeline/2, or GreenCal.lunar_events/2 for the same data grouped by family): phases (with an eclipse screening flag), perigees/apogees, node crossings, and lunar standstills (the exact ascending → descending flips)
• The day as one chronology — day.events lists everything that happens, sorted, from dawn to the exact full moon, so "what happens today" needs no assembling
• The constellation the Moon stands in — equal-sector sidereal zodiac (Lahiri) by default, or the real unequal IAU boundaries (13 constellations, Ophiuchus included) with boundaries: :iau, the convention of printed biodynamic calendars — plus its element (fire/earth/air/water) and the traditionally associated plant organ (fruit/root/flower/leaf)

Rise/set times are found by numeric search (sampling + bisection) rather than the closed-form hour-angle formula, so moonrise is accurate too (the closed form can be 15+ minutes off for the Moon) and polar edge cases (midnight sun, polar night, "no moonrise today") are reported explicitly instead of producing garbage. ΔT (TT − UT) uses observed IERS values on 2000–2026, the Espenak & Meeus polynomials before that, and a documented hold-then-bridge extrapolation after — so results don't drift over the years.

Usage

loc = {48.8566, 2.3522}   # Paris; {lat, lon}, East positive

day = GreenCal.day(loc, ~D[2026-06-21], elevation: 35.0)

day.sun.rise                #=> ~U[2026-06-21 03:45:21Z]
day.sun.day_length_minutes  #=> 974.1
day.twilight.dawn           #=> ~U[2026-06-21 03:04:16Z]
day.moon.phase              #=> :first_quarter
day.moon.trend              #=> :descending   (declination — sowing calendars)
day.moon.illumination_trend #=> :waxing       (independent cycle!)
day.constellation           #=> "Virgo"
day.organ                   #=> :root

# Everything that happens that day, in order — one uniform shape, no
# optional keys, already sorted:
for e <- day.events, do: {e.family, e.type, e.at}
#=> [{:twilight, :dawn, ...}, {:sun, :rise, ...}, {:moon, :transit, ...},
#    {:phase, :first_quarter, ...}, {:sun, :set, ...}, ...]

# A whole month, with local times (needs a tz database, e.g. tzdata):
GreenCal.calendar(loc, Date.range(~D[2026-07-01], ~D[2026-07-31]),
  time_zone: "Europe/Paris")

# Spread a year over the schedulers:
GreenCal.calendar(loc, Date.range(~D[2026-01-01], ~D[2026-12-31]), parallel: true)

# Exact instants of phases, apsides, nodes and standstills (geocentric):
GreenCal.lunar_timeline(Date.range(~D[2026-08-01], ~D[2026-08-31]))
#=> [%{family: :phase, type: :last_quarter, at: ~U[2026-08-06 02:21:49Z],
#      eclipse: :none}, ...]

The seven event families split along a line worth knowing: :sun, :twilight and :moon are topocentric (they depend on where you stand), while :phase, :apsis, :node and :standstill are geocentric — the same instants everywhere on Earth. Computing several places at once, only the first three change: get the rest once from GreenCal.lunar_timeline/2 instead of once per place.

The low-level astronomy is public too — GreenCal.Astro (UT-facing facade), GreenCal.Astro.Sun, GreenCal.Astro.Moon, GreenCal.Astro.RiseSet, GreenCal.Astro.Time — if you need positions, ephemerides or custom events.

An interactive tour lives in livebooks/green_cal.livemd.

Accuracy

Honesty note. The astronomy above is science; elements, organs and "sowing days" are tradition. GreenCal computes the former rigorously and labels the latter for what it is.

Known limitations

• Refraction is the fixed standard 34′. Real refraction varies with temperature and pressure; near the horizon at high latitudes this can shift a rise time by several minutes on unusual days. NOAA and USNO tables share this convention.
• :elevation models an unobstructed horizon below the observer (hilltop, coast, plain). In a valley the visible horizon is higher, not lower — pass 0 and expect the sun later than computed.
• Moon times are geocentric apart from the parallax term absorbed in h₀; the topocentric transit can differ by a few seconds.
• Future ΔT is unknowable. Observed values end in 2026; beyond, the last value is held (documented in GreenCal.Astro.Time). Error should stay under a second for ~a decade, then grow slowly. Override with :delta_t if you need better.
• Eclipse flags are screening, not circumstances — "an eclipse happens somewhere on Earth", not where or how deep.

Installation

def deps do
  [
    {:green_cal, "~> 0.2.0"}
  ]
end

Documentation: https://hexdocs.pm/green_cal.

License

MIT