Module calendrical_calculations::hebrew_keviyah

source ·
Expand description

Alternate, more efficient structures for working with the Hebrew Calendar using the keviyah and Four Gates system

The main entry point for this code is YearInfo::compute_for() and YearInfo::year_containing_rd(), which will efficiently calculate certain information about a Hebrew year, given the Hebrew year or a date that falls within it, and produce it as a YearInfo.

From there, you can compute additional information via YearInfo::new_year() and by accessing the methods on YearInfo::keviyah.

§How this code works:

§How the Hebrew Calendar works

The Hebrew calendar is a lunisolar calendar following a Metonic cycle: every 19 years, the pattern of leap years repeats. However, the precise month lengths vary from cycle to cycle: There are a handful of corrections performed to ensure that:

  • The lunar conjunction happens on or before the first day of the month
  • Yom Kippur is not before or after the Sabbath
  • Hoshana Rabbah is not on the Sabbath

These corrections can be done using systematic calculations, which this code attempts to efficiently perform.

§Molad

A molad is the time of a conjunction, the moment when the new moon occurs. The “Molad Tishrei” is the conjunction corresponding to the month Tishrei, the first month, so it is the molad that starts the new year. In this file we’ll typically use “molad” to refer to the molad Tishrei of a year.

The Hebrew calendar does not always start on the day of the molad Tishrei: it may be postponed one or two days. However, the time in the week that the molad occurs is sufficient to know when it gets postponed to.

§Keviyah

See also: the Keviyah type.

This is the core concept being used here. Everything you need to know about the characteristics of a hebrew year can be boiled down to a notion called the “keviyah” of a year. This encapsulates three bits of information:

  • What day of the week the year starts on
  • What the month lengths are
  • What day of the week Passover starts on.

While this seems like many possible combinations, only fourteen of them are possible.

Knowing the Keviyah of the year you can understand exactly what the lengths of each month are. Furthermore, if you know the week the year falls in, you can additionally understand what the precise day of the new year is.

YearInfo encapsulates these two pieces of information: the Keviyah and the number of weeks since the epoch of the Hebrew calendar.

§The Four Gates table

This is an efficient lookup based way of calculating the Keviyah for a year. In the Metonic cycle, there are four broad types of year: leap years, years preceding leap years, years succeeding leap years, and years sandwiched between leap years. For each of these year types, there is a partitioning of the week into seven segments, and the Keviyah of that year depends on which segment the molad falls in.

So to calculate the Keviyah of a year, we can calculate its molad, pick the right partitioning based on the year type, and see where the molad falls in that table.

Macros§

  • u16_cvt 🔒
  • ḥal 🔒
    Conveniently create a constant for a ḥalakim (by default in 1-indexed notation). Produces a constant that tracks the number of ḥalakim since the beginning of the week

Structs§

  • YearInfo
    Everything about a given year. Can be conveniently packed down into an i64 if needed.

Enums§

  • Keviyah
    The Keviyah (קביעה) of a year. A year may be one of fourteen types, categorized by the day of week of the new year (the first number, 1 = Sunday), the type of year (Deficient, Regular, Complete), and the day of week of the first day of Passover. The last segment disambiguates between cases that have the same first two but differ on whether they are leap years (since Passover happens in Nisan, after the leap month Adar).
  • MetonicCycleType 🔒
    “Metonic cycle” in general refers to any 19-year repeating pattern used by lunisolar calendars. The Hebrew calendar uses one where years 3, 6, 8, 11, 14, 17, 19 are leap years.
  • StartOfYear
    The day of the new year. Only these four days are permitted.
  • YearType
    The type of year it is

Constants§

Functions§

  • keviyah_for 🔒
    Perform the four gates calculation, giving you the Keviyah for a given year type and the ḥalakim-since-beginning-of-week of its molad Tishri
  • molad_details 🔒
    Given a Hebrew Year, returns its molad specified as:
  • months_preceding_molad 🔒
    Calculate the number of months preceding the molad Tishrei for a given hebrew year (Tishrei is the first month)