Skip to content

Latest commit

 

History

History

guide

README.md

How a Hindu Calendar Works — from scratch

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.


1. The big picture: why this calendar is luni-solar

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.


2. The one idea that makes the whole thing tractable

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


3. The accuracy philosophy (what makes this implementation trustworthy)

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:

  1. 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.
  2. Validate against an independent gold standard. We check our output against the Swiss Ephemeris (the library astro.com and professional software use) — not against the popular website we might be tempted to copy. Those checks live in tests/regression/*-vs-swisseph.test.ts and are regenerated by a committed script, tests/reference/gen_swisseph.py.
  3. 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.

4. The course

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

Part III — The five 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.


5. How to read the code alongside

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.