caelus 0.6.0 → 0.7.0

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

@@ -6,3 +6,4 @@ 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.6.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",