Module calendrical_calculations::hebrew_keviyah

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

• ADAR
  Normalized month constant (see TISHREI)
• ADARI_LEN 🔒
• ADAR_LEN 🔒
• AV
  Normalized month constant (see TISHREI)
• AV_LEN 🔒
• ELUL
  Normalized month constant (see TISHREI)
• ELUL_LEN 🔒
• FOUR_GATES_LEAP 🔒
• FOUR_GATES_LMINUSONE 🔒
• FOUR_GATES_LPLUSMINUSONE 🔒
• FOUR_GATES_LPLUSONE 🔒
• HEBREW_APPROX_YEAR_LENGTH 🔒
  From Reingold (ch 8.2, in implementation for fixed-from-hebrew)
• HEBREW_CALENDAR_EPOCH 🔒
  The Hebrew calendar epoch. It did not need to be postponed, so it occurs on Hebrew Monday, Oct 7, 3761 BCE (Julian), the same as the Molad Beherad.
• HEBREW_LUNATION_TIME 🔒
  The amount of time a Hebrew lunation takes (in ḥalakim). This is not exactly the amount of time taken by one revolution of the moon (the real world seldom has events that are perfect integer multiples of 1080ths of an hour), but it is what the Hebrew calendar uses. This does mean that there will be drift over time with the actual state of the celestial sphere, however that is irrelevant since the actual state of the celestial sphere is not what is used for the Hebrew calendar.
• HEBREW_MAX_RD
  The maximum R.D. supported by this code (this is the last day in HEBREW_MAX_YEAR)
• HEBREW_MAX_YEAR
  The maximum hebrew year supported by this code (this is the maximum alue for i32)
• HEBREW_MIN_RD
  The minumum R.D. supported by this code (this code will clamp outside of it)
• HEBREW_MIN_YEAR
  The minumum hebrew year supported by this code (this is the minimum value for i32)
• IYYAR
  Normalized month constant (see TISHREI)
• IYYAR_LEN 🔒
• KISLEV
  Normalized month constant (see TISHREI)
• KISLEV_DEFAULT_LEN 🔒
• MOLAD_BEHERAD_OFFSET 🔒
  The molad Beherad is the first molad, i.e. the molad of the epoch year. It occurred on Oct 6, 3761 BC, 23h:204ḥal (Jerusalem Time, Julian Calendar)
• NISAN
  Normalized month constant (see TISHREI)
• NISAN_LEN 🔒
• SHEVAT
  Normalized month constant (see TISHREI)
• SHEVAT_LEN 🔒
• SIVAN
  Normalized month constant (see TISHREI)
• SIVAN_LEN 🔒
• TAMMUZ
  Normalized month constant (see TISHREI)
• TAMMUZ_LEN 🔒
• TEVET
  Normalized month constant (see TISHREI)
• TEVET_LEN 🔒
• TISHREI
  Normalized month constant for Tishrei
• TISHREI_LEN 🔒
• ḤALAKIM_IN_WEEK 🔒
  The number of ḥalakim in a week
• ḤESHVAN
  Normalized month constant (see TISHREI)
• ḤESHVAN_DEFAULT_LEN 🔒

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)