lua-calendrica

# Module `calendrica-astro`

Time and astronomy calculations.

Ported from "Calendrical Calculations" (4th edition) by Nachum Dershowitz and Edward M. Reingold. Original Lisp code (CALENDRICA 4.0) is Apache 2.0 licensed.

### Info:

- Release: 0.1 2026-07-19

## Functions

hr (x) | `x` hours as a fraction of a day.
mn (x) | `x` minutes as a fraction of a day.
sec (x) | `x` seconds as a fraction of a day.
mt (x) | `x` meters (identity; for type clarity).
deg (x) | `x` degrees (identity; for type clarity).
mins (x) | `x` arcminutes expressed in degrees.
secs (x) | `x` arcseconds expressed in degrees.
angle (d, m, s) | Angle from `d` degrees, `m` arcminutes, `s` arcseconds.
sin_degrees (theta) | Sine of `theta` (given in degrees).
cos_degrees (theta) | Cosine of `theta` (given in degrees).
tan_degrees (theta) | Tangent of `theta` (given in degrees).
arctan_degrees (y, x) | Arctangent of `y`/`x` in degrees; returns BOGUS if both are 0.
arcsin_degrees (x) | Arcsine of `x` in degrees.
arccos_degrees (x) | Arccosine of `x` in degrees.
location (latitude, longitude, elevation, zone) | Construct a location from latitude, longitude, elevation, and time zone.
latitude (loc) | Latitude (degrees north) of location `loc`.
longitude (loc) | Longitude (degrees east) of location `loc`.
elevation (loc) | Elevation (meters) of location `loc`.
zone (loc) | Time zone offset (hours from UT) of location `loc`.
direction (loc, focus) | Angle (clockwise from North) to face `focus` when standing in `loc`.
standard_from_universal (tee_u, loc) | Standard time from universal time `tee_u` at `loc`.
universal_from_standard (tee_s, loc) | Universal time from standard time `tee_s` at `loc`.
local_from_universal (tee_u, loc) | Local time from universal time `tee_u` at `loc`.
universal_from_local (tee_l, loc) | Universal time from local time `tee_l` at `loc`.
apparent_from_universal (tee_u, loc) | True (apparent) time at universal time `tee_u` at `loc`.
midnight (date, loc) | Universal time of true (apparent) midnight of fixed `date` at `loc`.
midday (date, loc) | Universal time of midday on fixed `date` at `loc`.
ephemeris_correction (tee) | Ephemeris correction (dynamical − universal time) at moment `tee`.
sidereal_from_moment (tee) | Mean sidereal time of day from moment `tee` expressed as hour angle.
declination (tee, beta, lambda) | Declination of object at latitude `beta`, longitude `lambda` at moment `tee`.
right_ascension (tee, beta, lambda) | Right ascension of object at latitude `beta`, longitude `lambda` at moment `tee`.
solar_longitude (tee) | Longitude of sun (in degrees) at moment `tee`.
solar_longitude_after (lambda, tee) | Moment UT of first time at or after `tee` when solar longitude is `lambda` degrees.
season_in_gregorian (season, g_year) | Moment UT of `season` in Gregorian year `g_year`.
precession (tee) | Precession at moment `tee` using 0,0 as J2000 coordinates.
sidereal_solar_longitude (tee, sidereal_start) | Sidereal solar longitude at moment `tee`.
estimate_prior_solar_longitude (lambda, tee) | Approximate moment at or before `tee` when solar longitude last exceeded `lambda`.
equation_of_time (tee) | Equation of time (solar noon offset) at moment `tee`.
dawn (date, loc, alpha) | Standard time of dawn on fixed `date` at `loc` with depression angle `alpha`.
dusk (date, loc, alpha) | Standard time of dusk on fixed `date` at `loc` with depression angle `alpha`.
sunrise (date, loc) | Standard time of sunrise on fixed `date` at `loc`.
sunset (date, loc) | Standard time of sunset on fixed `date` at `loc`.
lunar_longitude (tee) | Longitude of moon in degrees at moment `tee`.
lunar_phase (tee) | Lunar phase as an angle in degrees at moment `tee`.
new_moon_before (tee) | Moment UT of last new moon before `tee`.
new_moon_at_or_after (tee) | Moment UT of first new moon at or after `tee`.
lunar_phase_at_or_before (phi, tee) | Moment UT of the last time at or before `tee` when the lunar phase was `phi` degrees.
lunar_phase_at_or_after (phi, tee) | Moment UT of the next time at or after `tee` when the lunar phase is `phi` degrees.
lunar_latitude (tee) | Latitude of moon in degrees at moment `tee`.
lunar_altitude (tee, loc) | Geocentric altitude of moon in degrees at `tee` at `loc`, ignoring parallax and refraction.
lunar_parallax (tee, loc) | Parallax of moon in degrees at `tee` at `loc`.
moonset (date, loc) | Standard time of moonset on fixed `date` at `loc`.
moonrise (date, loc) | Standard time of moonrise on fixed `date` at `loc`.
zone_from_longitude (phi) | Time zone offset (fraction of day) for longitude `phi` (degrees).
universal_from_dynamical (tee) | Universal time from dynamical time `tee` (subtracts ephemeris correction).
dynamical_from_universal (tee_u) | Dynamical time from universal time `tee_u` (adds ephemeris correction).
daytime_temporal_hour (date, loc) | Length of daytime temporal hour on fixed `date` at `loc`.
nighttime_temporal_hour (date, loc) | Length of nighttime temporal hour on fixed `date` at `loc`.
standard_from_sundial (tee, loc) | Standard time of temporal moment `tee` at `loc` (sundial time).
jewish_dusk (date, loc) | Standard time of Jewish dusk on fixed `date` at `loc` (sun 4°40' below horizon).
jewish_sabbath_ends (date, loc) | Standard time of end of Jewish Sabbath on fixed `date` at `loc` (Berthold Cohn; sun 7°5' below horizon).
jewish_morning_end (date, loc) | Standard time of end of Jewish morning on fixed `date` at `loc` (10th temporal hour).
asr (date, loc) | Standard time of Asr prayer (Hanafi rule) on fixed `date` at `loc`.
lunar_distance (tee) | Distance from Earth to Moon in meters at moment `tee`.
lunar_diameter (tee) | Geocentric apparent lunar diameter in degrees at moment `tee`.

## Fields

AUTUMN | Solar longitude at autumnal equinox (degrees).
EVENING | Signifies evening (false).
FIRST_QUARTER | Lunar phase at first quarter (degrees).
FULL | Lunar phase at full moon (degrees).
LAST_QUARTER | Lunar phase at last quarter (degrees).
MEAN_SIDEREAL_YEAR | Mean length of a sidereal year in days.
MEAN_SYNODIC_MONTH | Mean length of a synodic month in days.
MEAN_TROPICAL_YEAR | Mean length of a tropical year in days.
MECCA | Location of Mecca.
MORNING | Signifies morning (true).
NEW | Lunar phase at new moon (degrees).
PADUA | Location of Padua, Italy.
SPRING | Solar longitude at vernal equinox (degrees).
SUMMER | Solar longitude at summer solstice (degrees).
WINTER | Solar longitude at winter solstice (degrees).

## Functions

hr (x)
  `x` hours as a fraction of a day.

  ### Parameters:

  - x number Hours.

  ### Returns:

  number Fraction of a day.
mn (x)
  `x` minutes as a fraction of a day.

  ### Parameters:

  - x number Minutes.

  ### Returns:

  number Fraction of a day.
sec (x)
  `x` seconds as a fraction of a day.

  ### Parameters:

  - x number Seconds.

  ### Returns:

  number Fraction of a day.
mt (x)
  `x` meters (identity; for type clarity).

  ### Parameters:

  - x number Meters.

  ### Returns:

  number Distance in meters.
deg (x)
  `x` degrees (identity; for type clarity).

  ### Parameters:

  - x number Degrees.

  ### Returns:

  number Angle in degrees.
mins (x)
  `x` arcminutes expressed in degrees.

  ### Parameters:

  - x number Arcminutes.

  ### Returns:

  number Degrees.
secs (x)
  `x` arcseconds expressed in degrees.

  ### Parameters:

  - x number Arcseconds.

  ### Returns:

  number Degrees.
angle (d, m, s)
  Angle from `d` degrees, `m` arcminutes, `s` arcseconds.

  ### Parameters:

  - d number Degrees.
  - m number Arcminutes.
  - s number Arcseconds.

  ### Returns:

  number Angle in degrees.
sin_degrees (theta)
  Sine of `theta` (given in degrees).

  ### Parameters:

  - theta number Angle in degrees.

  ### Returns:

  number Sine value.
cos_degrees (theta)
  Cosine of `theta` (given in degrees).

  ### Parameters:

  - theta number Angle in degrees.

  ### Returns:

  number Cosine value.
tan_degrees (theta)
  Tangent of `theta` (given in degrees).

  ### Parameters:

  - theta number Angle in degrees.

  ### Returns:

  number Tangent value.
arctan_degrees (y, x)
  Arctangent of `y`/`x` in degrees; returns BOGUS if both are 0.

  ### Parameters:

  - y number Numerator.
  - x number Denominator.

  ### Returns:

  number Angle in degrees, or BOGUS.
arcsin_degrees (x)
  Arcsine of `x` in degrees.

  ### Parameters:

  - x number Sine value (−1..1).

  ### Returns:

  number Angle in degrees.
arccos_degrees (x)
  Arccosine of `x` in degrees.

  ### Parameters:

  - x number Cosine value (−1..1).

  ### Returns:

  number Angle in degrees.
location (latitude, longitude, elevation, zone)
  Construct a location from latitude, longitude, elevation, and time zone.

  ### Parameters:

  - latitude number Degrees north.
  - longitude number Degrees east.
  - elevation number Meters above sea level.
  - zone number Hours offset from UT.

  ### Returns:

  table {latitude, longitude, elevation, zone}
latitude (loc)
  Latitude (degrees north) of location `loc`.

  ### Parameters:

  - loc table Location.

  ### Returns:

  number Latitude.
longitude (loc)
  Longitude (degrees east) of location `loc`.

  ### Parameters:

  - loc table Location.

  ### Returns:

  number Longitude.
elevation (loc)
  Elevation (meters) of location `loc`.

  ### Parameters:

  - loc table Location.

  ### Returns:

  number Elevation.
zone (loc)
  Time zone offset (hours from UT) of location `loc`.

  ### Parameters:

  - loc table Location.

  ### Returns:

  number Zone offset.
direction (loc, focus)
  Angle (clockwise from North) to face `focus` when standing in `loc`. Subject to errors near focus and its antipode.

  ### Parameters:

  - loc table Observer's location.
  - focus table Target location.

  ### Returns:

  number Bearing in degrees.
standard_from_universal (tee_u, loc)
  Standard time from universal time `tee_u` at `loc`.

  ### Parameters:

  - tee_u number Universal time moment.
  - loc table Location.

  ### Returns:

  number Standard time moment.
universal_from_standard (tee_s, loc)
  Universal time from standard time `tee_s` at `loc`.

  ### Parameters:

  - tee_s number Standard time moment.
  - loc table Location.

  ### Returns:

  number Universal time moment.
local_from_universal (tee_u, loc)
  Local time from universal time `tee_u` at `loc`.

  ### Parameters:

  - tee_u number Universal time moment.
  - loc table Location.

  ### Returns:

  number Local time moment.
universal_from_local (tee_l, loc)
  Universal time from local time `tee_l` at `loc`.

  ### Parameters:

  - tee_l number Local time moment.
  - loc table Location.

  ### Returns:

  number Universal time moment.
apparent_from_universal (tee_u, loc)
  True (apparent) time at universal time `tee_u` at `loc`.

  ### Parameters:

  - tee_u number Universal time moment.
  - loc table Location.

  ### Returns:

  number Apparent time moment.
midnight (date, loc)
  Universal time of true (apparent) midnight of fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Universal time moment.
midday (date, loc)
  Universal time of midday on fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Universal time moment.
ephemeris_correction (tee)
  Ephemeris correction (dynamical − universal time) at moment `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Correction in days.
sidereal_from_moment (tee)
  Mean sidereal time of day from moment `tee` expressed as hour angle. Adapted from Meeus, "Astronomical Algorithms," 2nd edn., 1998, p. 88.

  ### Parameters:

  - tee number Universal time moment.

  ### Returns:

  number Hour angle in degrees.
declination (tee, beta, lambda)
  Declination of object at latitude `beta`, longitude `lambda` at moment `tee`.

  ### Parameters:

  - tee number Universal time moment.
  - beta number Latitude of object (degrees).
  - lambda number Longitude of object (degrees).

  ### Returns:

  number Declination in degrees.
right_ascension (tee, beta, lambda)
  Right ascension of object at latitude `beta`, longitude `lambda` at moment `tee`.

  ### Parameters:

  - tee number Universal time moment.
  - beta number Latitude of object (degrees).
  - lambda number Longitude of object (degrees).

  ### Returns:

  number Right ascension in degrees.
solar_longitude (tee)
  Longitude of sun (in degrees) at moment `tee`. Adapted from Bretagnon and Simon, "Planetary Programs and Tables," 1986.

  ### Parameters:

  - tee number Universal time moment.

  ### Returns:

  number Solar longitude in degrees.
solar_longitude_after (lambda, tee)
  Moment UT of first time at or after `tee` when solar longitude is `lambda` degrees.

  ### Parameters:

  - lambda number Target solar longitude (degrees).
  - tee number Start moment (UT).

  ### Returns:

  number Universal time moment.
season_in_gregorian (season, g_year)
  Moment UT of `season` in Gregorian year `g_year`.

  ### Parameters:

  - season number Solar longitude of season (e.g. SPRING=0).
  - g_year number Gregorian year.

  ### Returns:

  number Universal time moment.
precession (tee)
  Precession at moment `tee` using 0,0 as J2000 coordinates. Adapted from Meeus, "Astronomical Algorithms," 2nd edn., 1998, pp. 136-137.

  ### Parameters:

  - tee number Universal time moment.

  ### Returns:

  number Precession angle in degrees.
sidereal_solar_longitude (tee, sidereal_start)
  Sidereal solar longitude at moment `tee`. `sidereal_start` is the precession value at the Hindu reference epoch.

  ### Parameters:

  - tee number Universal time moment.
  - sidereal_start number Precession offset (degrees).

  ### Returns:

  number Sidereal solar longitude in degrees.
estimate_prior_solar_longitude (lambda, tee)
  Approximate moment at or before `tee` when solar longitude last exceeded `lambda`.

  ### Parameters:

  - lambda number Solar longitude (degrees).
  - tee number Upper bound moment (UT).

  ### Returns:

  number Universal time moment.
equation_of_time (tee)
  Equation of time (solar noon offset) at moment `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Fraction of a day.
dawn (date, loc, alpha)
  Standard time of dawn on fixed `date` at `loc` with depression angle `alpha`. Returns BOGUS if there is no dawn.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.
  - alpha number Depression angle (degrees).

  ### Returns:

  number Standard time, or BOGUS.
dusk (date, loc, alpha)
  Standard time of dusk on fixed `date` at `loc` with depression angle `alpha`. Returns BOGUS if there is no dusk.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.
  - alpha number Depression angle (degrees).

  ### Returns:

  number Standard time, or BOGUS.
sunrise (date, loc)
  Standard time of sunrise on fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time of sunrise, or BOGUS.
sunset (date, loc)
  Standard time of sunset on fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time of sunset, or BOGUS.
lunar_longitude (tee)
  Longitude of moon in degrees at moment `tee`. Adapted from "Astronomical Algorithms" by Jean Meeus, 2nd edn., 1998, pp. 338-342.

  ### Parameters:

  - tee number Moment (Julian day or fixed).

  ### Returns:

  number Lunar longitude in degrees.
lunar_phase (tee)
  Lunar phase as an angle in degrees at moment `tee`. 0=new moon, 90=first quarter, 180=full moon, 270=last quarter.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Lunar phase in degrees [0, 360).
new_moon_before (tee)
  Moment UT of last new moon before `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Moment UT of preceding new moon.
new_moon_at_or_after (tee)
  Moment UT of first new moon at or after `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Moment UT of next new moon.
lunar_phase_at_or_before (phi, tee)
  Moment UT of the last time at or before `tee` when the lunar phase was `phi` degrees.

  ### Parameters:

  - phi number Lunar phase in degrees.
  - tee number Moment.

  ### Returns:

  number Moment UT.
lunar_phase_at_or_after (phi, tee)
  Moment UT of the next time at or after `tee` when the lunar phase is `phi` degrees.

  ### Parameters:

  - phi number Lunar phase in degrees.
  - tee number Moment.

  ### Returns:

  number Moment UT.
lunar_latitude (tee)
  Latitude of moon in degrees at moment `tee`. Adapted from "Astronomical Algorithms" by Jean Meeus, 2nd edn., 1998, pp. 338-342.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Lunar latitude in degrees.
lunar_altitude (tee, loc)
  Geocentric altitude of moon in degrees at `tee` at `loc`, ignoring parallax and refraction.

  ### Parameters:

  - tee number Moment.
  - loc table Location.

  ### Returns:

  number Altitude in degrees.
lunar_parallax (tee, loc)
  Parallax of moon in degrees at `tee` at `loc`.

  ### Parameters:

  - tee number Moment.
  - loc table Location.

  ### Returns:

  number Parallax in degrees.
moonset (date, loc)
  Standard time of moonset on fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time of moonset, or BOGUS.
moonrise (date, loc)
  Standard time of moonrise on fixed `date` at `loc`.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time of moonrise, or BOGUS.
zone_from_longitude (phi)
  Time zone offset (fraction of day) for longitude `phi` (degrees).

  ### Parameters:

  - phi number Longitude in degrees.

  ### Returns:

  number Zone offset (fraction of day).
universal_from_dynamical (tee)
  Universal time from dynamical time `tee` (subtracts ephemeris correction).

  ### Parameters:

  - tee number Dynamical time moment.

  ### Returns:

  number Universal time moment.
dynamical_from_universal (tee_u)
  Dynamical time from universal time `tee_u` (adds ephemeris correction).

  ### Parameters:

  - tee_u number Universal time moment.

  ### Returns:

  number Dynamical time moment.
daytime_temporal_hour (date, loc)
  Length of daytime temporal hour on fixed `date` at `loc`. Returns BOGUS if there is no sunrise or sunset.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Duration in days, or BOGUS.
nighttime_temporal_hour (date, loc)
  Length of nighttime temporal hour on fixed `date` at `loc`. Returns BOGUS if there is no sunrise or sunset.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Duration in days, or BOGUS.
standard_from_sundial (tee, loc)
  Standard time of temporal moment `tee` at `loc` (sundial time). Returns BOGUS if temporal hour is undefined.

  ### Parameters:

  - tee number Moment.
  - loc table Location.

  ### Returns:

  number Standard time moment, or BOGUS.
jewish_dusk (date, loc)
  Standard time of Jewish dusk on fixed `date` at `loc` (sun 4°40' below horizon).

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time moment.
jewish_sabbath_ends (date, loc)
  Standard time of end of Jewish Sabbath on fixed `date` at `loc` (Berthold Cohn; sun 7°5' below horizon).

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time moment.
jewish_morning_end (date, loc)
  Standard time of end of Jewish morning on fixed `date` at `loc` (10th temporal hour).

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time moment.
asr (date, loc)
  Standard time of Asr prayer (Hanafi rule) on fixed `date` at `loc`. Returns BOGUS if no Asr occurs.

  ### Parameters:

  - date number Fixed date.
  - loc table Location.

  ### Returns:

  number Standard time moment, or BOGUS.
lunar_distance (tee)
  Distance from Earth to Moon in meters at moment `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Distance in meters.
lunar_diameter (tee)
  Geocentric apparent lunar diameter in degrees at moment `tee`.

  ### Parameters:

  - tee number Moment.

  ### Returns:

  number Diameter in degrees.

## Fields

AUTUMN
  Solar longitude at autumnal equinox (degrees).
EVENING
  Signifies evening (false).
FIRST_QUARTER
  Lunar phase at first quarter (degrees).
FULL
  Lunar phase at full moon (degrees).
LAST_QUARTER
  Lunar phase at last quarter (degrees).
MEAN_SIDEREAL_YEAR
  Mean length of a sidereal year in days.
MEAN_SYNODIC_MONTH
  Mean length of a synodic month in days.
MEAN_TROPICAL_YEAR
  Mean length of a tropical year in days.
MECCA
  Location of Mecca.
MORNING
  Signifies morning (true).
NEW
  Lunar phase at new moon (degrees).
PADUA
  Location of Padua, Italy.
SPRING
  Solar longitude at vernal equinox (degrees).
SUMMER
  Solar longitude at summer solstice (degrees).
WINTER
  Solar longitude at winter solstice (degrees).

generated by LDoc 1.5.0 Last updated 2026-07-19 03:28:25