Calendrical.Islamic.UmmAlQura.ReferenceData
(Calendrical v0.3.0)
Copy Markdown
Official Umm al-Qura first-day dates sourced from the dataset maintained by R.H. van Gent (Utrecht University) and cross-referenced against the KACST published tables.
Source: https://webspace.science.uu.nl/~gent0113/islam/ummalqura.htm
https://gist.github.com/akmalxxx/6492017The official_data/0 function contains cumulative day-count indices for each
Hijri month start, 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 approximately 145 years.
Note that they reference data here could be encoded in a much more efficient way. For example, it could be encoded as a bitstring where each bit indicates if the month is 29 or 30 days. Each year could be extracted as the 12 bits offset by ((year - 1) * 12) from the start of the bitstring. This way calculating firt_day_of_month would be O(1) for any date in the range of the data.
Summary
Functions
Returns a table of days since epoch for Hikiri 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 Hikiri 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 Hikiri 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).
@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 Hijiri month. There are two source available in this module:van_gent_data/0(the default) andakmal_data/0
Each map has three keys:
:hijri_year— Hijri year (integer):hijri_month— Hijri month number, 1–12 (1 = Muharram):gregorian—Calendar.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.
Returns a table of days since epoch for Hikiri 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.