caelus 0.16.0 → 0.17.0

package/dist/src/parans.d.ts

@@ -25,3 +25,31 @@ export interface Paran {
  * @returns The co-angular pairs as {@link Paran} objects.
  */
 export declare function parans(engine: Engine, jd: number, lat: number, bodies?: string[], toleranceMin?: number): Paran[];
+/**
+ * The four angle crossings of a fixed `star` over the day from `jd` at latitude
+ * `lat`: the meridian transits always occur; `rise`/`set` are absent when the
+ * star is circumpolar or never rises.
+ */
+export declare function starAngleTimes(engine: Engine, star: string, jd: number, lat: number): Record<string, number>;
+/** One star-to-body paran: a fixed star and a body on angles at ~the same time. */
+export interface StarParan {
+    star: string;
+    star_angle: string;
+    body: string;
+    body_angle: string;
+    jd: number;
+    gap_min: number;
+}
+/**
+ * Star-to-body parans over the day from `jd` (UT) at latitude `lat`: a fixed
+ * star and a moving body simultaneously on angles within `toleranceMin`
+ * minutes — Brady's fixed-star parans. Ordered by (star, body, jd).
+ *
+ * @param engine An engine whose data pack includes the fixed-star catalog.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param stars Catalog star names to test (see {@link Engine.starNames}).
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ */
+export declare function starParans(engine: Engine, jd: number, lat: number, stars: string[], bodies?: string[], toleranceMin?: number): StarParan[];

package/dist/src/parans.js

@@ -13,8 +13,15 @@
  * `parans-golden`.
  */
 import { riseSet } from "./events.js";
+import { gast } from "./houses.js";
+import { DEG, mod } from "./core.js";
 export const PARAN_ANGLES = ["rise", "mtransit", "set", "itransit"];
 export const DEFAULT_PARAN_BODIES = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+const TWO_PI = 2 * Math.PI;
+// Local sidereal time advances one turn per sidereal day.
+const SID_RATE = 360.98564736629 * DEG;
+// Standard rise/set: the geometric horizon lifted by ~34' of refraction.
+const RISE_ALT = -0.5667 * DEG;
 /**
  * Co-angular pairs over the 24 hours from `jd` (UT) at latitude `lat`: every
  * pair of different bodies whose angle crossings fall within `toleranceMin`
@@ -57,3 +64,80 @@ export function parans(engine, jd, lat, bodies = DEFAULT_PARAN_BODIES, tolerance
     out.sort((x, y) => (x.a < y.a ? -1 : x.a > y.a ? 1 : x.b < y.b ? -1 : x.b > y.b ? 1 : x.jd - y.jd));
     return out;
 }
+/** The UT instant in `[jd, jd+1)` when apparent sidereal time = `target` (rad). */
+function timeAtLst(engine, jd, target) {
+    const dlst = mod(target - gast(engine.data, jd), TWO_PI);
+    let t = jd + dlst / SID_RATE;
+    for (let i = 0; i < 2; i++) {
+        const err = mod(gast(engine.data, t) - target + Math.PI, TWO_PI) - Math.PI;
+        t -= err / SID_RATE;
+    }
+    return t;
+}
+/**
+ * The four angle crossings of a fixed `star` over the day from `jd` at latitude
+ * `lat`: the meridian transits always occur; `rise`/`set` are absent when the
+ * star is circumpolar or never rises.
+ */
+export function starAngleTimes(engine, star, jd, lat) {
+    const fs = engine.fixedStar(star, jd);
+    const alpha = mod(fs.ra * DEG, TWO_PI);
+    const delta = fs.dec * DEG;
+    const phi = lat * DEG;
+    const out = {
+        mtransit: timeAtLst(engine, jd, alpha),
+        itransit: timeAtLst(engine, jd, mod(alpha + Math.PI, TWO_PI)),
+    };
+    const denom = Math.cos(phi) * Math.cos(delta);
+    if (denom !== 0) {
+        const cosH0 = (Math.sin(RISE_ALT) - Math.sin(phi) * Math.sin(delta)) / denom;
+        if (cosH0 >= -1 && cosH0 <= 1) {
+            const h0 = Math.acos(cosH0);
+            out.rise = timeAtLst(engine, jd, mod(alpha - h0, TWO_PI));
+            out.set = timeAtLst(engine, jd, mod(alpha + h0, TWO_PI));
+        }
+    }
+    return out;
+}
+/**
+ * Star-to-body parans over the day from `jd` (UT) at latitude `lat`: a fixed
+ * star and a moving body simultaneously on angles within `toleranceMin`
+ * minutes — Brady's fixed-star parans. Ordered by (star, body, jd).
+ *
+ * @param engine An engine whose data pack includes the fixed-star catalog.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param stars Catalog star names to test (see {@link Engine.starNames}).
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ */
+export function starParans(engine, jd, lat, stars, bodies = DEFAULT_PARAN_BODIES, toleranceMin = 30) {
+    const bodyEvents = [];
+    for (const b of bodies) {
+        for (const kind of PARAN_ANGLES) {
+            const t = riseSet(engine, b, jd, lat, 0, kind);
+            if (t !== null && t < jd + 1)
+                bodyEvents.push([b, kind, t]);
+        }
+    }
+    const out = [];
+    for (const s of stars) {
+        const at = starAngleTimes(engine, s, jd, lat);
+        for (const [sa, ts] of Object.entries(at)) {
+            if (!(ts >= jd && ts < jd + 1))
+                continue;
+            for (const [b, ba, tb] of bodyEvents) {
+                const gap = Math.abs(ts - tb) * 1440;
+                if (gap <= toleranceMin) {
+                    out.push({
+                        star: s, star_angle: sa, body: b, body_angle: ba,
+                        jd: Math.round(((ts + tb) / 2) * 1e6) / 1e6,
+                        gap_min: Math.round(gap * 1e4) / 1e4,
+                    });
+                }
+            }
+        }
+    }
+    out.sort((x, y) => (x.star < y.star ? -1 : x.star > y.star ? 1 : x.body < y.body ? -1 : x.body > y.body ? 1 : x.jd - y.jd));
+    return out;
+}

package/package.json

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