@neilberkman/sidereon 1.0.1 → 1.1.0

package/pkg-node/sidereon.d.ts

@@ -6,6 +6,102 @@ export type Vec3 = [number, number, number] | Float64Array;
 export type Vec4 = [number, number, number, number] | Float64Array;
 export type Matrix3 = number[] | Float64Array;
 
+export interface SourceSensor {
+    /** Sensor position in a caller-chosen 2D or 3D Cartesian frame, in metres. */
+    positionM: number[] | Float64Array;
+    /** Optional propagation-speed override for this sensor, in metres per second. */
+    propagationSpeedMS?: number;
+}
+
+export type SourceLocateMode = "toa" | "ToA" | "TOA" | "tdoa" | "TDOA";
+
+export interface SourceSolveModeObject {
+    mode?: SourceLocateMode;
+    referenceSensor?: number;
+}
+
+export type SourceSolveMode = SourceLocateMode | SourceSolveModeObject;
+
+export interface SourceLocateOptions {
+    mode?: SourceLocateMode;
+    /** Reference sensor index for TDOA mode; defaults to zero. */
+    referenceSensor?: number;
+    /** Timing standard deviation used for covariance, CRLB, and influence scores. */
+    timingSigmaS?: number;
+    /**
+     * Whether to compute per-sensor leave-one-out influence diagnostics.
+     * Defaults to true. Set to false to skip one nonlinear re-solve per sensor;
+     * perSensorInfluence is then empty and every other output is bit-identical.
+     */
+    includeInfluence?: boolean;
+    loss?: "linear" | "softL1" | "soft_l1" | "huber" | "cauchy" | "arctan";
+    fScaleS?: number;
+    ftol?: number;
+    xtol?: number;
+    gtol?: number;
+    maxNfev?: number;
+}
+
+export interface SourceInitialGuess {
+    positionM: number[];
+    originTimeS: number | null;
+    residualRmsS: number;
+}
+
+export interface SourceResidual {
+    sensorIndex: number;
+    referenceSensorIndex: number | null;
+    residualS: number;
+}
+
+export interface SourceSensorInfluence {
+    sensorIndex: number;
+    residualS: number;
+    leaveOneOutResidualS: number | null;
+    positionDeltaM: number | null;
+    originTimeDeltaS: number | null;
+    /** First-derivative robust-loss weight for the full-solution residual. */
+    lossWeight: number;
+    /**
+     * max(abs(residualS), abs(leaveOneOutResidualS)) / timingSigmaS, or
+     * abs(residualS) / timingSigmaS when the leave-one-out solve is unavailable.
+     * Robust-loss downweighting is reported separately in lossWeight.
+     */
+    score: number;
+}
+
+export interface SourceCovariance {
+    state: number[][];
+    positionM2: number[][];
+    originTimeS2: number | null;
+    timingSigmaS: number;
+}
+
+export interface SourceGeometryQuality {
+    tier: "RankDeficient" | "ZeroRedundancy" | "Weak" | "Nominal";
+    redundancy: number;
+    rank: number;
+    conditionNumber: number;
+    gdop: number;
+    raimCheckable: boolean;
+    covarianceValidated: boolean;
+}
+
+export interface SourceSolution {
+    positionM: number[];
+    originTimeS: number | null;
+    covariance: SourceCovariance | null;
+    residuals: SourceResidual[];
+    perSensorInfluence: SourceSensorInfluence[];
+    geometryQuality: SourceGeometryQuality;
+    initialGuess: SourceInitialGuess;
+    status: number;
+    nfev: number;
+    njev: number;
+    cost: number;
+    optimality: number;
+}
+
 export interface ExactProductIdentityInput {
     family: "sp3" | "ionex" | "clk" | "nav";
     analysisCenter: string;
@@ -9417,13 +9513,11 @@ export function cfarCaPfaFromMultiplier(searched_cells: number, multiplier: numb
 export function cfarCaThreshold(searched_cells: number, false_alarm_probability: number, noise_level: number): number;
 
 /**
- * Compute the closed-form Chan-Ho seed used by [`locateSource`].
+ * Deprecated alias for [`closed_form_initial_guess`].
  *
- * `mode` is `"toa"`, `"tdoa"`, or `{ mode: "tdoa", referenceSensor }`.
- * Per-sensor speed overrides are not used by the closed-form equations, but
- * they are used by [`locateSource`] during iterative refinement.
+ * @deprecated Use `closedFormInitialGuess` instead.
  */
-export function chanHoInitialGuess(sensors: any, arrival_times_s: any, propagation_speed_m_s: number, mode: any): any;
+export function chanHoInitialGuess(sensors: SourceSensor[], arrivalTimesS: number[] | Float64Array, propagationSpeedMS: number, mode: SourceSolveMode): SourceInitialGuess;
 
 /**
  * Returns `true` when a diff has any findings.
@@ -9435,6 +9529,15 @@ export function changed(diff: any): boolean;
  */
 export function civilToJ2000Seconds(year: number, month: number, day: number, hour: number, minute: number, second: number): number;
 
+/**
+ * Compute the closed-form spherical-intersection seed used by [`locateSource`].
+ *
+ * `mode` is `"toa"`, `"tdoa"`, or `{ mode: "tdoa", referenceSensor }`.
+ * Per-sensor speed overrides are not used by the closed-form equations, but
+ * they are used by [`locateSource`] during iterative refinement.
+ */
+export function closedFormInitialGuess(sensors: SourceSensor[], arrivalTimesS: number[] | Float64Array, propagationSpeedMS: number, mode: SourceSolveMode): SourceInitialGuess;
+
 /**
  * Carrier-to-noise-density ratio, dB-Hz. `otherLossesDb` defaults to 0.
  */
@@ -10759,9 +10862,12 @@ export function loadSp3(bytes: Uint8Array): Sp3;
  * the same dimension. `arrivalTimesS` is an aligned seconds array,
  * `propagationSpeedMS` is the call-level speed in metres per second, and
  * `options` may include `mode`, `referenceSensor`, `timingSigmaS`, `loss`,
- * `fScaleS`, `ftol`, `xtol`, `gtol`, and `maxNfev`.
+ * `fScaleS`, `ftol`, `xtol`, `gtol`, `maxNfev`, and `includeInfluence`.
+ * `includeInfluence` defaults to `true`; set it to `false` to skip the
+ * per-sensor leave-one-out re-solves and return an empty `perSensorInfluence`
+ * array without changing any other output.
  */
-export function locateSource(sensors: any, arrival_times_s: any, propagation_speed_m_s: number, options: any): any;
+export function locateSource(sensors: SourceSensor[], arrivalTimesS: number[] | Float64Array, propagationSpeedMS: number, options?: SourceLocateOptions | null): SourceSolution;
 
 export function lunarSolarEclipses(start_unix_us: bigint, end_unix_us: bigint, step_s: number, tolerance_s: number): any;
 
@@ -12098,12 +12204,12 @@ export function sourceDop(sensors: any, source_position_m: any, propagation_spee
 /**
  * Return the plain mode object for TDOA solves against `referenceSensor`.
  */
-export function sourceSolveModeTdoa(reference_sensor: number): any;
+export function sourceSolveModeTdoa(referenceSensor: number): { mode: "tdoa"; referenceSensor: number };
 
 /**
  * Return the plain mode value for absolute time-of-arrival solves.
  */
-export function sourceSolveModeToa(): string;
+export function sourceSolveModeToa(): "toa";
 
 /**
  * Return the cataloged relationship between an SP3 filename epoch and its

package/pkg-node/sidereon.js

@@ -22783,11 +22783,9 @@ function cfarCaThreshold(searched_cells, false_alarm_probability, noise_level) {
 exports.cfarCaThreshold = cfarCaThreshold;
 
 /**
- * Compute the closed-form Chan-Ho seed used by [`locateSource`].
+ * Deprecated alias for [`closed_form_initial_guess`].
  *
- * `mode` is `"toa"`, `"tdoa"`, or `{ mode: "tdoa", referenceSensor }`.
- * Per-sensor speed overrides are not used by the closed-form equations, but
- * they are used by [`locateSource`] during iterative refinement.
+ * @deprecated Use `closedFormInitialGuess` instead.
  * @param {any} sensors
  * @param {any} arrival_times_s
  * @param {number} propagation_speed_m_s
@@ -22833,6 +22831,27 @@ function civilToJ2000Seconds(year, month, day, hour, minute, second) {
 }
 exports.civilToJ2000Seconds = civilToJ2000Seconds;
 
+/**
+ * Compute the closed-form spherical-intersection seed used by [`locateSource`].
+ *
+ * `mode` is `"toa"`, `"tdoa"`, or `{ mode: "tdoa", referenceSensor }`.
+ * Per-sensor speed overrides are not used by the closed-form equations, but
+ * they are used by [`locateSource`] during iterative refinement.
+ * @param {any} sensors
+ * @param {any} arrival_times_s
+ * @param {number} propagation_speed_m_s
+ * @param {any} mode
+ * @returns {any}
+ */
+function closedFormInitialGuess(sensors, arrival_times_s, propagation_speed_m_s, mode) {
+    const ret = wasm.closedFormInitialGuess(sensors, arrival_times_s, propagation_speed_m_s, mode);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.closedFormInitialGuess = closedFormInitialGuess;
+
 /**
  * Carrier-to-noise-density ratio, dB-Hz. `otherLossesDb` defaults to 0.
  * @param {number} eirp_dbw
@@ -26487,7 +26506,10 @@ exports.loadSp3 = loadSp3;
  * the same dimension. `arrivalTimesS` is an aligned seconds array,
  * `propagationSpeedMS` is the call-level speed in metres per second, and
  * `options` may include `mode`, `referenceSensor`, `timingSigmaS`, `loss`,
- * `fScaleS`, `ftol`, `xtol`, `gtol`, and `maxNfev`.
+ * `fScaleS`, `ftol`, `xtol`, `gtol`, `maxNfev`, and `includeInfluence`.
+ * `includeInfluence` defaults to `true`; set it to `false` to skip the
+ * per-sensor leave-one-out re-solves and return an empty `perSensorInfluence`
+ * array without changing any other output.
  * @param {any} sensors
  * @param {any} arrival_times_s
  * @param {number} propagation_speed_m_s