caelus-engine 0.8.0__tar.gz

caelus_engine-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 caelus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

caelus_engine-0.8.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: caelus-engine
+Version: 0.8.0
+Summary: Clean-room astrological ephemeris engine: planetary and lunar positions, houses, aspects, and events from published sources. The Python reference for the Caelus engine.
+Author-email: EphemEngine <info@ephemengine.com>
+License: MIT
+Project-URL: Homepage, https://ephemengine.com
+Project-URL: Repository, https://github.com/heavyblotto/caelus
+Project-URL: Issues, https://github.com/heavyblotto/caelus/issues
+Project-URL: Changelog, https://github.com/heavyblotto/caelus/blob/main/CHANGELOG.md
+Keywords: astronomy,astrology,ephemeris,vsop87,horoscope,chart,houses,aspects
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fit
+Requires-Dist: numpy>=1.24; extra == "fit"
+Dynamic: license-file
+
+# caelus-engine
+
+The Python reference implementation of the Caelus astrological ephemeris
+engine. Clean-room, MIT-licensed, written from published sources (VSOP87D,
+ELP/Meeus, IAU models, JPL Horizons fits). No Swiss Ephemeris code, no
+bundled third-party ephemeris files.
+
+The engine reads pre-built Chebyshev and series packs shipped with the
+package and runs on the Python standard library alone. It is also the
+reference that the TypeScript engine (`caelus` on npm) is pinned to by a
+golden conformance suite.
+
+## Install
+
+```bash
+pip install caelus-engine
+```
+
+The import package is `astroengine`:
+
+```python
+from astroengine import Engine, BODIES
+
+eng = Engine("full")
+jd = 2451545.0  # 2000-01-01 12:00 UT
+for body in BODIES:
+    print(f"{body:10s} {eng.longitude(body, jd):10.5f}")
+```
+
+## What it computes
+
+- Planetary and lunar apparent geocentric ecliptic longitudes (VSOP87D for
+  the planets, Meeus Ch. 47 for the Moon, Meeus Ch. 37 series for Pluto),
+  with light-time, annual aberration, FK5 frame correction, and IAU 1980
+  nutation.
+- 12 house systems; tropical and sidereal (8 ayanamsas).
+- Aspects with configurable orbs.
+- Events: rise/set/transit, longitude crossings, lunar phases, stations,
+  Gauquelin sectors, solar and lunar eclipses.
+- Fixed stars and topocentric positions.
+- Derived charts: returns, secondary progressions, solar arc, composite and
+  Davison, harmonics, antiscia, declination aspects and parallels,
+  out-of-bounds, dignities, sect.
+- A declarative `when()` query engine over celestial predicates.
+- A turbo tier (`Turbo`): segmented Chebyshev longitude packs fit to the
+  engine for bulk scans.
+
+## Accuracy
+
+Accuracy is calibrated against Swiss Ephemeris and validated against JPL
+Horizons, stated per body rather than as a blanket figure. See the
+validation tables at https://ephemengine.com.
+
+## Optional: the fitting toolchain
+
+The engine runs without any third-party dependency. The data-fitting tools
+that regenerate the coefficient packs need numpy:
+
+```bash
+pip install "caelus-engine[fit]"
+```
+
+## License
+
+MIT. See `LICENSE`. Project home: https://ephemengine.com. Source:
+https://github.com/heavyblotto/caelus.

caelus_engine-0.8.0/README.md

@@ -0,0 +1,66 @@
+# caelus-engine
+
+The Python reference implementation of the Caelus astrological ephemeris
+engine. Clean-room, MIT-licensed, written from published sources (VSOP87D,
+ELP/Meeus, IAU models, JPL Horizons fits). No Swiss Ephemeris code, no
+bundled third-party ephemeris files.
+
+The engine reads pre-built Chebyshev and series packs shipped with the
+package and runs on the Python standard library alone. It is also the
+reference that the TypeScript engine (`caelus` on npm) is pinned to by a
+golden conformance suite.
+
+## Install
+
+```bash
+pip install caelus-engine
+```
+
+The import package is `astroengine`:
+
+```python
+from astroengine import Engine, BODIES
+
+eng = Engine("full")
+jd = 2451545.0  # 2000-01-01 12:00 UT
+for body in BODIES:
+    print(f"{body:10s} {eng.longitude(body, jd):10.5f}")
+```
+
+## What it computes
+
+- Planetary and lunar apparent geocentric ecliptic longitudes (VSOP87D for
+  the planets, Meeus Ch. 47 for the Moon, Meeus Ch. 37 series for Pluto),
+  with light-time, annual aberration, FK5 frame correction, and IAU 1980
+  nutation.
+- 12 house systems; tropical and sidereal (8 ayanamsas).
+- Aspects with configurable orbs.
+- Events: rise/set/transit, longitude crossings, lunar phases, stations,
+  Gauquelin sectors, solar and lunar eclipses.
+- Fixed stars and topocentric positions.
+- Derived charts: returns, secondary progressions, solar arc, composite and
+  Davison, harmonics, antiscia, declination aspects and parallels,
+  out-of-bounds, dignities, sect.
+- A declarative `when()` query engine over celestial predicates.
+- A turbo tier (`Turbo`): segmented Chebyshev longitude packs fit to the
+  engine for bulk scans.
+
+## Accuracy
+
+Accuracy is calibrated against Swiss Ephemeris and validated against JPL
+Horizons, stated per body rather than as a blanket figure. See the
+validation tables at https://ephemengine.com.
+
+## Optional: the fitting toolchain
+
+The engine runs without any third-party dependency. The data-fitting tools
+that regenerate the coefficient packs need numpy:
+
+```bash
+pip install "caelus-engine[fit]"
+```
+
+## License
+
+MIT. See `LICENSE`. Project home: https://ephemengine.com. Source:
+https://github.com/heavyblotto/caelus.

caelus_engine-0.8.0/astroengine/__init__.py

@@ -0,0 +1 @@
+from .chart import Engine, fmt_lon, BODIES

caelus_engine-0.8.0/astroengine/chart.py

@@ -0,0 +1,293 @@
+"""astroengine.chart -- public API: natal charts, aspects, retrogrades."""
+import math
+from . import core
+from .core import (Vsop, jd_tt, julian_day, planet_apparent, sun_apparent,
+                   moon_apparent, pluto_apparent, mean_node, true_node,
+                   equatorial, ayanamsa, mean_lilith, topocentric_ecl,
+                   true_obliquity, nutation, DEG)
+from . import houses as H
+
+BODIES = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn",
+          "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node"]
+
+# Computable on request (not in the default chart set). Asteroids load
+# lazily from their Chebyshev packs (Horizons fits, 1850-2150).
+ASTEROIDS = ["ceres", "pallas", "juno", "vesta", "pholus"]
+URANIANS = ["cupido", "hades", "zeus", "kronos", "apollon", "admetos",
+            "vulkanus", "poseidon"]
+EXTRA_BODIES = ["mean_lilith", "true_lilith"] + ASTEROIDS + URANIANS
+
+# Points: excluded from aspect search by default.
+NOT_ASPECTABLE = {"mean_node", "true_node", "mean_lilith", "true_lilith"}
+
+SIGNS = ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra",
+         "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"]
+
+ASPECTS = {"conjunction": 0, "sextile": 60, "square": 90, "trine": 120, "opposition": 180}
+DEFAULT_ORBS = {"conjunction": 8, "sextile": 4, "square": 7, "trine": 7, "opposition": 8}
+
+KM_PER_AU = 149597870.7
+
+HOUSE_FNS = {
+    "porphyry": None, "equal": None, "whole_sign": None, "placidus": None,  # legacy paths
+    "koch": H.houses_koch,
+    "regiomontanus": H.houses_regiomontanus,
+    "campanus": H.houses_campanus,
+    "alcabitius": H.houses_alcabitius,
+    "morinus": H.houses_morinus,
+    "meridian": H.houses_meridian,
+    "polich_page": H.houses_polich_page,
+    "vehlow": H.houses_vehlow,
+}
+HOUSE_SYSTEMS = list(HOUSE_FNS.keys())
+
+
+# Star-anchored ayanamsas: the named star sits at the fixed sidereal
+# longitude by definition (Galactic Center at 0 Sagittarius; Spica at
+# 0 Libra "citra").
+STAR_AYANAMSAS = {"galcent_0sag": ("Galactic Center", 240.0),
+                  "true_citra": ("Spica", 180.0)}
+
+
+def _parse_zodiac(zodiac):
+    """'tropical' or 'sidereal:<ayanamsa>' -> ayanamsa mode or None."""
+    if zodiac == "tropical":
+        return None
+    if zodiac.startswith("sidereal:"):
+        mode = zodiac[len("sidereal:"):]
+        if mode in core.AYANAMSA_J2000 or mode in STAR_AYANAMSAS:
+            return mode
+    raise ValueError(f"unknown zodiac {zodiac!r}")
+
+
+class Engine:
+    def __init__(self, level="full"):
+        self.vsop = Vsop(level)
+        self._packs = {}
+
+    def _pack(self, body):
+        if body not in self._packs:
+            import json
+            import os
+            if body in URANIANS:
+                with open(os.path.join(core.DATA, "uranian_kepler.json")) as f:
+                    pack = json.load(f)
+                for name, els in pack["bodies"].items():
+                    self._packs[name] = core.KeplerOrbit(els, pack["epoch"])
+            else:
+                from .chebyshev import ChebSeries
+                path = os.path.join(core.DATA, f"{body}_cheb.json")
+                if not os.path.exists(path):
+                    raise ValueError(f"no data pack for {body!r}")
+                self._packs[body] = ChebSeries.load(path)
+        return self._packs[body]
+
+    def _ecliptic(self, body, jde):
+        """Apparent geocentric (lon rad, lat rad, dist AU or None)."""
+        if body == "sun":
+            return sun_apparent(self.vsop, jde)
+        if body == "moon":
+            if core.moon_in_precise_range(jde):
+                lon, lat, km = core.moon_apparent_precise(jde)
+            else:
+                lon, lat, km = moon_apparent(jde)
+            return lon, lat, km / KM_PER_AU
+        if body == "pluto":
+            return pluto_apparent(self.vsop, jde)
+        if body == "chiron":
+            return core.chiron_apparent(self.vsop, jde)
+        if body == "mean_node":
+            return mean_node(jde), 0.0, None
+        if body == "true_node":
+            if core.moon_in_precise_range(jde):
+                return core.true_node_precise(jde), 0.0, None
+            return true_node(jde), 0.0, None
+        if body == "mean_lilith":
+            lon, lat = mean_lilith(jde)
+            return lon, lat, None
+        if body == "true_lilith":
+            if core.moon_in_precise_range(jde):
+                lon, lat, km = core.osc_apogee_precise(jde)
+            else:
+                lon, lat, km = core.osc_apogee_series(jde)
+            return lon, lat, km / KM_PER_AU
+        if body in ASTEROIDS or body in URANIANS:
+            return core.smallbody_apparent(self.vsop, self._pack(body), jde)
+        return planet_apparent(self.vsop, body, jde)
+
+    def _ayan_shift(self, jde, mode):
+        """Degrees to subtract from a true-equinox tropical longitude."""
+        if mode in STAR_AYANAMSAS:
+            name, anchor = STAR_AYANAMSAS[mode]
+            from . import stars as ST
+            lon, _ = ST.star_apparent(self.vsop, ST.catalog()["stars"][name], jde)
+            return (lon / DEG - anchor) % 360
+        return (nutation(jde)[0] / DEG + ayanamsa(jde, mode)) % 360
+
+    def fixed_star(self, name, jd_ut, zodiac="tropical"):
+        """Apparent place of a catalog star: lon/lat/ra/dec (deg), sign, mag."""
+        from . import stars as ST
+        s = ST.catalog()["stars"][name]
+        mode = _parse_zodiac(zodiac)
+        jde = jd_tt(jd_ut)
+        lon_r, lat_r = ST.star_apparent(self.vsop, s, jde)
+        ra, dec = equatorial(lon_r, lat_r, true_obliquity(jde))
+        lon = lon_r / DEG
+        if mode is not None:
+            lon = (lon - self._ayan_shift(jde, mode)) % 360
+        return {"lon": lon, "lat": lat_r / DEG, "ra": ra / DEG, "dec": dec / DEG,
+                "mag": s["mag"], "sign": SIGNS[int(lon // 30)], "sign_deg": lon % 30}
+
+    def stars(self):
+        from . import stars as ST
+        return sorted(ST.catalog()["stars"])
+
+    def _lon_only(self, body, jd_ut, mode, topo):
+        jde = jd_tt(jd_ut)
+        lon, lat, dist = self._ecliptic(body, jde)
+        if topo is not None and dist is not None:
+            lst = (H.gast(jd_ut) + topo[1] * DEG) % (2 * math.pi)
+            lon, lat, dist = topocentric_ecl(lon, lat, dist, lst,
+                                             topo[0] * DEG, topo[2],
+                                             true_obliquity(jde))
+        lon_deg = lon / DEG
+        if mode is not None:
+            lon_deg = (lon_deg - self._ayan_shift(jde, mode)) % 360
+        return lon_deg
+
+    def longitude(self, body, jd_ut, zodiac="tropical", topocentric=False, observer=None):
+        """Apparent geocentric ecliptic longitude (deg). Tropical: true
+        equinox of date. Sidereal: mean equinox minus ayanamsa."""
+        mode = _parse_zodiac(zodiac)
+        topo = observer if topocentric else None
+        return self._lon_only(body, jd_ut, mode, topo)
+
+    def heliocentric(self, body, jd_ut):
+        """Geometric heliocentric ecliptic of date (deg, deg, AU)."""
+        jde = jd_tt(jd_ut)
+        if body == "pluto":
+            l, b, r = core.pluto_heliocentric(jde)
+            l, b = core._precess_ecliptic(l, b, core.J2000, jde)
+        elif body == "chiron":
+            if core._CHIRON is None:
+                core.chiron_apparent(self.vsop, jde)  # loads the fit
+            x, y, z = core._CHIRON.xyz(jde)
+            r = math.sqrt(x * x + y * y + z * z)
+            l = math.atan2(y, x) % (2 * math.pi)
+            b = math.atan2(z, math.hypot(x, y))
+            l, b = core._precess_ecliptic(l, b, core.J2000, jde)
+        elif body in ASTEROIDS or body in URANIANS:
+            x, y, z = self._pack(body).xyz(jde)
+            r = math.sqrt(x * x + y * y + z * z)
+            l = math.atan2(y, x) % (2 * math.pi)
+            b = math.atan2(z, math.hypot(x, y))
+            l, b = core._precess_ecliptic(l, b, core.J2000, jde)
+        elif body in core.PLANET_NAMES or body == "earth":
+            l, b, r = self.vsop.heliocentric(body, jde)
+        else:
+            raise ValueError(f"no heliocentric position for {body!r}")
+        return {"lon": l / DEG, "lat": b / DEG, "dist": r}
+
+    def position(self, body, jd_ut, zodiac="tropical", topocentric=False, observer=None):
+        """Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec."""
+        mode = _parse_zodiac(zodiac)
+        topo = observer if topocentric else None
+        jde = jd_tt(jd_ut)
+        lon_r, lat_r, dist = self._ecliptic(body, jde)
+        if topo is not None and dist is not None:
+            lst = (H.gast(jd_ut) + topo[1] * DEG) % (2 * math.pi)
+            lon_r, lat_r, dist = topocentric_ecl(lon_r, lat_r, dist, lst,
+                                                 topo[0] * DEG, topo[2],
+                                                 true_obliquity(jde))
+        ra, dec = equatorial(lon_r, lat_r, true_obliquity(jde))
+        lon = lon_r / DEG
+        if mode is not None:
+            lon = (lon - self._ayan_shift(jde, mode)) % 360
+        h = 0.25  # days; central difference
+        l0 = self._lon_only(body, jd_ut - h, mode, topo)
+        l1 = self._lon_only(body, jd_ut + h, mode, topo)
+        speed = ((l1 - l0 + 540) % 360 - 180) / (2 * h)
+        return {"lon": lon, "speed": speed, "retrograde": speed < 0,
+                "sign": SIGNS[int(lon // 30)], "sign_deg": lon % 30,
+                "lat": lat_r / DEG, "dist": dist,
+                "ra": ra / DEG, "dec": dec / DEG}
+
+    def chart(self, y, mo, d, h, mi, s, lat, lon_east, house_system="placidus",
+              zodiac="tropical", topocentric=False, extra_bodies=None, orbs=None):
+        """Full natal chart. Time is UT. East longitude positive."""
+        mode = _parse_zodiac(zodiac)
+        jd_ut = julian_day(y, mo, d, h, mi, s)
+        observer = (lat, lon_east, 0.0) if topocentric else None
+        names = BODIES + [b for b in (extra_bodies or []) if b not in BODIES]
+        bodies = {b: self.position(b, jd_ut, zodiac=zodiac,
+                                   topocentric=topocentric, observer=observer)
+                  for b in names}
+        asc, mc, armc, eps = H.angles(jd_ut, lat, lon_east)
+        vtx, east = H.vertex_east_point(armc, lat * DEG, eps)
+        phi = lat * DEG
+        used = house_system
+        try:
+            if house_system == "placidus":
+                if abs(lat) < 66.0:
+                    cusps = H.houses_placidus(armc, phi, eps)
+                else:
+                    raise ValueError("placidus undefined above polar circles")
+            elif house_system == "porphyry":
+                cusps = H.houses_porphyry(asc, mc)
+            elif house_system == "equal":
+                cusps = H.houses_equal(asc)
+            elif house_system == "whole_sign":
+                cusps = H.houses_whole_sign(asc)
+            elif house_system in HOUSE_FNS and HOUSE_FNS[house_system]:
+                cusps = HOUSE_FNS[house_system](armc, phi, eps)
+            else:
+                raise KeyError(house_system)
+        except ValueError:
+            used = "whole_sign"
+            cusps = H.houses_whole_sign(asc)
+        jde = jd_tt(jd_ut)
+        shift = 0.0
+        if mode is not None:
+            shift = self._ayan_shift(jde, mode)
+
+        def out_deg(rad):
+            return (rad / DEG - shift) % 360
+
+        if mode is not None and used == "whole_sign":
+            # whole-sign cusps must stay sign-aligned in the sidereal zodiac
+            sid_asc = out_deg(asc)
+            first = (int(sid_asc // 30)) * 30.0
+            cusps_deg = [(first + i * 30.0) % 360 for i in range(12)]
+        else:
+            cusps_deg = [out_deg(c) for c in cusps]
+        return {
+            "jd_ut": jd_ut,
+            "zodiac": zodiac,
+            "house_system": used,
+            "house_system_requested": house_system,
+            "bodies": bodies,
+            "angles": {"asc": out_deg(asc), "mc": out_deg(mc),
+                       "vertex": out_deg(vtx), "east_point": out_deg(east)},
+            "cusps": cusps_deg,
+            "aspects": find_aspects(bodies, orbs or DEFAULT_ORBS),
+        }
+
+
+def find_aspects(bodies, orbs=DEFAULT_ORBS):
+    out = []
+    names = [b for b in bodies if b not in NOT_ASPECTABLE]
+    for i, a in enumerate(names):
+        for b in names[i + 1:]:
+            sep = abs((bodies[a]["lon"] - bodies[b]["lon"] + 180) % 360 - 180)
+            for asp, angle in ASPECTS.items():
+                orb = abs(sep - angle)
+                if orb <= orbs[asp]:
+                    out.append({"a": a, "b": b, "aspect": asp, "orb": round(orb, 2)})
+    return out
+
+
+def fmt_lon(deg):
+    sign = SIGNS[int(deg // 30)]
+    d = deg % 30
+    m = (d % 1) * 60
+    return f"{int(d):2d}°{int(m):02d}' {sign}"

caelus_engine-0.8.0/astroengine/chebyshev.py

@@ -0,0 +1,94 @@
+"""astroengine.chebyshev -- segmented Chebyshev fit/eval for ephemeris data.
+
+The 'fit once, ship coefficients' recipe: sample any high-precision source
+(JPL DE, Horizons, ...) for a body's rectangular coordinates, fit Chebyshev
+polynomials per fixed-length time segment, store compactly as JSON. Runtime
+evaluation is a few dozen multiply-adds; derivatives are analytic.
+"""
+import json, math, os
+
+
+def _clenshaw(coeffs, x):
+    b0 = b1 = 0.0
+    for c in reversed(coeffs[1:]):
+        b0, b1 = 2.0 * x * b0 - b1 + c, b0
+    return x * b0 - b1 + coeffs[0]
+
+
+def cheb_eval_deriv(coeffs, x, half_span_days):
+    """Series value and time-derivative (per day) via derivative coefficients."""
+    n = len(coeffs)
+    d = [0.0] * n
+    for k in range(n - 1, 0, -1):
+        d[k - 1] = (d[k + 1] if k + 1 < n else 0.0) + 2.0 * k * coeffs[k]
+    d[0] *= 0.5
+    return _clenshaw(coeffs, x), _clenshaw(d[:max(n - 1, 1)], x) / half_span_days
+
+
+class ChebSeries:
+    """Runtime container: jd0, seg_days, segments[ [cx],[cy],[cz] ]."""
+
+    def __init__(self, data):
+        self.jd0 = data["jd0"]
+        self.seg = data["seg_days"]
+        self.segments = data["segments"]
+        self.jd1 = self.jd0 + self.seg * len(self.segments)
+        self.scale = data.get("scale", 1.0)
+
+    @classmethod
+    def load(cls, path):
+        with open(path) as f:
+            return cls(json.load(f))
+
+    def _locate(self, jd):
+        if not (self.jd0 <= jd <= self.jd1):
+            raise ValueError(f"jd {jd} outside fitted range {self.jd0}-{self.jd1}")
+        i = min(int((jd - self.jd0) / self.seg), len(self.segments) - 1)
+        x = 2.0 * (jd - (self.jd0 + i * self.seg)) / self.seg - 1.0
+        return i, x
+
+    def xyz(self, jd):
+        i, x = self._locate(jd)
+        s = self.segments[i]
+        return tuple(_clenshaw(c, x) * self.scale for c in s)
+
+    def xyz_vel(self, jd):
+        """Position and velocity (units/day)."""
+        i, x = self._locate(jd)
+        s = self.segments[i]
+        half = self.seg / 2.0
+        pos, vel = [], []
+        for c in s:
+            p, v = cheb_eval_deriv(c, x, half)
+            pos.append(p * self.scale)
+            vel.append(v * self.scale)
+        return tuple(pos), tuple(vel)
+
+
+def fit(sample_fn, jd0, jd1, seg_days, degree, scale=1.0, samples_per_seg=None,
+        sig=9):
+    """Fit segmented Chebyshev series.
+
+    sample_fn(jd_array) -> (x, y, z) arrays in source units.
+    scale: divide stored coefficients by this (runtime multiplies back).
+    Returns (data_dict, max_residual_in_source_units).
+    """
+    import numpy as np
+    nseg = int(math.ceil((jd1 - jd0) / seg_days))
+    m = samples_per_seg or (2 * degree + 2)
+    segments, max_resid = [], 0.0
+    # Chebyshev-Gauss-Lobatto sample points within each segment
+    xs = np.cos(np.pi * np.arange(m) / (m - 1))[::-1]  # [-1, 1]
+    for i in range(nseg):
+        a = jd0 + i * seg_days
+        jds = a + (xs + 1.0) * seg_days / 2.0
+        X, Y, Z = sample_fn(jds)
+        seg = []
+        for arr in (X, Y, Z):
+            c = np.polynomial.chebyshev.chebfit(xs, arr, degree)
+            resid = np.max(np.abs(np.polynomial.chebyshev.chebval(xs, c) - arr))
+            max_resid = max(max_resid, float(resid))
+            seg.append([float(f"%.{sig}g" % (v / scale)) for v in c])
+        segments.append(seg)
+    return {"jd0": jd0, "seg_days": seg_days, "scale": scale,
+            "segments": segments}, max_resid