Calendrical.
Copy Markdown
Umm al-Qura month starts computed by R.H. van Gent (Utrecht University)
from the published Umm al-Qura rules, used as the reference data for
Calendrical.Islamic.UmmAlQura.Astronomical.
These tables are an astronomical reconstruction, not KACST's official
published calendar. They differ from it in 695 of the months between
1356 and 1500 AH, and include a 28-day month (Sha'ban 1364) and
353-day years (1356 and 1401 AH) that the official table does not. The
tabular Calendrical.Islamic.UmmAlQura is built from KACST's official
month lengths instead.
Two datasets are available, van_gent_data/0 (the default) and
akmal_data/0. Each is a list of cumulative day counts for the start of
each Hijri month, from which successive first-day Gregorian dates are
derived by taking consecutive differences. The series begins at
1 Muharram 1356 AH (14 March 1937 CE) and covers 145 years.
Source: https://webspace.science.uu.nl/~gent0113/islam/ummalqura.htm
https://gist.github.com/akmalxxx/6492017Summary
Functions
Returns a table of days since epoch for Hijri months in the Umm al-Qura calendar.
Returns the complete sequence of Umm al-Qura first-day dates as a list of maps.
Returns a table of days since epoch for Hijri months in the Umm al-Qura calendar sourced from R.H. van Gent's Umm al-Qura tables at Utrecht University.
Types
@type entry() :: {pos_integer(), 1..12, Date.t()}
Functions
Returns a table of days since epoch for Hijri months in the Umm al-Qura calendar.
The data is sourced from https://gist.github.com/akmalxxx/6492017 which claims
it was taken from Van Gent. However this data is different for 3 dates
from current Van Gent (see van_gent_data/0 below).
Consecutive differences give the length (29 or 30 days) of each Hijri month, starting at 1 Muharram 1356 AH (14 March 1937 CE).
Returns
- A list of integers, the days since the epoch of the first day of each Hijri month.
Examples
iex> Calendrical.Islamic.UmmAlQura.ReferenceData.akmal_data() |> Enum.take(3)
[28607, 28636, 28665]@spec umm_al_qura_dates(hijiri_list_of_days_since_epoch :: [pos_integer()]) :: [ %{hijri_year: pos_integer(), hijri_month: 1..12, gregorian: Date.t()} ]
Returns the complete sequence of Umm al-Qura first-day dates as a list of maps.
Arguments
hijiri_list_of_days_since_epochis a list of integers marking the start of each Hijri month. There are two sources available in this module:van_gent_data/0(the default).
Returns
- A list of maps, one for each Hijri month, each with three keys:
:hijri_yearis the Hijri year (integer).:hijri_monthis the Hijri month number, 1–12 (1 = Muharram).:gregorianis theCalendar.date/0of the 1st day of that Hijri month.
The sequence starts at 1 Muharram 1356 AH (1937-03-14) and covers approximately 145 years.
Examples
iex> [first | _rest] = Calendrical.Islamic.UmmAlQura.ReferenceData.umm_al_qura_dates()
iex> first
%{hijri_year: 1356, hijri_month: 1, gregorian: ~D[1937-03-14]}Returns a table of days since epoch for Hijri months in the Umm al-Qura calendar sourced from R.H. van Gent's Umm al-Qura tables at Utrecht University.
Source: https://webspace.science.uu.nl/~gent0113/islam/ummalqura.htm on March 13th, 2026.
The https://github.com/dralshehri/hijridate library also uses the van Gent data.
Comparison with akmal_data/0
The two datasets are identical for 1,738 of 1,741 months (99.8 %). All differences fall within Era 4 (≥ 1423 AH) and involve extreme boundary cases where moonset and sunset at Mecca are within seconds of each other:
| Hijri date | Month | akmal | ghent | Margin |
|---|---|---|---|---|
| 1427/6 | Jumada al-Thani | 2006-06-26 | 2006-06-27 | conjunction 75 s before sunset |
| 1446/6 | Jumada al-Thani | 2024-12-03 | 2024-12-02 | moonset 5 s before sunset |
| 1485/10 | Shawwal (Eid al-Fitr) | 2063-01-31 | 2063-01-30 | moonset 8 s before sunset |
The discrepancies are likely caused by differences in the underlying astronomical algorithms (ephemeris model, atmospheric refraction, lunar parallax). At these razor-thin margins a few arcseconds of difference in the moon's computed position flips the binary moonset-before/after-sunset decision.
The 1485/10 case is the most consequential: 1 Shawwal determines Eid al-Fitr (end of Ramadan). However, it is a future date (2063) and both values are predictions; the official determination has not yet been made.
Era 2 (1392–1419 AH) and Era 3 (1420–1422 AH) are identical across both datasets.
Since the first two dates are in the past, and the last one is in the mid-future it is expected the discrepencies have limited negative impact. However they are included here as a reminder that not all data sets agree and astronomical calculations are hard.
Returns
- A list of integers, the days since the epoch of the first day of each Hijri month.
Examples
iex> Calendrical.Islamic.UmmAlQura.ReferenceData.van_gent_data() |> Enum.take(3)
[28607, 28636, 28665]