libephemeris 0.1.6__py3-none-any.whl

libephemeris/state.py

@@ -0,0 +1,213 @@
+"""
+Global state management for libephemeris.
+
+This module maintains the library's singleton state including:
+- Ephemeris data loader (Skyfield Loader)
+- Planetary ephemeris (DE421 or other JPL files)
+- Timescale (for UTC/TT conversions)
+- Observer topocentric location
+- Sidereal mode configuration
+- Cached angles for Arabic parts calculations
+
+All state is stored in module-level globals to provide SwissEphemeris-compatible
+stateful API behavior. This is thread-unsafe by design, matching SwissEph behavior.
+"""
+
+import os
+from typing import Optional, Union
+from skyfield.api import Loader, Topos
+from skyfield.timelib import Timescale
+from skyfield.jpllib import SpiceKernel
+
+# =============================================================================
+# GLOBAL STATE VARIABLES
+# =============================================================================
+
+_EPHEMERIS_PATH: Optional[str] = None  # Custom ephemeris directory
+_LOADER: Optional[Loader] = None  # Skyfield data loader
+_PLANETS: Optional[SpiceKernel]  = None  # Loaded planetary ephemeris
+_TS: Optional[Timescale] = None  # Timescale object
+_TOPO: Optional[Topos] = None  # Observer location
+_SIDEREAL_MODE: Optional[int] = None  # Active sidereal mode ID
+_SIDEREAL_AYAN_T0: float = 0.0  # Ayanamsha value at reference epoch
+_SIDEREAL_T0: float = 0.0  # Reference epoch (JD) for ayanamsha
+_ANGLES_CACHE: dict[str, float] = {}  # Pre-calculated angles {name: longitude}
+
+
+def get_loader() -> Loader:
+    """
+    Get or create the Skyfield data loader.
+    
+    Returns:
+        Loader: Skyfield Loader instance for downloading/caching ephemeris files
+        
+    Note:
+        Data files are cached in the parent directory of this module by default.
+    """
+    global _LOADER
+    if _LOADER is None:
+        data_dir = os.path.join(os.path.dirname(__file__), "..")
+        _LOADER = Loader(data_dir)
+    return _LOADER
+
+
+def get_timescale() -> Timescale:
+    """
+    Get or create the Skyfield timescale object.
+    
+    Returns:
+        Timescale: Skyfield timescale for time conversions (UTC, TT, etc.)
+        
+    Note:
+        Automatically downloads IERS data for Delta T calculations if needed.
+    """
+    global _TS
+    if _TS is None:
+        load = get_loader()
+        _TS = load.timescale()
+    return _TS
+
+
+def get_planets() -> SpiceKernel:
+    """
+    Get or load the planetary ephemeris (DE421 by default).
+    
+    Returns:
+        SpiceKernel: Loaded JPL ephemeris kernel containing planetary positions
+        
+    Raises:
+        FileNotFoundError: If de421.bsp cannot be found or downloaded
+        
+    Note:
+        Searches for de421.bsp in the workspace root, then downloads if not found.
+    """
+    global _PLANETS
+    if _PLANETS is None:
+        load = get_loader()
+        base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+        bsp_path = os.path.join(base_dir, "de421.bsp")
+        if not os.path.exists(bsp_path):
+            _PLANETS = load("de421.bsp")
+        else:
+            _PLANETS = load(bsp_path)
+    return _PLANETS
+
+
+def set_topo(lon: float, lat: float, alt: float) -> None:
+    """
+    Set observer's topocentric location for planet calculations.
+    
+    Args:
+        lon: Geographic longitude in degrees (East positive)
+        lat: Geographic latitude in degrees (North positive)
+        alt: Elevation above sea level in meters
+        
+    Note:
+        Required for topocentric calculations (SEFLG_TOPOCTR),
+        angles (Ascendant, MC), and Arabic parts.
+    """
+    global _TOPO
+    _TOPO = Topos(latitude_degrees=lat, longitude_degrees=lon, elevation_m=alt)
+
+
+def get_topo() -> Optional[Topos]:
+    """
+    Get the observer's topocentric location.
+    
+    Returns:
+        Optional[Topos]: Current observer location or None if not set
+    """
+    return _TOPO
+
+
+def set_sid_mode(mode: int, t0: float = 0.0, ayan_t0: float = 0.0) -> None:
+    """
+    Set the sidereal mode (ayanamsha system) for calculations.
+    
+    Args:
+        mode: Sidereal mode ID (SE_SIDM_*) or 255 for custom
+        t0: Reference epoch (Julian Day) for custom ayanamsha (default: J2000.0)
+        ayan_t0: Ayanamsha value at t0 in degrees (for custom mode)
+        
+    Note:
+        Affects all position calculations when SEFLG_SIDEREAL is set.
+        Default is Lahiri (SE_SIDM_LAHIRI) if never set.
+    """
+    global _SIDEREAL_MODE, _SIDEREAL_T0, _SIDEREAL_AYAN_T0
+    _SIDEREAL_MODE = mode
+    _SIDEREAL_T0 = t0 if t0 != 0.0 else 2451545.0
+    _SIDEREAL_AYAN_T0 = ayan_t0
+
+
+def get_sid_mode(full: bool = False) -> Union[int, tuple[int, float, float]]:
+    """
+    Get the current sidereal mode configuration.
+    
+    Args:
+        full: If True, return (mode, t0, ayan_t0); if False, return only mode ID
+        
+    Returns:
+        int or tuple: Sidereal mode ID, or full configuration tuple
+        
+    Note:
+        Returns SE_SIDM_LAHIRI (1) by default if never set.
+    """
+    if full:
+        return _SIDEREAL_MODE, _SIDEREAL_T0, _SIDEREAL_AYAN_T0
+    return _SIDEREAL_MODE if _SIDEREAL_MODE is not None else 1
+
+
+def get_angles_cache() -> dict[str, float]:
+    """
+    Get cached astrological angles for the current calculation context.
+    
+    Returns:
+        dict: Cached angles {name: longitude_degrees}
+        
+    Note:
+        Used by Arabic parts calculations which require pre-calculated
+        planetary positions and angles.
+    """
+    return _ANGLES_CACHE
+
+
+def set_angles_cache(angles: dict[str, float]) -> None:
+    """
+    Cache pre-calculated angles for use in Arabic parts and other virtual points.
+    
+    Args:
+        angles: Dictionary of angles {name: longitude_degrees}
+                e.g., {"Sun": 120.5, "Moon": 240.3, "Asc": 15.7}
+                
+    Note:
+        Creates a copy to prevent external mutation of cache.
+    """
+    global _ANGLES_CACHE
+    _ANGLES_CACHE = angles.copy()
+
+
+def clear_angles_cache() -> None:
+    """
+    Clear the angles cache.
+    
+    Use this between unrelated calculation contexts to prevent stale data.
+    """
+    global _ANGLES_CACHE
+    _ANGLES_CACHE = {}
+
+    _ANGLES_CACHE = {}
+
+
+def set_ephe_path(path: Optional[str]) -> None:
+    """
+    Set the path for ephemeris files.
+    
+    Args:
+        path: Path to directory containing ephemeris files.
+        
+    Note:
+        This is currently a placeholder for compatibility.
+        libephemeris uses Skyfield which manages its own cache.
+    """
+    global _EPHEMERIS_PATH
+    _EPHEMERIS_PATH = path

libephemeris/time_utils.py

@@ -0,0 +1,136 @@
+"""
+Time conversion utilities for libephemeris.
+
+Implements standard astronomical time functions for conversions between:
+- Calendar dates and Julian Day numbers
+- Gregorian and Julian calendar systems
+- UT1 (Universal Time) and TT (Terrestrial Time)
+
+Functions match the Swiss Ephemeris API for compatibility.
+All algorithms follow Meeus "Astronomical Algorithms" (1998).
+"""
+
+from .constants import SE_GREG_CAL
+from .state import get_timescale
+
+
+def swe_julday(
+    year: int, month: int, day: int, hour: float, gregflag: int = SE_GREG_CAL
+) -> float:
+    """
+    Convert calendar date to Julian Day number.
+    
+    Args:
+        year: Calendar year (negative for BCE)
+        month: Month (1-12)
+        day: Day of month (1-31)
+        hour: Decimal hour (0.0-23.999...)
+        gregflag: SE_GREG_CAL (1) for Gregorian, SE_JUL_CAL (0) for Julian
+        
+    Returns:
+        float: Julian Day number (days since JD 0.0 = noon Jan 1, 4713 BCE)
+        
+    Note:
+        Transition date: Oct 15, 1582 (Gregorian) = Oct 5, 1582 (Julian)
+        JD 2451545.0 = Jan 1, 2000 12:00 TT (J2000.0 epoch)
+    """
+    if month <= 2:
+        year -= 1
+        month += 12
+
+    a = int(year / 100)
+
+    if gregflag == SE_GREG_CAL:
+        b = 2 - a + int(a / 4)
+    else:
+        b = 0
+
+    jd = (
+        int(365.25 * (year + 4716))
+        + int(30.6001 * (month + 1))
+        + day
+        + hour / 24.0
+        + b
+        - 1524.5
+    )
+    return jd
+
+
+def swe_revjul(jd: float, gregflag: int = SE_GREG_CAL) -> tuple[int, int, int, float]:
+    """
+    Convert Julian Day number to calendar date.
+    
+    Args:
+        jd: Julian Day number
+        gregflag: SE_GREG_CAL (1) for Gregorian, SE_JUL_CAL (0) for Julian
+        
+    Returns:
+        tuple: (year, month, day, hour) where:
+            - year: Calendar year
+            - month: Month (1-12)
+            - day: Integer day of month
+            - hour: Decimal hour (0.0-23.999...)
+            
+    Note:
+        Automatic Gregorian calendar used for JD >= 2299161 (Oct 15, 1582)
+        unless Julian calendar explicitly requested.
+    """
+    jd = jd + 0.5
+    z = int(jd)
+    f = jd - z
+
+    if z < 2299161:
+        a = z
+    else:
+        if gregflag == SE_GREG_CAL:
+            alpha = int((z - 1867216.25) / 36524.25)
+            a = z + 1 + alpha - int(alpha / 4)
+        else:
+            a = z
+
+    b = a + 1524
+    c = int((b - 122.1) / 365.25)
+    d = int(365.25 * c)
+    e = int((b - d) / 30.6001)
+
+    day = b - d - int(30.6001 * e) + f
+    if e < 14:
+        month = e - 1
+    else:
+        month = e - 13
+
+    if month > 2:
+        year = c - 4716
+    else:
+        year = c - 4715
+
+    d_int = int(day)
+    d_frac = day - d_int
+    hour = d_frac * 24.0
+    day = d_int
+
+    return year, month, day, hour
+
+
+def swe_deltat(tjd: float) -> float:
+    """
+    Calculate Delta T (TT - UT1) for a given Julian Day.
+    
+    Args:
+        tjd: Julian Day number in UT1
+        
+    Returns:
+        float: Delta T in days (TT - UT1)
+        
+    Note:
+        Delta T accounts for Earth's irregular rotation and is required
+        for high-precision planetary calculations. Values are obtained
+        from IERS (International Earth Rotation Service) data.
+        
+        For modern dates: ~0.0008 days (~69 seconds as of 2024)
+        For historical dates: Calculated from polynomial models
+    """
+    ts = get_timescale()
+    t = ts.ut1_jd(tjd)
+    return t.delta_t
+

libephemeris/utils.py

@@ -0,0 +1,36 @@
+"""
+Utility functions for libephemeris.
+
+Provides helper functions compatible with pyswisseph API including
+angular calculations and other mathematical utilities.
+"""
+
+
+def difdeg2n(p1: float, p2: float) -> float:
+    """
+    Calculate distance in degrees p1 - p2 normalized to [-180;180].
+    
+    Compatible with pyswisseph's swe.difdeg2n() function.
+    Computes the signed angular difference, handling 360° wrapping.
+    
+    Args:
+        p1: First angle in degrees
+        p2: Second angle in degrees
+        
+    Returns:
+        Normalized difference in range [-180, 180]
+        
+    Examples:
+        >>> difdeg2n(10, 20)
+        -10.0
+        >>> difdeg2n(350, 10)
+        -20.0
+        >>> difdeg2n(10, 350)
+        20.0
+        >>> difdeg2n(180, 0)
+        180.0
+    """
+    diff = (p1 - p2) % 360.0
+    if diff > 180.0:
+        diff -= 360.0
+    return diff