@danielsimonjr/mathts-matrix 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -1216,6 +1216,13 @@ declare class WASMBackend implements MatrixBackend {
      * tests and multiple backend instances can coexist in the same process.
      */
     private loadAsModule;
+    /**
+     * WASM is only worth its copy/alloc overhead for compute-dense ops. The 2026-07-01
+     * backend audit (`tools/benchmarks/backend-audit`) measured element-wise / transpose
+     * ops 4–6× SLOWER on WASM than JS (memory-bound; the SIMD matmul kernel is the only
+     * clear win, 9–12×). So WASM is reserved for `opKind: 'matmul'`; everything else stays
+     * on JS via each method's existing `jsBackend` fallback.
+     */
     private shouldUseWasm;
     getFeatures(): WasmFeatures | null;
     add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
@@ -2513,62 +2520,34 @@ declare function norm2(matrix: number[][], options?: SVDOptions): number;
 declare function normFro(matrix: number[][]): number;
 
 /**
- * WASM-accelerated Eigendecomposition
- *
- * Provides eigenvalue/eigenvector computation with optional WASM acceleration
- * via the AssemblyScript-compiled Jacobi eigenvalue algorithm. Falls back to the pure
- * JavaScript QR-based implementation when WASM is unavailable.
+ * `eigWasm` / `eigvalsWasm` / `spectralRadiusWasm` — thin wrappers kept for API
+ * compatibility (consumed by `tensor` and `linalg`).
  *
- * WASM acceleration path:
- *   - Symmetric matrices: Jacobi eigenvalue algorithm (AssemblyScript
- *     `matrix_eig_symmetric`, `assembly/src/ops/eig.ts`)
- *   - Non-symmetric matrices: Hessenberg reduction + Francis double-shift
- *     implicit QR to the real Schur form, with eigenvector back-substitution
- *     (AssemblyScript `matrix_eig_general`, `assembly/src/ops/eig.ts`)
- *
- * JS fallback path (wasm unavailable, n < threshold, or missing export):
- *   - Full QR algorithm with implicit shifts (eig.ts)
- *
- * Packing of the AS return values (both decoded via `readReturnedFloat64Array`):
- *   - matrix_eig_symmetric: `[ eigenvalues(n) | eigenvectors(n*n) ]`
- *   - matrix_eig_general:   `[ re(n) | im(n) | eigenvectors(n*n) ]`
- * Eigenvectors are stored as COLUMNS (`V[i*n+j]` = component `i` of
- * eigenvector `j`). Complex-eigenvalue columns are zero (the real `number[][]`
- * vector contract cannot represent complex eigenvectors).
+ * The WASM eig path was RETIRED and REMOVED (2026-07-01): the AssemblyScript Jacobi
+ * (symmetric) / Hessenberg+Francis (general) kernels were scalar + async and measured
+ * 0.2–0.7× of the pure-JS path, worsening with size (~5× slower at 128²) — see
+ * `tools/benchmarks/decomp-audit`. Since a genuinely fast version would be a from-scratch
+ * SIMD implementation (not the removed scalar code), these now simply delegate to the
+ * synchronous JS `eig` / `eigvals` / `powerIteration`. The `async` signature is retained so
+ * existing callers (which `await`) are unaffected.
  *
  * @packageDocumentation
  */
 
 /**
- * WASM-accelerated eigendecomposition for symmetric matrices.
- *
- * Uses the AssemblyScript Jacobi eigenvalue algorithm when WASM is loaded,
- * otherwise falls back to the JavaScript QR algorithm.
- *
- * @param matrix - Square matrix as 2D array
- * @param options - Computation options
- * @returns Eigenvalues and eigenvectors
+ * Eigendecomposition. Delegates to the JS {@link eig} (WASM path retired — see file header).
  */
 declare function eigWasm(matrix: number[][], options?: EigOptions): Promise<EigResult>;
 /**
- * WASM-accelerated eigenvalues only (no eigenvectors).
- * Faster than full eigWasm when only eigenvalues are needed.
- *
- * @param matrix - Square matrix as 2D array
- * @param options - Computation options (computeVectors is ignored)
- * @returns Array of eigenvalues
+ * Eigenvalues only. Delegates to the JS {@link eigvals} (WASM path retired).
  */
 declare function eigvalsWasm(matrix: number[][], options?: Omit<EigOptions, 'computeVectors'>): Promise<Array<{
     re: number;
     im: number;
 }>>;
 /**
- * WASM-accelerated spectral radius.
- * Uses AssemblyScript power iteration when WASM is available.
- *
- * @param matrix - Square matrix as 2D array
- * @param options - Iteration options
- * @returns Spectral radius (absolute value of largest eigenvalue)
+ * Spectral radius (|largest eigenvalue|). Delegates to the JS {@link powerIteration}
+ * (WASM path retired).
  */
 declare function spectralRadiusWasm(matrix: number[][], options?: {
     maxIterations?: number;
@@ -2576,26 +2555,21 @@ declare function spectralRadiusWasm(matrix: number[][], options?: {
 }): Promise<number>;
 
 /**
- * WASM-accelerated Singular Value Decomposition.
- *
- * Routes through the AssemblyScript binary's one-sided Jacobi SVD
- * (`matrix_svd` export, `assembly/src/ops/svd.ts`) for any real `m x n`
- * matrix, and falls back to the synchronous JavaScript Golub-Reinsch
- * {@link svd} when the WASM module is unavailable. (Phase 7b: repointed onto
- * the AssemblyScript binary; singular values are bit-identical to the JS
- * reference per the 7a parity validation.)
+ * `svdWasm` — thin wrapper kept for API compatibility (consumed by `tensor` and `linalg`).
  *
- * Unlike the synchronous {@link svd} (which returns the *full* `m x m` /
- * `n x n` factors), `svdWasm` always returns the **thin / economy** form —
- * `U` is `m x k`, `V` is `n x k`, `k = min(m, n)` — on both the WASM and the
- * fallback path, so callers get a stable result shape.
+ * The WASM SVD path was RETIRED and REMOVED (2026-07-01): the AssemblyScript one-sided
+ * Jacobi kernel was scalar + async and measured 0.4–0.7× of the pure-JS Golub-Reinsch
+ * {@link svd}, worsening with size — see `tools/benchmarks/decomp-audit`. It now delegates
+ * to the JS `svd`, truncated to the **thin / economy** form (`U` is `m×k`, `V` is `n×k`,
+ * `k = min(m, n)`) so the result shape is unchanged. The `async` signature is retained so
+ * existing callers (which `await`) are unaffected.
  *
  * @packageDocumentation
  */
 
 /**
- * WASM-accelerated thin SVD. Always safe to call — falls back to the
- * synchronous JS SVD when the AssemblyScript WASM module is not available.
+ * Thin SVD. Delegates to the JS {@link svd} and truncates to the economy form
+ * (WASM path retired — see file header).
  *
  * @param matrix - Input matrix (m x n) as a row-major 2D array
  * @param options - SVD options; `rankTolerance` controls the rank estimate