caelus 0.11.0 → 0.12.0

package/dist/src/features.js

@@ -13,8 +13,15 @@ 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. */
+/**
+ * Build a feature vector from explicit `(longitude, weight)` pairs: each pair
+ * contributes a weighted unit-circle point `[w·cos(lon), w·sin(lon)]`. The
+ * low-level primitive behind {@link chartFeatures}; most callers want that.
+ *
+ * @param weightedLons `[longitudeDeg, weight]` pairs, in the order they should
+ *   appear in the vector.
+ * @returns A flat vector, two entries per pair.
+ */
 export function featureVector(weightedLons) {
     const out = [];
     for (const [lon, w] of weightedLons) {
@@ -23,7 +30,15 @@ export function featureVector(weightedLons) {
     }
     return out;
 }
-/** Cosine similarity of two feature vectors, in [-1, 1]. */
+/**
+ * Cosine similarity of two feature vectors, in `[-1, 1]`. For vectors from
+ * {@link chartFeatures} this is a weighted mean of `cos(Δlongitude)` per body:
+ * `1` when the configurations coincide, falling off as bodies diverge.
+ *
+ * @param a First feature vector.
+ * @param b Second feature vector (compared over the shorter length).
+ * @returns Similarity in `[-1, 1]`; `0` if either vector is all zeros.
+ */
 export function cosineSimilarity(a, b) {
     let dot = 0, na = 0, nb = 0;
     const n = Math.min(a.length, b.length);
@@ -36,7 +51,26 @@ export function cosineSimilarity(a, b) {
         return 0;
     return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
-/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+/**
+ * Encode the sky at an instant as a feature vector: each body's ecliptic
+ * longitude becomes a weighted unit-circle point. The deterministic substrate
+ * for matching and searching chart configurations — compare two with
+ * {@link cosineSimilarity}, or rank a time range against one with
+ * {@link searchConfigurations}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param opts `bodies` (ordered; defaults to the ten major bodies), per-body
+ *   `weights`, and `zodiac` (tropical by default).
+ * @returns A flat vector `[w·cos(lon), w·sin(lon), ...]`, two entries per body
+ *   in `bodies` order.
+ * @example
+ * ```ts
+ * const target = chartFeatures(engine, julianDay(2000, 1, 1));
+ * const now = chartFeatures(engine, julianDay(2025, 6, 1));
+ * cosineSimilarity(now, target); // 1 = identical configuration
+ * ```
+ */
 export function chartFeatures(engine, jdUt, opts = {}) {
     const bodies = opts.bodies ?? DEFAULT_BODIES;
     const zodiac = opts.zodiac ?? "tropical";
@@ -46,12 +80,40 @@ export function chartFeatures(engine, jdUt, opts = {}) {
     ]);
     return featureVector(wl);
 }
-/** Similarity between the sky at jdUt and a target feature vector. */
+/**
+ * Similarity between the sky at `jdUt` and a target feature vector — shorthand
+ * for `cosineSimilarity(chartFeatures(engine, jdUt, opts), target)`. The scoring
+ * function {@link searchConfigurations} maximizes.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts {@link FeatureOptions} — must match those used to build `target`.
+ * @returns Cosine similarity in `[-1, 1]`.
+ */
 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. */
+/**
+ * Rank the instants in `[start, end]` by how closely the sky resembles a
+ * `target` feature vector, best first — a realization search over the feature
+ * space. Build `target` with {@link chartFeatures} (e.g. from a natal chart).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts `start`/`end` (Julian Days, UT) and `step` (days) define the
+ *   scan, `limit` caps the results, plus the {@link FeatureOptions} (`bodies`,
+ *   `weights`, `zodiac`) — which must match those used to build `target`.
+ * @returns Ranked `{ jd, score }` moments, highest similarity first.
+ * @example
+ * ```ts
+ * const natal = chartFeatures(engine, julianDay(1990, 6, 10, 14, 30));
+ * const matches = searchConfigurations(engine, natal, {
+ *   start: julianDay(2025, 1, 1), end: julianDay(2026, 1, 1), step: 1, limit: 5,
+ * });
+ * matches[0].jd; // best-matching instant
+ * ```
+ */
 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/houses.d.ts

@@ -41,9 +41,18 @@ export declare function housesPolichPage(armc: number, phi: number, eps: number)
 /** Vehlow: equal houses with the ASC at the middle of house 1. */
 export declare function housesVehlow(armc: number, phi: number, eps: number): number[];
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export declare function housesPlacidus(armc: number, phi: number, eps: number): number[];

package/dist/src/houses.js

@@ -257,10 +257,19 @@ export function housesVehlow(armc, phi, eps) {
     return Array.from({ length: 12 }, (_, i) => mod(asc - 15 * DEG + i * 30 * DEG, TWO_PI));
 }
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export function housesPlacidus(armc, phi, eps) {
     const cusp = (offsetDeg, f) => {

package/dist/src/pheno.d.ts

@@ -19,8 +19,22 @@ export interface Pheno {
     diameter: number;
     magnitude: number;
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export declare function pheno(engine: Engine, body: BodyId, jdUt: number): Pheno;
 /** Apparent minus mean solar time, minutes (Meeus ch. 28). */
 export declare function equationOfTime(engine: Engine, jdUt: number): number;

package/dist/src/pheno.js

@@ -66,8 +66,22 @@ function magnitude(body, a, r, dlt, jde, lonDeg, latDeg) {
             return x - 1.01;
     }
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export function pheno(engine, body, jdUt) {
     if (DIAMETER_KM[body] === undefined) {
         throw new Error(`pheno not available for '${body}'`);

package/dist/src/query.d.ts

@@ -6,8 +6,26 @@ 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. */
+/**
+ * A {@link Predicate} that holds while `body` is within `orb` degrees of an
+ * exact aspect to `target`. Feed it to {@link when} to find the time windows,
+ * or compose it with {@link allOf}/{@link anyOf}.
+ *
+ * @param body The transiting body.
+ * @param kind Aspect name, e.g. `"conjunction"`, `"square"`, `"trine"`,
+ *   `"opposition"`, `"sextile"`.
+ * @param target The aspect target: a fixed ecliptic longitude in degrees (e.g.
+ *   a natal point) or another body id (a mutual aspect).
+ * @param orb Half-width of the window in degrees. Defaults to `1.0`.
+ * @param zodiac Zodiac for the longitudes. Defaults to tropical.
+ * @returns A predicate, true while within orb of the exact aspect.
+ * @throws Error if `kind` is not a known aspect.
+ * @example
+ * ```ts
+ * const natalSun = 79.3;
+ * when(engine, aspect("saturn", "square", natalSun, 1), jd0, jd1); // Saturn squares
+ * ```
+ */
 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;
@@ -25,8 +43,31 @@ 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. */
+/**
+ * Solve for the time intervals within `[jdStart, jdEnd]` (UT Julian Days) where
+ * a {@link Predicate} holds. Predicates compose from {@link aspect},
+ * {@link inSign}, {@link retrograde}, {@link notRetrograde}, and the
+ * {@link allOf}/{@link anyOf} combinators, so one call answers questions like
+ * "when is Venus in Taurus while Mercury is direct?".
+ *
+ * Returned intervals are sorted and disjoint; 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 — override it with `opts.step`.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param predicate A celestial predicate (see {@link aspect}, {@link inSign}).
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param opts `step` (scan resolution in days) and `maxIntervals`.
+ * @returns Sorted, disjoint `[startUt, endUt]` intervals where the predicate is
+ *   true.
+ * @example
+ * ```ts
+ * const windows = when(
+ *   engine,
+ *   allOf(inSign("venus", "Taurus"), notRetrograde("mercury")),
+ *   julianDay(2025, 1, 1), julianDay(2026, 1, 1),
+ * );
+ * ```
+ */
 export declare function when(engine: Engine, predicate: Predicate, jdStart: number, jdEnd: number, opts?: WhenOptions): Interval[];

package/dist/src/query.js

@@ -35,8 +35,26 @@ function mk(fn, 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. */
+/**
+ * A {@link Predicate} that holds while `body` is within `orb` degrees of an
+ * exact aspect to `target`. Feed it to {@link when} to find the time windows,
+ * or compose it with {@link allOf}/{@link anyOf}.
+ *
+ * @param body The transiting body.
+ * @param kind Aspect name, e.g. `"conjunction"`, `"square"`, `"trine"`,
+ *   `"opposition"`, `"sextile"`.
+ * @param target The aspect target: a fixed ecliptic longitude in degrees (e.g.
+ *   a natal point) or another body id (a mutual aspect).
+ * @param orb Half-width of the window in degrees. Defaults to `1.0`.
+ * @param zodiac Zodiac for the longitudes. Defaults to tropical.
+ * @returns A predicate, true while within orb of the exact aspect.
+ * @throws Error if `kind` is not a known aspect.
+ * @example
+ * ```ts
+ * const natalSun = 79.3;
+ * when(engine, aspect("saturn", "square", natalSun, 1), jd0, jd1); // Saturn squares
+ * ```
+ */
 export function aspect(body, kind, target, orb = 1.0, zodiac = "tropical") {
     const ang = QUERY_ASPECTS[kind];
     if (ang === undefined)
@@ -117,10 +135,33 @@ function bisect(f, a, b, tol = 1e-6) {
     }
     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. */
+/**
+ * Solve for the time intervals within `[jdStart, jdEnd]` (UT Julian Days) where
+ * a {@link Predicate} holds. Predicates compose from {@link aspect},
+ * {@link inSign}, {@link retrograde}, {@link notRetrograde}, and the
+ * {@link allOf}/{@link anyOf} combinators, so one call answers questions like
+ * "when is Venus in Taurus while Mercury is direct?".
+ *
+ * Returned intervals are sorted and disjoint; 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 — override it with `opts.step`.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param predicate A celestial predicate (see {@link aspect}, {@link inSign}).
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param opts `step` (scan resolution in days) and `maxIntervals`.
+ * @returns Sorted, disjoint `[startUt, endUt]` intervals where the predicate is
+ *   true.
+ * @example
+ * ```ts
+ * const windows = when(
+ *   engine,
+ *   allOf(inSign("venus", "Taurus"), notRetrograde("mercury")),
+ *   julianDay(2025, 1, 1), julianDay(2026, 1, 1),
+ * );
+ * ```
+ */
 export function when(engine, predicate, jdStart, jdEnd, opts = {}) {
     let step = opts.step;
     if (step === undefined) {

package/dist/src/turbo.d.ts

@@ -9,12 +9,46 @@ export interface TurboPack {
     zodiac: string;
     bodies: Record<string, TurboBody>;
 }
+/**
+ * Runtime evaluator for a **turbo pack** — a segmented Chebyshev fit of the
+ * engine's apparent longitude over a fixed range and body set. Evaluating a
+ * longitude costs a couple dozen multiply-adds, so a century-scale transit scan
+ * that calls it tens of thousands of times runs in milliseconds. Construct one
+ * from a pack you minted offline; it does no fitting, no I/O, and needs no
+ * {@link Engine}.
+ *
+ * @example
+ * ```ts
+ * const turbo = new Turbo(pack); // a TurboPack generated for your range/bodies
+ * if (turbo.has("mars")) turbo.longitude("mars", jd);
+ * ```
+ */
 export declare class Turbo {
+    /** Start of the pack's valid Julian Day (UT) range. */
     readonly jd0: number;
+    /** End of the pack's valid Julian Day (UT) range. */
     readonly jd1: number;
     private readonly bodies;
+    /**
+     * @param pack A {@link TurboPack}: the fitted segments plus its `jd0`/`jd1`
+     *   range, minted offline for your bodies and span.
+     */
     constructor(pack: TurboPack);
+    /**
+     * Whether this pack can evaluate a given body.
+     *
+     * @param body Body id to test.
+     * @returns `true` if {@link Turbo.longitude} accepts `body`.
+     */
     has(body: string): boolean;
-    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    /**
+     * Apparent ecliptic longitude (degrees) of a body from the turbo pack, in the
+     * pack's own zodiac. The hot path for bulk scans.
+     *
+     * @param body A body id the pack contains (see {@link Turbo.has}).
+     * @param jd Julian Day (UT), within `[jd0, jd1]`.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @throws Error if the pack lacks `body`, or `jd` is outside `[jd0, jd1]`.
+     */
     longitude(body: string, jd: number): number;
 }

package/dist/src/turbo.js

@@ -22,19 +22,53 @@ function clenshaw(coeffs, x) {
     }
     return x * b0 - b1 + coeffs[0];
 }
+/**
+ * Runtime evaluator for a **turbo pack** — a segmented Chebyshev fit of the
+ * engine's apparent longitude over a fixed range and body set. Evaluating a
+ * longitude costs a couple dozen multiply-adds, so a century-scale transit scan
+ * that calls it tens of thousands of times runs in milliseconds. Construct one
+ * from a pack you minted offline; it does no fitting, no I/O, and needs no
+ * {@link Engine}.
+ *
+ * @example
+ * ```ts
+ * const turbo = new Turbo(pack); // a TurboPack generated for your range/bodies
+ * if (turbo.has("mars")) turbo.longitude("mars", jd);
+ * ```
+ */
 export class Turbo {
+    /** Start of the pack's valid Julian Day (UT) range. */
     jd0;
+    /** End of the pack's valid Julian Day (UT) range. */
     jd1;
     bodies;
+    /**
+     * @param pack A {@link TurboPack}: the fitted segments plus its `jd0`/`jd1`
+     *   range, minted offline for your bodies and span.
+     */
     constructor(pack) {
         this.jd0 = pack.jd0;
         this.jd1 = pack.jd1;
         this.bodies = pack.bodies;
     }
+    /**
+     * Whether this pack can evaluate a given body.
+     *
+     * @param body Body id to test.
+     * @returns `true` if {@link Turbo.longitude} accepts `body`.
+     */
     has(body) {
         return body in this.bodies;
     }
-    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    /**
+     * Apparent ecliptic longitude (degrees) of a body from the turbo pack, in the
+     * pack's own zodiac. The hot path for bulk scans.
+     *
+     * @param body A body id the pack contains (see {@link Turbo.has}).
+     * @param jd Julian Day (UT), within `[jd0, jd1]`.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @throws Error if the pack lacks `body`, or `jd` is outside `[jd0, jd1]`.
+     */
     longitude(body, jd) {
         const b = this.bodies[body];
         if (!b)

package/package.json

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