gnss-js 1.23.0 → 1.24.0

package/dist/positioning.d.ts

@@ -54,7 +54,29 @@ declare function klobucharDelay(coeffs: KlobucharCoeffs, latRad: number, lonRad:
  *   (LAMBDA) needs the joint float ambiguity covariance — which the
  *   EKF maintains natively. This mirrors RTKLIB's float-filter
  *   structure (rtkpos.c), which the implementation was validated
- *   against; no integer fixing is attempted (`ratio` is reserved).
+ *   against.
+ *
+ * Stage 2 — integer ambiguity resolution (opt-in via
+ * `ambiguityResolution: 'instant'`): after each float update the
+ * engine extracts the DD ambiguity subvector and its joint covariance
+ * from the filter, runs MLAMBDA (`lambdaSearch`, a port of RTKLIB's
+ * lambda.c) and validates the best candidate with the ratio test
+ * (s₂/s₁ ≥ `ratioThreshold`, default 3.0 — RTKLIB's default). On
+ * acceptance the rover position is conditioned on the integer
+ * ambiguities (xa = x − P_xb·Q_b⁻¹·(b − ǎ), RTKLIB rtkpos.c
+ * `resamb_LAMBDA`) and reported as a FIXED solution; the filter state
+ * itself is *not* modified (instant, per-epoch fixing — RTKLIB's
+ * `armode=instantaneous`; continuous AR/fix-and-hold, which feed the
+ * fix back into the filter, are stage-3 continuity options). When the
+ * full set fails the ratio test, partial fixing retries after
+ * dropping the lowest-elevation ambiguity, one at a time, down to
+ * half the candidate set (and never below `minFixAmbiguities`) — an
+ * elevation-ordered subset walk in the spirit of RTKLIB demo5's
+ * satellite exclusion, floored so an unconverged float cannot buy a
+ * lucky ratio on a tiny subset. GLONASS ambiguities are excluded from
+ * fixing by
+ * default (DD IFB is only integer-safe across same-model receivers;
+ * enable with `glonassAr`).
  *
  * Differencing model: for satellites s and reference r observed by
  * rover R and base B, the DD pseudorange/phase cancels satellite
@@ -208,18 +230,65 @@ interface RtkFloatOptions {
     slipGateM?: number;
     /** Measurement-update relinearisations (IEKF). Default 2. */
     updateIterations?: number;
+    /**
+     * Integer ambiguity resolution: 'off' keeps the stage-1 float-only
+     * behaviour; 'instant' attempts a per-epoch LAMBDA fix after each
+     * float update (no state feedback — RTKLIB `armode=instantaneous`).
+     * Default 'off'.
+     */
+    ambiguityResolution?: 'off' | 'instant';
+    /** Ratio-test acceptance threshold (s₂/s₁). Default 3.0 (RTKLIB). */
+    ratioThreshold?: number;
+    /**
+     * Additional elevation mask (deg) for ambiguities entering the fix
+     * (RTKLIB `elmaskar`); 0 = use every measured ambiguity. Default 0.
+     */
+    arElevationMaskDeg?: number;
+    /**
+     * Include GLONASS FDMA ambiguities in the integer fix. Only sound
+     * across same-model receivers (differential IFB). Default false.
+     */
+    glonassAr?: boolean;
+    /**
+     * Partial fixing: when the full ambiguity set fails the ratio test,
+     * drop the lowest-elevation ambiguity and retry (elevation-ordered
+     * subset walk), never below half the candidates. Default true.
+     */
+    partialFixing?: boolean;
+    /** Minimum DD ambiguities to attempt/accept a fix. Default 4. */
+    minFixAmbiguities?: number;
 }
 interface RtkFloatSolution {
     /** Epoch, GPS-scale milliseconds. */
     timeMs: number;
-    /** Rover position, ECEF metres. */
+    /**
+     * Rover position, ECEF metres — the ambiguity-fixed position when
+     * `status === 'fixed'`, the float filter position otherwise.
+     */
     position: [number, number, number];
-    /** Float baseline rover − base, ECEF metres. */
+    /** Float baseline rover − base, ECEF metres (always the float). */
     floatBaseline: [number, number, number];
+    /**
+     * Solution quality: 'fixed' when LAMBDA passed the ratio test,
+     * 'float' when carrier ambiguities contributed but no (accepted)
+     * fix, 'dgnss' when the epoch was updated from code DDs only.
+     */
+    status: 'fixed' | 'float' | 'dgnss';
     /** Satellites contributing DD rows this epoch (incl. references). */
     nSats: number;
-    /** Ambiguity-validation ratio — undefined at stage 1 (no LAMBDA). */
+    /**
+     * Ambiguity-validation ratio (s₂/s₁ of the LAMBDA candidates,
+     * capped at 999.9 as RTKLIB): the accepted subset's ratio when
+     * fixed, the full-set ratio otherwise. Undefined when no fix was
+     * attempted (`ambiguityResolution: 'off'` or no eligible set).
+     */
     ratio?: number;
+    /** Number of integer-fixed DD ambiguities (when `status==='fixed'`). */
+    nFixed?: number;
+    /** Fixed baseline rover − base, ECEF metres (when fixed). */
+    fixedBaseline?: [number, number, number];
+    /** Integer DD ambiguity (cycles) per fixed PRN (when fixed). */
+    fixedAmbiguities?: Record<string, number>;
     /** Formal position sigmas (filter covariance), ECEF metres. */
     sigmas: [number, number, number];
     /** Float DD ambiguity (cycles) per non-reference PRN. */
@@ -262,6 +331,17 @@ declare class RtkFloatEngine {
      * transform of state and covariance (P' = T P Tᵀ).
      */
     private retarget;
+    /**
+     * Try to fix the ambiguity subset `idxs` (indices into `this.amb`):
+     * extract the float subvector b and covariance Q_b from the filter,
+     * run MLAMBDA and, without touching the filter state, condition the
+     * position on the best integer candidate,
+     *   xa = x − P_xb·Q_b⁻¹·(b − ǎ)
+     * (RTKLIB rtkpos.c `resamb_LAMBDA`). Returns null when Q_b is not
+     * positive definite / invertible or the search fails; ratio
+     * validation is the caller's job.
+     */
+    private tryFix;
     /**
      * Process one synchronized epoch (same nominal `timeMs` for both
      * receivers). Returns null until a first position can be
@@ -271,6 +351,88 @@ declare class RtkFloatEngine {
     process(rover: RtkEpochMeasurements, base: RtkEpochMeasurements, timeMs: number): RtkFloatSolution | null;
 }
 
+/**
+ * Integer ambiguity resolution: LAMBDA decorrelation + MLAMBDA
+ * integer least-squares search.
+ *
+ * Port of RTKLIB's `lambda.c` (demo5 / rtklibexplorer fork,
+ * src/lambda.c, Copyright (c) 2007-2008 T. Takasu, BSD-2-Clause),
+ * cross-checked against the reference papers where the C comments are
+ * thin:
+ *
+ * - [1] P.J.G. Teunissen, "The least-squares ambiguity decorrelation
+ *   adjustment: a method for fast GPS ambiguity estimation",
+ *   J. Geodesy 70, 65-82, 1995.
+ * - [2] X.-W. Chang, X. Yang, T. Zhou, "MLAMBDA: A modified LAMBDA
+ *   method for integer least-squares estimation", J. Geodesy 79,
+ *   552-565, 2005.
+ *
+ * Pipeline (identical to RTKLIB's `lambda()`):
+ * 1. LᵀDL factorization of the float covariance, Q = Lᵀ·diag(D)·L
+ *    with L unit lower triangular (RTKLIB's `LD`).
+ * 2. LAMBDA reduction [1]: integer Gauss transformations interleaved
+ *    with symmetric permutations until the transformed D is
+ *    (approximately) descending — producing a unimodular Z with
+ *    Qz = ZᵀQZ = Lᵀ·diag(D)·L far better conditioned than Q.
+ * 3. MLAMBDA search [2] in the decorrelated space: depth-first
+ *    enumeration over a shrinking ellipsoid, keeping the `m` smallest
+ *    residual quadratic forms (z−ž)ᵀQz⁻¹(z−ž).
+ * 4. Back-transform the candidates to the original space, a = Z⁻ᵀ·ž
+ *    (RTKLIB solves ZᵀF = E; Z is unimodular so F is exactly integer).
+ *
+ * Deviations from lambda.c:
+ * - matrices are `Float64Array` in the same column-major layout, with
+ *   allocation-failure paths dropped (JS throws instead),
+ * - failures (non-positive-definite Q, search loop overflow) return
+ *   `null` instead of a status code + stderr message,
+ * - back-transformed candidates are rounded to the nearest integer:
+ *   F = Z⁻ᵀ·ž is exactly integer in ℤ arithmetic and the rounding only
+ *   removes the ~1e-12 fuzz of the floating-point triangular solve,
+ * - the ratio s₂/s₁ used by the RTKLIB caller (`rtkpos.c`) is returned
+ *   alongside the candidates (∞ when s₁ = 0, i.e. noise-free input).
+ */
+/** Result of an integer least-squares search. */
+interface LambdaResult {
+    /**
+     * The `m` best integer candidate vectors (length n each), sorted by
+     * ascending residual quadratic form; `candidates[0]` is the integer
+     * least-squares minimizer.
+     */
+    candidates: Float64Array[];
+    /**
+     * Residual quadratic forms sᵢ = (a−ǎᵢ)ᵀQ⁻¹(a−ǎᵢ) matching
+     * `candidates`, ascending.
+     */
+    residuals: Float64Array;
+    /**
+     * Ratio-test statistic s₂/s₁ (second-best over best); `Infinity`
+     * when the best residual is exactly 0 (noise-free input). Callers
+     * typically cap it (RTKLIB uses 999.9) before thresholding.
+     */
+    ratio: number;
+}
+/**
+ * LAMBDA/MLAMBDA integer least-squares estimation (RTKLIB `lambda`):
+ * decorrelate the float ambiguities, search the `m` best integer
+ * vectors and back-transform them to the original space.
+ *
+ * @param a Float ambiguities (length ≥ n).
+ * @param Q Their covariance, n×n (symmetric — row/column-major agree).
+ * @param n Number of ambiguities.
+ * @param m Number of candidates to return (default 2: best +
+ *   second-best, what the ratio test needs).
+ * @returns Candidates + residuals + ratio, or null when Q is not
+ *   positive definite or the search does not terminate.
+ */
+declare function lambdaSearch(a: Float64Array, Q: Float64Array, n: number, m?: number): LambdaResult | null;
+/**
+ * LAMBDA reduction only (RTKLIB `lambda_reduction`): the unimodular
+ * decorrelation matrix Z (n×n, column-major) such that Qz = ZᵀQZ is
+ * (near-)diagonally dominant. Exposed for diagnostics/tests; returns
+ * null when Q is not positive definite.
+ */
+declare function lambdaReduction(Q: Float64Array, n: number): Float64Array | null;
+
 /**
  * Single-point positioning (SPP) from pseudoranges and broadcast
  * ephemerides.
@@ -351,4 +513,4 @@ declare function ionoFree(p1: number, p2: number, f1: number, f2: number): numbe
  */
 declare function solveSpp(pseudoranges: Map<string, number>, ephemerides: Map<string, Ephemeris>, timeMs: number, opts?: SppOptions): SppSolution | null;
 
-export { type DgnssOptions, type DgnssSolution, type EphemerisSource, type KlobucharCoeffs, type RawObservation, type RtkEpochMeasurements, RtkFloatEngine, type RtkFloatOptions, type RtkFloatSolution, type RtkMeasurement, type SppOptions, type SppSolution, ionoFree, klobucharDelay, satClockCorrection, solveDgnss, solveSpp, toRtkEpoch };
+export { type DgnssOptions, type DgnssSolution, type EphemerisSource, type KlobucharCoeffs, type LambdaResult, type RawObservation, type RtkEpochMeasurements, RtkFloatEngine, type RtkFloatOptions, type RtkFloatSolution, type RtkMeasurement, type SppOptions, type SppSolution, ionoFree, klobucharDelay, lambdaReduction, lambdaSearch, satClockCorrection, solveDgnss, solveSpp, toRtkEpoch };

package/dist/positioning.js

@@ -2,11 +2,13 @@ import {
   RtkFloatEngine,
   ionoFree,
   klobucharDelay,
+  lambdaReduction,
+  lambdaSearch,
   satClockCorrection,
   solveDgnss,
   solveSpp,
   toRtkEpoch
-} from "./chunk-CUWF56ST.js";
+} from "./chunk-T2ZMNRCY.js";
 import "./chunk-MHGNKSSH.js";
 import "./chunk-37QNKGTC.js";
 import "./chunk-6FAL6P4G.js";
@@ -17,6 +19,8 @@ export {
   RtkFloatEngine,
   ionoFree,
   klobucharDelay,
+  lambdaReduction,
+  lambdaSearch,
   satClockCorrection,
   solveDgnss,
   solveSpp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnss-js",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Comprehensive GNSS library for JavaScript — time scales, coordinates, RINEX parsing, RTCM3 decoding, orbit computation, and signal analysis",
   "type": "module",
   "sideEffects": false,