@saber-usa/node-common 1.7.17 → 1.7.18-alpha.1

package/src/wasmProp/wasmAstro.js

@@ -0,0 +1,251 @@
+import {
+    EciBaseCalculator,
+    GmstCalculator,
+    GeodeticPositionCalculator,
+} from "satellite.js";
+import {getBulkRuntime, getOrCreateBulkPropagator} from "./runtime.js";
+import {elsetsToSatrecs, propBulk} from "./primitives.js";
+import {
+    assembleLeoRpoResult,
+    assembleGeoRpoResult,
+    buildShadowZoneElsets,
+    analyzeShadowZoneSeries,
+    buildWaterfallBreakpoints,
+    decorateWaterfallSegment,
+    assembleWaterfallRows,
+    checkTle,
+    getLonAndDrift,
+    getEclipseStatus,
+} from "../astro.js";
+import {isDefined} from "../utils.js";
+import {RAD2DEG} from "../constants.js";
+
+// ----------------------------------------------------------------------------
+// High-level WASM-backed bulk siblings of the `getLeoRpoData`,
+// `getGeoRpoData`, `getLeoWaterfallData`, and `getGeoShadowZones` entry
+// points. Each function shares its pure assembly helpers with the JS-path
+// sibling in `../astro.js` to prevent logic drift between the two paths.
+//
+// See `docs/BULK_PROPAGATION.md` for the design rationale, the rollout
+// table, and the measured break-even threshold that drives flip decisions.
+// ----------------------------------------------------------------------------
+
+/**
+ * WASM-backed sibling of `getLeoRpoData`. Computes ephemerides for
+ * `[primary, ...sats]` in a single `propBulk` call (one WASM round-trip,
+ * one allocation pass, identical 10-second step), then forwards each
+ * (primary, threat) pair through the same `assembleLeoRpoResult` helper
+ * used by the JS path.
+ *
+ * Same contract as `getLeoRpoData` — same input shape, same output shape —
+ * but `async` because the WASM runtime is initialized lazily.
+ *
+ * Use when `sats.length × dates` is high enough to clear the break-even
+ * threshold documented in `docs/BULK_PROPAGATION.md` §10. For small
+ * `sats.length` (e.g. one or two threats) prefer the sync `getLeoRpoData`.
+ *
+ * @param {String} line1 line 1 of the target satellite
+ * @param {String} line2 line 2 of the target satellite
+ * @param {Array<Object>} sats array of potential threat satellites and their Elsets
+ * @param {Number} startTime start time of the analysis, Unix milliseconds
+ * @param {Number} endTime end time of the analysis, Unix milliseconds
+ * @return {Promise<Array<Object>>}
+ */
+const getLeoRpoDataBulk = async (line1, line2, sats, startTime, endTime) => {
+    const results = [];
+    const pSatRec = checkTle(line1, line2);
+    if (!isDefined(pSatRec)) {return results;}
+
+    const start = new Date(startTime).getTime();
+    const end = new Date(endTime).getTime();
+    const pElset = {Line1: line1, Line2: line2};
+
+    // One WASM round-trip for [primary, ...threats]. propBulk preserves
+    // input order in its returned outer array.
+    const ephemerides = await propBulk([pElset, ...sats], start, end, 10000);
+    const pEphem = ephemerides[0];
+    if (!isDefined(pEphem) || pEphem.length === 0) {
+        return results; // Primary may have re-entered the atmosphere.
+    }
+
+    for (let i = 0; i < sats.length; i++) {
+        const row = assembleLeoRpoResult(sats[i], pEphem, ephemerides[i + 1]);
+        if (isDefined(row)) {results.push(row);}
+    }
+    return results;
+};
+
+/**
+ * WASM-backed sibling of `getGeoRpoData`. Computes ephemerides for
+ * `[primary, ...sats]` in a single `propBulk` call (60-second step,
+ * matching the JS path), then assembles each (primary, threat) pair
+ * through the shared `assembleGeoRpoResult` helper.
+ *
+ * `getLonAndDrift` stays on the JS path: it is a single-satellite
+ * Brouwer-mean-element calculation that does not benefit from
+ * `BulkPropagator`'s amortized batch model (see `docs/BULK_PROPAGATION.md`
+ * "low-value opportunities").
+ *
+ * Same input/output contract as `getGeoRpoData`, but `async` because the
+ * WASM runtime is initialized lazily.
+ *
+ * @param {String} line1 line 1 of the target satellite
+ * @param {String} line2 line 2 of the target satellite
+ * @param {Array<Object>} sats array of potential threat satellites and their Elsets
+ * @param {Number} startTime start time of the analysis, Unix milliseconds
+ * @param {Number} endTime end time of the analysis, Unix milliseconds
+ * @param {Number} [lonTime] datetime to analyze longitude and lon drift at, Unix ms
+ * @return {Promise<Array<Object>>}
+ */
+const getGeoRpoDataBulk = async (line1, line2, sats, startTime, endTime, lonTime) => {
+    const results = [];
+    const start = new Date(startTime).getTime();
+    const end = new Date(endTime).getTime();
+    const pElset = {Line1: line1, Line2: line2};
+
+    const ephemerides = await propBulk([pElset, ...sats], start, end, 60000);
+    const pEphem = ephemerides[0];
+    if (!isDefined(pEphem) || pEphem.length === 0) {
+        return results; // Primary may have re-entered the atmosphere
+    }
+
+    const lonEvalTime = lonTime ? new Date(lonTime) : new Date(end);
+    const pLonAndDrift = getLonAndDrift(line1, line2, lonEvalTime);
+
+    for (let i = 0; i < sats.length; i++) {
+        const s = sats[i];
+        const sLonAndDrift = getLonAndDrift(s.Line1, s.Line2, lonEvalTime);
+        const row = assembleGeoRpoResult(s, pEphem, ephemerides[i + 1],
+            pLonAndDrift, sLonAndDrift);
+        if (isDefined(row)) {results.push(row);}
+    }
+
+    return results;
+};
+
+/**
+ * WASM-backed sibling of `getGeoShadowZones`. Synthesizes the
+ * `360 / accuracySecondsDeg` mean-anomaly GEO satrecs up front and
+ * dispatches one bulk propagation for the single requested time. The
+ * pipeline `[Eci, Gmst, Geodetic]` is run once so we get both ECI
+ * positions (for `getEclipseStatus`) and geodetic longitude (for the
+ * zone seam) without a second round-trip.
+ *
+ * Reuses the same per-thread `eci+gmst+geo` propagator as
+ * `propGeodeticBulk` (see `runtime.js`'s pipeline registry), so the
+ * WASM compile and pipeline-buffer allocations are amortized across all
+ * shadow-zone callers in the same worker.
+ *
+ * Same input/output contract as `getGeoShadowZones`, but `async`.
+ *
+ * @param {Date} time
+ * @param {Number} [accuracySecondsDeg=0.00416*100]
+ * @return {Promise<{penStartWestLon:?number, penStartEastLon:?number}>}
+ */
+const getGeoShadowZonesBulk = async (time, accuracySecondsDeg = 0.00416 * 100) => {
+    const elsets = buildShadowZoneElsets(accuracySecondsDeg);
+    const satrecs = elsetsToSatrecs(elsets);
+    const dates = [time instanceof Date ? time : new Date(time)];
+
+    const runtime = await getBulkRuntime();
+    const propagator = getOrCreateBulkPropagator({
+        runtime,
+        key: "eci+gmst+geo",
+        makeCalculators: () => [
+            new EciBaseCalculator(),
+            new GmstCalculator(),
+            new GeodeticPositionCalculator(),
+        ],
+        satRecsCount: satrecs.length,
+        datesCount: dates.length,
+    });
+    propagator.setSatRecs(satrecs);
+    propagator.setDates(dates);
+    propagator.run();
+
+    const {eci, geodeticPosition} = propagator.getRawOutput();
+    // raw eci.position layout: [sat0_date0_x, _y, _z, sat0_date1_x, ...]
+    // raw geodeticPosition layout: see `propGeodeticBulk` — the
+    // satellite.js@7.0.0 lat/lon swap applies here too.
+    const res = new Array(satrecs.length);
+    for (let s = 0; s < satrecs.length; s++) {
+        if (eci.error[s] !== 0) {
+            // Defensive: the canonical TLE is expected to propagate cleanly.
+            res[s] = {ecl: "SUN", geolon: 0};
+            continue;
+        }
+        const pIdx = s * 3;
+        const px = eci.position[pIdx];
+        const py = eci.position[pIdx + 1];
+        const pz = eci.position[pIdx + 2];
+        const gIdx = s * 3;
+        res[s] = {
+            ecl: getEclipseStatus(dates[0], [px, py, pz]),
+            geolon: geodeticPosition[gIdx] * RAD2DEG, // physical lon (see swap note)
+        };
+    }
+    return analyzeShadowZoneSeries(res);
+};
+
+/**
+ * WASM-backed sibling of `getLeoWaterfallData`. For each segment in
+ * the waterfall breakpoint schedule, dispatches a single `propBulk` call
+ * over the satellites' currently-active elsets, then forwards each
+ * per-segment ephemeris through the shared `decorateWaterfallSegment`
+ * helper. The cross-satellite assembly step (`assembleWaterfallRows`) is
+ * identical to the JS path.
+ *
+ * Calls `propBulk` once per segment (segments correspond to elset epoch
+ * boundaries — typically 1–10 in a multi-day window) rather than once per
+ * (segment × satellite) pair, so the WASM amortization is meaningful even
+ * at modest satellite counts. The WASM runtime + propagator are reused
+ * across segments via the per-thread registry in `./runtime.js`.
+ *
+ * Same input/output contract as `getLeoWaterfallData`, but `async`.
+ *
+ * @param {Array<Array<Object>>} elsets per-satellite elset arrays; primary at index 0
+ * @param {Number} startTime Unix ms
+ * @param {Number} endTime Unix ms
+ * @param {Number} [stepMs=10000] step in milliseconds
+ * @return {Promise<Array<Object>>}
+ */
+const getLeoWaterfallDataBulk = async (elsets, startTime, endTime, stepMs = 10000) => {
+    const start = new Date(startTime).getTime();
+    const end = new Date(endTime).getTime();
+
+    const breakpoints = buildWaterfallBreakpoints(elsets, start, end);
+    const currentIndices = elsets.map(() => 0);
+    const satEphems = elsets.map(() => []);
+
+    for (let i = 0; i < breakpoints.length - 1; i++) {
+        const bkpoint = breakpoints[i];
+        const segmentStart = bkpoint.time;
+        const segmentEnd = breakpoints[i + 1].time;
+
+        if (bkpoint.satIndex >= 0) {
+            currentIndices[bkpoint.satIndex] = bkpoint.elsetIndex;
+        }
+
+        const activeElsets = currentIndices.map(
+            (elsetIndex, satIndex) => elsets[satIndex][elsetIndex],
+        );
+        // One WASM round-trip per segment, ordered by satIndex.
+         
+        const segmentEphems = await propBulk(activeElsets, segmentStart, segmentEnd, stepMs);
+
+        activeElsets.forEach((elset, satIndex) => {
+            satEphems[satIndex].push(
+                ...decorateWaterfallSegment(segmentEphems[satIndex], elset, bkpoint, satIndex),
+            );
+        });
+    }
+
+    return assembleWaterfallRows(satEphems);
+};
+
+export {
+    getLeoRpoDataBulk,
+    getGeoRpoDataBulk,
+    getGeoShadowZonesBulk,
+    getLeoWaterfallDataBulk,
+};