Forem: Adi Kumar

370 Tithis, 4 Eclipses, and One Bug That Moved Dussehra by 11 Days

Adi Kumar — Tue, 19 May 2026 05:53:28 +0000

Computing the entire Hindu calendar in TypeScript — from lunar phase geometry to festival date resolution

In Part 1 I built a panchang engine that could tell you the state of any moment: the tithi, the nakshatra, the yoga, the karana, and the vara. Five limbs computed from the Sun-Moon elongation at a single point in time.

That's useful for a daily snapshot. It is not useful for building a calendar.

A calendar needs every tithi transition in the year, with exact start and end times. It needs to know which lunar month each tithi falls in, and whether that month is ordinary or intercalary. It needs to predict eclipses from orbital geometry. And it needs to map all of this onto the 150+ festivals that people actually observe, each defined by a specific lunar coordinate: this month, this fortnight, this tithi.

I got all three working. Then I shipped a bug that moved Dussehra by 11 days. The computation was correct. The mapping was wrong.

This article covers the three hardest problems I solved while building Dekho Panchang: the tithi table, eclipse prediction, and the festival engine.

The Tithi Table

A tithi is not a fixed-length day. In the Gregorian calendar, a day is always 24 hours. A tithi is the time it takes for the Moon to gain 12 degrees of elongation from the Sun. Because the Moon's orbit is elliptical, its angular speed varies between roughly 11.5 and 15.4 degrees per day. The Sun also moves at a variable rate (about 0.95 to 1.02 degrees per day), so the relative elongation rate changes continuously. A tithi can last anywhere from 19 to 26 hours. That's a 37% variation.

You cannot divide a lunar month into 30 equal slots. You have to find each boundary individually.

A naive approach would be to sample the elongation every minute and look for crossings. That works, but it's expensive: 525,600 function evaluations per year, each involving Sun and Moon longitude calculations. For a pre-computed table that gets built once, that's tolerable. For on-demand computation with a 2-second time budget, it's too slow.

The approach is binary search. Each tithi boundary corresponds to a specific Sun-Moon elongation: 0 degrees for the start of Shukla Pratipada, 12 degrees for Shukla Dwitiya, 24 degrees for Shukla Tritiya, all the way up to 348 degrees for Krishna Chaturdashi. For each boundary, I scan forward in coarse 2-hour steps until the tithi number changes, then binary-search the interval for 20 iterations. That converges to about 5 seconds of precision, which is more than enough.

function findTithiEndJd(startJd: number, currentTithi: number): number {
  const step = 2 / 24; // 2 hours in Julian Day units
  const maxJd = startJd + 2.0; // scan up to 2 days forward

  // Coarse scan: walk forward until the tithi number changes
  let lo = startJd;
  let hi = maxJd;
  for (let jd = startJd + step; jd <= maxJd; jd += step) {
    const t = calculateTithi(jd).number;
    if (t !== currentTithi) {
      lo = jd - step;
      hi = jd;
      break;
    }
  }

  // Binary search: 20 iterations gives ~5-second precision
  // (2 hours / 2^20 = 0.007 seconds)
  for (let i = 0; i < 20; i++) {
    const mid = (lo + hi) / 2;
    if (calculateTithi(mid).number === currentTithi) {
      lo = mid;
    } else {
      hi = mid;
    }
  }

  return (lo + hi) / 2;
}

calculateTithi computes the Sun-Moon elongation at a given Julian Day and divides by 12 to get the tithi number (1-30). It's the same function from Part 1. The binary search just calls it repeatedly until it finds the exact moment where the number flips.

Why 2-hour steps for the coarse scan? A tithi lasts at minimum about 19 hours, so stepping by 2 hours guarantees we will never skip an entire tithi. We might overshoot the boundary by up to 2 hours, but that's what the binary search is for. The 20 iterations of binary search divide a 2-hour interval by 2^20, giving a precision of about 0.007 seconds. In practice, the Sun and Moon longitude functions themselves have errors larger than that, so the limiting factor is the ephemeris, not the search.

Starting from 1 December of the previous year (to catch tithis that straddle the year boundary), the engine walks forward through every tithi, calling findTithiEndJd for each one. The result is a chain: the end of one tithi is the start of the next. The output is roughly 370 entries per year. Each entry has exact Julian Day start and end times, local time strings, the paksha (Shukla or Krishna), and flags for two special cases.

Kshaya tithis happen when a tithi is so short that no sunrise falls within it. It starts after one sunrise and ends before the next. The tithi effectively gets skipped in the civil calendar. The engine detects this by scanning every calendar date between the start and end of the tithi and checking whether sunrise falls within the window. If no sunrise does, isKshaya is true.

Vriddhi tithis are the opposite. A tithi is long enough that two sunrises fall within it. When a tithi spans two days, you need a rule for which day "owns" the festival. The rule is simple: for Ekadashi, use the second day. For everything else, use the first day. This is the Smarta Dwi-Ekadashi rule, and it's one of those things that sounds arbitrary until you read the Dharmasindhu and realise it's been standardised for centuries.

Dual masa assignment

Every tithi also needs a lunar month label. The Hindu calendar has two competing systems for this. The Amanta system (used in South India and by most reference sources) runs from New Moon to New Moon. The Purnimanta system (used in North India) runs from Full Moon to Full Moon. The same tithi can have different month names depending on which system you use.

For the Amanta months, the engine finds every true New Moon by scanning Sun-Moon elongation for zero-crossings. At each New Moon, it reads the Sun's sidereal longitude to determine the sign. The month is named by the sign the Sun occupies. If two consecutive New Moons have the Sun in the same sign, no Sankranti (solar ingress) occurred during that month, and it is classified as Adhika (intercalary).

// At each pair of consecutive New Moons:
const sunSid1 = toSidereal(sunLongitude(nm1.jd), nm1.jd);
const sunSid2 = toSidereal(sunLongitude(nm2.jd), nm2.jd);
const sign1 = Math.floor(sunSid1 / 30) + 1; // 1-12
const sign2 = Math.floor(sunSid2 / 30) + 1;

// No Sankranti between these two New Moons = Adhika month
const isAdhika = sign1 === sign2;

// Month name comes from the Sun's sign (classical convention)
// Mesha(1) -> Vaishakha, Vrishabha(2) -> Jyeshtha, ... Meena(12) -> Chaitra
const monthName = getHinduMonth(sign1);

This correctly produces Adhika Jyeshtha in 2026, Adhika Chaitra in 2029, and no false Adhika months in 2027. Getting here took three iterations.

The first version tried to derive month boundaries from the tithi scan's Amavasya entries. The Amavasya (tithi #30) starts when the Sun-Moon elongation hits 348 degrees, which is roughly 24 hours before the true conjunction at 0 degrees. I was using the start of the Amavasya tithi as a rough anchor for the New Moon, then refining with a +/- 24 hour search for the minimum elongation. This worked most of the time, but occasionally the refinement converged on the wrong conjunction, producing phantom Adhika months. 2027 showed both Adhika Ashadha and Adhika Shravana, when neither exists.

The second version tried to fix this with a tighter refinement window, but jitter from the elongation function near 0/360 degree crossings made it unreliable.

The third version, which shipped, decouples month detection entirely from the tithi scan. It does its own daily scan of Sun-Moon elongation looking for 360-to-0 crossings, then binary-searches each crossing to sub-minute precision. This gives the exact New Moon moment, from which the Sun's sidereal sign can be reliably read. Two clean phases, no coupling between them.

Eclipse Prediction

An eclipse happens when a New Moon or Full Moon occurs close to one of the lunar nodes. The nodes are the two points where the Moon's orbital plane crosses the ecliptic (the Sun's apparent path). The Moon's orbit is tilted about 5.14 degrees relative to the ecliptic, so most New Moons and Full Moons pass above or below the Sun's disc or Earth's shadow. Only when the Moon is near a node does its latitude become small enough for an eclipse to occur.

In Vedic astronomy these nodes are called Rahu (ascending node) and Ketu (descending node). They drift westward at about 0.053 degrees per day, completing one full cycle every 18.6 years. This is why eclipse seasons shift earlier by about 20 days each year.

The key quantity is the Moon's ecliptic latitude at the moment of conjunction (New Moon) or opposition (Full Moon). If the Moon is right at a node, its latitude is zero and you get a deep, central eclipse. As the Moon moves away from the node, its latitude increases and the eclipse becomes partial, then penumbral (for lunar eclipses), then there's no eclipse at all.

The thresholds depend on the apparent sizes of the Sun, Moon, and Earth's shadow, which in turn depend on the Moon's distance. The Moon's distance varies by about 13% between perigee and apogee. I use the Moon's daily angular speed as a proxy: faster motion means the Moon is closer, which means a larger apparent disc. At average speed (13.2 degrees/day), the Moon's apparent radius is about 0.259 degrees. At perigee (14.5 degrees/day), it's about 0.283 degrees. That difference determines whether a central solar eclipse is total (Moon larger than Sun) or annular (Moon smaller, leaving a ring).

for (const nm of newMoons) {
  const jd = (nm.startJd + nm.endJd) / 2;
  const positions = getPlanetaryPositions(jd);
  const moonPos = positions.find(p => p.id === 1); // Moon
  if (!moonPos) continue;

  const moonLat = Math.abs(moonPos.latitude);
  const moonSpeed = Math.abs(moonPos.speed);

  // Scale thresholds by apparent size (speed is a proxy for distance)
  const speedFactor = moonSpeed / 13.2; // 13.2 deg/day = average
  const partialLimit = 1.25 * speedFactor + 0.26 + 0.15;
  const centralLimit = 0.53 * speedFactor + 0.26 + 0.10;

  if (moonLat < partialLimit) {
    let magnitude: 'total' | 'annular' | 'partial';
    if (moonLat < centralLimit) {
      // Close enough for central: total if Moon is close (fast),
      // annular if Moon is far (slow, smaller apparent disc)
      magnitude = moonSpeed > 13.0 ? 'total' : 'annular';
    } else {
      magnitude = 'partial';
    }

    // Which node? Compare Sun's longitude to Rahu and Ketu
    const rahuLon = positions.find(p => p.id === 7)?.longitude ?? 0;
    const ketuLon = normalizeDeg(rahuLon + 180);
    const distToRahu = angularDistance(sunLongitude(jd), rahuLon);
    const distToKetu = angularDistance(sunLongitude(jd), ketuLon);
    const node = distToRahu < distToKetu ? 'rahu' : 'ketu';

    eclipses.push({ type: 'solar', magnitude, node, date: jdToDate(jd) });
  }
}

The same logic runs for Full Moons with different thresholds. Lunar eclipses have three tiers: the Moon can pass through the penumbra (faint outer shadow), the umbra (dark inner shadow) partially, or the umbra entirely for a total eclipse. The umbral radius at the Moon's distance is roughly 0.72 degrees on average, the penumbral radius roughly 1.28 degrees.

I deliberately set the thresholds wider than the theoretical limits by about 0.15 degrees. This is because the Moon latitude comes from Swiss Ephemeris via the Meeus-derived positions, which have a precision limit of about 0.1 degrees. Generous thresholds ensure we never miss a real eclipse. The trade-off is false positives at the margins.

Hybrid validation

To handle those false positives, the engine cross-checks against a pre-computed table of eclipses from NASA data (2024-2035). Any eclipse the engine finds that does not appear in the table (within one day tolerance) gets discarded. Any eclipse in the table that the engine missed gets injected.

const nasaTable = getEclipsesForYear(year);
if (nasaTable.length > 0) {
  const validated: EclipseEvent[] = [];

  // Keep engine results that match a NASA entry (same type, +/- 1 day)
  for (const e of eclipses) {
    const match = nasaTable.find(t =>
      t.kind === e.type &&
      Math.abs(daysBetween(t.date, e.date)) <= 1
    );
    if (match) validated.push(e);
  }

  // Inject any NASA eclipses the engine missed
  for (const t of nasaTable) {
    const alreadyFound = validated.some(e =>
      e.type === t.kind &&
      Math.abs(daysBetween(t.date, e.date)) <= 1
    );
    if (!alreadyFound) {
      validated.push(buildEclipseFromTable(t));
    }
  }

  return validated;
}

This hybrid approach gives us the best of both worlds. The engine provides the astronomical details (node identification, sidereal longitude, eclipse type classification) while the NASA table provides ground truth on which eclipses actually happen. For years beyond 2035, the engine runs unsupervised, which is fine because its recall is near-perfect. It just occasionally hallucinates a penumbral lunar eclipse at the margins.

One thing worth noting: the Meeus fallback (when Swiss Ephemeris is not available) returns Moon latitude as zero, because the simplified Meeus series only computes longitude and speed, not latitude. In that case, eclipse detection is disabled entirely, because with latitude always zero, every New Moon and Full Moon would register as a total eclipse. The engine logs a warning and returns an empty array rather than returning garbage. This is a deliberate design choice: wrong data is worse than no data.

The Festival Engine

Dussehra was 11 days early. Diwali was 30 days early. Users noticed before I did.

The computation was mathematically correct. Every tithi boundary was accurate to within a minute. The month assignments matched Prokerala. The bug was in one comparison.

Here is the problem. Hindu festivals are defined by lunar calendar coordinates. Dussehra is Ashvina Shukla Dashami (the 10th tithi of the bright fortnight of the month Ashvina). Diwali is Kartika Krishna Amavasya (the New Moon of the dark fortnight of Kartika). To display these on a Gregorian calendar, you scan your tithi table for entries matching the right month + paksha + tithi number.

Every reference source defines festivals using Purnimanta month names. This is the convention used by Prokerala, Drik Panchang, and the traditional almanacs. In my code, each tithi entry has both an Amanta and a Purnimanta month label.

During Shukla Paksha (bright fortnight), both systems agree. Ashvina Shukla Dashami is Ashvina in both Amanta and Purnimanta. No problem.

During Krishna Paksha (dark fortnight), they diverge. The Purnimanta system is one month ahead of Amanta. What Purnimanta calls "Kartika Krishna Amavasya" (Diwali) is "Ashvina Krishna Amavasya" in Amanta.

My code was matching entry.masa.amanta === definition.masa for all festivals. For Shukla Paksha festivals this worked by coincidence, because the two systems agree. For Krishna Paksha festivals, it was looking in the wrong month. Diwali, defined as Kartika in the festival definitions, was being searched in the Amanta column where it's listed as Ashvina. No match. The engine would find a Kartika Amavasya in the Amanta column, but that was actually Purnimanta Kartika which is a full month later. Diwali landed 30 days late. Dussehra, being Shukla Paksha, should have been fine, but a secondary Kala-Vyapti overlap calculation was pulling a date from the wrong month, shifting it by 11 days.

The fix was a branching comparison:

for (const def of MAJOR_FESTIVALS) {
  const tithiNum = defToTithiNumber(def);

  const matches = table.entries.filter(entry => {
    if (entry.number !== tithiNum) return false;
    if (entry.masa.isAdhika) return false; // skip intercalary months

    if (tithiNum <= 15) {
      // Shukla Paksha: Amanta and Purnimanta agree.
      // Match directly against Amanta.
      return entry.masa.amanta === def.masa;
    }

    // Krishna Paksha: definition uses Purnimanta convention,
    // which is one month AHEAD of Amanta.
    // So: Amanta's NEXT month should equal the definition's month.
    return getNextHinduMonth(entry.masa.amanta) === def.masa;
  });

  // ... date resolution, Kala-Vyapti, puja muhurat
}

One function call. getNextHinduMonth maps 'ashvina' to 'kartika', 'kartika' to 'margashirsha', and so on through the twelve-month cycle. Three weeks of confused users, fixed by six characters of code change plus a function call.

The worst part is that I had both month labels available in each tithi entry. The data was right there. I was just reading the wrong column. This is the kind of bug that no amount of type safety catches. TypeScript will happily let you compare entry.masa.amanta with a string that happens to be a Purnimanta month name. Both are string. Both compile. One is wrong.

Kala-Vyapti: when a tithi spans two days

Even after finding the right tithi entry, you sometimes need to decide which of two calendar days to assign the festival to. A tithi lasting 25 hours will straddle two sunrises. Which day is "the" festival day?

The answer depends on the festival. Each festival has a preferred time window, called its Muhurta Rule. Ram Navami should be observed during Madhyahna (the middle fifth of the daytime). Diwali during Pradosh (after sunset). Maha Shivaratri during Nishita Kaal (the eighth muhurta of the night).

The engine computes the overlap of the tithi with the festival's preferred window on both candidate days, then picks the day with greater overlap. Night festivals (Pradosh, Nishita) prefer the earlier day when overlap is equal. Day festivals pick the greater overlap.

// Compute the festival's time window on both candidate days
const win1 = getKalaWindow(day1, lat, lon, timezone, rule);
const win2 = getKalaWindow(day2, lat, lon, timezone, rule);

// Measure tithi overlap with each window (in Julian Day fractions)
const overlap1 = Math.max(0,
  Math.min(tithi.endJd, win1.endJd) - Math.max(tithi.startJd, win1.startJd)
);
const overlap2 = Math.max(0,
  Math.min(tithi.endJd, win2.endJd) - Math.max(tithi.startJd, win2.startJd)
);

if (overlap1 > 0 && overlap2 === 0) {
  festivalDate = day1;
} else if (overlap1 > 0 && overlap2 > 0) {
  // Night festivals (pradosh, nishita) prefer the earlier day
  if (['pradosh', 'nishita'].includes(rule) || overlap1 >= overlap2) {
    festivalDate = day1;
  }
}

This is the Dharmasindhu resolution method. It handles the standard cases well. Edge cases, like a Kshaya tithi (no sunrise within it at all), fall back to the preceding day, which the sunriseDate field already points to.

Ekadashi and Parana: the most complex recurring vrat

Ekadashi (the 11th tithi of each fortnight) deserves special mention because it has the most complex rules of any recurring observance.

There are 24 named Ekadashis per year, each with a specific name tied to its lunar month and paksha. Nirjala Ekadashi in Jyeshtha Shukla, Devshayani in Ashadha Shukla, Kamika in Shravana Krishna, and so on. During Adhika (intercalary) months, the Ekadashis get special names: Kamala for Shukla, Padmini for Krishna.

The fasting rules are strict. You fast from sunrise on Ekadashi day until a specific window the next morning called Parana. The Parana window is bounded by multiple constraints: it must be after Hari Vasara ends (the first quarter of the Dwadashi tithi's duration), it should fall within Pratahkala (the first fifth of daytime), and it must avoid Madhyahna (the middle fifth of daytime). If Hari Vasara ends during Madhyahna, the Parana shifts to after Madhyahna ends.

The engine computes all of this from the tithi table. It reads the Dwadashi entry (the one right after Ekadashi), calculates its duration, derives the Hari Vasara end point, computes the five-fold daytime division from sunrise and sunset, and resolves the optimal window. The output includes the Parana start and end times, sunrise time, Hari Vasara end, Dwadashi end, and Madhyahna boundaries. That is seven separate time calculations for each of the 24 Ekadashis per year.

The scope

The festival engine currently handles 150+ festivals from declarative definitions, 24 named Ekadashis with full Parana calculations, 12 Sankrantis (solar ingress dates), monthly recurring vrats (Pradosham, Chaturthi, Purnima, Amavasya), and puja muhurat windows for major festivals (Diwali Lakshmi Puja during Vrishabha Kaal, Ram Navami during Madhyahna, Maha Shivaratri during Nishita Kaal).

Each festival definition is declarative: a slug, a month name, a paksha, a tithi number, and a muhurta rule. The engine does the rest. Adding a new festival is a single object in an array. No date computation code needs to change.

All of it runs in TypeScript, server-side on initial page load, then cached. No external APIs, no database lookups for festival dates. The tithi table for a full year computes in about 2 seconds on a modern machine. Eclipse detection adds negligible time since it just iterates the New Moon and Full Moon entries that already exist.

What I learned

The Amanta-Purnimanta bug taught me something I keep relearning. The hard part of calendar computation is not the astronomy. The Sun-Moon elongation, the binary search, the node detection, the eclipse thresholds: those are well-defined problems with well-defined solutions. The hard part is the conventions. Two month-naming systems that agree half the time and diverge the other half. Festival definitions that use one convention while your data uses the other. The mismatch is invisible during testing if you only test Shukla Paksha festivals.

I now have a rule: after touching any festival date logic, verify at least three Krishna Paksha festivals against a reference source for the same year and location. If I had done that before shipping, the bug would have been caught in minutes.

The second lesson is about testing coverage. My test suite had tithi accuracy tests (comparing computed times against reference values), Adhika month detection tests, and Ekadashi name resolution tests. All passing. None of them tested a Krishna Paksha festival date end-to-end. The gap was invisible until users reported it.

The third lesson is about the cost of dual conventions in a single system. If I had stored everything in Amanta and done the Purnimanta conversion only at display time, the bug could not have happened. Having both conventions in the data model, with some code reading one column and other code reading the other, created a surface area for exactly this kind of mismatch. I kept both because users need to see both month names, but the festival matching should have been locked to a single convention from the start.

What's next

art 3 will cover the muhurta scoring engine (multi-factor auspiciousness rating for 20+ activities), the KP system (sub-lord theory implemented from Placidus house cusps), and transit prediction. Each of these builds on top of the tithi table and the planetary position engine from Parts 1 and 2. The muhurta engine alone checks seven different inauspicious period types before scoring a time slot, and the KP system requires computing Placidus house cusps from scratch, since no JavaScript library does it accurately for all latitudes.

The full application is live at Dekho Panchang. Everything described here runs in the browser with zero external API calls.

If you have questions about the astronomical algorithms, the Hindu calendar system, or the trade-offs involved in building this kind of engine in the browser, I'm in the comments.

How I Built a Vedic Panchang Engine in TypeScript — Swiss Ephemeris, Meeus Fallback, Zero External APIs

Adi Kumar — Sun, 17 May 2026 09:38:48 +0000

Sub-arcsecond planetary positions, sunrise for any location on Earth, and an entire astronomical calendar — all computed server-side in a Next.js app.

For the past year I've been building Dekho Panchang — an Indian Vedic astrology web app that computes a daily Panchang (the traditional Hindu almanac) for any location on Earth. Every astronomical value — sunrise, sunset, Moon's position, tithis, nakshatras, yogas, karanas — is computed locally on the server. No external ephemeris APIs. No third-party astrology services.

The production engine uses Swiss Ephemeris (sub-arcsecond accuracy, the same library used by professional observatories) with a pure-math Meeus fallback for environments where native modules can't load. This post walks through the architecture and mathematics, with real code from the production codebase.

What Is a Panchang?

A Panchang (पञ्चाङ्ग, literally "five limbs") is the daily Indian almanac. The five limbs are:

Limb	What It Measures	Astronomical Basis
Tithi	Lunar day (1-30)	Moon–Sun elongation ÷ 12°
Nakshatra	Lunar mansion (1-27)	Moon's sidereal longitude ÷ 13°20′
Yoga	Sun-Moon combination (1-27)	(Sun + Moon sidereal) ÷ 13°20′
Karana	Half a tithi (1-11 types)	Moon–Sun elongation ÷ 6°
Vara	Weekday	Julian Day → day of week

Every Hindu festival date, auspicious muhurta (electional window), and fast (vrat) is determined by these five values. Get the Sun or Moon wrong by half a degree, and a festival lands on the wrong day.

The Dual-Engine Architecture

The core design decision: every astronomical function checks for Swiss Ephemeris first, falls back to Meeus if unavailable.

export function sunLongitude(jd: number): number {
  if (isSwissEphAvailable()) {
    return swissPlanetLongitude(jd, 0).longitude; // < 0.001° accuracy
  }
  return _meeusSunLongitude(jd); // ±0.01° fallback
}

export function moonLongitude(jd: number): number {
  if (isSwissEphAvailable()) {
    return swissPlanetLongitude(jd, 1).longitude; // < 0.001° accuracy
  }
  return _meeusMoonLongitude(jd); // ±0.5° fallback
}

Swiss Ephemeris loads as a native Node.js module on the server — it's the sweph npm package wrapping the C library from the Astronomical Institute at the University of Zurich. On the client side or in edge runtimes where native modules can't load, Meeus kicks in automatically.

Engine	Sun	Moon	Outer Planets	Where It Runs
Swiss Ephemeris	±0.001°	±0.001°	±0.001°	Server (Node.js) — primary
Meeus	±0.01°	±0.5°	±1-3°	Browser/Edge — fallback

The Swiss Ephemeris integration includes a memoisation cache (keyed on JD rounded to 6 decimals) to avoid redundant calls — a single panchang computation queries the same JD dozens of times for different planets:

const planetCache = new Map<string, PlanetResult>();
const CACHE_MAX = 500;

function cacheKey(jd: number, planetId?: number): string {
  return `${jd.toFixed(6)}${planetId !== undefined ? `:${planetId}` : ''}`;
}

Step 1: Julian Day — The Universal Time Counter

Both engines start by converting a calendar date to a Julian Day Number — a continuous day count used by astronomers since 1583. JD 2451545.0 = 1 January 2000, 12:00 UT (the J2000.0 epoch).

The algorithm comes from Jean Meeus's Astronomical Algorithms (Ch.7):

export function dateToJD(
  year: number, month: number, day: number, hour: number = 0
): number {
  // Meeus convention: Jan/Feb treated as months 13/14 of prior year
  if (month <= 2) { year -= 1; month += 12; }
  // Gregorian correction for the 10-day gap
  const A = Math.floor(year / 100);
  const B = 2 - A + Math.floor(A / 4);
  return Math.floor(365.25 * (year + 4716))
    + Math.floor(30.6001 * (month + 1))
    + day + hour / 24 + B - 1524.5;
}

Everything downstream — Sun position, Moon position, sunrise — takes a JD as input. Swiss Ephemeris has its own swe_julday function, but ours matches it to 10 decimal places.

Step 2: The Meeus Fallback — How It Works

When Swiss Ephemeris isn't available, the Meeus algorithms handle everything. Here's the Sun's position via Meeus Ch.25:

function _meeusSunLongitude(jd: number): number {
  const t = (jd - 2451545.0) / 36525.0; // Julian centuries from J2000.0

  // Geometric mean longitude
  const L0 = normalizeDeg(280.46646 + 36000.76983 * t + 0.0003032 * t * t);
  // Mean anomaly — angle from perihelion
  const M = normalizeDeg(357.52911 + 35999.05029 * t - 0.0001537 * t * t);
  const Mrad = M * Math.PI / 180;

  // Equation of centre — correction for elliptical orbit
  const C = (1.914602 - 0.004817 * t) * Math.sin(Mrad)
    + (0.019993 - 0.000101 * t) * Math.sin(2 * Mrad)
    + 0.000289 * Math.sin(3 * Mrad);

  const sunTrue = normalizeDeg(L0 + C);

  // Nutation + aberration correction
  const omega = 125.04 - 1934.136 * t;
  return normalizeDeg(sunTrue - 0.00569
    - 0.00478 * Math.sin(omega * Math.PI / 180));
}

The dominant term (1.9146°) in the equation of centre reflects Earth's orbital eccentricity (~0.017). The Sun moves ~1°/day, so ±0.01° accuracy means we're within ~14 seconds of the true position.

The Moon is more complex — Meeus Ch.47 implements a truncated ELP-2000/82 lunar theory with 60 periodic terms:

function _meeusMoonLongitude(jd: number): number {
  const t = (jd - 2451545.0) / 36525.0;

  // Four fundamental arguments (degrees)
  const Lp = normalizeDeg(218.3164477 + 481267.88123421 * t
    - 0.0015786 * t * t + t**3 / 538841);
  const D  = normalizeDeg(297.8501921 + 445267.1114034 * t
    - 0.0018819 * t * t + t**3 / 545868);
  const M  = normalizeDeg(357.5291092 + 35999.0502909 * t
    - 0.0001536 * t * t);
  const Mp = normalizeDeg(134.9633964 + 477198.8675055 * t
    + 0.0087414 * t * t + t**3 / 69699);
  const F  = normalizeDeg(93.2720950 + 483202.0175233 * t
    - 0.0036539 * t * t);

  // Sum 60 periodic terms: each is sin(aD + bM + cMp + dF) × coefficient
  let sumL = 0;
  for (const [coeffD, coeffM, coeffMp, coeffF, sinCoeff] of MOON_TERMS) {
    const arg = coeffD * D + coeffM * M + coeffMp * Mp + coeffF * F;
    sumL += sinCoeff * Math.sin(arg * Math.PI / 180);
  }

  // Planetary corrections (Venus, Jupiter perturbations)
  const A1 = normalizeDeg(119.75 + 131.849 * t);
  const A2 = normalizeDeg(53.09 + 479264.290 * t);
  sumL += 3958 * Math.sin(A1 * Math.PI / 180)
       + 1962 * Math.sin((Lp - F) * Math.PI / 180)
       + 318  * Math.sin(A2 * Math.PI / 180);

  return normalizeDeg(Lp + sumL / 1_000_000);
}

The Moon's orbit is perturbed by the Sun, Jupiter, and the non-spherical Earth. Even this 60-term truncation gives ±0.5° — well within the 13°20' span of each nakshatra. In production, Swiss Ephemeris handles the Moon with full precision.

Step 3: Tropical → Sidereal (The Ayanamsha Bridge)

Western astronomy uses the tropical zodiac (anchored to the vernal equinox). Indian astronomy uses the sidereal zodiac (anchored to fixed stars). The difference is called ayanamsha — the accumulated precession of the equinoxes.

Swiss Ephemeris has built-in ayanamsha computation for multiple systems. Our fallback uses the Lahiri (Chitrapaksha) polynomial, anchoring the star Spica (Chitra) at exactly 180° sidereal:

export function lahiriAyanamsha(jd: number): number {
  if (isSwissEphAvailable()) {
    return swissAyanamsha(jd); // Uses SE_SIDM_LAHIRI mode
  }
  const t = (jd - 2451545.0) / 36525.0;
  // ~50.29 arcseconds/year precession rate
  return 23.85306 + 1.39722 * t + 0.00018 * t * t;
}

function toSidereal(tropicalLong: number, jd: number): number {
  return normalizeDeg(tropicalLong - lahiriAyanamsha(jd));
}

In 2026, the ayanamsha is approximately 24.2° — meaning the tropical and sidereal zodiacs differ by nearly a full sign. This is why your "Sun sign" in Western astrology is often one sign ahead of your Vedic rashi.

Step 4: Computing the Five Limbs

With Sun and Moon positions in sidereal coordinates, the five Panchang elements are straightforward:

// Tithi: 30 lunar days per synodic month
// Each tithi = 12° of Moon-Sun elongation
function calculateTithi(jd: number): { number: number; degree: number } {
  const sunSid = toSidereal(sunLongitude(jd), jd);
  const moonSid = toSidereal(moonLongitude(jd), jd);
  const diff = normalizeDeg(moonSid - sunSid); // 0° = new moon, 180° = full
  return { number: Math.floor(diff / 12) + 1, degree: diff };
}

// Nakshatra: Moon's sidereal position in 27 equal divisions
function getNakshatraNumber(moonSidereal: number): number {
  return Math.floor(moonSidereal / (360 / 27)) + 1; // 1-27
}

// Yoga: sum of Sun + Moon sidereal longitudes, divided by 13°20'
function calculateYoga(jd: number): number {
  const sunSid = toSidereal(sunLongitude(jd), jd);
  const moonSid = toSidereal(moonLongitude(jd), jd);
  const sum = normalizeDeg(sunSid + moonSid);
  return Math.floor(sum / (360 / 27)) + 1; // 1-27
}

// Karana: half a tithi — each 6° arc of Moon-Sun elongation
// 7 repeating types cycle through 56 slots, 4 fixed types fill the edges
function calculateKarana(jd: number): number {
  const { degree } = calculateTithi(jd);
  const idx = Math.floor(degree / 6);
  if (idx === 0) return 11;         // Kimstughna
  if (idx >= 57) return [8, 9, 10][idx - 57]; // Shakuni, Chatushpada, Naga
  return ((idx - 1) % 7) + 1;       // Bava through Vishti cycle
}

These functions are engine-agnostic — they call sunLongitude() and moonLongitude(), which internally route to Swiss Ephemeris or Meeus. The panchang logic itself doesn't know or care which engine produced the positions.

Step 5: Sunrise — The Panchang Day Boundary

In Vedic tradition, the panchang day runs sunrise to sunrise (not midnight to midnight). All five limbs are evaluated at the moment of sunrise. Swiss Ephemeris provides precise sunrise via atmospheric refraction models, but the Meeus fallback solves the hour angle equation directly (Meeus Ch.15):

cos(H) = (sin(-0.8333°) - sin(lat) × sin(δ)) / (cos(lat) × cos(δ))

Where -0.8333° accounts for atmospheric refraction (34 arcminutes) and the Sun's semi-diameter (16 arcminutes). Then sunrise = solar noon − H/15 hours.

function approximateSunrise(jd: number, lat: number, lng: number): number | null {
  if (isSwissEphAvailable()) {
    return swissSunrise(jd, lat, lng); // ±10 seconds accuracy
  }

  // Meeus fallback: ±2 minutes accuracy
  const T = (jd - 2451545.0) / 36525;
  const obliquity = 23.4393 - 0.0130 * T;
  const sunLong = _meeusSunLongitude(jd);
  const decl = toDeg(Math.asin(
    Math.sin(toRad(obliquity)) * Math.sin(toRad(sunLong))
  ));

  const cosH = (Math.sin(toRad(-0.8333)) - Math.sin(toRad(lat)) * Math.sin(toRad(decl)))
    / (Math.cos(toRad(lat)) * Math.cos(toRad(decl)));
  if (cosH > 1 || cosH < -1) return null; // Polar — no sunrise

  const H = toDeg(Math.acos(cosH));

  // Equation of Time: corrects for orbital eccentricity + obliquity
  const y2 = Math.tan(toRad(obliquity / 2)) ** 2;
  const L0 = toRad(280.46646 + 36000.76983 * T);
  const M = toRad(357.52911 + 35999.05029 * T);
  const e = 0.016708634 - 0.000042037 * T;
  const eot = toDeg(
    y2 * Math.sin(2 * L0) - 2 * e * Math.sin(M)
    + 4 * e * y2 * Math.sin(M) * Math.cos(2 * L0)
    - 0.5 * y2 * y2 * Math.sin(4 * L0)
    - 1.25 * e * e * Math.sin(2 * M)
  ) * 4; // minutes

  const solarNoon = (720 - 4 * lng - eot) / 60;
  return ((solarNoon - H / 15) % 24 + 24) % 24; // UT hours
}

The Equation of Time (up to ±16 minutes) corrects for two effects: Earth's orbital eccentricity makes the Sun appear to speed up and slow down, and the obliquity of the ecliptic means equal ecliptic arcs don't correspond to equal time intervals.

How Accurate Is It?

We run automated regression tests on every commit for Bern (UTC+1/+2), Delhi (UTC+5:30), and Seattle (UTC-7/-8) — covering DST transitions, half-hour offsets, and western hemisphere edge cases.

Element	Swiss Ephemeris (production)	Meeus Fallback
Sunrise/Sunset	±10 seconds	±2 minutes
Moonrise/Moonset	±30 seconds	±5 minutes
Tithi transition	±1 second	±1 minute
Nakshatra transition	±1 second	±1 minute
Yoga / Karana	Exact	Exact (within element span)
Planet longitudes	< 1 arcsecond	Sun ±36″, Moon ±30′

// From our actual test suite
it('sunrise within 2 min of reference', () =>
  assertWithinMinutes('sunrise', computed.sunrise, reference.sunrise, 2));

it('tithi end time within 2 min', () =>
  assertWithinMinutes('tithi end', computed.tithiEnd, reference.tithiEnd, 2));

Hard Lessons from Production

Building this over the past year, I've catalogued 63+ bugs across 6 audit rounds. Some highlights:

The Timezone Trap

// BAD: Creates date in server's local timezone (UTC on Vercel, UTC+2 on my laptop)
const d = new Date(1990, 2, 15, 10, 30);

// GOOD: Always use UTC explicitly
const d = new Date(Date.UTC(1990, 2, 15, 10, 30));

Every single new Date(year, month, day) call in computation code is a landmine. On Vercel (UTC), it works fine. On a dev machine in Switzerland (UTC+2), birth time 10:30 IST silently becomes 10:30 CET — and your dasha dates drift by 5.5 hours.

The Sidereal Double-Subtraction

Moon's longitude from Swiss Ephemeris is already sidereal (ayanamsha pre-subtracted). One module re-derived the nakshatra by subtracting ayanamsha again. Result: Moon appeared to be in the wrong nakshatra — off by nearly a full mansion. The fix: always use the stored .nakshatra.id or .sign instead of re-deriving from longitude.

Midnight-Crossing Time Ranges

Rahu Kaal might run 23:30–01:15. A naïve now >= start && now < end check never triggers because start > end. The fix:

function isTimeActive(now: number, start: number, end: number): boolean {
  if (end < start) return now >= start || now < end; // Wraps past midnight
  return now >= start && now < end;
}

This same bug appeared in three separate components before we found all instances.

Fixed Intervals for Lunar Phenomena

// WRONG: Moon's orbit is elliptical — intervals vary 13.9 to 15.6 days
const fullMoonDate = newMoonDate + 15 * DAY_MS;

// RIGHT: Binary search for the actual Moon-Sun elongation = 180°
function findFullMoon(startJd: number): number {
  // Newton-Raphson or bisection on moonSid - sunSid = 180°
}

We shipped Purnimant month boundaries that used a fixed 15-day offset from New Moon. Result: months started on Ashtami instead of Purnima. The Moon's elliptical orbit means this interval varies by nearly 2 days.

The Stack

Framework: Next.js 16 (App Router, React 19, TypeScript)
Primary engine: Swiss Ephemeris via sweph npm package (sub-arcsecond, 5400 BC – 5400 AD)
Fallback engine: ~3,000 lines of Meeus algorithms (pure TypeScript, no native deps)
Deployment: Vercel with ISR (revalidate every 24 hours)
Testing: Vitest with automated regression across 3 timezone locations

The entire panchang calculation runs in ~15ms on a cold start. No network requests, no API keys, no rate limits.

Try It

dekhopanchang.com — free, no signup needed. Enter any location and get the complete Panchang with all five limbs, sunrise/sunset, Rahu Kaal, auspicious windows, and more.

The full computation engine handles:

Daily Panchang for any location globally
Birth charts (Kundali) with 9 planets, 12 houses, and interpretive commentary
Dasha systems (Vimshottari, Yogini, Chara, and 5 more)
80+ yoga detections with classical source references
Festival calendar with Amanta/Purnimanta month support
Muhurta (electional astrology) with multi-factor scoring
Compatibility matching (Ashta Kuta, 36 points)

All computed from first principles. No black boxes.

If you're interested in astronomical computing, celestial mechanics, or the intersection of ancient knowledge systems and modern engineering — I'd love to hear your thoughts in the comments.

The codebase handles 142 pages across multiple locales, serves users from Seattle to Delhi to Bern, and every number on every page is computed fresh from orbital equations. It's the most fun I've had with trigonometry since university.
`