kundali-chart-mcp 0.2.1

package/azure-function/python/kundali_lib/vedic/upagrahas.py

@@ -0,0 +1,229 @@
+"""Upagrahas: Shadow planets and sub-planets in Vedic astrology."""
+
+import math
+
+try:
+    import swisseph as swe
+
+    _SWE_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _SWE_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Reference data
+# ---------------------------------------------------------------------------
+
+RASHIS = [
+    "Aries",
+    "Taurus",
+    "Gemini",
+    "Cancer",
+    "Leo",
+    "Virgo",
+    "Libra",
+    "Scorpio",
+    "Sagittarius",
+    "Capricorn",
+    "Aquarius",
+    "Pisces",
+]
+
+NAKSHATRAS = [
+    "Ashwini",
+    "Bharani",
+    "Krittika",
+    "Rohini",
+    "Mrigashira",
+    "Ardra",
+    "Punarvasu",
+    "Pushya",
+    "Ashlesha",
+    "Magha",
+    "Purva Phalguni",
+    "Uttara Phalguni",
+    "Hasta",
+    "Chitra",
+    "Swati",
+    "Vishakha",
+    "Anuradha",
+    "Jyeshtha",
+    "Mula",
+    "Purva Ashadha",
+    "Uttara Ashadha",
+    "Shravana",
+    "Dhanishta",
+    "Shatabhisha",
+    "Purva Bhadrapada",
+    "Uttara Bhadrapada",
+    "Revati",
+]
+
+# How many portions into the day each weekday's Gulika begins.
+# Weekday index: 0=Sunday, 1=Monday, ..., 6=Saturday
+# Each day is split into 8 equal portions; Gulika occupies one of them.
+_GULIKA_WEEKDAY_PORTION = {
+    0: 6,  # Sunday   — 7th portion (index 6)
+    1: 0,  # Monday   — 1st portion (index 0)
+    2: 1,  # Tuesday  — 2nd portion (index 1)
+    3: 2,  # Wednesday— 3rd portion (index 2)
+    4: 3,  # Thursday — 4th portion (index 3)
+    5: 4,  # Friday   — 5th portion (index 4)
+    6: 5,  # Saturday — 6th portion (index 5)
+}
+
+# Mandi (start of portion, vs Gulika which is midpoint)
+_MANDI_WEEKDAY_PORTION = _GULIKA_WEEKDAY_PORTION  # same portions, different point
+
+_UPAGRAHA_SIGNIFICANCE = {
+    "Gulika": "Most malefic upagraha, son of Saturn. Very important in KP and Nadi astrology.",
+    "Mandi": "Shadow of Gulika; marks the start of Saturn's portion. Strongly malefic.",
+    "Dhuma": "Smoky planet; Sun + 133°20'. Associated with obstacles and disruptions.",
+    "Vyatipata": "Calamity indicator; 360° − Dhuma. Highly inauspicious transit point.",
+    "Parivesha": "Encirclement; Vyatipata + 180°. Related to entrapment or enclosure.",
+    "Indra_Chapa": "Indra's bow; 360° − Parivesha (= Kodanda). Indicates ambition and pride.",
+    "Upaketu": "Comet-like sub-planet; Sun + 30°. Associated with sudden events.",
+}
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _rashi_from_lon(lon: float) -> str:
+    """Return the rashi name for an absolute sidereal longitude."""
+    return RASHIS[int(lon / 30) % 12]
+
+
+def _nakshatra_from_lon(lon: float) -> str:
+    """Return the nakshatra name for an absolute sidereal longitude."""
+    return NAKSHATRAS[int(lon / (360 / 27)) % 27]
+
+
+def _house_from_lon(lon: float, asc_lon: float) -> int:
+    """Return the house number (1–12) for a longitude given the ascendant longitude."""
+    diff = (lon - asc_lon) % 360
+    return int(diff / 30) + 1
+
+
+def _normalise(lon: float) -> float:
+    """Bring a longitude into the [0, 360) range."""
+    return lon % 360
+
+
+def _build_upagraha_entry(name: str, lon: float, asc_lon: float) -> dict:
+    lon = _normalise(lon)
+    return {
+        "longitude": round(lon, 4),
+        "rashi": _rashi_from_lon(lon),
+        "degree_in_sign": round(lon % 30, 4),
+        "nakshatra": _nakshatra_from_lon(lon),
+        "house": _house_from_lon(lon, asc_lon),
+        "significance": _UPAGRAHA_SIGNIFICANCE.get(name, ""),
+    }
+
+
+def _get_sun_longitude(julian_day: float, ayanamsa_offset: float) -> float:
+    """Compute the Sun's sidereal longitude using swisseph (if available)."""
+    if _SWE_AVAILABLE:
+        flags = swe.FLG_SWIEPH | swe.FLG_SPEED | swe.FLG_SIDEREAL
+        result, _ = swe.calc_ut(julian_day, swe.SUN, flags)
+        return result[0] % 360
+    # Fallback: very rough tropical approximation minus ayanamsa
+    # (useful only if swisseph is genuinely absent)
+    T = (julian_day - 2451545.0) / 36525.0
+    lon_tropical = (280.46646 + 36000.76983 * T) % 360
+    return (lon_tropical - ayanamsa_offset) % 360
+
+
+def _get_ascendant_longitude(
+    julian_day: float, birth_lat: float, birth_lon: float, ayanamsa_offset: float
+) -> float:
+    """Compute the sidereal ascendant longitude."""
+    if _SWE_AVAILABLE:
+        houses, ascmc = swe.houses(julian_day, birth_lat, birth_lon, b"P")
+        asc_tropical = ascmc[0]
+        return (asc_tropical - ayanamsa_offset) % 360
+    # Rough fallback: estimate LST-based ascendant
+    T = (julian_day - 2451545.0) / 36525.0
+    gst = (280.46061837 + 360.98564736629 * (julian_day - 2451545.0)) % 360
+    lst = (gst + birth_lon) % 360
+    return (lst - ayanamsa_offset) % 360
+
+
+# ---------------------------------------------------------------------------
+# Main function
+# ---------------------------------------------------------------------------
+
+
+def get_upagrahas(
+    julian_day: float, birth_lat: float, birth_lon: float, ayanamsa_offset: float
+) -> dict:
+    """Calculate all major upagrahas (shadow sub-planets).
+
+    Parameters
+    ----------
+    julian_day : float
+        Julian Day Number for the birth moment (UT).
+    birth_lat : float
+        Geographic latitude of birth location (degrees, N positive).
+    birth_lon : float
+        Geographic longitude of birth location (degrees, E positive).
+    ayanamsa_offset : float
+        Ayanamsa in degrees at the time of birth
+        (e.g. from ``swe.get_ayanamsa_ut(jd)``).
+
+    Returns
+    -------
+    dict
+        Keys: Gulika, Mandi, Dhuma, Vyatipata, Parivesha, Indra_Chapa, Upaketu.
+        Each value is a dict with longitude, rashi, degree_in_sign,
+        nakshatra, house, significance.
+    """
+    sun_lon = _get_sun_longitude(julian_day, ayanamsa_offset)
+    asc_lon = _get_ascendant_longitude(
+        julian_day, birth_lat, birth_lon, ayanamsa_offset
+    )
+
+    # ------------------------------------------------------------------
+    # Weekday from Julian Day
+    # jd 0.0 = Monday noon UT; int(jd + 1.5) % 7 gives 0=Sunday … 6=Sat
+    # ------------------------------------------------------------------
+    weekday = int(julian_day + 1.5) % 7  # 0=Sunday, 6=Saturday
+
+    # ------------------------------------------------------------------
+    # Gulika & Mandi
+    # Day duration assumed = 12 hours (simplified; sunrise 6 AM, sunset 6 PM).
+    # Split into 8 equal portions of 90 minutes each.
+    # Lagna (ascendant sign) changes roughly every 2 hours (120 min).
+    # Portion sign offset: each 90-min portion ≈ 90/120 × 30° = 22.5° from asc.
+    # Gulika longitude = ascendant + portion_index × (360/8)
+    # ------------------------------------------------------------------
+    day_duration_deg = 180.0  # 12 hours × 15°/hour (Sun travels 180° in a day)
+    portion_size_deg = day_duration_deg / 8  # 22.5° per portion
+
+    gulika_portion = _GULIKA_WEEKDAY_PORTION[weekday]
+    gulika_lon = _normalise(
+        asc_lon + gulika_portion * portion_size_deg + portion_size_deg / 2
+    )
+
+    mandi_portion = _MANDI_WEEKDAY_PORTION[weekday]
+    mandi_lon = _normalise(asc_lon + mandi_portion * portion_size_deg)
+
+    # ------------------------------------------------------------------
+    # Dhuma and derived upagrahas (purely Sun-based calculations)
+    # ------------------------------------------------------------------
+    dhuma_lon = _normalise(sun_lon + 133.333)  # Sun + 133°20'
+    vyatipata_lon = _normalise(360.0 - dhuma_lon)  # 360° − Dhuma
+    parivesha_lon = _normalise(vyatipata_lon + 180.0)  # Vyatipata + 180°
+    indrachapa_lon = _normalise(360.0 - parivesha_lon)  # 360° − Parivesha
+    upaketu_lon = _normalise(sun_lon + 30.0)  # Sun + 30°
+
+    return {
+        "Gulika": _build_upagraha_entry("Gulika", gulika_lon, asc_lon),
+        "Mandi": _build_upagraha_entry("Mandi", mandi_lon, asc_lon),
+        "Dhuma": _build_upagraha_entry("Dhuma", dhuma_lon, asc_lon),
+        "Vyatipata": _build_upagraha_entry("Vyatipata", vyatipata_lon, asc_lon),
+        "Parivesha": _build_upagraha_entry("Parivesha", parivesha_lon, asc_lon),
+        "Indra_Chapa": _build_upagraha_entry("Indra_Chapa", indrachapa_lon, asc_lon),
+        "Upaketu": _build_upagraha_entry("Upaketu", upaketu_lon, asc_lon),
+    }

package/azure-function/python/kundali_lib/vedic/varshaphal.py

@@ -0,0 +1,185 @@
+"""Varshaphal: Vedic Solar Return chart for any given year of life.
+
+The Varshaphal chart is cast for the exact moment the Sun returns to its
+natal sidereal longitude each year (solar return).  The chart is erected
+for the querent's current place of residence rather than their birth place.
+"""
+
+import calendar
+from datetime import datetime
+
+import pytz
+import swisseph as swe
+
+from kundali_lib.vedic.chart import _jd_ut, build_chart
+
+_SIDEREAL_FLAGS = swe.FLG_SWIEPH | swe.FLG_SPEED | swe.FLG_SIDEREAL
+
+
+# ── Internal helpers ─────────────────────────────────────────────────────────
+
+
+def _sun_lon(jd: float) -> float:
+    """Sidereal (Lahiri) Sun longitude for a given Julian Day."""
+    swe.set_sid_mode(swe.SIDM_LAHIRI)
+    xx, _ = swe.calc_ut(jd, swe.SUN, _SIDEREAL_FLAGS)
+    return xx[0]
+
+
+def _angular_diff(a: float, b: float) -> float:
+    """Signed difference (a − b) normalised to [−180, 180]."""
+    diff = (a - b) % 360.0
+    if diff > 180.0:
+        diff -= 360.0
+    return diff
+
+
+def _find_solar_return_jd(
+    natal_sun_lon: float,
+    target_year: int,
+    birth_month: int,
+    birth_day: int,
+) -> float:
+    """Return the Julian Day when the sidereal Sun equals natal_sun_lon.
+
+    Strategy:
+    1. Start scanning ~2 months before the expected solar-return date in
+       ``target_year`` (to be safely before the crossing).
+    2. Walk day by day until a sign change in (sun_lon − natal_lon) is found.
+    3. Refine with 60 iterations of binary search (sub-second accuracy).
+    """
+    start_month = birth_month - 2
+    start_year = target_year
+    if start_month < 1:
+        start_month += 12
+        start_year -= 1
+
+    # Clamp birth_day to a valid day in start_month
+    max_day = calendar.monthrange(start_year, start_month)[1]
+    start_day = min(birth_day, max_day)
+    start_jd = swe.julday(start_year, start_month, start_day, 0.0)
+
+    # ── Coarse day-level scan ────────────────────────────────────────────────
+    prev_diff = _angular_diff(_sun_lon(start_jd), natal_sun_lon)
+    lo_jd: float | None = None
+    hi_jd: float | None = None
+
+    for day_offset in range(1, 400):
+        jd = start_jd + day_offset
+        curr_diff = _angular_diff(_sun_lon(jd), natal_sun_lon)
+
+        if abs(curr_diff) < 0.001:
+            return jd  # Landed almost exactly on the crossing
+
+        # Sun moves forward — we want the zero-crossing from negative → positive
+        if prev_diff < 0.0 and curr_diff >= 0.0:
+            lo_jd = jd - 1.0
+            hi_jd = jd
+            break
+
+        prev_diff = curr_diff
+
+    if lo_jd is None or hi_jd is None:
+        # Fallback (should not occur with a 400-day window)
+        return start_jd
+
+    # ── Fine binary search (~60 iterations → microsecond precision) ──────────
+    for _ in range(60):
+        mid = (lo_jd + hi_jd) / 2.0
+        diff = _angular_diff(_sun_lon(mid), natal_sun_lon)
+        if abs(diff) < 0.0001:
+            return mid
+        if diff < 0.0:
+            lo_jd = mid
+        else:
+            hi_jd = mid
+
+    return (lo_jd + hi_jd) / 2.0
+
+
+def _jd_to_utc_datetime(jd: float) -> datetime:
+    """Convert a Julian Day number to a UTC-aware datetime."""
+    year, month, day, hour_frac = swe.revjul(jd, 1)  # 1 = Gregorian calendar
+    hour = int(hour_frac)
+    minute_frac = (hour_frac - hour) * 60.0
+    minute = int(minute_frac)
+    second_frac = (minute_frac - minute) * 60.0
+    second = min(int(round(second_frac)), 59)  # guard against rounding to 60
+    return datetime(
+        int(year), int(month), int(day), hour, minute, second, tzinfo=pytz.UTC
+    )
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+
+def get_varshaphal(
+    birth_dt: datetime,
+    birth_lat: float,
+    birth_lon: float,
+    birth_timezone: str,
+    year_of_life: int,
+    query_lat: float,
+    query_lon: float,
+    query_timezone: str,
+) -> dict:
+    """Calculate a Varshaphal (Solar Return) chart for a given year of life.
+
+    Args:
+        birth_dt: Naive local birth datetime.
+        birth_lat: Latitude of birth place.
+        birth_lon: Longitude of birth place.
+        birth_timezone: IANA timezone string for the birth place (e.g. "Asia/Kolkata").
+        year_of_life: Which solar return to compute (e.g. 26 for the 26th year).
+                      Target calendar year = birth_year + year_of_life.
+        query_lat: Latitude of current residence.
+        query_lon: Longitude of current residence.
+        query_timezone: IANA timezone string for current residence.
+
+    Returns:
+        dict with solar-return timing and the full Varshaphal chart.
+    """
+    swe.set_ephe_path(None)
+    swe.set_sid_mode(swe.SIDM_LAHIRI)
+
+    # ── Step 1: natal Sun sidereal longitude ─────────────────────────────────
+    birth_jd = _jd_ut(birth_dt, birth_timezone)
+    xx, _ = swe.calc_ut(birth_jd, swe.SUN, _SIDEREAL_FLAGS)
+    natal_sun_lon: float = xx[0]
+
+    # ── Step 2: find JD of solar return in target year ───────────────────────
+    target_year = birth_dt.year + year_of_life
+    sr_jd = _find_solar_return_jd(
+        natal_sun_lon, target_year, birth_dt.month, birth_dt.day
+    )
+
+    # ── Step 3: convert to datetimes ─────────────────────────────────────────
+    sr_utc = _jd_to_utc_datetime(sr_jd)
+    query_tz = pytz.timezone(query_timezone)
+    sr_local_aware = sr_utc.astimezone(query_tz)
+    sr_local_naive = sr_local_aware.replace(tzinfo=None)
+
+    # ── Step 4: build chart at query location ────────────────────────────────
+    chart = build_chart(
+        name="Varshaphal",
+        birth_dt=sr_local_naive,
+        lat=query_lat,
+        lon=query_lon,
+        timezone=query_timezone,
+    )
+
+    return {
+        "year_of_life": year_of_life,
+        "solar_return_datetime_utc": sr_utc.isoformat(),
+        "solar_return_datetime_local": sr_local_aware.isoformat(),
+        "natal_sun_longitude": round(natal_sun_lon, 4),
+        "varshaphal_chart": {
+            "planetary_positions": chart["planetary_positions"],
+            "houses": chart["houses"],
+            "ascendant": chart["ascendant"],
+            "moon_sign": chart["moon_sign"],
+            "sun_sign": chart["sun_sign"],
+            "ayanamsa": chart["ayanamsa"],
+            "ayanamsa_name": chart["ayanamsa_name"],
+        },
+    }