caelus 0.9.0 → 0.11.0

package/dist/src/astrocartography.d.ts

@@ -0,0 +1,16 @@
+import { Engine, BodyId } from "./chart.js";
+export interface AngleLines {
+    /** MC meridian longitude (culmination). */
+    mc: number;
+    /** IC meridian longitude (anti-culmination). */
+    ic: number;
+    /** Rising track, [lon, lat] points over the latitude band. */
+    asc: [number, number][];
+    /** Setting track, [lon, lat] points. */
+    dsc: [number, number][];
+}
+/** Angle lines for one body at right ascension/declination (degrees) and a
+ *  Greenwich apparent sidereal time (degrees). */
+export declare function planetLines(ra: number, dec: number, gastDeg: number, latMin?: number, latMax?: number, latStep?: number): AngleLines;
+/** Angle lines for each body at jdUt: { body: AngleLines }. */
+export declare function astrocartography(engine: Engine, jdUt: number, bodies: BodyId[], latMin?: number, latMax?: number, latStep?: number): Record<string, AngleLines>;

package/dist/src/astrocartography.js

@@ -0,0 +1,47 @@
+/**
+ * astroengine astrocartography -- planetary angle lines across the globe.
+ *
+ * For one moment, each planet is exactly on an angle along a curve on the
+ * Earth's surface: MC and IC are meridians (culmination / anti-culmination),
+ * ASC and DSC are the curved rising / setting tracks. Geometry from each body's
+ * right ascension and declination and the moment's Greenwich apparent sidereal
+ * time. Mirrors the Python reference (astroengine/astrocartography.py); the
+ * golden pins the two.
+ */
+import { DEG } from "./core.js";
+import { gast } from "./houses.js";
+/** Wrap a longitude to (-180, 180], east positive. */
+function mapLon(deg) {
+    const d = ((deg % 360) + 360) % 360;
+    return d > 180 ? d - 360 : d;
+}
+/** Angle lines for one body at right ascension/declination (degrees) and a
+ *  Greenwich apparent sidereal time (degrees). */
+export function planetLines(ra, dec, gastDeg, latMin = -85.0, latMax = 85.0, latStep = 1.0) {
+    const mc = mapLon(ra - gastDeg);
+    const ic = mapLon(ra - gastDeg - 180.0);
+    const td = Math.tan(dec * DEG);
+    const asc = [];
+    const dsc = [];
+    const n = Math.floor((latMax - latMin) / latStep + 1e-9); // never exceed latMax
+    for (let i = 0; i <= n; i++) {
+        const phi = latMin + i * latStep;
+        const x = -Math.tan(phi * DEG) * td;
+        if (x >= -1.0 && x <= 1.0) {
+            const h0 = Math.acos(x) / DEG; // hour-angle half-width, degrees
+            asc.push([mapLon(ra - h0 - gastDeg), phi]); // eastern horizon
+            dsc.push([mapLon(ra + h0 - gastDeg), phi]); // western horizon
+        }
+    }
+    return { mc, ic, asc, dsc };
+}
+/** Angle lines for each body at jdUt: { body: AngleLines }. */
+export function astrocartography(engine, jdUt, bodies, latMin = -85.0, latMax = 85.0, latStep = 1.0) {
+    const g = gast(engine.data, jdUt) / DEG; // Greenwich apparent sidereal time, deg
+    const out = {};
+    for (const b of bodies) {
+        const p = engine.position(b, jdUt);
+        out[b] = planetLines(p.ra, p.dec, g, latMin, latMax, latStep);
+    }
+    return out;
+}

package/dist/src/compiler.d.ts

@@ -0,0 +1,38 @@
+export type Constraint = {
+    kind: "aspect";
+    a: string;
+    b: string;
+    angle: number;
+    weight?: number;
+} | {
+    kind: "sign";
+    body: string;
+    sign: number;
+    weight?: number;
+} | {
+    kind: "degree";
+    body: string;
+    degree: number;
+    weight?: number;
+};
+/** Degrees by which a single constraint is unmet given the longitudes. */
+export declare function constraintLoss(lons: Record<string, number>, c: Constraint): number;
+/** Total weighted constraint loss for a set of body longitudes. */
+export declare function formLoss(lons: Record<string, number>, constraints: Constraint[]): number;
+export interface CompiledForm {
+    longitudes: Record<string, number>;
+    residual: number;
+    maxConstraintLoss: number;
+    impossible: boolean;
+    constraints: Array<Constraint & {
+        loss: number;
+    }>;
+}
+export interface CompileOptions {
+    restarts?: number;
+    iters?: number;
+    /** A form is impossible when its worst constraint exceeds this (degrees). */
+    impossibleDeg?: number;
+}
+/** Find body longitudes minimizing the weighted constraint loss. */
+export declare function compileForm(constraints: Constraint[], opts?: CompileOptions): CompiledForm;

package/dist/src/compiler.js

@@ -0,0 +1,111 @@
+/**
+ * astroengine compiler -- synthesize a chart form from geometric constraints.
+ *
+ * The inverse of (time, place) -> chart: given weighted geometric constraints
+ * (aspects between bodies, sign or degree placements), find the body longitudes
+ * that best satisfy them, and report how well they can be. If the best fit is
+ * still poor, the form is geometrically impossible -- a valid result.
+ *
+ * The loss / constraint math is pure and mirrors the Python reference
+ * (astroengine/compiler.py), pinned by the golden. The optimizer is a
+ * deterministic coordinate descent with fixed low-discrepancy restarts.
+ */
+const PHI = 0.6180339887498949;
+function angDist(a, b) {
+    return Math.abs(((a - b + 180.0) % 360.0) - 180.0);
+}
+function signLoss(lon, sign) {
+    const lo = (((sign % 12) + 12) % 12) * 30.0;
+    const d = (((lon - lo) % 360.0) + 360.0) % 360.0;
+    if (d < 30.0)
+        return 0.0;
+    return Math.min(d - 30.0, 360.0 - d);
+}
+/** Degrees by which a single constraint is unmet given the longitudes. */
+export function constraintLoss(lons, c) {
+    if (c.kind === "aspect")
+        return Math.abs(angDist(lons[c.a], lons[c.b]) - c.angle);
+    if (c.kind === "sign")
+        return signLoss(lons[c.body], c.sign);
+    return angDist(lons[c.body], c.degree);
+}
+/** Total weighted constraint loss for a set of body longitudes. */
+export function formLoss(lons, constraints) {
+    let total = 0;
+    for (const c of constraints)
+        total += (c.weight ?? 1.0) * constraintLoss(lons, c);
+    return total;
+}
+function bodiesOf(constraints) {
+    const s = new Set();
+    for (const c of constraints) {
+        if (c.kind === "aspect") {
+            s.add(c.a);
+            s.add(c.b);
+        }
+        else
+            s.add(c.body);
+    }
+    return [...s].sort();
+}
+function involves(c, body) {
+    return c.kind === "aspect" ? (c.a === body || c.b === body) : c.body === body;
+}
+function bodyLoss(lons, body, constraints) {
+    let total = 0;
+    for (const c of constraints)
+        if (involves(c, body))
+            total += (c.weight ?? 1.0) * constraintLoss(lons, c);
+    return total;
+}
+/** Find body longitudes minimizing the weighted constraint loss. */
+export function compileForm(constraints, opts = {}) {
+    const restarts = opts.restarts ?? 12;
+    const iters = opts.iters ?? 8;
+    const impossibleDeg = opts.impossibleDeg ?? 5.0;
+    const bodies = bodiesOf(constraints);
+    const n = Math.max(bodies.length, 1);
+    let best = null;
+    for (let r = 0; r < restarts; r++) {
+        const lons = {};
+        bodies.forEach((b, i) => { lons[b] = (((r * n + i + 1) * PHI) % 1.0) * 360.0; });
+        for (let it = 0; it < iters; it++) {
+            for (const b of bodies) {
+                let bestL = lons[b];
+                let bestE = bodyLoss(lons, b, constraints);
+                for (let i = 0; i < 360; i++) {
+                    lons[b] = i;
+                    const e = bodyLoss(lons, b, constraints);
+                    if (e < bestE) {
+                        bestE = e;
+                        bestL = i;
+                    }
+                }
+                for (let k = -20; k <= 20; k++) {
+                    const cand = (((bestL + k * 0.05) % 360.0) + 360.0) % 360.0;
+                    lons[b] = cand;
+                    const e = bodyLoss(lons, b, constraints);
+                    if (e < bestE) {
+                        bestE = e;
+                        bestL = cand;
+                    }
+                }
+                lons[b] = bestL;
+            }
+        }
+        const e = formLoss(lons, constraints);
+        if (best === null || e < best.e)
+            best = { e, lons: { ...lons } };
+    }
+    const lons = best.lons;
+    let maxLoss = 0;
+    for (const c of constraints)
+        maxLoss = Math.max(maxLoss, constraintLoss(lons, c));
+    return {
+        longitudes: lons,
+        residual: best.e,
+        maxConstraintLoss: maxLoss,
+        impossible: maxLoss > impossibleDeg,
+        constraints: constraints.map((c) => ({ ...c, loss: constraintLoss(lons, c) })),
+    };
+}

package/dist/src/ephemeris.d.ts

@@ -0,0 +1,27 @@
+/**
+ * astroengine ephemeris -- a time series of one value per body over a range, the
+ * data behind a graphic ephemeris. A thin collector over the validated
+ * positions (longitude, latitude, declination, right ascension, or speed), so
+ * there is no new math here; the underlying values are the ones the conformance
+ * suite already pins. Pair it with caelus-wheel's EphemerisGraph to draw it.
+ */
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export type EphemerisValue = "longitude" | "latitude" | "declination" | "rightAscension" | "speed";
+export interface EphemerisOptions {
+    /** 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;
+    /** Which quantity to sample (default longitude). */
+    value?: EphemerisValue;
+    zodiac?: Zodiac;
+}
+export interface EphemerisPoint {
+    jd: number;
+    value: number;
+}
+/** Sample `value` for each body across [start, end], returning per-body series
+ *  in time order. */
+export declare function ephemeris(engine: Engine, bodies: BodyId[], opts: EphemerisOptions): Record<string, EphemerisPoint[]>;

package/dist/src/ephemeris.js

@@ -0,0 +1,30 @@
+/** Sample `value` for each body across [start, end], returning per-body series
+ *  in time order. */
+export function ephemeris(engine, bodies, opts) {
+    if (opts.step <= 0)
+        throw new Error("ephemeris step must be positive");
+    const value = opts.value ?? "longitude";
+    const zodiac = opts.zodiac ?? "tropical";
+    const out = {};
+    for (const b of bodies)
+        out[b] = [];
+    const total = Math.floor((opts.end - opts.start) / opts.step + 1e-9) + 1;
+    for (let i = 0; i < total; i++) {
+        const jd = opts.start + i * opts.step;
+        for (const b of bodies) {
+            let v;
+            if (value === "longitude") {
+                v = engine.longitude(b, jd, { zodiac });
+            }
+            else {
+                const p = engine.position(b, jd, { zodiac });
+                v = value === "latitude" ? p.lat
+                    : value === "declination" ? p.dec
+                        : value === "rightAscension" ? p.ra
+                            : p.speed;
+            }
+            out[b].push({ jd, value: v });
+        }
+    }
+    return out;
+}

package/dist/src/features.d.ts

@@ -0,0 +1,26 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+import { RankedMoment } from "./scan.js";
+export declare const DEFAULT_BODIES: string[];
+/** Flat vector [w*cos(lon), w*sin(lon), ...] for the given (longitude, weight)
+ *  pairs, in order. */
+export declare function featureVector(weightedLons: [number, number][]): number[];
+/** Cosine similarity of two feature vectors, in [-1, 1]. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export interface FeatureOptions {
+    bodies?: BodyId[];
+    weights?: Record<string, number>;
+    zodiac?: Zodiac;
+}
+/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+export declare function chartFeatures(engine: Engine, jdUt: number, opts?: FeatureOptions): number[];
+/** Similarity between the sky at jdUt and a target feature vector. */
+export declare function configurationFit(engine: Engine, jdUt: number, target: number[], opts?: FeatureOptions): number;
+export interface SearchConfigOptions extends FeatureOptions {
+    start: number;
+    end: number;
+    step: number;
+    limit?: number;
+}
+/** Rank the instants in [start, end] by how closely the sky resembles `target`
+ *  (a feature vector), best first. Realization search over the feature space. */
+export declare function searchConfigurations(engine: Engine, target: number[], opts: SearchConfigOptions): RankedMoment[];

package/dist/src/features.js

@@ -0,0 +1,57 @@
+/**
+ * astroengine features -- a chart as a feature vector, similarity between
+ * charts, and search for when the sky most resembles a target configuration.
+ *
+ * Each body's ecliptic longitude is circular, so it contributes a unit-circle
+ * point (cos, sin), optionally weighted. Cosine similarity between two such
+ * vectors is a weighted mean of cos(delta-longitude) per body: 1 when the
+ * configurations coincide, falling off as bodies diverge. The deterministic
+ * substrate for matching, retrieving, and searching chart configurations.
+ * Mirrors the Python reference (astroengine/features.py); the golden pins them.
+ */
+import { DEG } from "./core.js";
+import { rankMoments } from "./scan.js";
+export const DEFAULT_BODIES = ["sun", "moon", "mercury", "venus", "mars",
+    "jupiter", "saturn", "uranus", "neptune", "pluto"];
+/** Flat vector [w*cos(lon), w*sin(lon), ...] for the given (longitude, weight)
+ *  pairs, in order. */
+export function featureVector(weightedLons) {
+    const out = [];
+    for (const [lon, w] of weightedLons) {
+        const r = lon * DEG;
+        out.push(w * Math.cos(r), w * Math.sin(r));
+    }
+    return out;
+}
+/** Cosine similarity of two feature vectors, in [-1, 1]. */
+export function cosineSimilarity(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+export function chartFeatures(engine, jdUt, opts = {}) {
+    const bodies = opts.bodies ?? DEFAULT_BODIES;
+    const zodiac = opts.zodiac ?? "tropical";
+    const wl = bodies.map((b) => [
+        engine.longitude(b, jdUt, { zodiac }),
+        opts.weights?.[b] ?? 1.0,
+    ]);
+    return featureVector(wl);
+}
+/** Similarity between the sky at jdUt and a target feature vector. */
+export function configurationFit(engine, jdUt, target, opts = {}) {
+    return cosineSimilarity(chartFeatures(engine, jdUt, opts), target);
+}
+/** Rank the instants in [start, end] by how closely the sky resembles `target`
+ *  (a feature vector), best first. Realization search over the feature space. */
+export function searchConfigurations(engine, target, opts) {
+    return rankMoments({ start: opts.start, end: opts.end, step: opts.step, limit: opts.limit }, (jd) => configurationFit(engine, jd, target, opts));
+}

package/dist/src/index.d.ts

@@ -10,3 +10,8 @@ export * from "./derived.js";
 export * from "./turbo.js";
 export * from "./electional.js";
 export * from "./scan.js";
+export * from "./spherical.js";
+export * from "./astrocartography.js";
+export * from "./ephemeris.js";
+export * from "./features.js";
+export * from "./compiler.js";

package/dist/src/index.js

@@ -10,3 +10,8 @@ export * from "./derived.js";
 export * from "./turbo.js";
 export * from "./electional.js";
 export * from "./scan.js";
+export * from "./spherical.js";
+export * from "./astrocartography.js";
+export * from "./ephemeris.js";
+export * from "./features.js";
+export * from "./compiler.js";

package/dist/src/spherical.d.ts

@@ -0,0 +1,8 @@
+export type Vec3 = [number, number, number];
+/** Unit vector on the sphere for an (ecliptic longitude, latitude) pair, in the
+ *  ecliptic frame: x toward 0 Aries, z toward the north ecliptic pole. */
+export declare function unitVector(lonDeg: number, latDeg: number): Vec3;
+/** True great-circle angle (degrees) between two bodies from their ecliptic
+ *  longitude and latitude. With both latitudes zero this is the unsigned
+ *  longitude difference; latitude pulls the two apart in three dimensions. */
+export declare function angularSeparation3d(lonA: number, latA: number, lonB: number, latB: number): number;

package/dist/src/spherical.js

@@ -0,0 +1,28 @@
+/**
+ * astroengine spherical -- spherical-geometry primitives for 3D chart views.
+ *
+ * A body sits at a point on the celestial sphere, not just a zodiac longitude.
+ * `unitVector` gives the direction for an (ecliptic longitude, latitude) pair;
+ * `angularSeparation3d` gives the true great-circle angle between two bodies,
+ * which is the basis for 3D aspects (the separation in space, accounting for
+ * ecliptic latitude, rather than the 2D longitude difference). Mirrors the
+ * Python reference (astroengine/spherical.py); the golden pins the two.
+ */
+import { DEG } from "./core.js";
+/** Unit vector on the sphere for an (ecliptic longitude, latitude) pair, in the
+ *  ecliptic frame: x toward 0 Aries, z toward the north ecliptic pole. */
+export function unitVector(lonDeg, latDeg) {
+    const lam = lonDeg * DEG;
+    const beta = latDeg * DEG;
+    const cb = Math.cos(beta);
+    return [cb * Math.cos(lam), cb * Math.sin(lam), Math.sin(beta)];
+}
+/** True great-circle angle (degrees) between two bodies from their ecliptic
+ *  longitude and latitude. With both latitudes zero this is the unsigned
+ *  longitude difference; latitude pulls the two apart in three dimensions. */
+export function angularSeparation3d(lonA, latA, lonB, latB) {
+    const [ax, ay, az] = unitVector(lonA, latA);
+    const [bx, by, bz] = unitVector(lonB, latB);
+    const dot = Math.max(-1, Math.min(1, ax * bx + ay * by + az * bz));
+    return Math.acos(dot) / DEG;
+}

package/package.json

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