# `Calendrical.Islamic.UmmAlQura.ReferenceData`

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/6492017

The `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.

# `entry`

```elixir
@type entry() :: {pos_integer(), 1..12, Date.t()}
```

# `akmal_data`

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

# `umm_al_qura_dates`

```elixir
@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_epoch` is 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) and
  * `akmal_data/0`

Each map has three keys:
  - `:hijri_year`  — Hijri year (integer)
  - `:hijri_month` — Hijri month number, 1–12 (1 = Muharram)
  - `:gregorian`   — `t:Calendar.date/0` of the 1st day of that Hijri month

The sequence starts at 1 Muharram 1356 AH
(1937-03-14) and covers approximately 145 years.

# `van_gent_data`

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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*