The math, the code, and the why behind the पञ्चाङ्ग (pañcāṅga).
This is a teaching course, not a reference manual. It starts from "what is the Moon doing tonight" and builds, step by step, to a calendar that can tell you the तिथि (lunar day), the festival dates, and the birth chart for any place on Earth and any moment from 1500 CE to 2500 CE — and explains why each piece exists and how we make it accurate. Every lesson points at the exact code in this repository that implements it, so you can read the idea and then read the 20 lines that do it.
A note on the Sanskrit/Hindi words: they carry meaning that the English loses, so this course keeps them — always with the Devanagari and a transliteration the first time, e.g. तिथि (tithi). There is a glossary at the end.
Almost every calendar is a compromise between two clocks in the sky that refuse to divide evenly:
- The Moon (चन्द्र, candra) is the easy clock. Anyone can see its phases; from one new moon to the next is about 29.53 days — a natural "month."
- The Sun (सूर्य, sūrya) is the important clock. It rules the seasons and the harvest; one full cycle of seasons is about 365.24 days — a "year."
The trouble: a year is not a whole number of lunar months (365.24 / 29.53 ≈ 12.37). So you must choose what to sacrifice:
| Calendar | Follows | Cost |
|---|---|---|
| Islamic (Hijri) | only the Moon | drifts through the seasons ~11 days/year |
| Gregorian | only the Sun | months have nothing to do with the Moon |
| Hindu | both | needs a leap month every ~3 years to stay aligned |
The Hindu calendar refuses to sacrifice either. It counts months by the Moon and keeps them locked to the Sun's seasons by occasionally inserting a leap month — the अधिक मास (adhika māsa), which you'll meet in Lesson 9. That single decision — keep both clocks — is the source of everything that follows, including all the beauty and all the complications.
Here is the secret that turns "a 2000-year-old astronomical tradition" into "a few hundred lines of code":
Everything reduces to two numbers — the position of the Sun and the position of the Moon along the zodiac, at the instant you care about.
"Position along the zodiac" means the ecliptic longitude: an angle from 0° to 360° measured along the Sun's yearly path. Call them λ☉ (Sun) and λ☽ (Moon). Then, astonishingly, all five limbs of the pañcāṅga are just arithmetic on these two angles:
| Limb | Hindi | What it is | Formula (sketch) |
|---|---|---|---|
| Tithi | तिथि | lunar day | from λ☽ − λ☉ (Moon's lead over Sun) |
| Nakshatra | नक्षत्र | lunar mansion | from λ☽ alone |
| Yoga | योग | a Sun+Moon angle | from λ☽ + λ☉ |
| Karana | करण | half-tithi | from λ☽ − λ☉ |
| Vara | वार | weekday | from the civil day (the one piece that isn't λ) |
So the course has a natural shape. First we learn to compute λ☉ and λ☽ accurately for any time and place (Lessons 1–5). Then everything else is definitions and bookkeeping on top (Lessons 6–12).
Old pañcāṅgas computed λ☉ and λ☽ with the Sūrya Siddhānta — clever medieval formulas that drift by up to a degree today. Modern ones use dṛk gaṇita (दृक् गणित, "observation-based mathematics"): real ephemeris models fit to centuries of telescope and spacecraft data. This project is dṛk gaṇita. Three rules keep it honest, and you'll see them enforced in every lesson:
- Compute from first principles, not from a lookup of someone else's
answer. The Sun and Moon come from
astronomy-engine(a port of NASA-grade models); the calendar logic is the classical definitions applied to those positions. - Validate against an independent gold standard. We check our output
against the Swiss Ephemeris (the library
astro.comand professional software use) — not against the popular website we might be tempted to copy. Those checks live intests/regression/*-vs-swisseph.test.tsand are regenerated by a committed script,tests/reference/gen_swisseph.py. - Separate facts from conventions, and say which is which. That the Moon is at a certain longitude is a fact. Which day a festival is observed when a tithi is skipped is a convention — and traditions genuinely disagree. Where we follow a convention (often the popular Drik Panchang), we label it; where we can't cite a source, we say so. Lesson 11 is blunt about this.
Read in order — each lesson assumes the previous ones. Every lesson ends with
the files in src/ that implement it.
Part I — Foundations (telling when and where)
- 1 · Keeping time — civil time, time zones, and the
Julian Day (the single number that names an instant).
astro/julian.ts. - 2 · The sky — the ecliptic (क्रान्तिवृत्त), ecliptic longitude, and sidereal time. Where a "position in the zodiac" actually is.
Part II — The two lights and the fixed zodiac
- 3 · Sūrya and Candra — computing λ☉ and λ☽:
apparent geocentric longitudes, and why "apparent" matters.
astro/ephemeris.ts. - 4 · Precession and the अयनांश — the
tropical vs sidereal zodiac, the slow wobble of the equinox, and the
ayanāṁśa correction. The honest story of "which Lahiri."
astro/ayanamsa.ts. - 5 · नक्षत्र and राशि — cutting the sidereal circle into 27 mansions and 12 signs.
Part III — The five limbs (पञ्चाङ्ग)
- 6 · तिथि — the lunar day — the heart of the calendar:
the Sun–Moon elongation, why a tithi isn't 24 hours, and how we find the exact
instant it ends.
panchanga/tithi.ts. (written — the worked example) - 7 · Yoga, Karana, Vara — the remaining limbs.
Part IV — Building the calendar
- 8 · The day and सूर्योदय — why the Hindu day begins at
sunrise, and how we compute sunrise for any latitude.
astro/sunrise.ts. - 9 · मास — the lunar month — amānta vs pūrṇimānta, naming a
month by the Sun, and the leap (अधिक) and lost (क्षय) months.
panchanga/masa.ts. - 10 · The year — संवत् era counts, ऋतु seasons, the अयन (solstice halves), and संक्रान्ति (the Sun changing sign).
Part V — Application
-
11 · Festivals — how a tithi becomes a date on the wall: the vyāpinī rules, the tie-breakers, and an honest accounting of where we match tradition and where we can't.
-
12 · कुण्डली — the birth chart — the same Sun/Moon machinery, turned on a moment of birth: लग्न, ग्रह, भाव, दशा.
-
Glossary — every Sanskrit/Hindi term, with Devanagari.
The repository is organized exactly like this course:
src/lib/
astro/ ← Lessons 1–4, 8 : time, ephemeris, ayanamsa, sunrise
panchanga/ ← Lessons 5–11 : tithi, nakshatra, yoga, masa, festivals
jyotish/ ← Lesson 12 : the kundli engine
When a lesson says "see panchanga/tithi.ts", open it — the functions are
small and named after the concept (tithiAtJD, tithiAtInstant). The goal is
that after this course you could delete a file and rewrite it from the lesson.