caelus 0.5.0 → 0.7.0

package/README.md

@@ -11,7 +11,7 @@ ephemeris files. 1:1 port of the Python reference, checked by golden fixtures.
    (vs full DE431 files, 1850–2149), angles and Placidus cusps ≤ 3.2″ — all
    invisible at the arcminute display precision chart software uses.
 2. TypeScript port verified against Python golden fixtures: **3,218 checks,
-   0 failures, worst deviation 1.64 nano-arcseconds.** The two implementations
+   0 failures, worst deviation 0.41 nano-arcseconds.** The two implementations
    are numerically identical.
 
 Regenerate fixtures any time from the Python side; any future TS change must

package/accuracy.json

@@ -107,9 +107,9 @@
     },
     {
       "name": "Sidereal longitudes",
-      "max": "0.1",
+      "max": "—",
       "rms": "—",
-      "note": "ayanamsa model vs SE ≤0.30″ at the 1900/2099 edges (IAU 1976 vs Vondrák precession); Sun worst-case 0.08″ at 120 sampled epochs"
+      "note": "ayanamsa model vs SE ≤0.005″ (Vondrák 2011, same model both sides); sidereal longitudes inherit each body's tropical bound"
     },
     {
       "name": "RA / Dec",
@@ -119,7 +119,7 @@
     },
     {
       "name": "Topocentric Moon",
-      "max": "2.7",
+      "max": "2.5",
       "rms": "—",
       "note": "parallax model adds ≤0.1″ over the geocentric bound"
     },
@@ -179,15 +179,15 @@
     },
     {
       "name": "Fixed stars (318-star catalog)",
-      "max": "0.6",
+      "max": "0.3",
       "rms": "—",
-      "note": "HYG-derived catalog (ICRS J2000 + proper motions, full 3D space motion); vs swe_fixstar fed the same rows. Floor is the IAU 1976 vs Vondrák precession difference"
+      "note": "HYG-derived catalog (ICRS J2000 + proper motions, full 3D space motion, Vondrák 2011 precession); vs swe_fixstar fed the same rows"
     },
     {
       "name": "Star-anchored ayanamsas",
-      "max": "0.2",
+      "max": "0.5",
       "rms": "—",
-      "note": "galcent_0sag and true_citra computed from the apparent star (Galactic Center / Spica); sidereal Sun vs SE ≤0.19″"
+      "note": "galcent_0sag and true_citra computed from the apparent star; bound tracks the fixed-star chain (≤0.3″) plus the body's tropical accuracy"
     },
     {
       "name": "Gauquelin sectors",
@@ -257,11 +257,11 @@
     },
     {
       "label": "Fixed stars",
-      "bound": "≤ 0.6″"
+      "bound": "≤ 0.3″"
     },
     {
       "label": "Sidereal (7 ayanamsas)",
-      "bound": "≤ 0.3″ added"
+      "bound": "≤ 0.005″ added"
     },
     {
       "label": "Eclipses",

package/dist/src/core.d.ts

@@ -69,7 +69,8 @@ export declare function vsopHeliocentric(series: VsopSeries, jde: number): [numb
 export declare function nutation(data: EngineData, jde: number): [number, number];
 export declare function meanObliquity(jde: number): number;
 export declare function trueObliquity(data: EngineData, jde: number): number;
-/** Precession of ecliptic coordinates (Meeus 21.7). */
+/** Precession of ecliptic coordinates between epochs (Vondrak 2011):
+ *  ecliptic-of-from -> J2000 equatorial -> ecliptic-of-to. */
 export declare function precessEcliptic(lon: number, lat: number, jdeFrom: number, jdeTo: number): [number, number];
 /** Apparent geocentric ecliptic lon/lat (true equinox of date), distance. */
 export declare function planetApparent(data: EngineData, name: string, jde: number): [number, number, number];
@@ -96,9 +97,9 @@ export declare function trueNodeSeries(data: EngineData, jde: number): number;
 /** Ecliptic lon/lat -> right ascension, declination (all radians). */
 export declare function equatorial(lon: number, lat: number, eps: number): [number, number];
 /** Mean ayanamsa at J2000.0 (degrees) per mode. Standard epoch anchors
- *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses IAU 1976
- *  ecliptic precession. Agreement with Swiss Ephemeris over 1900-2099 is
- *  <=0.30 arcsec (precession-model difference: SE uses Vondrak 2011). */
+ *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses Vondrak
+ *  2011 ecliptic precession, the same model Swiss Ephemeris uses:
+ *  agreement over 1900-2099 is <=0.005 arcsec. */
 export declare const AYANAMSA_J2000: Record<string, number>;
 /** Mean ayanamsa in degrees. Sidereal longitude = (tropical true-equinox
  *  longitude - nutation in longitude) - ayanamsa: the sidereal zodiac is

package/dist/src/core.js

@@ -140,48 +140,138 @@ function fk5Correction(L, B, jde) {
     const dB = 0.03916 * ARCSEC * (Math.cos(Lp) - Math.sin(Lp));
     return [L + dL, B + dB];
 }
-/** Precession of ecliptic coordinates (Meeus 21.7). */
+// ------------------------------------------------- Vondrak 2011 precession
+// Long-term precession of the ecliptic and equator (Vondrak, Capitaine &
+// Wallace 2011, A&A 534 A22; coefficient tables as carried by ERFA under
+// BSD-3). Replaces the IAU 1976 angles.
+const PQ_POL = [
+    [5851.607687, -0.1189, -0.00028913, 0.000000101],
+    [-1600.8863, 1.1689818, -0.0000002, -0.000000437],
+];
+const PQ_PER = [
+    [708.15, -5486.751211, -684.66156, 667.66673, -5523.863691],
+    [2309.0, -17.127623, 2446.28388, -2354.886252, -549.74745],
+    [1620.0, -617.517403, 399.671049, -428.152441, -310.998056],
+    [492.2, 413.44294, -356.652376, 376.202861, 421.535876],
+    [1183.0, 78.614193, -186.387003, 184.778874, -36.776172],
+    [622.0, -180.732815, -316.80007, 335.321713, -145.278396],
+    [882.0, -87.676083, 198.296701, -185.138669, -34.74445],
+    [547.0, 46.140315, 101.135679, -120.97283, 22.885731],
+];
+const XY_POL = [
+    [5453.282155, 0.4252841, -0.00037173, -0.000000152],
+    [-73750.93035, -0.7675452, -0.00018725, 0.000000231],
+];
+const XY_PER = [
+    [256.75, -819.940624, 75004.344875, 81491.287984, 1558.515853],
+    [708.15, -8444.676815, 624.033993, 787.163481, 7774.939698],
+    [274.2, 2600.009459, 1251.136893, 1251.296102, -2219.534038],
+    [241.45, 2755.17563, -1102.212834, -1257.950837, -2523.969396],
+    [2309.0, -167.659835, -2660.66498, -2966.79973, 247.850422],
+    [492.2, 871.855056, 699.291817, 639.744522, -846.485643],
+    [396.1, 44.769698, 153.16722, 131.600209, -1393.124055],
+    [288.9, -512.313065, -950.865637, -445.040117, 368.526116],
+    [231.1, -819.415595, 499.754645, 584.522874, 749.045012],
+    [1610.0, -538.071099, -145.18821, -89.756563, 444.704518],
+    [620.0, -189.793622, 558.116553, 524.42963, 235.934465],
+    [157.87, -402.922932, -23.923029, -13.549067, 374.049623],
+    [220.3, 179.516345, -165.405086, -210.157124, -171.33018],
+    [1200.0, -9.814756, 9.344131, -44.919798, -22.899655],
+];
+const EPS0_V = 84381.406 * ARCSEC; // J2000 obliquity of the Vondrak model
+const EPS0_FRAME = 84381.448 * ARCSEC; // obliquity defining our ecliptic-J2000 data
+function ltpPecl(jde) {
+    const t = (jde - J2000) / 36525.0;
+    let p = 0.0;
+    let q = 0.0;
+    const w = 2.0 * Math.PI * t;
+    for (const [per, c1, c2, s1, s2] of PQ_PER) {
+        const a = w / per;
+        const ca = Math.cos(a);
+        const sa = Math.sin(a);
+        p += ca * c1 + sa * s1;
+        q += ca * c2 + sa * s2;
+    }
+    let tn = 1.0;
+    for (let i = 0; i < 4; i++) {
+        p += PQ_POL[0][i] * tn;
+        q += PQ_POL[1][i] * tn;
+        tn *= t;
+    }
+    p *= ARCSEC;
+    q *= ARCSEC;
+    const z = Math.sqrt(Math.max(1.0 - p * p - q * q, 0.0));
+    const s = Math.sin(EPS0_V);
+    const c = Math.cos(EPS0_V);
+    return [p, -q * c - z * s, -q * s + z * c];
+}
+function ltpPequ(jde) {
+    const t = (jde - J2000) / 36525.0;
+    let x = 0.0;
+    let y = 0.0;
+    const w = 2.0 * Math.PI * t;
+    for (const [per, c1, c2, s1, s2] of XY_PER) {
+        const a = w / per;
+        const ca = Math.cos(a);
+        const sa = Math.sin(a);
+        x += ca * c1 + sa * s1;
+        y += ca * c2 + sa * s2;
+    }
+    let tn = 1.0;
+    for (let i = 0; i < 4; i++) {
+        x += XY_POL[0][i] * tn;
+        y += XY_POL[1][i] * tn;
+        tn *= t;
+    }
+    x *= ARCSEC;
+    y *= ARCSEC;
+    return [x, y, Math.sqrt(Math.max(1.0 - x * x - y * y, 0.0))];
+}
+/** Rows of the rotation J2000-equatorial -> mean ecliptic/equinox of date
+ *  (ERFA eraLtecm): x = equinox, z = ecliptic pole, y = z cross x. */
+function ltpEclMatrix(jde) {
+    const p = ltpPequ(jde);
+    const z = ltpPecl(jde);
+    const wx = [
+        p[1] * z[2] - p[2] * z[1], p[2] * z[0] - p[0] * z[2], p[0] * z[1] - p[1] * z[0],
+    ];
+    const n = Math.sqrt(wx[0] ** 2 + wx[1] ** 2 + wx[2] ** 2);
+    const x = [wx[0] / n, wx[1] / n, wx[2] / n];
+    const y = [
+        z[1] * x[2] - z[2] * x[1], z[2] * x[0] - z[0] * x[2], z[0] * x[1] - z[1] * x[0],
+    ];
+    return [x, y, z];
+}
+/** Precession of ecliptic coordinates between epochs (Vondrak 2011):
+ *  ecliptic-of-from -> J2000 equatorial -> ecliptic-of-to. */
 export function precessEcliptic(lon, lat, jdeFrom, jdeTo) {
-    const T = (jdeFrom - J2000) / 36525.0;
-    const t = (jdeTo - jdeFrom) / 36525.0;
-    const eta = ((47.0029 - 0.06603 * T + 0.000598 * T * T) * t
-        + (-0.03302 + 0.000598 * T) * t * t + 0.00006 * t ** 3) * ARCSEC;
-    const Pi = (174.876384 * 3600 + 3289.4789 * T + 0.60622 * T * T) * ARCSEC
-        - ((869.8089 + 0.50491 * T) * t - 0.03536 * t * t) * ARCSEC;
-    const p = ((5029.0966 + 2.22226 * T - 0.000042 * T * T) * t
-        + (1.11113 - 0.000042 * T) * t * t - 0.000006 * t ** 3) * ARCSEC;
-    const se = Math.sin(eta);
-    const ce = Math.cos(eta);
-    const A = ce * Math.cos(lat) * Math.sin(Pi - lon) - se * Math.sin(lat);
-    const Bv = Math.cos(lat) * Math.cos(Pi - lon);
-    const C = ce * Math.sin(lat) + se * Math.cos(lat) * Math.sin(Pi - lon);
-    return [mod(p + Pi - Math.atan2(A, Bv), TWO_PI), Math.asin(C)];
-}
-/** Rotate a vector from ecliptic-J2000 to ecliptic-of-date frame. */
+    const cb = Math.cos(lat);
+    const v = [cb * Math.cos(lon), cb * Math.sin(lon), Math.sin(lat)];
+    const [xf, yf, zf] = ltpEclMatrix(jdeFrom);
+    const e = [0, 1, 2].map((i) => xf[i] * v[0] + yf[i] * v[1] + zf[i] * v[2]);
+    const [xt, yt, zt] = ltpEclMatrix(jdeTo);
+    const u = [
+        xt[0] * e[0] + xt[1] * e[1] + xt[2] * e[2],
+        yt[0] * e[0] + yt[1] * e[1] + yt[2] * e[2],
+        zt[0] * e[0] + zt[1] * e[1] + zt[2] * e[2],
+    ];
+    return [mod(Math.atan2(u[1], u[0]), TWO_PI),
+        Math.asin(Math.max(-1, Math.min(1, u[2])))];
+}
+/** Rotate a vector from the ecliptic-J2000 data frame (obliquity 84381.448
+ *  arcsec, as used by Horizons/Meeus) to the mean ecliptic of date
+ *  (Vondrak 2011). */
 function eclJ2000ToEclDate(v, jde) {
-    let [x, y, z] = v;
-    const e0 = 84381.448 * ARCSEC;
-    [y, z] = [y * Math.cos(e0) - z * Math.sin(e0), y * Math.sin(e0) + z * Math.cos(e0)];
-    const T = (jde - J2000) / 36525.0;
-    const zeta = (2306.2181 * T + 0.30188 * T * T + 0.017998 * T ** 3) * ARCSEC;
-    const zz = (2306.2181 * T + 1.09468 * T * T + 0.018203 * T ** 3) * ARCSEC;
-    const th = (2004.3109 * T - 0.42665 * T * T - 0.041833 * T ** 3) * ARCSEC;
-    const rz = (a) => {
-        const c = Math.cos(a);
-        const s = Math.sin(a);
-        [x, y] = [c * x + s * y, -s * x + c * y];
-    };
-    const ry = (a) => {
-        const c = Math.cos(a);
-        const s = Math.sin(a);
-        [x, z] = [c * x - s * z, s * x + c * z];
-    };
-    rz(-zeta);
-    ry(th);
-    rz(-zz);
-    const e = meanObliquity(jde);
-    [y, z] = [y * Math.cos(e) + z * Math.sin(e), -y * Math.sin(e) + z * Math.cos(e)];
-    return [x, y, z];
+    const [x, y, z] = v;
+    const s = Math.sin(EPS0_FRAME);
+    const c = Math.cos(EPS0_FRAME);
+    const e = [x, y * c - z * s, y * s + z * c];
+    const [xt, yt, zt] = ltpEclMatrix(jde);
+    return [
+        xt[0] * e[0] + xt[1] * e[1] + xt[2] * e[2],
+        yt[0] * e[0] + yt[1] * e[1] + yt[2] * e[2],
+        zt[0] * e[0] + zt[1] * e[1] + zt[2] * e[2],
+    ];
 }
 // ---------------------------------------------------------------- planets
 function geoVector(data, name, jde) {
@@ -385,9 +475,9 @@ export function equatorial(lon, lat, eps) {
     return [ra, dec];
 }
 /** Mean ayanamsa at J2000.0 (degrees) per mode. Standard epoch anchors
- *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses IAU 1976
- *  ecliptic precession. Agreement with Swiss Ephemeris over 1900-2099 is
- *  <=0.30 arcsec (precession-model difference: SE uses Vondrak 2011). */
+ *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses Vondrak
+ *  2011 ecliptic precession, the same model Swiss Ephemeris uses:
+ *  agreement over 1900-2099 is <=0.005 arcsec. */
 export const AYANAMSA_J2000 = {
     lahiri: 23.857092325,
     fagan_bradley: 24.740299966,

package/dist/src/derived.d.ts

@@ -0,0 +1,51 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export declare const TROPICAL_YEAR = 365.24219;
+/** Shorter-arc midpoint of two longitudes (degrees). */
+export declare function midpointLon(a: number, b: number): number;
+/** UT JDs in [jdStart, jdEnd] when `body` returns to its natal longitude.
+ *  Outer-planet returns can show three crossings around a retrograde loop. */
+export declare function returns(engine: Engine, body: BodyId, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac, maxHits?: number): number[];
+export declare function solarReturn(engine: Engine, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac): number[];
+export declare function lunarReturn(engine: Engine, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac): number[];
+/** The JD whose real positions are the secondary-progressed positions for the
+ *  age (targetJd - natalJd): one day of motion per year of life. */
+export declare function progressedJd(natalJd: number, targetJd: number, yearLength?: number): number;
+export declare function progressedLongitude(engine: Engine, body: BodyId, natalJd: number, targetJd: number, yearLength?: number, zodiac?: Zodiac): number;
+/** Solar-arc direction angle (degrees, forward): how far the secondary-
+ *  progressed Sun has moved from the natal Sun. Add it to any natal longitude. */
+export declare function solarArc(engine: Engine, natalJd: number, targetJd: number, yearLength?: number, zodiac?: Zodiac): number;
+export declare function directedLongitude(engine: Engine, body: BodyId, natalJd: number, targetJd: number, yearLength?: number, zodiac?: Zodiac): number;
+/** Midpoint-method composite: the shorter-arc midpoint of each body's two
+ *  longitudes. Angles compose the same way via midpointLon on the two ASC/MC. */
+export declare function compositeLongitudes(engine: Engine, jdA: number, jdB: number, bodies: BodyId[], zodiac?: Zodiac): Record<string, number>;
+/** Time and place for a Davison relationship chart: the temporal midpoint and
+ *  the geographic midpoint (mean latitude, shorter-arc mean longitude). Compute
+ *  a normal chart at these to get the Davison chart. Returns [jd, lat, lonEast]. */
+export declare function davisonParams(jdA: number, jdB: number, latA: number, lonEastA: number, latB: number, lonEastB: number): [number, number, number];
+/** The nth-harmonic longitude of a point: lon * n, wrapped to 360. */
+export declare function harmonicLongitude(lon: number, n: number): number;
+export declare function harmonicChart(engine: Engine, jd: number, bodies: BodyId[], n: number, zodiac?: Zodiac): Record<string, number>;
+/** Reflection across the solstice (Cancer-Capricorn) axis. */
+export declare function antiscion(lon: number): number;
+/** Reflection across the equinox (Aries-Libra) axis. */
+export declare function contraAntiscion(lon: number): number;
+export type DeclinationKind = "parallel" | "contraparallel" | null;
+/** Classify two declinations: parallel (same), contraparallel (opposite), null. */
+export declare function declinationAspect(decA: number, decB: number, orb?: number): DeclinationKind;
+export interface DeclinationPair {
+    a: string;
+    b: string;
+    kind: DeclinationKind;
+}
+export declare function declinationAspects(engine: Engine, bodies: BodyId[], jd: number, orb?: number): DeclinationPair[];
+/** |declination| minus the mean obliquity, degrees. Positive = out of bounds. */
+export declare function outOfBoundsMargin(engine: Engine, body: BodyId, jd: number): number;
+export declare function outOfBounds(engine: Engine, body: BodyId, jd: number): boolean;
+/** Essential dignities of `body` in `sign`: domicile, exaltation, detriment,
+ *  fall (the last two are the signs opposite domicile and exaltation). */
+export declare function dignities(body: string, sign: number | string): string[];
+export declare function dignityOf(engine: Engine, body: BodyId, jd: number, zodiac?: Zodiac): string[];
+/** Diurnal when the Sun is above the horizon at the given place. */
+export declare function isDayChart(engine: Engine, jd: number, lat: number, lonEast: number): boolean;
+export declare function planetarySect(body: string): "diurnal" | "nocturnal" | null;
+export declare function inSect(body: string, dayChart: boolean): boolean | null;

package/dist/src/derived.js

@@ -0,0 +1,184 @@
+/**
+ * astroengine derived -- standard chart derivations built on the validated
+ * primitives: returns, secondary progressions, solar arc directions, composite
+ * charts, Davison charts.
+ *
+ * These are constructions on top of apparent positions (already checked against
+ * Swiss Ephemeris), so this layer is time-mapping and arithmetic, not new
+ * ephemeris. Mirrors the Python reference (astroengine/derived.py); the
+ * golden fixtures pin the two together.
+ */
+import { mod, meanObliquity, jdTT, DEG } from "./core.js";
+import { SIGNS } from "./chart.js";
+import { crossings } from "./events.js";
+import { azAlt } from "./pheno.js";
+export const TROPICAL_YEAR = 365.24219; // mean tropical year, days
+/** Shorter-arc midpoint of two longitudes (degrees). */
+export function midpointLon(a, b) {
+    const d = mod(b - a + 180, 360) - 180; // signed shortest a -> b
+    return mod(a + d / 2, 360);
+}
+// ---------------------------------------------------------------- returns
+/** UT JDs in [jdStart, jdEnd] when `body` returns to its natal longitude.
+ *  Outer-planet returns can show three crossings around a retrograde loop. */
+export function returns(engine, body, natalJd, jdStart, jdEnd, zodiac = "tropical", maxHits = 60) {
+    const natalLon = engine.longitude(body, natalJd, { zodiac });
+    return crossings(engine, body, natalLon, jdStart, jdEnd, zodiac, maxHits);
+}
+export function solarReturn(engine, natalJd, jdStart, jdEnd, zodiac = "tropical") {
+    return returns(engine, "sun", natalJd, jdStart, jdEnd, zodiac);
+}
+export function lunarReturn(engine, natalJd, jdStart, jdEnd, zodiac = "tropical") {
+    return returns(engine, "moon", natalJd, jdStart, jdEnd, zodiac);
+}
+// ----------------------------------------------- secondary progressions
+/** The JD whose real positions are the secondary-progressed positions for the
+ *  age (targetJd - natalJd): one day of motion per year of life. */
+export function progressedJd(natalJd, targetJd, yearLength = TROPICAL_YEAR) {
+    return natalJd + (targetJd - natalJd) / yearLength;
+}
+export function progressedLongitude(engine, body, natalJd, targetJd, yearLength = TROPICAL_YEAR, zodiac = "tropical") {
+    return engine.longitude(body, progressedJd(natalJd, targetJd, yearLength), { zodiac });
+}
+// ----------------------------------------------------------- solar arc
+/** Solar-arc direction angle (degrees, forward): how far the secondary-
+ *  progressed Sun has moved from the natal Sun. Add it to any natal longitude. */
+export function solarArc(engine, natalJd, targetJd, yearLength = TROPICAL_YEAR, zodiac = "tropical") {
+    const pjd = progressedJd(natalJd, targetJd, yearLength);
+    const natalSun = engine.longitude("sun", natalJd, { zodiac });
+    const progSun = engine.longitude("sun", pjd, { zodiac });
+    return mod(progSun - natalSun, 360); // Sun only moves forward
+}
+export function directedLongitude(engine, body, natalJd, targetJd, yearLength = TROPICAL_YEAR, zodiac = "tropical") {
+    const arc = solarArc(engine, natalJd, targetJd, yearLength, zodiac);
+    return mod(engine.longitude(body, natalJd, { zodiac }) + arc, 360);
+}
+// ----------------------------------------------------------- composite
+/** Midpoint-method composite: the shorter-arc midpoint of each body's two
+ *  longitudes. Angles compose the same way via midpointLon on the two ASC/MC. */
+export function compositeLongitudes(engine, jdA, jdB, bodies, zodiac = "tropical") {
+    const out = {};
+    for (const body of bodies) {
+        const la = engine.longitude(body, jdA, { zodiac });
+        const lb = engine.longitude(body, jdB, { zodiac });
+        out[body] = midpointLon(la, lb);
+    }
+    return out;
+}
+// ----------------------------------------------------------- davison
+/** Time and place for a Davison relationship chart: the temporal midpoint and
+ *  the geographic midpoint (mean latitude, shorter-arc mean longitude). Compute
+ *  a normal chart at these to get the Davison chart. Returns [jd, lat, lonEast]. */
+export function davisonParams(jdA, jdB, latA, lonEastA, latB, lonEastB) {
+    const midJd = 0.5 * (jdA + jdB);
+    const midLat = 0.5 * (latA + latB);
+    let midLon = midpointLon(mod(lonEastA, 360), mod(lonEastB, 360));
+    if (midLon > 180)
+        midLon -= 360; // back to (-180, 180] east-longitude
+    return [midJd, midLat, midLon];
+}
+// ----------------------------------------------------------- harmonics
+/** The nth-harmonic longitude of a point: lon * n, wrapped to 360. */
+export function harmonicLongitude(lon, n) {
+    return mod(lon * n, 360);
+}
+export function harmonicChart(engine, jd, bodies, n, zodiac = "tropical") {
+    const out = {};
+    for (const b of bodies)
+        out[b] = harmonicLongitude(engine.longitude(b, jd, { zodiac }), n);
+    return out;
+}
+// ----------------------------------------------------------- antiscia
+/** Reflection across the solstice (Cancer-Capricorn) axis. */
+export function antiscion(lon) {
+    return mod(180 - lon, 360);
+}
+/** Reflection across the equinox (Aries-Libra) axis. */
+export function contraAntiscion(lon) {
+    return mod(-lon, 360);
+}
+/** Classify two declinations: parallel (same), contraparallel (opposite), null. */
+export function declinationAspect(decA, decB, orb = 1.0) {
+    if (Math.abs(decA - decB) <= orb)
+        return "parallel";
+    if (Math.abs(decA + decB) <= orb)
+        return "contraparallel";
+    return null;
+}
+export function declinationAspects(engine, bodies, jd, orb = 1.0) {
+    const decs = {};
+    for (const b of bodies)
+        decs[b] = engine.position(b, jd).dec;
+    const out = [];
+    for (let i = 0; i < bodies.length; i++) {
+        for (let j = i + 1; j < bodies.length; j++) {
+            const kind = declinationAspect(decs[bodies[i]], decs[bodies[j]], orb);
+            if (kind)
+                out.push({ a: bodies[i], b: bodies[j], kind });
+        }
+    }
+    return out;
+}
+// ----------------------------------------------------------- out of bounds
+/** |declination| minus the mean obliquity, degrees. Positive = out of bounds. */
+export function outOfBoundsMargin(engine, body, jd) {
+    const dec = engine.position(body, jd).dec;
+    const eps = meanObliquity(jdTT(jd)) / DEG;
+    return Math.abs(dec) - eps;
+}
+export function outOfBounds(engine, body, jd) {
+    return outOfBoundsMargin(engine, body, jd) > 0;
+}
+// ----------------------------------------------------------- dignities
+const DOMICILE = {
+    sun: [4], moon: [3], mercury: [2, 5], venus: [1, 6],
+    mars: [0, 7], jupiter: [8, 11], saturn: [9, 10],
+};
+const EXALTATION = {
+    sun: 0, moon: 1, mercury: 5, venus: 11, mars: 9, jupiter: 3, saturn: 6,
+};
+function signIndex(sign) {
+    return typeof sign === "number" ? sign : SIGNS.indexOf(sign);
+}
+/** Essential dignities of `body` in `sign`: domicile, exaltation, detriment,
+ *  fall (the last two are the signs opposite domicile and exaltation). */
+export function dignities(body, sign) {
+    const idx = signIndex(sign);
+    const dom = DOMICILE[body] ?? [];
+    const out = [];
+    if (dom.includes(idx))
+        out.push("domicile");
+    if (EXALTATION[body] === idx)
+        out.push("exaltation");
+    if (dom.map((d) => mod(d + 6, 12)).includes(idx))
+        out.push("detriment");
+    if (body in EXALTATION && mod(EXALTATION[body] + 6, 12) === idx)
+        out.push("fall");
+    return out;
+}
+export function dignityOf(engine, body, jd, zodiac = "tropical") {
+    const lon = engine.longitude(body, jd, { zodiac });
+    return dignities(body, mod(Math.floor(lon / 30), 12));
+}
+// ----------------------------------------------------------- sect
+const DIURNAL = new Set(["sun", "jupiter", "saturn"]);
+const NOCTURNAL = new Set(["moon", "venus", "mars"]);
+/** Diurnal when the Sun is above the horizon at the given place. */
+export function isDayChart(engine, jd, lat, lonEast) {
+    const sun = engine.position("sun", jd);
+    const [, alt] = azAlt(engine.data, sun.lon, sun.lat, jd, lat, lonEast);
+    return alt > 0;
+}
+export function planetarySect(body) {
+    if (DIURNAL.has(body))
+        return "diurnal";
+    if (NOCTURNAL.has(body))
+        return "nocturnal";
+    return null;
+}
+export function inSect(body, dayChart) {
+    const s = planetarySect(body);
+    if (s === null)
+        return null;
+    return (s === "diurnal") === Boolean(dayChart);
+}

package/dist/src/index.d.ts

@@ -5,3 +5,5 @@ export * from "./pheno.js";
 export * from "./events.js";
 export * from "./stars.js";
 export * from "./eclipses.js";
+export * from "./query.js";
+export * from "./derived.js";

package/dist/src/index.js

@@ -5,3 +5,5 @@ export * from "./pheno.js";
 export * from "./events.js";
 export * from "./stars.js";
 export * from "./eclipses.js";
+export * from "./query.js";
+export * from "./derived.js";

package/dist/src/query.d.ts

@@ -0,0 +1,32 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export declare const QUERY_ASPECTS: Record<string, number>;
+export type Interval = [number, number];
+/** Margin function (true where >= 0) carrying the bodies it depends on. */
+export interface Predicate {
+    (engine: Engine, t: number): number;
+    bodies: Set<string>;
+}
+/** True while `body` is within `orb` deg of an exact `kind` aspect to
+ *  `target` -- a fixed ecliptic longitude (deg) or another body name. */
+export declare function aspect(body: BodyId, kind: string, target: number | BodyId, orb?: number, zodiac?: Zodiac): Predicate;
+/** True while `body` is in `sign` (index 0=Aries..11=Pisces, or name). */
+export declare function inSign(body: BodyId, sign: number | string, zodiac?: Zodiac): Predicate;
+/** True while `body` is in apparent retrograde motion. */
+export declare function retrograde(body: BodyId, zodiac?: Zodiac): Predicate;
+/** True while `body` is direct or stationary. */
+export declare function notRetrograde(body: BodyId, zodiac?: Zodiac): Predicate;
+/** True where every predicate is true (interval intersection). */
+export declare function allOf(...preds: Predicate[]): Predicate;
+/** True where any predicate is true (interval union). */
+export declare function anyOf(...preds: Predicate[]): Predicate;
+/** True where `pred` is false (interval complement). */
+export declare function notOf(pred: Predicate): Predicate;
+export interface WhenOptions {
+    step?: number;
+    maxIntervals?: number;
+}
+/** Time intervals (jdStartUt, jdEndUt) in [jdStart, jdEnd] where `predicate`
+ *  is true. Endpoints touching the range bounds are clamped. The scan step
+ *  defaults to 0.125 d when a fast body (Moon, nodes, Lilith) is involved
+ *  and 1 d otherwise. */
+export declare function when(engine: Engine, predicate: Predicate, jdStart: number, jdEnd: number, opts?: WhenOptions): Interval[];

package/dist/src/query.js

@@ -0,0 +1,161 @@
+/**
+ * astroengine query -- declarative time queries ("when is ...?").
+ *
+ * The engine answers "where is the body?"; this answers "when is the
+ * configuration true?" over a time range. A predicate is a continuous
+ * "margin" function, true exactly where margin >= 0 (e.g. aspect-within-orb
+ * -> orb minus angular distance from exact). A boolean combination is then
+ * itself a margin -- AND = min of the parts, OR = max, NOT = negation -- so
+ * any query reduces to one continuous function and `when()` returns the
+ * intervals where it is true using the same coarse-scan-then-bisect root
+ * finder as events.crossings.
+ *
+ *   when(engine, allOf(aspect("saturn", "square", natalMoon),
+ *                      notRetrograde("mercury"),
+ *                      inSign("venus", "Taurus")), jdStart, jdEnd)
+ *
+ * Mirrors the Python reference (astroengine/query.py); the golden fixtures
+ * pin the two implementations together.
+ */
+import { mod } from "./core.js";
+import { SIGNS } from "./chart.js";
+export const QUERY_ASPECTS = {
+    conjunction: 0, semisextile: 30, sextile: 60, square: 90,
+    trine: 120, quincunx: 150, opposition: 180,
+};
+const FAST = new Set([
+    "moon", "mean_node", "true_node", "mean_lilith", "true_lilith",
+]);
+function wrap180(d) {
+    return mod(d + 180, 360) - 180;
+}
+function mk(fn, bodies) {
+    const p = fn;
+    p.bodies = bodies;
+    return p;
+}
+// ---------------------------------------------------------------- predicates
+/** True while `body` is within `orb` deg of an exact `kind` aspect to
+ *  `target` -- a fixed ecliptic longitude (deg) or another body name. */
+export function aspect(body, kind, target, orb = 1.0, zodiac = "tropical") {
+    const ang = QUERY_ASPECTS[kind];
+    if (ang === undefined)
+        throw new Error(`unknown aspect ${kind}`);
+    const isLon = typeof target === "number";
+    const bodies = new Set([body]);
+    if (!isLon)
+        bodies.add(target);
+    return mk((engine, t) => {
+        const lon = engine.longitude(body, t, { zodiac });
+        const tl = isLon
+            ? target
+            : engine.longitude(target, t, { zodiac });
+        const sep = lon - tl;
+        return orb - Math.min(Math.abs(wrap180(sep - ang)), Math.abs(wrap180(sep + ang)));
+    }, bodies);
+}
+/** True while `body` is in `sign` (index 0=Aries..11=Pisces, or name). */
+export function inSign(body, sign, zodiac = "tropical") {
+    const idx = typeof sign === "number" ? sign : SIGNS.indexOf(sign);
+    if (idx < 0)
+        throw new Error(`unknown sign ${sign}`);
+    const lo = idx * 30;
+    return mk((engine, t) => {
+        const d = mod(engine.longitude(body, t, { zodiac }) - lo, 360);
+        // signed distance to the nearest 30-deg band edge, positive inside
+        return d <= 30 ? Math.min(d, 30 - d) : -Math.min(d - 30, 360 - d);
+    }, new Set([body]));
+}
+/** True while `body` is in apparent retrograde motion. */
+export function retrograde(body, zodiac = "tropical") {
+    const h = 0.25;
+    return mk((engine, t) => {
+        const l0 = engine.longitude(body, t - h, { zodiac });
+        const l1 = engine.longitude(body, t + h, { zodiac });
+        return -wrap180(l1 - l0) / (2 * h); // >= 0 when moving backwards
+    }, new Set([body]));
+}
+/** True while `body` is direct or stationary. */
+export function notRetrograde(body, zodiac = "tropical") {
+    return notOf(retrograde(body, zodiac));
+}
+// --------------------------------------------------------------- combinators
+function combine(op, preds) {
+    const bodies = new Set();
+    for (const p of preds)
+        for (const b of p.bodies)
+            bodies.add(b);
+    return mk((engine, t) => op(preds.map((p) => p(engine, t))), bodies);
+}
+/** True where every predicate is true (interval intersection). */
+export function allOf(...preds) {
+    return combine((xs) => Math.min(...xs), preds);
+}
+/** True where any predicate is true (interval union). */
+export function anyOf(...preds) {
+    return combine((xs) => Math.max(...xs), preds);
+}
+/** True where `pred` is false (interval complement). */
+export function notOf(pred) {
+    return mk((engine, t) => -pred(engine, t), new Set(pred.bodies));
+}
+// --------------------------------------------------------------- solver
+function bisect(f, a, b, tol = 1e-6) {
+    let fa = f(a);
+    for (let i = 0; i < 60; i++) {
+        const m = 0.5 * (a + b);
+        if (Math.abs(b - a) < tol)
+            return m;
+        const fm = f(m);
+        if ((fa < 0) !== (fm < 0)) {
+            b = m;
+        }
+        else {
+            a = m;
+            fa = fm;
+        }
+    }
+    return 0.5 * (a + b);
+}
+/** Time intervals (jdStartUt, jdEndUt) in [jdStart, jdEnd] where `predicate`
+ *  is true. Endpoints touching the range bounds are clamped. The scan step
+ *  defaults to 0.125 d when a fast body (Moon, nodes, Lilith) is involved
+ *  and 1 d otherwise. */
+export function when(engine, predicate, jdStart, jdEnd, opts = {}) {
+    let step = opts.step;
+    if (step === undefined) {
+        let fast = false;
+        for (const b of predicate.bodies)
+            if (FAST.has(b))
+                fast = true;
+        step = fast ? 0.125 : 1.0;
+    }
+    const maxIntervals = opts.maxIntervals ?? 500;
+    const f = (t) => predicate(engine, t);
+    const intervals = [];
+    let prev = f(jdStart);
+    let openStart = prev >= 0 ? jdStart : null;
+    let t = jdStart + step;
+    while (t <= jdEnd + 1e-9 && intervals.length < maxIntervals) {
+        if (t > jdEnd)
+            t = jdEnd;
+        const cur = f(t);
+        if ((prev < 0) !== (cur < 0)) {
+            const edge = bisect(f, t - step, t);
+            if (cur >= 0) {
+                openStart = edge;
+            }
+            else if (openStart !== null) {
+                intervals.push([openStart, edge]);
+                openStart = null;
+            }
+        }
+        prev = cur;
+        if (t >= jdEnd)
+            break;
+        t += step;
+    }
+    if (openStart !== null)
+        intervals.push([openStart, jdEnd]);
+    return intervals;
+}

package/dist/src/stars.d.ts

@@ -3,11 +3,10 @@
  * catalog (data/fixed_stars.json; ICRS J2000 with proper motions).
  *
  * Chain: full 3D space motion (proper motion + radial velocity at the
- * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> IAU 1976
+ * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> Vondrak 2011
  * precession to date -> annual aberration (classic elliptic form, as for
  * Pluto/Chiron) -> nutation. Validated against swe_fixstar fed the same
- * catalog rows: <=0.6 arcsec over 1900-2099 (the floor is the IAU 1976 vs
- * Vondrak precession difference, shared with the rest of the engine).
+ * catalog rows: <=0.3 arcsec over 1900-2099.
  */
 import { EngineData } from "./core.js";
 export interface StarEntry {

package/dist/src/stars.js

@@ -3,11 +3,10 @@
  * catalog (data/fixed_stars.json; ICRS J2000 with proper motions).
  *
  * Chain: full 3D space motion (proper motion + radial velocity at the
- * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> IAU 1976
+ * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> Vondrak 2011
  * precession to date -> annual aberration (classic elliptic form, as for
  * Pluto/Chiron) -> nutation. Validated against swe_fixstar fed the same
- * catalog rows: <=0.6 arcsec over 1900-2099 (the floor is the IAU 1976 vs
- * Vondrak precession difference, shared with the rest of the engine).
+ * catalog rows: <=0.3 arcsec over 1900-2099.
  */
 import { DEG, ARCSEC, J2000, mod, nutation, precessEcliptic, vsopHeliocentric, } from "./core.js";
 const TWO_PI = 2 * Math.PI;

package/package.json

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