Methodology

Julian Day Number as Universal Pivot

All date conversions in kalkal pass through the Julian Day Number (JDN) — a continuous count of days since the beginning of the Julian Period on 1 January 4713 BCE (Julian proleptic calendar). Each calendar system implements two functions: one to convert a date into a JDN, and one to convert a JDN back into a date in that calendar. To convert from calendar A to calendar B, we compute A → JDN → B. This approach avoids the combinatorial explosion of writing direct conversion functions between every pair of calendars.

Architecture and Construction

kalkal runs entirely in the browser with zero external dependencies and no build step. The computational engine is a single JavaScript module (Cal) exposing toJD() and fromJD() functions for each of the 24 supported calendar systems. A separate registry maps each calendar to its Cal functions, handling UI concerns like variant selection (e.g. the 4 tabular Hijri variants, 3 Byzantine Anno Mundi variants, 2 Seleucid reckonings) independently from the algorithms. Internationalization covers 4 languages (EN, PL, AR, EO) with full RTL support for Arabic.

Nearly all algorithms are purely arithmetic — no astronomical calculations, no external API calls, no lookup tables of observed data. The one exception is the Babylonian calendar, which uses the Parker & Dubberstein observational tables for 626 BCE–45 CE (with an arithmetic fallback outside that range). For all other calendars, every conversion is reproducible: the same input always produces the same output regardless of platform, locale, or network state.

Algorithm Sources

Gregorian and Julian conversions follow the algorithms in Meeus (1998). The tabular Hijri calendar uses a 30-year cycle with 4 historical leap-year variants (IIc/Wüstenfeld as default). The Solar Hijri uses the 2820-year arithmetic cycle from Birashk, refined by Borkowski; the Ilkhanid (Khānī) calendar shares this algorithm with a different epoch (1302 CE), supplemented by the 12-year Turkic-Mongol animal cycle. Coptic, Ethiopian, Egyptian, Yazdgerdi, and Armenian calendars use epoch-offset arithmetic from Reingold & Dershowitz (2018). The Hebrew calendar implements the full molad-based rules from the same source. The Babylonian calendar uses the Hebrew calendar's molad arithmetic as an approximation, with Nisan-based year start and Nabonassar era offset (747 BCE); historical Babylonian months began at observed first crescent, so this approximation may differ by ±1 day. Byzantine (3 Anno Mundi variants: Constantinople, Alexandrian, Chronicon Paschale), Seleucid (Macedonian and Babylonian reckonings), Antiochene, Syriac, Rumi, AUC, Roman, Spanish Era, Olympiad, and Macedonian calendars are Julian-based with epoch offsets. The Roman calendar adds traditional day notation (Kalends, Nones, Ides). The 15-year Indiction cycle is displayed alongside Byzantine dates.

Validation and Verification

Every calendar conversion is validated through three independent methods. First, round-trip testing: for each calendar, a date is converted to JDN and back, confirming that fromJD(toJD(date)) === date across hundreds of test cases spanning epochs, boundaries, and modern dates. Second, cross-verification against independent implementations: the Fourmilab algorithm (public domain), the browser's Intl.DateTimeFormat API, and Python's hijri-converter library. Third, spot-checking known historical dates (e.g. Battle of Badr = 17 Ramadan 2 AH = 13 March 624 CE Julian, Fall of Baghdad = 10 February 1258 CE) against published scholarly sources.

Tests run in Node.js by loading the browser-targeted Cal module. No test framework is used — the verification scripts output pass/fail counts directly, making the test suite itself auditable with zero dependencies.