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

package/src/ballisticPropagator.js

@@ -1029,4 +1029,4 @@ export {BallisticPropagator, BallisticPropagatorUtils, PosVelVec, EarthConstants
  * console.log('Position after 300s:', result.position);
  * console.log('Velocity after 300s:', result.velocity);
  */
-
+

package/src/index.js

@@ -4,6 +4,7 @@ export * from "./transform.js";
 export * from "./checkNetwork.cjs";
 export * from "./fixDate.js";
 export * from "./astro.js";
+export * from "./wasmProp/index.js";
 export * from "./launchNominal.js";
 export * from "./LaunchNominalClass.js";
 export * from "./OrbitUtils.js";
@@ -22,6 +23,7 @@ import * as transformNS from "./transform.js";
 import * as checkNetworkNS from "./checkNetwork.cjs";
 import * as fixDateNS from "./fixDate.js";
 import * as astroNS from "./astro.js";
+import * as wasmPropNS from "./wasmProp/index.js";
 import * as launchNominalNS from "./launchNominal.js";
 import * as LaunchNominalClassNS from "./LaunchNominalClass.js";
 import * as OrbitUtilsNS from "./OrbitUtils.js";
@@ -35,6 +37,7 @@ const aggregate = {
     ...checkNetworkNS,
     ...fixDateNS,
     ...astroNS,
+    ...wasmPropNS,
     ...launchNominalNS,
     ...LaunchNominalClassNS,
     ...OrbitUtilsNS,

package/src/wasmProp/index.js

@@ -0,0 +1,10 @@
+// Barrel for all WASM-backed bulk propagation exports. Kept behind a
+// single entry point so the rest of the codebase (and external consumers
+// via `@saber-usa/node-common`) can discover the bulk API without having
+// to reach into per-feature files.
+//
+// See `docs/BULK_PROPAGATION.md` for the design rationale, lifecycle, and
+// the measured performance characteristics.
+export * from "./runtime.js";
+export * from "./primitives.js";
+export * from "./wasmAstro.js";

package/src/wasmProp/primitives.js

@@ -0,0 +1,295 @@
+import {
+    twoline2satrec,
+    EciBaseCalculator,
+    GmstCalculator,
+    EcfPositionCalculator,
+    GeodeticPositionCalculator,
+    LookAnglesCalculator,
+} from "satellite.js";
+import {getBulkRuntime, getOrCreateBulkPropagator} from "./runtime.js";
+import {RAD2DEG} from "../constants.js";
+
+// ----------------------------------------------------------------------------
+// WASM-backed bulk primitives
+//
+// Sibling functions to `prop` / `propGeodetic` / the manual LookAngles chain
+// that live in `../astro.js`. The originals stay synchronous; these are
+// async because the per-thread `BulkPropagator` runtime is async-bootstrapped
+// (see `docs/BULK_PROPAGATION.md`).
+//
+// Time-grid semantics are matched exactly to the JS-path siblings to keep
+// parity tests trivial:
+//   - `propBulk`         mirrors `prop`         -> half-open [start, end)
+//   - `propGeodeticBulk` mirrors `propGeodetic` -> closed    [start, end]
+//
+// Return shapes mirror the JS-path siblings element-wise so callers can swap
+// transparently. `meanElements` is intentionally absent from `propBulk`
+// records: the WASM `EciBaseCalculator` exposes only position/velocity/error,
+// it does not surface SGP4 mean elements. Callers that need them must either
+// stay on `prop` or recompute osculating elements from p/v.
+// ----------------------------------------------------------------------------
+
+/**
+ * Builds the closed list of evaluation timestamps for a half-open or closed
+ * interval, matching the loop semantics of `prop` / `propGeodetic`.
+ *
+ * @param {number} start
+ * @param {number} end
+ * @param {number} stepMs
+ * @param {boolean} inclusive when true, end is included (propGeodetic).
+ * @return {number[]}
+ */
+const buildTimeGrid = (start, end, stepMs, inclusive) => {
+    const grid = [];
+    if (inclusive) {
+        for (let t = start; t <= end; t = t + stepMs) {grid.push(t);}
+    } else {
+        for (let t = start; t < end; t = t + stepMs) {grid.push(t);}
+    }
+    return grid;
+};
+
+/**
+ * Bulk-converts an array of `{Line1, Line2}` elsets into satrecs, returning
+ * `null` if any single elset fails to convert. Mirrors the silent-skip
+ * behavior of `prop` (which returns `[]` on the first invalid pv).
+ *
+ * @param {Array<{Line1: string, Line2: string}>} elsets
+ * @return {Array|null}
+ */
+const elsetsToSatrecs = (elsets) => {
+    const satrecs = elsets.map((e) => twoline2satrec(e.Line1, e.Line2));
+    return satrecs;
+};
+
+/**
+ * WASM-backed sibling of `prop`. Computes ECI position and velocity for
+ * `elsets.length` satellites at every step in the half-open interval
+ * `[start, end)` with step `stepMs`.
+ *
+ * Returns `Array<Array<{p, v, t}>>` indexed `[satIdx][dateIdx]`. Each inner
+ * array matches the shape returned by `prop` minus the `meanElements` field
+ * (see module-level note). If the WASM SGP4 produces a non-zero error code
+ * for any (sat, date) pair, that satellite's entire ephemeris is returned as
+ * `[]` — same all-or-nothing semantic as `prop` on `propTo` failure.
+ *
+ * @param {Array<{Line1: string, Line2: string}>} elsets
+ * @param {number} start UNIX milliseconds
+ * @param {number} end UNIX milliseconds (exclusive)
+ * @param {number} stepMs default 1000
+ * @return {Promise<Array<Array<{p: object, v: object, t: number}>>>}
+ */
+const propBulk = async (elsets, start, end, stepMs = 1000) => {
+    const grid = buildTimeGrid(start, end, stepMs, false);
+    if (elsets.length === 0 || grid.length === 0) {
+        return elsets.map(() => []);
+    }
+    const satrecs = elsetsToSatrecs(elsets);
+    const dates = grid.map((t) => new Date(t));
+
+    const runtime = await getBulkRuntime();
+    const propagator = getOrCreateBulkPropagator({
+        runtime,
+        key: "eci",
+        makeCalculators: () => [new EciBaseCalculator()],
+        satRecsCount: satrecs.length,
+        datesCount: dates.length,
+    });
+    propagator.setSatRecs(satrecs);
+    propagator.setDates(dates);
+    propagator.run();
+
+    const {eci} = propagator.getRawOutput();
+    // raw layout: [sat0 date0 (x,y,z), sat0 date1 (x,y,z), ..., sat1 date0, ...]
+    // error layout: [sat0 date0, sat0 date1, ..., sat1 date0, ...]
+    const out = new Array(satrecs.length);
+    const m = dates.length;
+    for (let s = 0; s < satrecs.length; s++) {
+        const ephem = new Array(m);
+        let satFailed = false;
+        for (let d = 0; d < m; d++) {
+            const errIdx = s * m + d;
+            if (eci.error[errIdx] !== 0) {
+                satFailed = true;
+                break;
+            }
+            const vec = (s * m + d) * 3;
+            ephem[d] = {
+                p: {
+                    x: eci.position[vec],
+                    y: eci.position[vec + 1],
+                    z: eci.position[vec + 2],
+                },
+                v: {
+                    x: eci.velocity[vec],
+                    y: eci.velocity[vec + 1],
+                    z: eci.velocity[vec + 2],
+                },
+                t: grid[d],
+            };
+        }
+        out[s] = satFailed ? [] : ephem;
+    }
+    return out;
+};
+
+/**
+ * WASM-backed sibling of `propGeodetic`. Computes geodetic
+ * (lat, lon, t) for every satellite at every step in the closed interval
+ * `[start, end]`.
+ *
+ * Lat/Lon are returned in **degrees** to match `propGeodetic`. Returns
+ * `Array<Array<{lat, lon, t}>>` indexed `[satIdx][dateIdx]`. On any SGP4
+ * error for a satellite the whole ephemeris for that satellite is `[]`,
+ * matching `propGeodetic`'s short-circuit behavior.
+ *
+ * @param {Array<{Line1: string, Line2: string}>} elsets
+ * @param {number} start UNIX milliseconds
+ * @param {number} end UNIX milliseconds (inclusive)
+ * @param {number} stepMs default 60000
+ * @return {Promise<Array<Array<{lat: number, lon: number, t: number}>>>}
+ */
+const propGeodeticBulk = async (elsets, start, end, stepMs = 60000) => {
+    const grid = buildTimeGrid(start, end, stepMs, true);
+    if (elsets.length === 0 || grid.length === 0) {
+        return elsets.map(() => []);
+    }
+    const satrecs = elsetsToSatrecs(elsets);
+    const dates = grid.map((t) => new Date(t));
+
+    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();
+    // KNOWN satellite.js@7.0.0 BUG / docs error: the
+    // `GeodeticPositionCalculator` raw layout is documented as
+    // `[lat, lon, height, ...]`, and `getFormattedOutput()` exposes fields
+    // `{latitude: raw[0], longitude: raw[1], height: raw[2]}` — but the
+    // physical values are SWAPPED. Empirically, against the canonical JS
+    // `eciToGeodetic` path:
+    //   raw[3*k + 0] -> physical LONGITUDE (in radians)
+    //   raw[3*k + 1] -> physical LATITUDE  (in radians)
+    //   raw[3*k + 2] -> height (km)
+    // We map raw -> {lat, lon} accordingly so `propGeodeticBulk` is exactly
+    // value-equivalent to `propGeodetic`. If a future satellite.js release
+    // fixes this upstream, swap the indices back here.
+    const out = new Array(satrecs.length);
+    const m = dates.length;
+    for (let s = 0; s < satrecs.length; s++) {
+        const positions = new Array(m);
+        let satFailed = false;
+        for (let d = 0; d < m; d++) {
+            const errIdx = s * m + d;
+            if (eci.error[errIdx] !== 0) {
+                satFailed = true;
+                break;
+            }
+            const vec = (s * m + d) * 3;
+            positions[d] = {
+                lat: geodeticPosition[vec + 1] * RAD2DEG,
+                lon: geodeticPosition[vec] * RAD2DEG,
+                t: grid[d],
+            };
+        }
+        out[s] = satFailed ? [] : positions;
+    }
+    return out;
+};
+
+/**
+ * WASM-backed bulk look-angles primitive. Computes (azimuth, elevation,
+ * rangeSat) for every satellite at every supplied date relative to a single
+ * observer (Geodetic location, **radians + km** as required by satellite.js
+ * v7 — `{latitude, longitude, height}`).
+ *
+ * Unlike `propBulk` and `propGeodeticBulk` this primitive takes an explicit
+ * `dates` array (rather than start/end/step) because look-angles consumers
+ * typically already hold the date list (e.g. observation timestamps in
+ * `GetResiduals`) and synthesizing a regular grid would re-impose JS-side
+ * step math the WASM pipeline is meant to avoid.
+ *
+ * Returns `Array<Array<{azimuth, elevation, rangeSat, t}>>` indexed
+ * `[satIdx][dateIdx]`, with angles in **radians** and `rangeSat` in km. On
+ * any SGP4 error for a satellite that satellite's entire output is `[]`.
+ *
+ * @param {Array<{Line1: string, Line2: string}>} elsets
+ * @param {Date[]|number[]} dates
+ * @param {{latitude: number, longitude: number, height: number}} observerGd
+ *   Observer position in radians (lat/lon) and km (height).
+ * @return {Promise<Array<Array<{azimuth: number, elevation: number, rangeSat: number, t: number}>>>}
+ */
+const propLookAnglesBulk = async (elsets, dates, observerGd) => {
+    if (elsets.length === 0 || dates.length === 0) {
+        return elsets.map(() => []);
+    }
+    const satrecs = elsetsToSatrecs(elsets);
+    const dateObjs = dates.map((d) => (d instanceof Date ? d : new Date(d)));
+    const ts = dateObjs.map((d) => d.getTime());
+
+    const runtime = await getBulkRuntime();
+    const propagator = getOrCreateBulkPropagator({
+        runtime,
+        key: "eci+gmst+ecf+lookAngles",
+        makeCalculators: () => [
+            new EciBaseCalculator(),
+            new GmstCalculator(),
+            new EcfPositionCalculator(),
+            new LookAnglesCalculator(),
+        ],
+        satRecsCount: satrecs.length,
+        datesCount: dateObjs.length,
+    });
+    propagator.setSatRecs(satrecs);
+    propagator.setDates(dateObjs);
+    propagator.run({lookAngles: {observer: observerGd}});
+
+    const {eci, lookAngles} = propagator.getRawOutput();
+    // lookAngles layout: [sat0 date0 (az, el, range), sat0 date1, ...]
+    const out = new Array(satrecs.length);
+    const m = dateObjs.length;
+    for (let s = 0; s < satrecs.length; s++) {
+        const samples = new Array(m);
+        let satFailed = false;
+        for (let d = 0; d < m; d++) {
+            const errIdx = s * m + d;
+            if (eci.error[errIdx] !== 0) {
+                satFailed = true;
+                break;
+            }
+            const vec = (s * m + d) * 3;
+            samples[d] = {
+                azimuth: lookAngles[vec],
+                elevation: lookAngles[vec + 1],
+                rangeSat: lookAngles[vec + 2],
+                t: ts[d],
+            };
+        }
+        out[s] = satFailed ? [] : samples;
+    }
+    return out;
+};
+
+export {
+    // `buildTimeGrid` is intentionally NOT exported: it is consumed only by
+    // `propBulk` / `propGeodeticBulk` inside this module. Keeping it private
+    // avoids polluting the public `@saber-usa/node-common` surface with a
+    // helper that exists purely to bridge the JS-path loop semantics to the
+    // WASM `setDates(Date[])` API.
+    elsetsToSatrecs, // used by `./wasmAstro.js#getGeoShadowZonesBulk`
+    propBulk,
+    propGeodeticBulk,
+    propLookAnglesBulk,
+};

package/src/wasmProp/runtime.js

@@ -0,0 +1,147 @@
+import {createSingleThreadRuntime, BulkPropagator} from "satellite.js";
+
+// Module-local state. In Node, ES module instances are per Realm/per worker
+// thread, so this state is naturally per-thread when consumed inside
+// `worker_threads` (e.g. node-pub-sub's workerpool workers).
+//
+// See docs/BULK_PROPAGATION.md sections 6, 7, and 8 for the consumer model,
+// lifecycle, and registry design.
+let runtimePromise = null;
+let registry = new Map();
+
+/**
+ * Lazily creates (or returns) the per-thread WASM runtime.
+ *
+ * On first call within a thread, triggers `createSingleThreadRuntime()`
+ * (the v7 successor to the blog's `createWasmModule()`) and caches the
+ * resulting promise. All subsequent callers in that thread reuse it.
+ *
+ * Safe to await concurrently: every caller awaits the same in-flight
+ * promise, so only one WASM compile + instantiate ever happens.
+ *
+ * @return {Promise<import("satellite.js").SingleThreadRuntime>}
+ */
+const getBulkRuntime = () => {
+    if (runtimePromise === null) {
+        runtimePromise = createSingleThreadRuntime();
+    }
+    return runtimePromise;
+};
+
+/**
+ * Eager bootstrap. Equivalent to `await getBulkRuntime()` but named for the
+ * explicit warm-up call site (e.g. top of `dedicated_worker.js`).
+ *
+ * @return {Promise<import("satellite.js").SingleThreadRuntime>}
+ */
+const initBulkRuntime = () => getBulkRuntime();
+
+/**
+ * Returns true if the runtime has been requested in this thread (regardless
+ * of whether it has finished initializing). Used by tests and by the
+ * disposal path to decide whether dispose work is necessary.
+ *
+ * @return {boolean}
+ */
+const isBulkRuntimeInitialized = () => runtimePromise !== null;
+
+/**
+ * Acquires (or lazily constructs) the per-thread, per-pipeline singleton
+ * `BulkPropagator` for the given pipeline key.
+ *
+ * Reuse rules:
+ * - The same instance is returned on every call with the same `key`.
+ * - If the caller's `satRecsCount` or `datesCount` exceed the current
+ *   allocation, the propagator's own `setSatRecs` / `setDates` will perform
+ *   a single `free` + `malloc` grow-realloc internally on the next set.
+ *   The initial allocation here is sized to the first caller's request, so
+ *   "warm" subsequent calls of the same shape pay zero allocation cost.
+ *
+ * Caller responsibilities:
+ * - `setSatRecs`, `setDates`, then `run()` between `acquire` and using
+ *   results. Within a single thread these are synchronous so no other
+ *   pipeline consumer can interleave (per docs/BULK_PROPAGATION.md §9).
+ * - **Do not call `dispose()` on the returned propagator.** Lifecycle is
+ *   owned by the registry; `disposeBulkRuntime()` is the only sanctioned
+ *   teardown path.
+ *
+ * @param {Object} params
+ * @param {import("satellite.js").SingleThreadRuntime} params.runtime
+ * @param {string} params.key Pipeline signature, e.g. `"eci"`.
+ * @param {() => readonly any[]} params.makeCalculators Factory invoked once
+ *   per (key, thread) to build fresh calculator instances. A factory is
+ *   required because calculator instances are stateful and bound to a
+ *   propagator at construction time; they cannot be shared across keys.
+ * @param {number} params.satRecsCount Initial satellite-record allocation
+ *   hint. Used only on first construction for this key in this thread.
+ * @param {number} params.datesCount Initial dates allocation hint. Same
+ *   first-call-only semantics.
+ * @return {import("satellite.js").BulkPropagator<any, any>}
+ */
+const getOrCreateBulkPropagator = ({
+    runtime,
+    key,
+    makeCalculators,
+    satRecsCount,
+    datesCount,
+}) => {
+    const cached = registry.get(key);
+    if (cached) {
+        return cached;
+    }
+
+    const propagator = new BulkPropagator({
+        runtime,
+        calculators: makeCalculators(),
+        satRecsCount: Math.max(1, satRecsCount),
+        datesCount: Math.max(1, datesCount),
+    });
+    registry.set(key, propagator);
+    return propagator;
+};
+
+/**
+ * Releases all WASM memory owned by this thread: every registry-held
+ * `BulkPropagator` is disposed and the runtime itself is torn down.
+ *
+ * Idempotent: safe to call when nothing was ever initialized. After this
+ * returns, the next `getBulkRuntime()` will lazily re-initialize from
+ * scratch.
+ */
+const disposeBulkRuntime = async () => {
+    for (const propagator of registry.values()) {
+        try {
+            propagator.dispose();
+        } catch (e) {
+            // Disposal must never throw out of teardown; we surface the
+            // failure to stderr but continue cleaning up the rest of the
+            // registry to minimize the leak surface.
+            console.error("disposeBulkRuntime: failed to dispose propagator", e);
+        }
+    }
+    registry = new Map();
+
+    if (runtimePromise !== null) {
+        const pending = runtimePromise;
+        runtimePromise = null;
+        try {
+            const runtime = await pending;
+            runtime.dispose();
+        } catch (e) {
+            // Emscripten's `_exit_runtime` (with EXIT_RUNTIME=1) signals clean
+            // shutdown by throwing an `ExitStatus` object with `status === 0`.
+            // That is the documented success path, not a failure to log.
+            if (e?.name !== "ExitStatus" || e?.status !== 0) {
+                console.error("disposeBulkRuntime: failed to dispose runtime", e);
+            }
+        }
+    }
+};
+
+export {
+    getBulkRuntime,
+    initBulkRuntime,
+    isBulkRuntimeInitialized,
+    getOrCreateBulkPropagator,
+    disposeBulkRuntime,
+};