jyotish-calc 1.2.0 → 1.3.0

package/src/panchanga/muhurtas.js

@@ -0,0 +1,370 @@
+/**
+ * Muhurta (Auspicious/Inauspicious Time Periods)
+ * Various time divisions used in Vedic astrology
+ */
+
+const sunriseSunset = require('./sunrise-sunset');
+const vaaraModule = require('./vaara');
+const utils = require('./utils');
+const {
+    RAAHU_KAALAM_OFFSETS, GULIKAI_OFFSETS, YAMAGANDAM_OFFSETS,
+    DURMUHURTAM_OFFSETS, GAURI_CHOGHADIYA_DAY, GAURI_CHOGHADIYA_NIGHT,
+    CHOGHADIYA_NAMES, DAY_RULERS, NIGHT_RULERS
+} = require('./constants');
+
+/**
+ * Calculate Trikalam (Raahu Kaalam, Yamagandam, Gulikai)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @param {string} type - 'raahu', 'yamagandam', or 'gulikai'
+ * @returns {object} {startTime, endTime, startString, endString}
+ */
+function trikalam(jd, place, type = 'raahu') {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+    const weekday = vaaraModule.vaara(jd).number;
+
+    if (!rise) return null;
+
+    let offsets;
+    switch (type.toLowerCase()) {
+        case 'raahu':
+        case 'raahukaalam':
+            offsets = RAAHU_KAALAM_OFFSETS;
+            break;
+        case 'gulikai':
+        case 'gulikaikaalam':
+            offsets = GULIKAI_OFFSETS;
+            break;
+        case 'yamagandam':
+        case 'yamagandakaalam':
+            offsets = YAMAGANDAM_OFFSETS;
+            break;
+        default:
+            offsets = RAAHU_KAALAM_OFFSETS;
+    }
+
+    const startTime = rise.hours + dayDur * offsets[weekday];
+    const endTime = startTime + 0.125 * dayDur; // 1/8 of day
+
+    return {
+        startTime,
+        endTime,
+        startString: utils.formatTime(startTime),
+        endString: utils.formatTime(endTime),
+        duration: endTime - startTime
+    };
+}
+
+// Convenience functions
+const raahuKaalam = (jd, place) => trikalam(jd, place, 'raahu');
+const yamagandaKaalam = (jd, place) => trikalam(jd, place, 'yamagandam');
+const gulikaiKaalam = (jd, place) => trikalam(jd, place, 'gulikai');
+
+/**
+ * Calculate Abhijit Muhurta (most auspicious - 8th muhurta around noon)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {startTime, endTime}
+ */
+function abhijitMuhurta(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+
+    if (!rise) return null;
+
+    // Abhijit = 7/15 to 8/15 of day (8th of 15 day muhurtas)
+    const startTime = rise.hours + (7 / 15) * dayDur;
+    const endTime = rise.hours + (8 / 15) * dayDur;
+
+    return {
+        startTime,
+        endTime,
+        startString: utils.formatTime(startTime),
+        endString: utils.formatTime(endTime),
+        duration: endTime - startTime
+    };
+}
+
+/**
+ * Calculate Durmuhurtam (inauspicious muhurta)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {array} List of durmuhurtam periods
+ */
+function durmuhurtam(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const set = sunriseSunset.sunset(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+    const nightDur = sunriseSunset.nightLength(jd, place);
+    const weekday = vaaraModule.vaara(jd).number;
+
+    if (!rise || !set) return [];
+
+    const offsets = DURMUHURTAM_OFFSETS[weekday];
+    const results = [];
+
+    // Duration of one durmuhurtam = 0.8/12 of day
+    const durDuration = dayDur * 0.8 / 12;
+
+    for (let i = 0; i < offsets.length; i++) {
+        if (offsets[i] === 0.0) continue;
+
+        let base, dur;
+        // Tuesday's second durmuhurtam uses night duration
+        if (weekday === 2 && i === 1) {
+            base = set.hours;
+            dur = nightDur;
+        } else {
+            base = rise.hours;
+            dur = dayDur;
+        }
+
+        const startTime = base + dur * offsets[i] / 12;
+        const endTime = startTime + durDuration;
+
+        results.push({
+            startTime,
+            endTime,
+            startString: utils.formatTime(startTime),
+            endString: utils.formatTime(endTime)
+        });
+    }
+
+    return results;
+}
+
+/**
+ * Calculate Brahma Muhurta (pre-dawn auspicious period)
+ * 2 muhurtas before sunrise
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {startTime, endTime}
+ */
+function brahmaMuhurta(jd, place) {
+    const nightDur = sunriseSunset.nightLength(jd - 1, place);
+    const rise = sunriseSunset.sunrise(jd, place);
+
+    if (!rise) return null;
+
+    const muhurtaDur = nightDur / 15; // One night muhurta
+    const startTime = rise.hours - 2 * muhurtaDur;
+    const endTime = rise.hours - muhurtaDur;
+
+    return {
+        startTime: startTime < 0 ? startTime + 24 : startTime,
+        endTime: endTime < 0 ? endTime + 24 : endTime,
+        startString: utils.formatTime(startTime < 0 ? startTime + 24 : startTime),
+        endString: utils.formatTime(endTime < 0 ? endTime + 24 : endTime)
+    };
+}
+
+/**
+ * Calculate Godhuli Muhurta (cow-dust time around sunset)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {startTime, endTime}
+ */
+function godhuliMuhurta(jd, place) {
+    const set = sunriseSunset.sunset(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+    const nightDur = sunriseSunset.nightLength(jd, place);
+
+    if (!set) return null;
+
+    const dayMuhurta = dayDur / 15;
+    const nightMuhurta = nightDur / 15;
+
+    const startTime = set.hours - 0.25 * dayMuhurta;
+    const endTime = set.hours + 0.25 * nightMuhurta;
+
+    return {
+        startTime,
+        endTime,
+        startString: utils.formatTime(startTime),
+        endString: utils.formatTime(endTime)
+    };
+}
+
+/**
+ * Calculate Vijaya Muhurta (victory time - around noon and midnight)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {day, night} - both periods
+ */
+function vijayaMuhurta(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const set = sunriseSunset.sunset(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+    const nightDur = sunriseSunset.nightLength(jd, place);
+
+    if (!rise || !set) return null;
+
+    const dayGhati = dayDur / 30;
+    const nightGhati = nightDur / 30;
+
+    const noon = rise.hours + dayDur / 2;
+    const midnight = set.hours + nightDur / 2;
+
+    return {
+        day: {
+            startTime: noon - dayGhati,
+            endTime: noon + dayGhati,
+            startString: utils.formatTime(noon - dayGhati),
+            endString: utils.formatTime(noon + dayGhati)
+        },
+        night: {
+            startTime: midnight - nightGhati,
+            endTime: midnight + nightGhati,
+            startString: utils.formatTime((midnight - nightGhati) % 24),
+            endString: utils.formatTime((midnight + nightGhati) % 24)
+        }
+    };
+}
+
+/**
+ * Calculate Nishita Kaala (8th muhurta of night)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {startTime, endTime}
+ */
+function nishitaKaala(jd, place) {
+    const set = sunriseSunset.sunset(jd, place);
+    const nightDur = sunriseSunset.nightLength(jd, place);
+
+    if (!set) return null;
+
+    const nightGhati = nightDur / 30;
+    const startTime = set.hours + 7 * nightGhati;
+    const endTime = set.hours + 8 * nightGhati;
+
+    return {
+        startTime: startTime % 24,
+        endTime: endTime % 24,
+        startString: utils.formatTime(startTime % 24),
+        endString: utils.formatTime(endTime % 24)
+    };
+}
+
+/**
+ * Calculate Gauri Choghadiya (North Indian time system)
+ * 8 periods during day, 8 during night
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {array} List of choghadiya periods
+ */
+function gauriChoghadiya(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const set = sunriseSunset.sunset(jd, place);
+    const nextRise = sunriseSunset.sunrise(jd + 1, place);
+    const weekday = vaaraModule.vaara(jd).number;
+
+    if (!rise || !set || !nextRise) return [];
+
+    const dayDur = (set.hours - rise.hours) / 8;
+    const nightDur = (24 + nextRise.hours - set.hours) / 8;
+
+    const periods = [];
+
+    // Day periods
+    for (let i = 0; i < 8; i++) {
+        const typeIndex = GAURI_CHOGHADIYA_DAY[weekday][i];
+        const startTime = rise.hours + i * dayDur;
+        const endTime = rise.hours + (i + 1) * dayDur;
+
+        periods.push({
+            period: i + 1,
+            type: CHOGHADIYA_NAMES[typeIndex],
+            typeIndex,
+            startTime,
+            endTime,
+            startString: utils.formatTime(startTime),
+            endString: utils.formatTime(endTime),
+            isDay: true,
+            isAuspicious: [2, 3, 5].includes(typeIndex) // Labh, Amrit, Shubh
+        });
+    }
+
+    // Night periods
+    for (let i = 0; i < 8; i++) {
+        const typeIndex = GAURI_CHOGHADIYA_NIGHT[weekday][i];
+        const startTime = set.hours + i * nightDur;
+        const endTime = set.hours + (i + 1) * nightDur;
+
+        periods.push({
+            period: i + 9,
+            type: CHOGHADIYA_NAMES[typeIndex],
+            typeIndex,
+            startTime: startTime % 24,
+            endTime: endTime % 24,
+            startString: utils.formatTime(startTime % 24),
+            endString: utils.formatTime(endTime % 24),
+            isDay: false,
+            isAuspicious: [2, 3, 5].includes(typeIndex)
+        });
+    }
+
+    return periods;
+}
+
+/**
+ * Get Amrit Kaalam (most auspicious choghadiya period)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {array} List of Amrit periods
+ */
+function amritKaalam(jd, place) {
+    const choghadiyas = gauriChoghadiya(jd, place);
+    return choghadiyas.filter(c => c.type === 'Amrit');
+}
+
+/**
+ * Calculate Sandhya periods (twilight - important for prayers)
+ * @param {number} jd - Julian Day Number
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} {pratah, madhyahna, sayam} - three sandhya periods
+ */
+function sandhyaPeriods(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    const set = sunriseSunset.sunset(jd, place);
+    const dayDur = sunriseSunset.dayLength(jd, place);
+
+    if (!rise || !set) return null;
+
+    const ghati = dayDur / 30;
+    const noon = rise.hours + dayDur / 2;
+
+    return {
+        pratah: {
+            startTime: rise.hours - 2 * ghati,
+            endTime: rise.hours + ghati,
+            description: '2 ghatis before and 1 ghati after sunrise'
+        },
+        madhyahna: {
+            startTime: noon - 1.5 * ghati,
+            endTime: noon + 1.5 * ghati,
+            description: '1.5 ghatis before and after noon'
+        },
+        sayam: {
+            startTime: set.hours - ghati,
+            endTime: set.hours + 2 * ghati,
+            description: '1 ghati before and 2 ghatis after sunset'
+        }
+    };
+}
+
+module.exports = {
+    trikalam,
+    raahuKaalam,
+    yamagandaKaalam,
+    gulikaiKaalam,
+    abhijitMuhurta,
+    durmuhurtam,
+    brahmaMuhurta,
+    godhuliMuhurta,
+    vijayaMuhurta,
+    nishitaKaala,
+    gauriChoghadiya,
+    amritKaalam,
+    sandhyaPeriods
+};

package/src/panchanga/nakshatra.js

@@ -0,0 +1,180 @@
+/**
+ * Nakshatra (Lunar Mansion) Calculations
+ * Nakshatra = floor(Moon longitude / 13.333) + 1
+ * 27 nakshatras, each with 4 padas (quarters)
+ */
+
+const sunriseSunset = require('./sunrise-sunset');
+const utils = require('./utils');
+const { NAKSHATRA_NAMES, ONE_NAKSHATRA, ONE_PADA } = require('./constants');
+
+/**
+ * Get nakshatra and pada from longitude
+ * @param {number} longitude - Ecliptic longitude (0-360)
+ * @returns {object} {nakshatra, pada, remainder}
+ */
+function nakshatraPada(longitude) {
+    const normalizedLong = utils.norm360(longitude);
+    const nakshatraIndex = Math.floor(normalizedLong / ONE_NAKSHATRA);
+    const remainder = normalizedLong % ONE_NAKSHATRA;
+    const padaIndex = Math.floor(remainder / ONE_PADA);
+
+    return {
+        nakshatra: nakshatraIndex + 1,  // 1-27
+        pada: padaIndex + 1,             // 1-4
+        remainder: remainder,            // Degrees within nakshatra
+        degreesInPada: remainder % ONE_PADA
+    };
+}
+
+/**
+ * Get nakshatra details for given date/time
+ * @param {number} jd - Julian Day Number (local)
+ * @param {object} place - {latitude, longitude, timezone}
+ * @returns {object} Nakshatra details
+ */
+function nakshatra(jd, place) {
+    const jdUTC = utils.toUTC(jd, place.timezone);
+    const rise = sunriseSunset.sunrise(jd, place);
+
+    if (!rise) return null;
+
+    const riseJDUTC = utils.toUTC(rise.jd, place.timezone);
+    const moonLong = sunriseSunset.lunarLongitude(jdUTC);
+    const { nakshatra: nakNo, pada: padaNo, remainder } = nakshatraPada(moonLong);
+
+    // Calculate nakshatra end time
+    const targetDegree = nakNo * ONE_NAKSHATRA;
+    const degreesLeft = targetDegree - moonLong;
+
+    // Get moon positions at intervals
+    const offsets = [0.0, 0.25, 0.5, 0.75, 1.0];
+    const moonLongs = offsets.map(t => sunriseSunset.lunarLongitude(riseJDUTC + t));
+    const unwrapped = utils.unwrapAngles(moonLongs);
+
+    // Find when nakshatra ends
+    let endTime;
+    try {
+        const jdAtStart = utils.dateToJD(
+            utils.jdToDate(jd).year,
+            utils.jdToDate(jd).month,
+            utils.jdToDate(jd).day
+        );
+        const approxEnd = utils.inverseLagrange(offsets, unwrapped, targetDegree);
+        endTime = (rise.jd + approxEnd - jdAtStart) * 24;
+    } catch {
+        // Fallback using average moon speed
+        const avgMoonSpeed = 13.17; // degrees per day
+        endTime = rise.hours + (degreesLeft / avgMoonSpeed) * 24;
+    }
+
+    // Get start time from previous day
+    const prevNak = _getNakshatraAtSunrise(jd - 1, place);
+    let startTime = prevNak ? prevNak.endTime : rise.hours;
+    if (startTime > 24) startTime -= 24;
+    if (startTime < 0) startTime = -startTime;
+
+    // Check for nakshatra change during day
+    let nextNakshatra = null;
+    if (endTime < 24) {
+        const nextNakNo = (nakNo % 27) + 1;
+        nextNakshatra = {
+            number: nextNakNo,
+            name: NAKSHATRA_NAMES[nextNakNo - 1],
+            pada: 1,
+            startTime: endTime
+        };
+    }
+
+    const result = {
+        number: nakNo,
+        name: NAKSHATRA_NAMES[nakNo - 1],
+        pada: padaNo,
+        startTime,
+        endTime,
+        startTimeString: utils.formatTime(startTime < 0 ? startTime + 24 : startTime),
+        endTimeString: utils.formatTime(endTime > 24 ? endTime - 24 : endTime) + (endTime > 24 ? ' (+1)' : ''),
+        remainder,
+        moonLongitude: moonLong
+    };
+
+    if (nextNakshatra) {
+        result.nextNakshatra = nextNakshatra;
+    }
+
+    return result;
+}
+
+/**
+ * Internal helper to get nakshatra at sunrise
+ */
+function _getNakshatraAtSunrise(jd, place) {
+    const rise = sunriseSunset.sunrise(jd, place);
+    if (!rise) return null;
+
+    const riseJDUTC = utils.toUTC(rise.jd, place.timezone);
+    const moonLong = sunriseSunset.lunarLongitude(riseJDUTC);
+    const nakNo = Math.floor(moonLong / ONE_NAKSHATRA) + 1;
+    const targetDegree = nakNo * ONE_NAKSHATRA;
+
+    const offsets = [0.0, 0.25, 0.5, 0.75, 1.0];
+    const moonLongs = offsets.map(t => sunriseSunset.lunarLongitude(riseJDUTC + t));
+    const unwrapped = utils.unwrapAngles(moonLongs);
+
+    try {
+        const jdAtStart = utils.dateToJD(
+            utils.jdToDate(jd).year,
+            utils.jdToDate(jd).month,
+            utils.jdToDate(jd).day
+        );
+        const approxEnd = utils.inverseLagrange(offsets, unwrapped, targetDegree);
+        const endTime = (rise.jd + approxEnd - jdAtStart) * 24;
+        return { nakNo, endTime };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Quick nakshatra lookup (without full timing calculation)
+ * @param {number} jdUTC - Julian Day (UTC)
+ * @returns {object} {nakshatra, pada}
+ */
+function quickNakshatra(jdUTC) {
+    const moonLong = sunriseSunset.lunarLongitude(jdUTC);
+    return nakshatraPada(moonLong);
+}
+
+/**
+ * Get nakshatra lord (planet ruling the nakshatra)
+ * @param {number} nakshatra - Nakshatra number (1-27)
+ * @returns {number} Planet index (0=Sun, 1=Moon, ...)
+ */
+function nakshatraLord(nakshatra) {
+    // Vimshottari lords: Ketu(8), Venus(5), Sun(0), Moon(1), Mars(2), Rahu(7), Jupiter(4), Saturn(6), Mercury(3)
+    const lords = [8, 5, 0, 1, 2, 7, 4, 6, 3];
+    return lords[(nakshatra - 1) % 9];
+}
+
+/**
+ * Get abhijit nakshatra bounds
+ * Abhijit spans the last quarter of Uttara Ashadha and first 1/15th of Shravana
+ * @returns {object} Start and end degrees
+ */
+function abhijitBounds() {
+    // Uttara Ashadha ends at 280°, Shravana starts at 280°
+    // Abhijit: 276°40' to 280°53'20"
+    return {
+        start: 276 + 40 / 60,
+        end: 280 + 53 / 60 + 20 / 3600
+    };
+}
+
+module.exports = {
+    nakshatra,
+    nakshatraPada,
+    quickNakshatra,
+    nakshatraLord,
+    abhijitBounds,
+    NAKSHATRA_NAMES
+};