caelus 0.10.0 → 0.11.0

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/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

@@ -13,3 +13,5 @@ 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

@@ -13,3 +13,5 @@ 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/package.json

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