lua-calendrica

• Index

Contents

• Functions
• Fields

Modules

• calendrica
• calendrica-akan
• calendrica-astro
• calendrica-astronomical-lunar
• calendrica-bahai
• calendrica-balinese
• calendrica-basic
• calendrica-chinese
• calendrica-coptic-ethiopic
• calendrica-ecclesiastical
• calendrica-egyptian-armenian
• calendrica-french-revolutionary
• calendrica-gregorian
• calendrica-hebrew
• calendrica-icelandic
• calendrica-islamic
• calendrica-iso
• calendrica-julian
• calendrica-mayan
• calendrica-modern-civil
• calendrica-modern-hindu
• calendrica-old-hindu
• calendrica-persian
• calendrica-tibetan

Topics

• manual
• calendars
• holidays

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.2 2026-09-21

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).