jyotish-calc 1.2.0 → 1.3.0

package/src/panchanga/karana.js

@@ -0,0 +1,185 @@
+/**
+ * Karana (Half-Tithi) Calculations
+ * Karana = half of a tithi (6 degrees of moon-sun separation)
+ * 60 karanas in a lunar month (11 types cycling through fixed positions)
+ */
+
+const tithiModule = require('./tithi');
+const utils = require('./utils');
+const { KARANA_NAMES, ONE_TITHI } = require('./constants');
+
+/**
+ * Get karana number and name
+ * There are 11 types of karanas:
+ * - 4 Fixed (Shakuni, Chatushpada, Naga, Kimstughna) - occur once each
+ * - 7 Repeating (Bava, Balava, Kaulava, Taitila, Garaja, Vanija, Vishti) - repeat 8 times each
+ * 
+ * Distribution in 60 karanas:
+ * K1=Kimstughna (1st half of Shukla Pratipada)
+ * K2-K57: Bava to Vishti repeating 8 times
+ * K58=Shakuni, K59=Chatushpada, K60=Naga
+ */
+
+/**
+ * Get karana type (fixed or repeating) and name
+ * @param {number} karanaNo - Karana number (1-60)
+ * @returns {object} {number, name, type}
+ */
+function getKaranaInfo(karanaNo) {
+    // Normalize to 1-60
+    const k = ((karanaNo - 1) % 60) + 1;
+
+    let name, type;
+
+    if (k === 1) {
+        name = 'Kimstughna';
+        type = 'fixed';
+    } else if (k === 58) {
+        name = 'Shakuni';
+        type = 'fixed';
+    } else if (k === 59) {
+        name = 'Chatushpada';
+        type = 'fixed';
+    } else if (k === 60) {
+        name = 'Naga';
+        type = 'fixed';
+    } else {
+        // Repeating karanas (k=2 to k=57)
+        // Bava(0), Balava(1), Kaulava(2), Taitila(3), Garaja(4), Vanija(5), Vishti(6)
+        const repeatIndex = (k - 2) % 7;
+        const repeatNames = ['Bava', 'Balava', 'Kaulava', 'Taitila', 'Garaja', 'Vanija', 'Vishti'];
+        name = repeatNames[repeatIndex];
+        type = 'repeating';
+
+        // Vishti (Bhadra) is considered inauspicious
+        if (name === 'Vishti') {
+            type = 'inauspicious';
+        }
+    }
+
+    return { number: k, name, type };
+}
+
+/**
+ * Get karana from tithi
+ * @param {number} tithiNo - Tithi number (1-30)
+ * @param {boolean} firstHalf - True for first half of tithi
+ * @returns {number} Karana number (1-60)
+ */
+function karanaFromTithi(tithiNo, firstHalf = true) {
+    // Each tithi has 2 karanas
+    const baseKarana = (tithiNo - 1) * 2 + 1;
+    return firstHalf ? baseKarana : baseKarana + 1;
+}
+
+/**
+ * Get karana details for given date/time
+ * @param {number} jd - Julian Day Number (local)
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} Karana details
+ */
+function karana(jd, place) {
+    // Get tithi info
+    const tithiInfo = tithiModule.tithi(jd, place);
+    if (!tithiInfo) return null;
+
+    const { year, month, day, hour } = utils.jdToDate(jd);
+    const currentHours = hour;
+
+    // Calculate midpoint of tithi (when karana changes)
+    const tithiMid = (tithiInfo.startTime + tithiInfo.endTime) / 2;
+
+    // Determine which half of tithi we're in
+    const isFirstHalf = currentHours <= tithiMid || tithiInfo.startTime < 0;
+    const karanaNo = karanaFromTithi(tithiInfo.number, isFirstHalf);
+    const karanaInfo = getKaranaInfo(karanaNo);
+
+    // Calculate karana start and end times
+    let startTime, endTime;
+    if (isFirstHalf) {
+        startTime = tithiInfo.startTime;
+        endTime = tithiMid;
+    } else {
+        startTime = tithiMid;
+        endTime = tithiInfo.endTime;
+    }
+
+    // Handle negative start time (from previous day)
+    if (startTime < 0) {
+        startTime = startTime + 24;
+    }
+
+    return {
+        number: karanaNo,
+        name: karanaInfo.name,
+        type: karanaInfo.type,
+        startTime,
+        endTime,
+        startTimeString: utils.formatTime(startTime),
+        endTimeString: utils.formatTime(endTime > 24 ? endTime - 24 : endTime) + (endTime > 24 ? ' (+1)' : ''),
+        isVishti: karanaInfo.name === 'Vishti',
+        tithi: tithiInfo.number,
+        halfOfTithi: isFirstHalf ? 'first' : 'second'
+    };
+}
+
+/**
+ * Check if karana is Vishti (Bhadra) - inauspicious
+ * @param {number} karanaNo - Karana number
+ * @returns {boolean} True if Vishti
+ */
+function isVishti(karanaNo) {
+    const info = getKaranaInfo(karanaNo);
+    return info.name === 'Vishti';
+}
+
+/**
+ * Get all karanas for a day
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {array} List of karanas for the day
+ */
+function karanasForDay(jd, place) {
+    const tithiInfo = tithiModule.tithi(jd, place);
+    if (!tithiInfo) return [];
+
+    const karanas = [];
+
+    // First karana (first half of current tithi)
+    const mid = (tithiInfo.startTime + tithiInfo.endTime) / 2;
+    const k1 = karanaFromTithi(tithiInfo.number, true);
+    const k1Info = getKaranaInfo(k1);
+
+    if (tithiInfo.startTime < mid && mid < 24) {
+        karanas.push({
+            number: k1,
+            name: k1Info.name,
+            startTime: tithiInfo.startTime < 0 ? tithiInfo.startTime + 24 : tithiInfo.startTime,
+            endTime: mid
+        });
+    }
+
+    // Second karana (second half of current tithi)
+    const k2 = karanaFromTithi(tithiInfo.number, false);
+    const k2Info = getKaranaInfo(k2);
+
+    if (mid < tithiInfo.endTime) {
+        karanas.push({
+            number: k2,
+            name: k2Info.name,
+            startTime: mid,
+            endTime: tithiInfo.endTime > 24 ? tithiInfo.endTime - 24 : tithiInfo.endTime
+        });
+    }
+
+    return karanas;
+}
+
+module.exports = {
+    karana,
+    karanaFromTithi,
+    getKaranaInfo,
+    isVishti,
+    karanasForDay,
+    KARANA_NAMES
+};

package/src/panchanga/lunar-calendar.js

@@ -0,0 +1,207 @@
+/**
+ * Lunar Calendar Functions
+ * Lunar month, adhika detection, new/full moon, etc.
+ */
+
+const sunriseSunset = require('./sunrise-sunset');
+const tithiModule = require('./tithi');
+const utils = require('./utils');
+const { LUNAR_MONTH_NAMES, SIDEREAL_YEAR, KALI_YUGA_JD } = require('./constants');
+
+/**
+ * Get lunar month for given date
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} Lunar month details
+ */
+function lunarMonth(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    if (!rise) return null;
+
+    const jdUTC = utils.toUTC(rise.jd, place.timezone);
+    const currentTithi = tithiModule.quickTithi(jdUTC);
+
+    // Find last and next new moons
+    const lastNewMoon = tithiModule.newMoon(jdUTC, currentTithi, -1);
+    const nextNewMoon = tithiModule.newMoon(jdUTC, currentTithi, +1);
+
+    // Get solar month (raasi) at each new moon
+    const thisSolarMonth = Math.floor(sunriseSunset.solarLongitude(lastNewMoon) / 30);
+    const nextSolarMonth = Math.floor(sunriseSunset.solarLongitude(nextNewMoon) / 30);
+
+    // If both new moons are in same solar month, it's an adhika (leap) month
+    const isAdhika = (thisSolarMonth === nextSolarMonth);
+
+    // Lunar month is named after the solar month at the start
+    const lunarMonthIndex = (thisSolarMonth + 1) % 12;
+
+    // Check for nija (second occurrence after adhika)
+    let isNija = false;
+    if (!isAdhika) {
+        const prevMonthData = lunarMonth(jd - 30, place);
+        if (prevMonthData && prevMonthData.index === lunarMonthIndex && prevMonthData.isAdhika) {
+            isNija = true;
+        }
+    }
+
+    return {
+        index: lunarMonthIndex,
+        number: lunarMonthIndex + 1, // 1-12
+        name: LUNAR_MONTH_NAMES[lunarMonthIndex],
+        isAdhika,
+        isNija,
+        prefix: isAdhika ? 'Adhika ' : (isNija ? 'Nija ' : ''),
+        fullName: (isAdhika ? 'Adhika ' : (isNija ? 'Nija ' : '')) + LUNAR_MONTH_NAMES[lunarMonthIndex],
+        lastNewMoon: utils.jdToDate(lastNewMoon),
+        nextNewMoon: utils.jdToDate(nextNewMoon)
+    };
+}
+
+/**
+ * Get complete lunar date (month + day + year)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @param {boolean} usePurnimanta - Use Purnimanta system (month ends at full moon)
+ * @returns {object} Complete lunar date
+ */
+function lunarDate(jd, place, usePurnimanta = false) {
+    const month = lunarMonth(jd, place);
+    const tithiInfo = tithiModule.tithi(jd, place);
+
+    if (!month || !tithiInfo) return null;
+
+    let lunarDay = tithiInfo.number;
+    let monthIndex = month.index;
+
+    // In Purnimanta system, month changes at full moon (tithi 15)
+    if (usePurnimanta) {
+        if (lunarDay > 15) {
+            monthIndex = (monthIndex + 1) % 12;
+            lunarDay = (lunarDay - 16) % 30 + 1;
+        }
+    }
+
+    // Calculate lunar year (Samvatsara)
+    const yearIndex = lunarYearIndex(jd, monthIndex + 1);
+
+    return {
+        month: monthIndex + 1,
+        monthName: LUNAR_MONTH_NAMES[monthIndex],
+        day: lunarDay,
+        tithiName: tithiInfo.name,
+        paksha: tithiInfo.paksha,
+        year: yearIndex,
+        isAdhika: month.isAdhika,
+        isNija: month.isNija,
+        system: usePurnimanta ? 'Purnimanta' : 'Amanta'
+    };
+}
+
+/**
+ * Calculate lunar year index (0-59 Samvatsara cycle)
+ * @param {number} jd - Julian Day Number
+ * @param {number} maasaIndex - Lunar month (1-12)
+ * @returns {number} Year index in 60-year cycle
+ */
+function lunarYearIndex(jd, maasaIndex) {
+    const kali = elapsedKaliYears(jd, maasaIndex);
+    const kaliBase = 14;
+    const kaliStart = 27; // Pramaadhi
+
+    let adjustedKali = kali;
+    if (kali >= 4009) {
+        adjustedKali = (kali - kaliBase) % 60;
+    }
+
+    const samvatIndex = (adjustedKali + kaliStart + Math.floor((adjustedKali * 211 - 108) / 18000)) % 60;
+    return samvatIndex - 1;
+}
+
+/**
+ * Calculate elapsed Kali Yuga years
+ * @param {number} jd - Julian Day Number
+ * @param {number} maasaIndex - Month index (1-12)
+ * @returns {number} Kali year number
+ */
+function elapsedKaliYears(jd, maasaIndex) {
+    const ahar = jd - KALI_YUGA_JD;
+    return Math.floor((ahar + (4 - maasaIndex) * 30) / SIDEREAL_YEAR);
+}
+
+/**
+ * Calculate era years (Kali, Vikrama, Saka)
+ * @param {number} jd - Julian Day Number
+ * @param {number} maasaIndex - Month index
+ * @returns {object} {kali, vikrama, saka}
+ */
+function eraYears(jd, maasaIndex) {
+    const kali = elapsedKaliYears(jd, maasaIndex);
+    const saka = kali - 3179;
+    const vikrama = saka + 135;
+    return { kali, vikrama, saka };
+}
+
+/**
+ * Get next lunar month start date
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @param {number} direction - 1 for next, -1 for previous
+ * @returns {object} {date, time}
+ */
+function nextLunarMonthStart(jd, place, direction = 1) {
+    const currentTithi = tithiModule.quickTithi(utils.toUTC(jd, place.timezone));
+    const newMoonJD = tithiModule.newMoon(jd, currentTithi, direction);
+
+    // Get tithi at new moon to find exact start
+    const tithiAtNewMoon = tithiModule.tithi(newMoonJD + place.timezone / 24, place);
+
+    if (!tithiAtNewMoon) return null;
+
+    const date = utils.jdToDate(newMoonJD + place.timezone / 24);
+
+    return {
+        year: date.year,
+        month: date.month,
+        day: Math.floor(date.day),
+        hours: tithiAtNewMoon.endTime,
+        jd: newMoonJD
+    };
+}
+
+/**
+ * Calculate Ritu (season) from lunar month
+ * @param {number} monthIndex - Lunar month (0-11 or 1-12)
+ * @returns {object} Ritu details
+ */
+function ritu(monthIndex) {
+    // Normalize to 0-11
+    const idx = monthIndex > 0 && monthIndex <= 12 ? monthIndex - 1 : monthIndex;
+    const rituIndex = Math.floor(idx / 2);
+
+    const rituNames = ['Vasanta', 'Grishma', 'Varsha', 'Sharad', 'Hemanta', 'Shishira'];
+    const rituDescriptions = [
+        'Spring (Chaitra-Vaishakha)',
+        'Summer (Jyeshtha-Ashadha)',
+        'Monsoon (Shravana-Bhadrapada)',
+        'Autumn (Ashwin-Kartik)',
+        'Pre-winter (Margashirsha-Pausha)',
+        'Winter (Magha-Phalguna)'
+    ];
+
+    return {
+        index: rituIndex,
+        name: rituNames[rituIndex],
+        description: rituDescriptions[rituIndex]
+    };
+}
+
+module.exports = {
+    lunarMonth,
+    lunarDate,
+    lunarYearIndex,
+    elapsedKaliYears,
+    eraYears,
+    nextLunarMonthStart,
+    ritu,
+    LUNAR_MONTH_NAMES
+};