@openwaters/almanac 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # Almanac
 
 Offline sun & moon engine for the Salish Sea and everywhere else — positions,
-rise/set/twilight, moon phase, and lunar eclipses (solar planned), computed from pure
-geometry with zero network and zero runtime data files.
+rise/set/twilight, moon phase, lunar eclipses (solar planned), and where any fixed
+star stands from a catalog position, computed from pure geometry with zero network
+and zero runtime data files.
 
 Twin implementations, one behavior:
 
@@ -22,6 +23,48 @@ future — see the design spec's Conventions section for what that means and why
 Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/astronomy)
 (MIT, Don Cross) — see [NOTICE](NOTICE). MIT licensed.
 
+## Performance
+
+Almanac includes a shared performance harness for both ports: **15 workloads**
+cover positions, a 228-hour sky track, short/year/polar event windows, full-range
+moon phases, and next/previous/range eclipse searches, including empty windows.
+
+The v0.2.1 optimizations reuse Moon and shadow geometry, flatten scratch arrays,
+and refine altitude crossings with fewer position evaluations. In the
+[hosted CI comparison](https://github.com/openwatersio/almanac/actions/runs/34119038860),
+median query time fell relative to the v0.2.0 astronomy code:
+
+| Workload | TypeScript: less time | Swift: less time |
+| --- | ---: | ---: |
+| Moon positions / 1,024 hours | 29.8% | 22.1% |
+| Sky track / 228 hours | 40.0% | 42.4% |
+| Sun events / 228 hours | 39.3% | 40.2% |
+| Moon events / 228 hours | 39.1% | 35.1% |
+| Previous lunar eclipse | 26.0% | 36.6% |
+| Lunar eclipses / 1950–2100 | 26.4% | 23.4% |
+
+TypeScript was measured on Ubuntu with Node 22; Swift used release builds on
+macOS 15. Each comparison builds both revisions with the same harness and
+toolchain, then takes seven interleaved process pairs with 300 ms warmup per
+process. Build and startup time are excluded. Timings vary by machine; the shared
+correctness fixtures and parity tolerances remain the accuracy gates.
+
+Reproduce the comparison locally from the repository root (Node 22+ and Swift
+5.9+):
+
+```bash
+npm ci --prefix typescript
+node benchmarks/run.mjs --base v0.2.0
+```
+
+CI runs the harness on code changes and fails on **median regressions over 20%**.
+Results include timing tables, raw samples, checksums, and revision/toolchain
+metadata. See [the harness guide](CONTRIBUTING.md#performance) for choosing a
+baseline, running one port, and inspecting reports.
+
+Event searches scale with window length. Run a full 151-year sweep in a worker or
+background task; use shorter windows for interactive queries.
+
 ## Usage
 
 ### TypeScript
@@ -31,7 +74,7 @@ npm install @openwaters/almanac
 ```
 
 ```ts
-import { nextLunarEclipse, lunarEclipseVisibility, sunEvents } from '@openwaters/almanac';
+import { nextLunarEclipse, lunarEclipseVisibility, sunEvents, starAltAz } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
 
@@ -44,12 +87,15 @@ const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
 for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
   console.log(kind, time.toISOString());
 }
+
+// Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
+const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ```
 
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.2.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.3.0")
 ```
 
 ```swift
@@ -67,6 +113,9 @@ let tomorrow = today.addingTimeInterval(24 * 60 * 60)
 for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
   print(event.kind, event.time)
 }
+
+// Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
+let star = try starAltAz(raDeg: 88.792939, decDeg: 7.407064, at: today, observer: observer)
 ```
 
 ### Eclipse searches
@@ -87,15 +136,3 @@ let eclipses = try lunarEclipses(from: today, to: tomorrow)
 Ranges include peaks at the start and exclude peaks at the end. Contacts may
 extend outside the range. Previous/next searches skip peaks within 100 ms of the
 anchor. Search results are global; apply `lunarEclipseVisibility` for an observer.
-
-### Performance
-
-Event searches (`sunEvents`/`moonEvents`) are linear in window length. The full
-151-year supported interval is a measured cost, not a guess: ~68 s in TypeScript,
-~44 s in Swift release builds. Chunk or worker a full-range call rather than
-running it inline.
-
-Run `node benchmarks/run.mjs --base origin/main` from the repository root to
-compare both ports against a baseline. CI reports timings and fails on median
-regressions over 20%; see [the performance harness](CONTRIBUTING.md#performance)
-for workloads, results and local options.

package/dist/eclipse.js

@@ -108,10 +108,13 @@ function peakEarthShadow(centerUt) {
  * then averages the two halves, so the contacts this package reports are
  * symmetric about the peak by construction (as upstream's are).
  */
-function shadowSemiDurationMinutes(centerUt, radiusLimitKm, windowMinutes) {
+function shadowSemiDurationMinutes(shadow, radiusLimitKm, windowMinutes) {
+    const centerUt = shadow.ut;
+    // Both contact searches sample the peak, whose geometry is already known.
+    const distance = (ut) => ut === centerUt ? shadow.r : earthShadow(ut).r;
     const window = windowMinutes / MINUTES_PER_DAY;
-    const t1 = search(ut => -(earthShadow(ut).r - radiusLimitKm), centerUt - window, centerUt, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (before)');
-    const t2 = search(ut => +(earthShadow(ut).r - radiusLimitKm), centerUt, centerUt + window, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (after)');
+    const t1 = search(ut => -(distance(ut) - radiusLimitKm), centerUt - window, centerUt, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (before)');
+    const t2 = search(ut => +(distance(ut) - radiusLimitKm), centerUt, centerUt + window, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (after)');
     if (t1 === null || t2 === null)
         throw new Error('almanac internal: failed to find shadow semiduration');
     return (t2 - t1) * (MINUTES_PER_DAY / 2.0); // convert days to minutes and average the semi-durations
@@ -209,15 +212,15 @@ function buildEclipse(shadow, peak) {
     let kind = 'penumbral';
     let sdTotal = 0.0;
     let sdPartial = 0.0;
-    const sdPenum = shadowSemiDurationMinutes(shadow.ut, shadow.p + MOON_MEAN_RADIUS_KM, PENUMBRAL_WINDOW_MINUTES);
+    const sdPenum = shadowSemiDurationMinutes(shadow, shadow.p + MOON_MEAN_RADIUS_KM, PENUMBRAL_WINDOW_MINUTES);
     if (shadow.r < shadow.k + MOON_MEAN_RADIUS_KM) {
         // This is at least a partial eclipse.
         kind = 'partial';
-        sdPartial = shadowSemiDurationMinutes(shadow.ut, shadow.k + MOON_MEAN_RADIUS_KM, sdPenum);
+        sdPartial = shadowSemiDurationMinutes(shadow, shadow.k + MOON_MEAN_RADIUS_KM, sdPenum);
         if (shadow.r + MOON_MEAN_RADIUS_KM < shadow.k) {
             // This is a total eclipse.
             kind = 'total';
-            sdTotal = shadowSemiDurationMinutes(shadow.ut, shadow.k - MOON_MEAN_RADIUS_KM, sdPartial);
+            sdTotal = shadowSemiDurationMinutes(shadow, shadow.k - MOON_MEAN_RADIUS_KM, sdPartial);
         }
     }
     // Fraction of the Moon's diameter immersed in each shadow. Shadow radii,

package/dist/events.js

@@ -215,13 +215,25 @@ function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
     return score(s1) > score(s2) ? s1 : s2;
 }
 /**
- * Bisection for the single crossing of `level` on the monotonic segment
- * between two consecutive extrema.
+ * Quadratically accelerated search for the single crossing of `level` on a
+ * monotonic segment, with bisection if the estimate cannot be verified.
  */
 function bisectCrossing(sample, level, s0, s1) {
     let a = s0.ut;
     let b = s1.ut;
-    let belowAtA = offsetDeg(s0, level) < 0;
+    const belowAtA = offsetDeg(s0, level) < 0;
+    // Reuse the phase search's quadratic acceleration, normalized to an
+    // ascending crossing. Endpoint geometry has already been evaluated.
+    const f = (ut) => (belowAtA ? 1 : -1) * offsetDeg(ut === s0.ut ? s0 : ut === s1.ut ? s1 : sample(ut), level);
+    const root = search(f, a, b, 0.25, BISECTION_CAP, 'altitude crossing');
+    if (root !== null) {
+        // A derivative-based estimate alone does not establish a time bound.
+        // Accept only a verified half-second bracket, including near grazes.
+        const left = Math.max(a, root - TIME_TOL_DAYS / 4);
+        const right = Math.min(b, root + TIME_TOL_DAYS / 4);
+        if (f(left) < 0 && f(right) >= 0)
+            return (left + right) / 2;
+    }
     for (let i = 0; i < BISECTION_CAP; i++) {
         if (b - a < TIME_TOL_DAYS)
             return (a + b) / 2;
@@ -266,12 +278,28 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
         const s1 = atRangeEnd ? sample(MAX_UT)
             : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut);
         assertReached(s1.ut > s0.ut, 'extremum chain ordering');
-        for (const spec of levels) {
-            const g0 = crossingSign(s0, spec.level);
-            const g1 = crossingSign(s1, spec.level);
-            if (g0 * g1 >= 0)
-                continue; // no crossing, or a graze that only touches
-            emit(bisectCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
+        // Earlier extrema still establish the chain, but their crossings cannot be emitted.
+        if (quantizedUt(s1.ut) >= startUt) {
+            let crossingSample = sample;
+            if (levels.length > 1) {
+                // Twilight levels share midpoint probes; retain them only for this segment.
+                const samples = new Map();
+                crossingSample = (ut) => {
+                    const previous = samples.get(ut);
+                    if (previous)
+                        return previous;
+                    const current = sample(ut);
+                    samples.set(ut, current);
+                    return current;
+                };
+            }
+            for (const spec of levels) {
+                const g0 = crossingSign(s0, spec.level);
+                const g1 = crossingSign(s1, spec.level);
+                if (g0 * g1 >= 0)
+                    continue; // no crossing, or a graze that only touches
+                emit(bisectCrossing(crossingSample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
+            }
         }
         if (nextIsMax && transitKind !== null && !atRangeEnd)
             emit(nextEst, transitKind);

package/dist/illumination.js

@@ -63,7 +63,10 @@ function normalizeLongitude(lon) {
  * that far off the USNO catalogue.
  */
 export function moonPhaseDeg(tt) {
-    return normalizeLongitude(eclipticLonOfDateDeg(moonGeoVectorEqj(tt), tt) - eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt));
+    return moonPhaseFromVector(tt, moonGeoVectorEqj(tt));
+}
+function moonPhaseFromVector(tt, moon) {
+    return normalizeLongitude(eclipticLonOfDateDeg(moon, tt) - eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt));
 }
 /** INTERNAL: moon illumination for a TT instant. See {@link moonIllumination}. */
 export function moonIlluminationAtTT(tt) {
@@ -74,7 +77,7 @@ export function moonIlluminationAtTT(tt) {
     const hc = { x: earth.x + gc.x, y: earth.y + gc.y, z: earth.z + gc.z };
     const phaseAngleDeg = angleBetweenDeg(gc, hc);
     const fraction = (1 + Math.cos(DEG2RAD * phaseAngleDeg)) / 2;
-    const phase = moonPhaseDeg(tt) / 360;
+    const phase = moonPhaseFromVector(tt, gc) / 360;
     return { fraction, phaseAngleDeg, phase, waxing: phase < 0.5 };
 }
 /**

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { AlmanacOutOfRangeError } from './types.js';
 export type { SunPosition, MoonPosition } from './positions.js';
 export { sunPosition, moonPosition } from './positions.js';
 export type { AltAz } from './transforms.js';
-export { sunAltAz, moonAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export type { MoonIllumination } from './illumination.js';
 export { moonIllumination } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName } from './events.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { AlmanacOutOfRangeError } from './types.js';
 export { sunPosition, moonPosition } from './positions.js';
-export { sunAltAz, moonAltAz } from './transforms.js';
+export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/dist/moon.js

@@ -14,43 +14,21 @@ import { ARC, EARTH_EQUATORIAL_RADIUS_AU, PI2, PrecessDirection, eclipticToEquat
  */
 export function calcMoon(tt) {
     const T = tt / 36525;
-    function DeclareArray1(xmin, xmax) {
-        const array = [];
-        let i;
-        for (i = 0; i <= xmax - xmin; ++i) {
-            array.push(0);
-        }
-        return { min: xmin, array: array };
-    }
-    function DeclareArray2(xmin, xmax, ymin, ymax) {
-        const array = [];
-        for (let i = 0; i <= xmax - xmin; ++i) {
-            array.push(DeclareArray1(ymin, ymax));
-        }
-        return { min: xmin, array: array };
-    }
-    function ArrayGet2(a, x, y) {
-        const m = a.array[x - a.min];
-        return m.array[y - m.min];
-    }
-    function ArraySet2(a, x, y, v) {
-        const m = a.array[x - a.min];
-        m.array[y - m.min] = v;
-    }
     let S, MAX, ARG, FAC, I, J, T2, DGAM, DLAM, N, GAM1C, SINPI, L0, L, LS, F, D, DL0, DL, DLS, DF, DD, DS;
-    let coArray = DeclareArray2(-6, 6, 1, 4);
-    let siArray = DeclareArray2(-6, 6, 1, 4);
+    // CO/SI tables: x in -6...6, y in 1...4, stored in flat 13x4 arrays.
+    const coArray = new Array(52).fill(0);
+    const siArray = new Array(52).fill(0);
     function CO(x, y) {
-        return ArrayGet2(coArray, x, y);
+        return coArray[(x + 6) * 4 + y - 1];
     }
     function SI(x, y) {
-        return ArrayGet2(siArray, x, y);
+        return siArray[(x + 6) * 4 + y - 1];
     }
     function SetCO(x, y, v) {
-        return ArraySet2(coArray, x, y, v);
+        coArray[(x + 6) * 4 + y - 1] = v;
     }
     function SetSI(x, y, v) {
-        return ArraySet2(siArray, x, y, v);
+        siArray[(x + 6) * 4 + y - 1] = v;
     }
     function AddThe(c1, s1, c2, s2, func) {
         func(c1 * c2 - s1 * s2, s1 * c2 + c1 * s2);

package/dist/transforms.d.ts

@@ -59,3 +59,15 @@ export declare function sunAltAz(time: Date, observer: Observer): AltAz;
  * refraction (upstream `'normal'` model) both applied.
  */
 export declare function moonAltAz(time: Date, observer: Observer): AltAz;
+/**
+ * Topocentric azimuth/altitude of a fixed star from its J2000 (ICRS)
+ * catalog right ascension and declination, both in degrees.
+ *
+ * Applied: precession and nutation to the equator of date, Greenwich
+ * apparent sidereal time, and atmospheric refraction (upstream `'normal'`
+ * model, the same as sunAltAz/moonAltAz). Not applied: annual aberration
+ * (at most 20.5″ — see the roadmap), proper motion (pass catalog
+ * coordinates; fast movers such as Arcturus drift ~1′ in 26 years), and
+ * stellar parallax (negligible at the 1000 ly the star is placed at).
+ */
+export declare function starAltAz(raDeg: number, decDeg: number, time: Date, observer: Observer): AltAz;

package/dist/transforms.js

@@ -196,3 +196,41 @@ export function moonAltAz(time, observer) {
     const ut = utDays(time);
     return refract(topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer));
 }
+/**
+ * UPSTREAM: the user-defined star path — `HelioVector` for a `DefineStar`
+ * body (astronomy.ts ~4097: `VectorFromSphere(Spherical(dec, 15*ra, dist))`)
+ * into `Equator(body, date, observer, ofdate=true, aberration=false)` (~2803)
+ * and `Horizon` (~2565): the same topocentric path sunAltAz/moonAltAz take.
+ * Upstream floors a star's distance at 1 light-year and suggests 1000 when
+ * unknown; the star sits at 1000 ly here (`AU_PER_LY`, astronomy.ts line 52).
+ * Upstream's geocentric step (star vector minus Earth's heliocentric
+ * position) is skipped: at 1000 ly it moves the star 0.003″.
+ */
+const STAR_DISTANCE_AU = 1000 * 63241.07708807546;
+/**
+ * Topocentric azimuth/altitude of a fixed star from its J2000 (ICRS)
+ * catalog right ascension and declination, both in degrees.
+ *
+ * Applied: precession and nutation to the equator of date, Greenwich
+ * apparent sidereal time, and atmospheric refraction (upstream `'normal'`
+ * model, the same as sunAltAz/moonAltAz). Not applied: annual aberration
+ * (at most 20.5″ — see the roadmap), proper motion (pass catalog
+ * coordinates; fast movers such as Arcturus drift ~1′ in 26 years), and
+ * stellar parallax (negligible at the 1000 ly the star is placed at).
+ */
+export function starAltAz(raDeg, decDeg, time, observer) {
+    assertSupported(time);
+    assertObserver(observer);
+    if (!(raDeg >= 0 && raDeg < 360))
+        throw new RangeError(`raDeg out of range: ${raDeg}`);
+    if (!(decDeg >= -90 && decDeg <= 90))
+        throw new RangeError(`decDeg out of range: ${decDeg}`);
+    const ut = utDays(time);
+    const rCosDec = STAR_DISTANCE_AU * Math.cos(decDeg * DEG2RAD);
+    const eqj = {
+        x: rCosDec * Math.cos(raDeg * DEG2RAD),
+        y: rCosDec * Math.sin(raDeg * DEG2RAD),
+        z: STAR_DISTANCE_AU * Math.sin(decDeg * DEG2RAD),
+    };
+    return refract(topoAltAzUnrefracted(eqj, ut, observer));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar eclipses.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/openwatersio/almanac.git", "directory": "typescript" },