caelus 0.7.0 → 0.9.0

package/README.md

@@ -100,4 +100,4 @@ test/golden.test.ts  conformance suite vs Python fixtures
 - caelus — this package
 - [caelus-birth](https://www.npmjs.com/package/caelus-birth) — local birth time + place → UT (charts take UT; use this)
 - [caelus-wheel](https://www.npmjs.com/package/caelus-wheel) — React SVG chart wheel
-- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, seven chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, nine chart tools over stdio

package/accuracy.json

@@ -269,5 +269,11 @@
     }
   ],
   "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)",
-  "true_node_vs_builtin": "1′"
+  "true_node_vs_builtin": "1′",
+  "counts": {
+    "house_systems": 12,
+    "sidereal_ayanamsas": 7,
+    "mcp_tools": 9,
+    "default_bodies": 13
+  }
 }

package/dist/src/electional.d.ts

@@ -0,0 +1,54 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export declare const CAZIMI_DEG = 0.2833;
+export declare const COMBUST_DEG = 8.5;
+export declare const UNDER_BEAMS_DEG = 15;
+/** Signed shortest angle from b to a, in (-180, 180] degrees. */
+export declare function signedElongation(lonA: number, lonB: number): number;
+/** Unsigned angular separation in [0, 180] degrees. */
+export declare function separation(lonA: number, lonB: number): number;
+export type AspectPhase = "applying" | "separating" | "exact";
+/** Applying/separating/exact for the aspect (degrees) between body a and body b,
+ *  from their longitudes and longitude speeds (deg/day). Applying = the orb to
+ *  the exact aspect is closing. */
+export declare function aspectPhase(lonA: number, speedA: number, lonB: number, speedB: number, aspectDeg: number): AspectPhase;
+export interface AspectMatch {
+    aspect: string;
+    orb: number;
+    separation: number;
+    phase: AspectPhase;
+}
+/** The tightest major aspect between two bodies at jd, within orb, or null.
+ *  orb is the signed distance from exact (degrees). */
+export declare function aspectBetween(engine: Engine, bodyA: BodyId, bodyB: BodyId, jdUt: number, zodiac?: Zodiac, orbs?: Record<string, number>): AspectMatch | null;
+export type SolarPhase = "cazimi" | "combust" | "under_beams" | null;
+/** Ecliptic-longitude separation between a body and the Sun (degrees). */
+export declare function solarElongation(engine: Engine, body: BodyId, jdUt: number, zodiac?: Zodiac): number;
+/** cazimi / combust / under_beams / null for a body's nearness to the Sun by
+ *  ecliptic longitude. The Sun itself returns null. */
+export declare function solarPhase(engine: Engine, body: BodyId, jdUt: number, zodiac?: Zodiac, cazimi?: number, combust?: number, underBeams?: number): SolarPhase;
+export interface PlanetaryHour {
+    ruler: string;
+    kind: "day" | "night";
+    hour: number;
+    dayRuler: string;
+    start: number;
+    end: number;
+}
+/** The planetary hour containing jdUt at a place, or null at latitudes where
+ *  the Sun does not rise or set on the day in question. */
+export declare function planetaryHour(engine: Engine, jdUt: number, lat: number, lonEast: number): PlanetaryHour | null;
+export interface VoidOfCourse {
+    isVoid: boolean;
+    sign: string;
+    signExit: number;
+    nextAspect: number | null;
+}
+/** Void-of-course state of the Moon at jdUt: void from its last perfecting
+ *  aspect to a traditional planet (Sun..Saturn) until it leaves the sign it
+ *  occupies at jdUt. */
+export declare function voidOfCourse(engine: Engine, jdUt: number, zodiac?: Zodiac, maxDays?: number): VoidOfCourse;
+/** 1-based house number for an ecliptic longitude (degrees) given the twelve
+ *  cusps (degrees), wrapping across 0. */
+export declare function houseOf(lon: number, cusps: number[]): number;
+/** angular / succedent / cadent for a 1-based house number. */
+export declare function angularity(house: number): "angular" | "succedent" | "cadent";

package/dist/src/electional.js

@@ -0,0 +1,222 @@
+/**
+ * astroengine electional -- electional building blocks on the validated
+ * primitives: applying/separating aspects, solar phase (combustion/cazimi),
+ * planetary hours, void-of-course Moon, and house placement.
+ *
+ * Arithmetic and time-mapping on apparent positions already checked against
+ * Swiss Ephemeris and JPL Horizons. Mirrors the Python reference
+ * (astroengine/electional.py); the golden fixtures pin the two together.
+ */
+import { mod } from "./core.js";
+import { SIGNS, ASPECTS, DEFAULT_ORBS } from "./chart.js";
+import { riseSet } from "./events.js";
+/** Chaldean order for planetary hours (slowest to fastest). */
+const CHALDEAN = ["saturn", "jupiter", "mars", "sun", "venus", "mercury", "moon"];
+/** Weekday ruler, index 0 = Sunday (Meeus day-of-week convention). */
+const DAY_RULERS = ["sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn"];
+export const CAZIMI_DEG = 0.2833; // 17 arcminutes
+export const COMBUST_DEG = 8.5;
+export const UNDER_BEAMS_DEG = 15.0;
+// Local copy of the events.ts bisection (identical), to keep the same roots.
+function bisect(f, a, b, iters = 45) {
+    let fa = f(a);
+    for (let i = 0; i < iters; i++) {
+        const m = (a + b) / 2;
+        if (fa * f(m) <= 0) {
+            b = m;
+        }
+        else {
+            a = m;
+            fa = f(a);
+        }
+    }
+    return (a + b) / 2;
+}
+function wrap180(x) {
+    return mod(x + 180.0, 360.0) - 180.0;
+}
+/** Signed shortest angle from b to a, in (-180, 180] degrees. */
+export function signedElongation(lonA, lonB) {
+    return wrap180(lonA - lonB);
+}
+/** Unsigned angular separation in [0, 180] degrees. */
+export function separation(lonA, lonB) {
+    return Math.abs(wrap180(lonA - lonB));
+}
+/** Applying/separating/exact for the aspect (degrees) between body a and body b,
+ *  from their longitudes and longitude speeds (deg/day). Applying = the orb to
+ *  the exact aspect is closing. */
+export function aspectPhase(lonA, speedA, lonB, speedB, aspectDeg) {
+    const e = wrap180(lonA - lonB);
+    const sep = Math.abs(e);
+    const dsepDt = (e >= 0.0 ? 1.0 : -1.0) * (speedA - speedB);
+    const orb = sep - aspectDeg;
+    if (Math.abs(orb) < 1e-9)
+        return "exact";
+    const dAbsOrbDt = (orb >= 0.0 ? 1.0 : -1.0) * dsepDt;
+    return dAbsOrbDt < 0.0 ? "applying" : "separating";
+}
+/** The tightest major aspect between two bodies at jd, within orb, or null.
+ *  orb is the signed distance from exact (degrees). */
+export function aspectBetween(engine, bodyA, bodyB, jdUt, zodiac = "tropical", orbs = DEFAULT_ORBS) {
+    const pa = engine.position(bodyA, jdUt, { zodiac });
+    const pb = engine.position(bodyB, jdUt, { zodiac });
+    const sep = separation(pa.lon, pb.lon);
+    let best = null;
+    for (const [name, deg] of Object.entries(ASPECTS)) {
+        const orb = sep - deg;
+        if (Math.abs(orb) <= (orbs[name] ?? 0.0)) {
+            if (best === null || Math.abs(orb) < Math.abs(best[1]))
+                best = [name, orb];
+        }
+    }
+    if (best === null)
+        return null;
+    const [name, orb] = best;
+    return {
+        aspect: name,
+        orb,
+        separation: sep,
+        phase: aspectPhase(pa.lon, pa.speed, pb.lon, pb.speed, ASPECTS[name]),
+    };
+}
+/** Ecliptic-longitude separation between a body and the Sun (degrees). */
+export function solarElongation(engine, body, jdUt, zodiac = "tropical") {
+    return separation(engine.longitude(body, jdUt, { zodiac }), engine.longitude("sun", jdUt, { zodiac }));
+}
+/** cazimi / combust / under_beams / null for a body's nearness to the Sun by
+ *  ecliptic longitude. The Sun itself returns null. */
+export function solarPhase(engine, body, jdUt, zodiac = "tropical", cazimi = CAZIMI_DEG, combust = COMBUST_DEG, underBeams = UNDER_BEAMS_DEG) {
+    if (body === "sun")
+        return null;
+    const sep = solarElongation(engine, body, jdUt, zodiac);
+    if (sep <= cazimi)
+        return "cazimi";
+    if (sep <= combust)
+        return "combust";
+    if (sep <= underBeams)
+        return "under_beams";
+    return null;
+}
+/** The planetary hour containing jdUt at a place, or null at latitudes where
+ *  the Sun does not rise or set on the day in question. */
+export function planetaryHour(engine, jdUt, lat, lonEast) {
+    let sr = riseSet(engine, "sun", jdUt - 1.0, lat, lonEast, "rise");
+    if (sr === null)
+        return null;
+    let nxt = riseSet(engine, "sun", sr + 0.01, lat, lonEast, "rise");
+    while (nxt !== null && nxt <= jdUt) {
+        sr = nxt;
+        nxt = riseSet(engine, "sun", sr + 0.01, lat, lonEast, "rise");
+    }
+    if (sr > jdUt)
+        return null;
+    const dayStart = sr;
+    const dayEnd = riseSet(engine, "sun", dayStart + 0.01, lat, lonEast, "set");
+    if (dayEnd === null)
+        return null;
+    const nightEnd = riseSet(engine, "sun", dayEnd + 0.01, lat, lonEast, "rise");
+    if (nightEnd === null)
+        return null;
+    let span;
+    let kind;
+    let hourNumber;
+    let start;
+    if (jdUt < dayEnd) {
+        span = (dayEnd - dayStart) / 12.0;
+        const idx = Math.min(Math.floor((jdUt - dayStart) / span), 11);
+        kind = "day";
+        hourNumber = idx;
+        start = dayStart + idx * span;
+    }
+    else {
+        span = (nightEnd - dayEnd) / 12.0;
+        const idx = Math.min(Math.floor((jdUt - dayEnd) / span), 11);
+        kind = "night";
+        hourNumber = 12 + idx;
+        start = dayEnd + idx * span;
+    }
+    const weekday = Math.floor(dayStart + 1.5) % 7; // 0 = Sunday
+    const dayRuler = DAY_RULERS[weekday];
+    const ruler = CHALDEAN[(CHALDEAN.indexOf(dayRuler) + hourNumber) % 7];
+    return { ruler, kind, hour: hourNumber + 1, dayRuler, start, end: start + span };
+}
+// --------------------------------------------------------- void-of-course Moon
+function perfections(engine, bodyA, bodyB, aspectDeg, jdStart, jdEnd, zodiac, step) {
+    const roots = [];
+    const orientations = aspectDeg !== 0.0 && aspectDeg !== 180.0 ? [1, -1] : [1];
+    for (const orient of orientations) {
+        const f = (t) => {
+            const la = engine.longitude(bodyA, t, { zodiac });
+            const lb = engine.longitude(bodyB, t, { zodiac });
+            return mod(la - lb - orient * aspectDeg + 180.0, 360.0) - 180.0;
+        };
+        let prev = f(jdStart);
+        for (let t = jdStart + step; t <= jdEnd; t += step) {
+            const cur = f(t);
+            if (prev * cur < 0.0 && Math.abs(cur - prev) < 180.0) {
+                roots.push(bisect(f, t - step, t));
+            }
+            prev = cur;
+        }
+    }
+    roots.sort((a, b) => a - b);
+    return roots;
+}
+/** Void-of-course state of the Moon at jdUt: void from its last perfecting
+ *  aspect to a traditional planet (Sun..Saturn) until it leaves the sign it
+ *  occupies at jdUt. */
+export function voidOfCourse(engine, jdUt, zodiac = "tropical", maxDays = 14.0) {
+    const moon = engine.longitude("moon", jdUt, { zodiac });
+    const sign = mod(Math.floor(moon / 30), 12);
+    const boundary = mod((sign + 1) * 30.0, 360.0);
+    const edge = (t) => mod(engine.longitude("moon", t, { zodiac }) - boundary + 180.0, 360.0) - 180.0;
+    let signExit = null;
+    const step = 0.125;
+    let prev = edge(jdUt);
+    for (let t = jdUt + step; t <= jdUt + maxDays; t += step) {
+        const cur = edge(t);
+        if (prev * cur < 0.0 && Math.abs(cur - prev) < 180.0) {
+            signExit = bisect(edge, t - step, t);
+            break;
+        }
+        prev = cur;
+    }
+    if (signExit === null)
+        signExit = jdUt + maxDays;
+    let nextAspect = null;
+    for (const planet of ["sun", "mercury", "venus", "mars", "jupiter", "saturn"]) {
+        for (const deg of Object.values(ASPECTS)) {
+            for (const jd of perfections(engine, "moon", planet, deg, jdUt, signExit, zodiac, 0.125)) {
+                if (jd > jdUt && (nextAspect === null || jd < nextAspect))
+                    nextAspect = jd;
+            }
+        }
+    }
+    return {
+        isVoid: nextAspect === null,
+        sign: SIGNS[sign],
+        signExit,
+        nextAspect,
+    };
+}
+// -------------------------------------------------------------- house helpers
+/** 1-based house number for an ecliptic longitude (degrees) given the twelve
+ *  cusps (degrees), wrapping across 0. */
+export function houseOf(lon, cusps) {
+    lon = mod(lon, 360.0);
+    for (let i = 0; i < 12; i++) {
+        const a = mod(cusps[i], 360.0);
+        const b = mod(cusps[(i + 1) % 12], 360.0);
+        const span = mod(b - a, 360.0);
+        if (span === 0.0)
+            continue;
+        if (mod(lon - a, 360.0) < span)
+            return i + 1;
+    }
+    return 12;
+}
+/** angular / succedent / cadent for a 1-based house number. */
+export function angularity(house) {
+    return ["angular", "succedent", "cadent"][(house - 1) % 3];
+}

package/dist/src/index.d.ts

@@ -7,3 +7,6 @@ export * from "./stars.js";
 export * from "./eclipses.js";
 export * from "./query.js";
 export * from "./derived.js";
+export * from "./turbo.js";
+export * from "./electional.js";
+export * from "./scan.js";

package/dist/src/index.js

@@ -7,3 +7,6 @@ export * from "./stars.js";
 export * from "./eclipses.js";
 export * from "./query.js";
 export * from "./derived.js";
+export * from "./turbo.js";
+export * from "./electional.js";
+export * from "./scan.js";

package/dist/src/scan.d.ts

@@ -0,0 +1,44 @@
+/**
+ * astroengine scan -- long-scan ergonomics over the engine: a batched scan with
+ * progress, and rankMoments to find the best instants by a score, synchronously
+ * or without blocking the event loop.
+ *
+ * This is control flow over the validated primitives, not new ephemeris. The
+ * score function is yours: compose it from positions, aspects, or the electional
+ * state. scan imposes no scoring model. Because the core engine does no I/O,
+ * these helpers (and the engine calls inside your score) run unchanged inside a
+ * Web Worker; rankMomentsAsync additionally yields to the event loop so a
+ * main-thread scan of hundreds of charts keeps the UI responsive.
+ */
+export interface ScanOptions {
+    /** First instant, UT Julian Day (inclusive). */
+    start: number;
+    /** Last instant, UT Julian Day (inclusive). */
+    end: number;
+    /** Spacing between samples, days. Must be positive. */
+    step: number;
+    /** Called with (done, total) sample counts during the scan. */
+    onProgress?: (done: number, total: number) => void;
+    /** Samples between progress callbacks (default 256). */
+    progressEvery?: number;
+}
+/** Number of samples a scan of these options visits. */
+export declare function sampleCount(start: number, end: number, step: number): number;
+/** Evaluate fn at each sampled instant in [start, end], returning the results in
+ *  time order. */
+export declare function scan<T>(opts: ScanOptions, fn: (jd: number) => T): T[];
+export interface RankOptions extends ScanOptions {
+    /** Keep only the top N moments (default: all). */
+    limit?: number;
+    /** Drop moments scoring below this (default: keep all). */
+    minScore?: number;
+}
+export interface RankedMoment {
+    jd: number;
+    score: number;
+}
+/** Score every sampled instant and return the best, highest score first. */
+export declare function rankMoments(opts: RankOptions, score: (jd: number) => number): RankedMoment[];
+/** rankMoments that yields to the event loop every `chunk` samples, so a long
+ *  main-thread scan does not freeze the UI. Same result as rankMoments. */
+export declare function rankMomentsAsync(opts: RankOptions, score: (jd: number) => number, chunk?: number): Promise<RankedMoment[]>;

package/dist/src/scan.js

@@ -0,0 +1,74 @@
+/**
+ * astroengine scan -- long-scan ergonomics over the engine: a batched scan with
+ * progress, and rankMoments to find the best instants by a score, synchronously
+ * or without blocking the event loop.
+ *
+ * This is control flow over the validated primitives, not new ephemeris. The
+ * score function is yours: compose it from positions, aspects, or the electional
+ * state. scan imposes no scoring model. Because the core engine does no I/O,
+ * these helpers (and the engine calls inside your score) run unchanged inside a
+ * Web Worker; rankMomentsAsync additionally yields to the event loop so a
+ * main-thread scan of hundreds of charts keeps the UI responsive.
+ */
+/** Number of samples a scan of these options visits. */
+export function sampleCount(start, end, step) {
+    if (step <= 0)
+        throw new Error("scan step must be positive");
+    if (end < start)
+        return 0;
+    return Math.floor((end - start) / step + 1e-9) + 1;
+}
+/** Evaluate fn at each sampled instant in [start, end], returning the results in
+ *  time order. */
+export function scan(opts, fn) {
+    const total = sampleCount(opts.start, opts.end, opts.step);
+    const every = opts.progressEvery ?? 256;
+    const out = [];
+    for (let i = 0; i < total; i++) {
+        out.push(fn(opts.start + i * opts.step));
+        if (opts.onProgress && (i + 1) % every === 0)
+            opts.onProgress(i + 1, total);
+    }
+    if (opts.onProgress && total > 0)
+        opts.onProgress(total, total);
+    return out;
+}
+function rank(moments, limit) {
+    // Highest score first; ties broken by earliest instant, so the order is
+    // deterministic and identical between the sync and async paths.
+    moments.sort((a, b) => b.score - a.score || a.jd - b.jd);
+    return limit === Infinity ? moments : moments.slice(0, limit);
+}
+/** Score every sampled instant and return the best, highest score first. */
+export function rankMoments(opts, score) {
+    const minScore = opts.minScore ?? -Infinity;
+    const moments = [];
+    scan(opts, (jd) => {
+        const s = score(jd);
+        if (s >= minScore)
+            moments.push({ jd, score: s });
+        return s;
+    });
+    return rank(moments, opts.limit ?? Infinity);
+}
+/** rankMoments that yields to the event loop every `chunk` samples, so a long
+ *  main-thread scan does not freeze the UI. Same result as rankMoments. */
+export async function rankMomentsAsync(opts, score, chunk = 256) {
+    const minScore = opts.minScore ?? -Infinity;
+    const total = sampleCount(opts.start, opts.end, opts.step);
+    const moments = [];
+    for (let i = 0; i < total; i++) {
+        const jd = opts.start + i * opts.step;
+        const s = score(jd);
+        if (s >= minScore)
+            moments.push({ jd, score: s });
+        if ((i + 1) % chunk === 0) {
+            if (opts.onProgress)
+                opts.onProgress(i + 1, total);
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    if (opts.onProgress && total > 0)
+        opts.onProgress(total, total);
+    return rank(moments, opts.limit ?? Infinity);
+}

package/dist/src/turbo.d.ts

@@ -0,0 +1,20 @@
+export interface TurboBody {
+    seg_days: number;
+    segments: number[][];
+}
+export interface TurboPack {
+    jd0: number;
+    jd1: number;
+    degree: number;
+    zodiac: string;
+    bodies: Record<string, TurboBody>;
+}
+export declare class Turbo {
+    readonly jd0: number;
+    readonly jd1: number;
+    private readonly bodies;
+    constructor(pack: TurboPack);
+    has(body: string): boolean;
+    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    longitude(body: string, jd: number): number;
+}

package/dist/src/turbo.js

@@ -0,0 +1,50 @@
+/**
+ * astroengine turbo -- fast longitude evaluator for a turbo pack.
+ *
+ * A turbo pack is a segmented Chebyshev representation of the engine's apparent
+ * longitude, fit to the engine itself (see python/astroengine/turbo.py and
+ * fit_turbo.py). Evaluating a longitude is a couple of dozen multiply-adds, so
+ * a century-scale transit scan that calls it tens of thousands of times runs in
+ * milliseconds. The pack is data you mint for your range and bodies; this is
+ * the runtime-only evaluator (no fitting, no engine, no I/O).
+ *
+ * The evaluator mirrors the Python reference exactly, so both reproduce the
+ * pack bit-identically.
+ */
+import { mod } from "./core.js";
+function clenshaw(coeffs, x) {
+    let b0 = 0;
+    let b1 = 0;
+    for (let i = coeffs.length - 1; i >= 1; i--) {
+        const t = 2 * x * b0 - b1 + coeffs[i];
+        b1 = b0;
+        b0 = t;
+    }
+    return x * b0 - b1 + coeffs[0];
+}
+export class Turbo {
+    jd0;
+    jd1;
+    bodies;
+    constructor(pack) {
+        this.jd0 = pack.jd0;
+        this.jd1 = pack.jd1;
+        this.bodies = pack.bodies;
+    }
+    has(body) {
+        return body in this.bodies;
+    }
+    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    longitude(body, jd) {
+        const b = this.bodies[body];
+        if (!b)
+            throw new Error(`turbo: no pack for ${body}`);
+        if (jd < this.jd0 || jd > this.jd1) {
+            throw new Error(`jd ${jd} outside turbo range ${this.jd0}-${this.jd1}`);
+        }
+        const seg = b.seg_days;
+        const i = Math.min(Math.floor((jd - this.jd0) / seg), b.segments.length - 1);
+        const x = 2 * (jd - (this.jd0 + i * seg)) / seg - 1;
+        return mod(clenshaw(b.segments[i], x), 360);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",