The Hebrew calendar explained

This post was triggered by Jon Skeet's tweet about adding Hebrew calendar support to NodaTime. Jon complained that because the hour and day lengths change all the time in the Hebrew calendar, it requires some fundamental changes to NodaTime's inner workings.

Well Jon, I think you can save yourself the trouble.

Initially I intended to do a full write up on the Hebrew calendar, but the Wikipedia article on the topic is very good and thorough. You really should read it, and if you can read Hebrew make sure to check the Hebrew version of the page, it adds quite a lot.

What I will do instead is summarize the basics and inner workings of this calendar system, and use that to explain why most of those calculations can be safely ignored as they are only done ad-hoc in very specific scenarios.

We start with the definitions of time of day, and then move to discussing days months and years.

A Temporal Hour

The most basic unit in the calendar system is probably an hour, and it is defined very differently from what we are used to. An hour is the product of the following calculation: the time between sunrise and sundown divided by 12. This is referred to as a "temporal hour", because its actual length changes all the time.

While the length of a temporal hour is around 60 minutes, its length in Israel can be any value between 48 minutes (in the shortest of Winter days) and 72 minutes (in long summer days). This is obviously affected by the geographic location since the length of the day changes - around the mediator a temporal hour will always be close to 60 minutes, and as you go closer to the north pole the differences get much bigger.

There is actually a disagreement on what is the definition of sunrise and sundown in this context. There are 2 methods: one considers the astronomical sunrise and sundown to be the deciders, that is - sunrise is when the tip of the sun is seen at the east horizon, and when the tip of the sun disappears in the west is sundown. This approach is commonly referred to as The Gra's Method (שיטת הגר"א), the Gra being one of the recent rabbis advocating for it.

The other method is named after the Magen-Avraham's (מג"א), and considers sunrise to be the time in which the transition begins from night to day (when the skies begin to have some light in them - the dawn), and sundown to be when stars can be seen in the sky - when the transition to night completes.

Unlike the first definition, which is purely astronomical and where times can be calculated using scientific methods and navy tables, the second definition is a lot harder to "put the finger on". After many arguments in traditional Jewish texts there are 3 common definitions of the time that is referred to as "dawn" (Alot HaShacher - עלות השחר):

1. 72 minutes before the astronomical sunrise (the time it takes to calmly walk 4 times 1 Talmudic mile - about 1km, so 18 minutes * 4). This is the most widely accepted method for the time of the dawn.
2. 90 minutes before sunrise (5 * 18 minutes) is the method many in Jerusalem use.
3. 120 minutes before sunrise is a lesser used method, but still many use it (Chabad for example).

Similarly, there are multiple methods to define the start of the night - how much time after the astronomical sundown it is definitely dark outside, and stars can be seen clearly. Most differences originate from arguments over how much time it takes to walk 1 Talmudic mile (most think its 18 minutes, but there are also other methods), and how many miles are to be considered for this calculation. There are 3 commonly used methods:

1. Most widely accepted method is 18 minutes after the astronomical sundown. This is again the Gra's method, and there are some variants of it measuring 13.5 or 24 minutes instead.
2. 72 minutes after sundown, also known as Rabenu Tam's method. Mostly used as a precaution time measurement, for example to tell when Shabbat or holidays are over.
3. 40 minutes after sundown, Hazon Ish's method.

As usual with Jewish tradition, there's a lot of arguments over almost anything, and there are 2 or 3 commonly used methods which really set the tone. This argument over the length of daylight time affect the length of a temporal hour, but also the length of the day as we will just see. Temporal hours aren't being really used as a unit of time today as I'll explain in the last section.

One day's length

In the Hebrew calendar a day is not a product of the number of hours. Rather, a day starts and ends in sundown. But what is sundown?

It is widely agreed that the actual transition between days is sometime after sundown, but since we can't really put the finger on it, there are multiple opinions on how much time that actually is.

The core of the question is about the length of what is called "Bein Hashmashot" - between the suns, the sun that can be seen in the sky and the sun that gives the light to the sky. It's the same entity but two different concepts.

This is where the second definition from above for sundown is mostly used - when its clearly dark outside, some minutes after the astronomical sundown, its clear that the sun is completely absent. There's again a lot of details which I'll skip this time, but you get the idea.

Once stars are out, you can flip the day on the calendar.

One month's length

The Hebrew calendar is a lunisolar one - meaning it uses both solar and lunar calendar systems to calculate dates. Months follow the moon, years and seasons follow the sun.

Unlike other calendars (like the commonly used Gregorian), a month in the Hebrew calendar is measured by the time it takes the moon to complete a full cycle. This time is on average 29 Hebrew days, 12 hours and 793 hour-parts (a part is 1/1080 of the hour).

Because it doesn't make any sense to switch dates and months in the middle of the day, some rounding mechanism is applied, so Hebrew months are either 29 or 30 days long, in a way that it self-compensates over lost time.

To assure the holiday of Passover always happens in the autumn the Hebrew calendar has the concept of leap years to synchronize between the lunar calendar and the solar calendar system. While there is still a very small drift, this is achieved and the Hebrew and Gregorian calendars meet every 19 years.

Modern use and computerized systems

In Jewish tradition, the Hebrew calendar is used to tell when holidays and memorial days should be honored. Passover, for example, has the fixed Hebrew date of 15th of Nissan. The Gregorian date for this Hebrew date changes every year, and therefore the Hebrew calendar is used to tell when a holiday should be celebrated.

Since the Hebrew day starts at sundown, the Gregorian and Hebrew dates only partially overlap. As a result, Shabbat and holidays for example begin when the sun sets the evening of the day before. So if 15th of Nissan is, for example, on March 20th, Passover will actually start on March 19th at around 7pm, at sundown.

The Hebrew calendar is still used by many people around the world in day-to-day life, mostly by Jews. Of those aware of the Hebrew calendar, there are 3 types of people:

1. People who are aware of the Hebrew calendar, maybe sometimes they can tell the current Hebrew date, but usually mostly unfamiliar with it. Most (or many-of) secular Jews fall into this category.
2. Those who live their life close to the Hebrew calendar, but still use the Gregorian calendar for daily uses. Under this category are many secular Jews, but mostly religious Jews who are involved with the world through businesses etc.
3. There are groups of ultra-orthodox Jews who only keep track of the Hebrew calendar, and while they are usually familiar with the Gregorian calendar, they usually are not keeping track of dates using it.

This is as far as tracking dates. As for telling time, nobody today uses temporal hours. Everybody, including those who never use the Gregorian calendar, have a standard clock. Temporal hours are used mainly to tell prayer times and other Jewish times of day - like when Shabbat starts or ends - and also then they are only used for the calculation, and the result is told in terms of "modern" hours.

Because all of this, computerized systems never really use the Hebrew calendar. Even when they do, its for very specific needs like telling today's Hebrew date, mostly for display, and then they can calculate the values ad-hoc using simple to use formulas and tables which are widely available.

Even if you wanted to serve customers who only observe the Hebrew calendar, you can get away with it very easily by a simple Hebrew-calendar-aware layer on top of Gregorian dates, which computerized systems already know how to work with (well, at least - lets not add an extra complexity to what is already quite complex, and Jon can testify on that).

TL;DR

The Hebrew calendar is fascinating with lots of historic reasons for every bit of it, but since most of its constructs aren't being used today, most of your code and libraries should just ignore it. Really. Stay away from complexity where it isn't needed, especially when it can be added where necessary fairly easily with a dedicated software layer.

I'll be happy to dive in further on any of the items above if there's interest.