@openwaters/almanac 0.4.0 → 0.4.2

package/README.md

@@ -26,31 +26,32 @@ cover positions, a 228-hour sky track, short/year/polar event windows, full-rang
 moon phases, next/previous/range lunar and solar eclipse searches, including empty
 windows, and solar obscuration over a 228-hour track.
 
-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:
+Event searches find altitude extrema with Brent's method and altitude crossings
+with a cosine-seeded secant solver, each root proven inside a half-second
+bracket, and the TypeScript Sun series evaluates its terms as straight-line
+arithmetic. Median query time relative to v0.4.1:
 
 | 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% |
+| Sun events / year | 73.4% | 62.8% |
+| Moon events / year | 57.6% | 57.4% |
+| Sun events / 228 hours | 73.4% | 61.9% |
+| Moon events / 228 hours | 57.1% | 57.0% |
+| Sun positions / 1,024 hours | 35.5% | — |
+| Lunar eclipses / 1950–2100 | 24.6% | — |
 
-TypeScript was measured on Ubuntu; Swift used release builds on macOS. 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.
+Swift already evaluated the Sun series efficiently, so its gains are confined to
+the searches. 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 with mise 2026.9.1 or newer after installing the configured Node and Swift versions in `mise.toml`:
 
 ```bash
 mise install
 mise exec -- npm ci --prefix typescript
-mise exec -- node benchmarks/run.mjs --base v0.2.0 --skip '^solar/'
+mise exec -- node benchmarks/run.mjs --base v0.4.1
 ```
 
-The `--skip` pattern leaves out the solar eclipse workloads, which need a base of 0.4.0 or later.
+Pass `--skip '^solar/'` when the base predates 0.4.0, which is when the solar eclipse workloads arrived.
 
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain

package/dist/events.js

@@ -8,8 +8,9 @@
 // a grid can straddle both halves of a grazing pair (the polar-onset day where
 // the Sun sets at 08:00 and rises again at 08:16) and report neither. Here each
 // daily cycle's altitude extrema are located numerically and every monotonic
-// segment between consecutive extrema is bisected, so a pair of crossings
-// minutes apart is bracketed by construction rather than by luck of the grid.
+// segment between consecutive extrema is solved for each target level, so a
+// pair of crossings minutes apart is bracketed by construction rather than by
+// luck of the grid.
 // Hour angle supplies only the initial bracket: HA 0/12h are not the exact
 // extrema, because declination, distance and lunar parallax all drift within a
 // cycle, and toward the poles the daily altitude cycle flattens until the
@@ -22,7 +23,7 @@
 // and `NextMoonQuarter` (~5362).
 import { assertObserver, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
-import { KM_PER_AU, RAD2DEG } from './nutation.js';
+import { DEG2RAD, KM_PER_AU, RAD2DEG } from './nutation.js';
 import { topoAltAzUnrefracted } from './transforms.js';
 import { sunGeoVectorEqj } from './sun.js';
 import { moonGeoVectorEqj } from './moon.js';
@@ -57,7 +58,7 @@ const SUN_CYCLE_DAYS = 1;
 const MOON_CYCLE_DAYS = 1.035050;
 const MOON_HA_RATE_DEG_PER_DAY = 360 / MOON_CYCLE_DAYS;
 const SECOND_DAYS = 1 / 86400;
-/** Bisection and golden-section both stop under a second; events are reported to the ms. */
+/** Every search stops under a second; events are reported to the ms. */
 const TIME_TOL_DAYS = SECOND_DAYS;
 /** An extremum this close to the target grazes it without crossing: no event. */
 const TANGENT_EPS_DEG = 1e-6;
@@ -76,6 +77,7 @@ const EXTREMUM_HALF_WIDTH_DAYS = 2 / 24;
 const FLAT_CYCLE_LATITUDE_DEG = 85;
 const GOLDEN_SECTION_CAP = 100;
 const BISECTION_CAP = 60;
+const SECANT_CAP = 8;
 const HOUR_ANGLE_ITER_CAP = 20;
 const MOON_PHASE_ITER_CAP = 50;
 const INV_PHI = 0.6180339887498949;
@@ -171,8 +173,7 @@ function nextHourAngle(sample, afterUt, targetHaDeg, rateDegPerDay) {
     return ut;
 }
 /**
- * Golden-section refinement of the altitude extremum bracketed around
- * `centreUt`. Evaluating the true extremum is what makes a grazing pair
+ * Refinement of the altitude extremum bracketed around `centreUt`. Evaluating the true extremum is what makes a grazing pair
  * findable: the segment on either side of it is monotonic, so bisection can
  * only miss a crossing if the extremum itself was never seen.
  *
@@ -182,9 +183,105 @@ function nextHourAngle(sample, afterUt, targetHaDeg, rateDegPerDay) {
  * declination's slow annual drift, unclamped golden section will happily walk
  * backwards and break the chain's ordering.
  */
-function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
-    let a = Math.max(clampUt(centreUt - halfWidthDays), afterUt);
-    let b = clampUt(centreUt + halfWidthDays);
+function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt, flatCycle) {
+    const a = Math.max(clampUt(centreUt - halfWidthDays), afterUt);
+    const b = clampUt(centreUt + halfWidthDays);
+    if (!flatCycle) {
+        const best = brentExtremum(sample, a, b, wantMax);
+        if (best !== null)
+            return best;
+    }
+    return goldenExtremum(sample, a, b, wantMax);
+}
+/**
+ * Brent's parabolic-plus-golden minimizer on `[a, b]`, scored for a maximum
+ * or minimum. Each step evaluates one sample; a parabola through the three
+ * best points supplies the step whenever it is finite, lands strictly inside
+ * the bracket, and contracts faster than the step before last, and golden
+ * section takes over otherwise. Returns `null` when the search hits its cap or
+ * settles within a tolerance of the original bracket edge, where the flat,
+ * asymmetric altitude curve has made the parabola unreliable; the caller then
+ * runs the golden search unchanged.
+ */
+function brentExtremum(sample, a0, b0, wantMax) {
+    const cost = (s) => (wantMax ? -s.altDeg : s.altDeg);
+    let a = a0;
+    let b = b0;
+    let x = a + (1 - INV_PHI) * (b - a);
+    let w = x;
+    let v = x;
+    let sx = sample(x);
+    let fx = cost(sx);
+    let fw = fx;
+    let fv = fx;
+    let d = 0; // the last step taken
+    let e = 0; // the step before last, which the parabolic step must beat
+    for (let i = 0; i < GOLDEN_SECTION_CAP; i++) {
+        if (b - a < TIME_TOL_DAYS) {
+            return x - a0 < TIME_TOL_DAYS || b0 - x < TIME_TOL_DAYS ? null : sx;
+        }
+        const tol1 = Math.max(TIME_TOL_DAYS / 16, 4 * Number.EPSILON * Math.abs(x));
+        const xm = (a + b) / 2;
+        let golden = true;
+        if (Math.abs(e) > tol1) {
+            const r = (x - w) * (fx - fv);
+            let q = (x - v) * (fx - fw);
+            let p = (x - v) * q - (x - w) * r;
+            q = 2 * (q - r);
+            if (q > 0)
+                p = -p;
+            q = Math.abs(q);
+            const eTemp = e;
+            e = d;
+            if (Number.isFinite(p / q) && Math.abs(p) < Math.abs(0.5 * q * eTemp) && p > q * (a - x) && p < q * (b - x)) {
+                d = p / q;
+                // Near an edge the parabola only re-proposes the best point; step across it instead.
+                if (x + d - a < 2 * tol1 || b - (x + d) < 2 * tol1)
+                    d = xm >= x ? tol1 : -tol1;
+                golden = false;
+            }
+        }
+        if (golden) {
+            e = x >= xm ? a - x : b - x;
+            d = (1 - INV_PHI) * e;
+        }
+        const u = Math.abs(d) >= tol1 ? x + d : x + (d >= 0 ? tol1 : -tol1);
+        const su = sample(u);
+        const fu = cost(su);
+        if (fu <= fx) {
+            if (u >= x)
+                a = x;
+            else
+                b = x;
+            v = w;
+            fv = fw;
+            w = x;
+            fw = fx;
+            x = u;
+            fx = fu;
+            sx = su;
+        }
+        else {
+            if (u < x)
+                a = u;
+            else
+                b = u;
+            if (fu <= fw || w === x) {
+                v = w;
+                fv = fw;
+                w = u;
+                fw = fu;
+            }
+            else if (fu <= fv || v === x || v === w) {
+                v = u;
+                fv = fu;
+            }
+        }
+    }
+    return null;
+}
+/** Golden-section search of the extremum on `[a, b]`: slow, and safe on any curve shape. */
+function goldenExtremum(sample, a, b, wantMax) {
     let x1 = b - INV_PHI * (b - a);
     let x2 = a + INV_PHI * (b - a);
     let s1 = sample(x1);
@@ -215,16 +312,27 @@ function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
     return score(s1) > score(s2) ? s1 : s2;
 }
 /**
- * Quadratically accelerated search for the single crossing of `level` on a
- * monotonic segment, with bisection if the estimate cannot be verified.
+ * The single crossing of `level` on a monotonic segment between two extrema,
+ * reported from inside a verified half-second bracket.
+ *
+ * Between extrema the altitude offset is close to a half cosine, so the cosine
+ * through the two endpoints predicts the crossing to within a minute for the
+ * Sun and a few minutes for the Moon, with no probe at all. Secant steps from
+ * that estimate reach the second in one or two probes, and one more probe on
+ * the side the last sign points to proves the bracket. Anything that escapes
+ * the segment, stalls, or fails the proof falls back to the quadratically
+ * accelerated bracketed search with bisection behind it.
  */
-function bisectCrossing(sample, level, s0, s1) {
+function solveCrossing(sample, level, s0, s1) {
     let a = s0.ut;
     let b = s1.ut;
     const belowAtA = offsetDeg(s0, level) < 0;
-    // Reuse the phase search's quadratic acceleration, normalized to an
-    // ascending crossing. Endpoint geometry has already been evaluated.
+    // 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 targetDeg = level === null ? (s0.riseSetAltDeg + s1.riseSetAltDeg) / 2 : level;
+    const secant = secantCrossing(f, a, b, s0, s1, targetDeg);
+    if (secant !== null)
+        return secant;
     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.
@@ -246,6 +354,51 @@ function bisectCrossing(sample, level, s0, s1) {
     assertReached(false, 'crossing bisection');
     return (a + b) / 2;
 }
+/**
+ * Secant refinement of the ascending crossing of `f` on `[a, b]`, started from
+ * the half cosine that the sine of altitude follows between two extrema.
+ * Returns the root inside a proven half-second bracket, or `null` when the
+ * caller should run the bracketed search.
+ */
+function secantCrossing(f, a, b, s0, s1, targetDeg) {
+    // sin(alt) ≈ c + amp·cos(π (t − a) / (b − a)) passes through both extrema; a
+    // constant declination and no parallax would make it exact.
+    const g0 = Math.sin(s0.altDeg * DEG2RAD);
+    const g1 = Math.sin(s1.altDeg * DEG2RAD);
+    const c = (g0 + g1) / 2;
+    const amp = (g0 - g1) / 2;
+    const ratio = (Math.sin(targetDeg * DEG2RAD) - c) / amp;
+    if (!(Math.abs(ratio) < 1))
+        return null;
+    const theta = Math.acos(ratio);
+    let t = a + theta * (b - a) / Math.PI;
+    let slope = Math.abs(amp) * Math.sin(theta) * Math.PI / (b - a) / Math.cos(targetDeg * DEG2RAD) * RAD2DEG;
+    let ft = f(t);
+    for (let i = 0; i < SECANT_CAP; i++) {
+        const step = -ft / slope;
+        if (!Number.isFinite(step))
+            return null;
+        if (Math.abs(step) < TIME_TOL_DAYS / 4) {
+            // The last sign says which side the root is on: prove a half-second
+            // bracket there, then report the secant root itself, held inside the
+            // bracket, so the answer does not jump with the side the probe picked.
+            if (ft < 0) {
+                const right = Math.min(b, t + TIME_TOL_DAYS / 2);
+                return f(right) >= 0 ? Math.min(t + step, right) : null;
+            }
+            const left = Math.max(a, t - TIME_TOL_DAYS / 2);
+            return f(left) < 0 ? Math.max(left, t + step) : null;
+        }
+        const next = t + step;
+        if (next <= a || next >= b)
+            return null;
+        const fNext = f(next);
+        slope = (fNext - ft) / (next - t);
+        t = next;
+        ft = fNext;
+    }
+    return null;
+}
 /**
  * Walk the window one half-cycle at a time, refining each altitude extremum and
  * solving every monotonic segment between consecutive extrema for every target
@@ -253,7 +406,8 @@ function bisectCrossing(sample, level, s0, s1) {
  * containing the window's first instant is covered, and runs one extremum past
  * `endUt` so an event just inside the window's end is too.
  */
-function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, extremumHalfWidthDays) {
+function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
+    const extremumHalfWidthDays = flatCycle ? cycleDays / 2 : EXTREMUM_HALF_WIDTH_DAYS;
     const found = [];
     const emit = (ut, kind) => {
         const q = quantizedUt(ut);
@@ -276,29 +430,16 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
         // extremum we are not allowed to probe past. The segment up to it is
         // still monotonic, so any crossing inside the window is still found.
         const s1 = atRangeEnd ? sample(MAX_UT)
-            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut);
+            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut, flatCycle);
         assertReached(s1.ut > s0.ut, 'extremum chain ordering');
         // 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);
+                emit(solveCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
             }
         }
         if (nextIsMax && transitKind !== null && !atRangeEnd)
@@ -321,10 +462,8 @@ const SUN_LEVELS = [
 const MOON_LEVELS = [
     { level: null, rising: 'rise', falling: 'set' },
 ];
-function extremumHalfWidth(observer, cycleDays) {
-    return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG
-        ? cycleDays / 2
-        : EXTREMUM_HALF_WIDTH_DAYS;
+function flatCycle(observer) {
+    return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG;
 }
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
@@ -344,7 +483,7 @@ export function sunEvents(startUtc, endUtc, observer) {
     assertObserver(observer);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(sunSampler(observer), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, extremumHalfWidth(observer, SUN_CYCLE_DAYS));
+    return searchAltitudeEvents(sunSampler(observer), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
 }
 /**
  * Moonrise and moonset within the half-open window `[startUtc, endUtc)`,
@@ -358,7 +497,7 @@ export function moonEvents(startUtc, endUtc, observer) {
     assertObserver(observer);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, extremumHalfWidth(observer, MOON_CYCLE_DAYS));
+    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
 }
 // -------------------------------------------------------------- moon phases
 /**