@openwaters/almanac 0.10.0 → 0.11.0

package/README.md

@@ -111,7 +111,7 @@ npm install @openwaters/almanac
 ```ts
 import {
   nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, nextGlobalSolarEclipse, sunEvents, starAltAz,
-  seasons, moonApsides, equationOfTime
+  seasons, moonApsides, earthApsides, equationOfTime
 } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
@@ -141,6 +141,7 @@ const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 const year = new Date(today.getUTCFullYear() + 1, 0, 1);
 for (const { kind, time } of seasons(today, year)) console.log(kind, time.toISOString());
 for (const { kind, time, distanceKm } of moonApsides(today, year)) console.log(kind, time.toISOString(), distanceKm);
+for (const { kind, time, distanceKm } of earthApsides(today, year)) console.log(kind, time.toISOString(), distanceKm);
 console.log(equationOfTime(today));   // sundial minus clock, minutes
 ```
 
@@ -160,7 +161,7 @@ const crossings = sunEvents(today, tomorrow, viewer, eyeHeightM);
 Requires a Swift 6 or newer toolchain.
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.10.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.11.0")
 ```
 
 ```swift
@@ -197,6 +198,7 @@ let star = try starAltAz(raDeg: 88.792939, decDeg: 7.407064, at: today, observer
 let year = today.addingTimeInterval(366 * 24 * 60 * 60)
 for event in try seasons(from: today, to: year) { print(event.kind, event.time) }
 for apsis in try moonApsides(from: today, to: year) { print(apsis.kind, apsis.time, apsis.distanceKm) }
+for apsis in try earthApsides(from: today, to: year) { print(apsis.kind, apsis.time, apsis.distanceKm) }
 print(try equationOfTime(today))   // sundial minus clock, minutes
 ```
 

package/dist/earthApsides.d.ts

@@ -0,0 +1,14 @@
+/** Closest approach or farthest remove of the Earth from the Sun's centre. */
+export type EarthApsisKind = 'perihelion' | 'aphelion';
+/** A terrestrial perihelion or aphelion, with the Sun–Earth centre distance there. */
+export interface EarthApsis {
+    time: Date;
+    kind: EarthApsisKind;
+    distanceKm: number;
+}
+/**
+ * The Earth's perihelia and aphelia within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the heliocentric distance
+ * at that instant.
+ */
+export declare function earthApsides(startUtc: Date, endUtc: Date): EarthApsis[];

package/dist/earthApsides.js

@@ -0,0 +1,76 @@
+// SearchPlanetApsis (Earth), pinned Astronomy Engine 865d3da7d8112bbc7911238052c6af4aaf877181.
+// Central difference in UT, orbital-period/6 brackets; fixed J2000 grid gives window-independent roots.
+import { assertSupported, assertSupportedWindowEnd } from './types.js';
+import { utDays, ttDaysFromUt, dateFromUt } from './time.js';
+import { KM_PER_AU } from './nutation.js';
+import { earthHelioDistance } from './sun.js';
+import { search, quantizedUt, assertReached } from './events.js';
+/** UPSTREAM: the central-difference half-width `dt` inside `SearchPlanetApsis`. */
+const SLOPE_DT_DAYS = 0.001;
+/** UPSTREAM: `increment` — the scan step, here also the grid cell in days since J2000 UT. */
+const APSIS_CELL_DAYS = 365.256 / 6;
+/** UPSTREAM: `positive_slope` — dr/dt in AU per day, by central difference. */
+function distanceSlope(ut) {
+    const r1 = earthHelioDistance(ttDaysFromUt(ut - SLOPE_DT_DAYS / 2));
+    const r2 = earthHelioDistance(ttDaysFromUt(ut + SLOPE_DT_DAYS / 2));
+    return (r2 - r1) / SLOPE_DT_DAYS;
+}
+function negativeDistanceSlope(ut) {
+    return -distanceSlope(ut);
+}
+/**
+ * UPSTREAM: the body of `SearchPlanetApsis`'s scan loop for one cell `[t1, t2]`
+ * with the slopes `m1`, `m2` at its ends. A slope rising through zero is a
+ * perihelion and falling through zero an aphelion. A zero exactly at a grid point
+ * belongs to the cell it ends, so no apsis is reported twice.
+ */
+function searchApsisInCell(t1, t2, m1, m2) {
+    if (m1 < 0 && m2 >= 0) {
+        const ut = search(distanceSlope, t1, t2, 1, undefined, 'perihelion search');
+        assertReached(ut !== null, 'perihelion search');
+        return { ut: ut, kind: 'perihelion' };
+    }
+    if (m1 > 0 && m2 <= 0) {
+        const ut = search(negativeDistanceSlope, t1, t2, 1, undefined, 'aphelion search');
+        assertReached(ut !== null, 'aphelion search');
+        return { ut: ut, kind: 'aphelion' };
+    }
+    return null;
+}
+/**
+ * The Earth's perihelia and aphelia within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the heliocentric distance
+ * at that instant.
+ */
+export function earthApsides(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    let cell = Math.floor(startUt / APSIS_CELL_DAYS);
+    let t1 = cell * APSIS_CELL_DAYS;
+    let m1 = distanceSlope(t1);
+    while (t1 < endUt) {
+        const t2 = (cell + 1) * APSIS_CELL_DAYS;
+        const m2 = distanceSlope(t2);
+        const found = searchApsisInCell(t1, t2, m1, m2);
+        if (found !== null) {
+            const q = quantizedUt(found.ut); // judge the half-open bounds on the reported instant, not the raw root
+            if (q >= endUt)
+                break;
+            if (q >= startUt) {
+                events.push({
+                    time: dateFromUt(found.ut), kind: found.kind,
+                    distanceKm: earthHelioDistance(ttDaysFromUt(found.ut)) * KM_PER_AU
+                });
+            }
+        }
+        cell++;
+        t1 = t2;
+        m1 = m2;
+    }
+    return events;
+}

package/dist/index.d.ts

@@ -22,3 +22,5 @@ export type { SolarEclipse, SolarEclipseKind, SolarEclipseSunAltitudes } from '.
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export type { GlobalSolarEclipse, SolarEclipseAxisPoint } from './globalSolar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';
+export type { EarthApsisKind, EarthApsis } from './earthApsides.js';
+export { earthApsides } from './earthApsides.js';

package/dist/index.js

@@ -12,3 +12,4 @@ export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAlti
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';
+export { earthApsides } from './earthApsides.js';

package/dist/sun.d.ts

@@ -11,6 +11,7 @@ export declare const vsopEarth: VsopModel;
 export declare function vsopRotate(eclip: Vec3): Vec3;
 /** UPSTREAM: `VsopSphereToRect`, astronomy.ts lines 3243-3253. */
 export declare function vsopSphereToRect(lon: number, lat: number, radius: number): Vec3;
+export declare function earthHelioDistance(tt: number): number;
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).

package/dist/sun.js

@@ -223,6 +223,8 @@ export function vsopSphereToRect(lon, lat, radius) {
         z: radius * Math.sin(lat)
     };
 }
+// UPSTREAM: HelioDistance(Body.Earth), the scalar VSOP radius without rotations.
+export function earthHelioDistance(tt) { return earthRad(tt / 365250); }
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {