ml-matrix 6.12.2 → 6.13.0

package/matrix.d.ts

@@ -616,6 +616,26 @@ export abstract class AbstractMatrix {
    */
   mmul(other: MaybeMatrix): Matrix;
 
+  /**
+   * Returns the Gram matrix `thisᵀ · this` (the `columns × columns` matrix of
+   * the dot products of every pair of columns). The result is symmetric, so only
+   * its upper triangle is computed and mirrored, and the transpose is never
+   * materialized, making it about twice as fast as `this.transpose().mmul(this)`
+   * on dense matrices and much faster on sparse ones (zero entries are skipped).
+   * For finite inputs the result is identical to `this.transpose().mmul(this)`.
+   */
+  gram(): Matrix;
+
+  /**
+   * Returns the matrix product between `this` and its transpose (`this · thisᵀ`),
+   * optionally weighting each column by `scale` (`this · diag(scale) · thisᵀ`).
+   * The result is symmetric, so only its upper triangle is computed and mirrored
+   * and the transpose is never materialized, making it about twice as fast as
+   * `this.mmul(this.transpose())`.
+   * @param scale - Optional per-column factors (length equal to the number of columns).
+   */
+  mmulByTranspose(scale?: ArrayLike<number>): Matrix;
+
   /**
    * Returns the square matrix raised to the given power
    * @param scalar - the non-negative integer power to raise this matrix to
@@ -860,7 +880,7 @@ export abstract class AbstractMatrix {
     [row: number, column: number, value: number],
     void,
     void
-    >;
+  >;
 
   /**
    * iterator from left to right, from top to bottom
@@ -1489,7 +1509,7 @@ export { EigenvalueDecomposition as EVD };
  * The Cholesky decomposition of a matrix. Given a matrix A, the Cholesky Decomposition of A is L
  * such that A = (L)(L.transpose).
  * Only works for symmetric, positive definite matrix A.
- * 
+ *
  * @link https://github.com/lutzroeder/Mapack/blob/master/Source/CholeskyDecomposition.cs
  */
 export class CholeskyDecomposition {

package/matrix.js

@@ -2216,6 +2216,78 @@ class AbstractMatrix {
     return result;
   }
 
+  gram() {
+    const rows = this.rows;
+    const n = this.columns;
+
+    // The Gram matrix `thisᵀ · this` is symmetric, so only its upper triangle is
+    // accumulated (then mirrored) and the transpose is never materialized.
+    // Row-streaming rank-1 updates read each row of `this` contiguously and skip
+    // zero entries, so the cost scales with the number of non-zeros: it is as
+    // fast as the dense version on dense matrices (the skip never fires) and far
+    // faster on sparse ones.
+    const gramData = new Float64Array(n * n);
+    for (let r = 0; r < rows; r++) {
+      for (let i = 0; i < n; i++) {
+        const value = this.get(r, i);
+        if (value === 0) continue;
+        const offset = i * n;
+        for (let j = i; j < n; j++) {
+          gramData[offset + j] += value * this.get(r, j);
+        }
+      }
+    }
+
+    const result = new Matrix(n, n);
+    for (let i = 0; i < n; i++) {
+      const offset = i * n;
+      for (let j = i; j < n; j++) {
+        const value = gramData[offset + j];
+        result.set(i, j, value);
+        result.set(j, i, value);
+      }
+    }
+    return result;
+  }
+
+  mmulByTranspose(scale) {
+    let m = this.rows;
+    let n = this.columns;
+
+    if (scale !== undefined && scale.length !== n) {
+      throw new RangeError('scale must have one value per column');
+    }
+
+    let result = new Matrix(m, m);
+
+    // result = this · diag(scale) · thisᵀ is symmetric, so only the upper
+    // triangle is computed and mirrored, and the transpose is never
+    // materialized. `scale` (one factor per column) is folded into one operand.
+    let rowj = new Float64Array(n);
+    for (let j = 0; j < m; j++) {
+      if (scale === undefined) {
+        for (let k = 0; k < n; k++) {
+          rowj[k] = this.get(j, k);
+        }
+      } else {
+        for (let k = 0; k < n; k++) {
+          rowj[k] = scale[k] * this.get(j, k);
+        }
+      }
+
+      for (let i = j; i < m; i++) {
+        let s = 0;
+        for (let k = 0; k < n; k++) {
+          s += this.get(i, k) * rowj[k];
+        }
+
+        result.set(i, j, s);
+        result.set(j, i, s);
+      }
+    }
+    return result;
+  }
+
   mpow(scalar) {
     if (!this.isSquare()) {
       throw new RangeError('Matrix must be square');
@@ -3851,6 +3923,27 @@ class LuDecomposition {
   }
 }
 
+/**
+ * Transpose a square matrix in place, without allocating a copy.
+ * Used to restore the logical layout of decomposition outputs that were
+ * accumulated in transposed storage for cache-sequential inner loops.
+ * @param {import('../matrix').default} matrix - square matrix, mutated in place
+ * @returns {import('../matrix').default} the same matrix
+ */
+function transposeSquareInPlace(matrix) {
+  const data = matrix.data;
+  const n = matrix.rows;
+  for (let i = 0; i < n; i++) {
+    const rowI = data[i];
+    for (let j = i + 1; j < n; j++) {
+      const tmp = rowI[j];
+      rowI[j] = data[j][i];
+      data[j][i] = tmp;
+    }
+  }
+  return matrix;
+}
+
 function hypotenuse(a, b) {
   let r = 0;
   if (Math.abs(a) > Math.abs(b)) {
@@ -4029,32 +4122,40 @@ class SingularValueDecomposition {
     let wantu = Boolean(computeLeftSingularVectors);
     let wantv = Boolean(computeRightSingularVectors);
 
+    // Work on the transpose of the input so the hot inner loops (which iterate
+    // over rows for a fixed column) scan memory sequentially in the row-major
+    // backing store. `at` holds the transpose: at.get(j, i) === a.get(i, j)
+    // where `a` is the logical m x n working matrix.
     let swapped = false;
-    let a;
+    let at;
     if (m < n) {
       if (!autoTranspose) {
-        a = value.clone();
         // eslint-disable-next-line no-console
         console.warn(
           'Computing SVD on a matrix with more columns than rows. Consider enabling autoTranspose',
         );
+        at = value.transpose();
       } else {
-        a = value.transpose();
-        m = a.rows;
-        n = a.columns;
+        at = value.clone();
+        m = value.columns;
+        n = value.rows;
         swapped = true;
         let aux = wantu;
         wantu = wantv;
         wantv = aux;
       }
     } else {
-      a = value.clone();
+      at = value.transpose();
     }
 
     let nu = Math.min(m, n);
     let ni = Math.min(m + 1, n);
     let s = new Float64Array(ni);
-    let U = new Matrix(m, nu);
+    // U and V are stored transposed during the computation so the inner loops
+    // (which always vary the row index) scan memory sequentially. They are
+    // transposed back to their logical layout before being returned.
+    // Ut.get(j, i) === U.get(i, j) and Vt.get(j, i) === V.get(i, j).
+    let U = new Matrix(nu, m);
     let V = new Matrix(n, n);
 
     let e = new Float64Array(n);
@@ -4071,16 +4172,16 @@ class SingularValueDecomposition {
       if (k < nct) {
         s[k] = 0;
         for (let i = k; i < m; i++) {
-          s[k] = hypotenuse(s[k], a.get(i, k));
+          s[k] = hypotenuse(s[k], at.get(k, i));
         }
         if (s[k] !== 0) {
-          if (a.get(k, k) < 0) {
+          if (at.get(k, k) < 0) {
             s[k] = -s[k];
           }
           for (let i = k; i < m; i++) {
-            a.set(i, k, a.get(i, k) / s[k]);
+            at.set(k, i, at.get(k, i) / s[k]);
           }
-          a.set(k, k, a.get(k, k) + 1);
+          at.set(k, k, at.get(k, k) + 1);
         }
         s[k] = -s[k];
       }
@@ -4089,19 +4190,19 @@ class SingularValueDecomposition {
         if (k < nct && s[k] !== 0) {
           let t = 0;
           for (let i = k; i < m; i++) {
-            t += a.get(i, k) * a.get(i, j);
+            t += at.get(k, i) * at.get(j, i);
           }
-          t = -t / a.get(k, k);
+          t = -t / at.get(k, k);
           for (let i = k; i < m; i++) {
-            a.set(i, j, a.get(i, j) + t * a.get(i, k));
+            at.set(j, i, at.get(j, i) + t * at.get(k, i));
           }
         }
-        e[j] = a.get(k, j);
+        e[j] = at.get(j, k);
       }
 
       if (wantu && k < nct) {
         for (let i = k; i < m; i++) {
-          U.set(i, k, a.get(i, k));
+          U.set(k, i, at.get(k, i));
         }
       }
 
@@ -4126,19 +4227,19 @@ class SingularValueDecomposition {
           }
           for (let i = k + 1; i < m; i++) {
             for (let j = k + 1; j < n; j++) {
-              work[i] += e[j] * a.get(i, j);
+              work[i] += e[j] * at.get(j, i);
             }
           }
           for (let j = k + 1; j < n; j++) {
             let t = -e[j] / e[k + 1];
             for (let i = k + 1; i < m; i++) {
-              a.set(i, j, a.get(i, j) + t * work[i]);
+              at.set(j, i, at.get(j, i) + t * work[i]);
             }
           }
         }
         if (wantv) {
           for (let i = k + 1; i < n; i++) {
-            V.set(i, k, e[i]);
+            V.set(k, i, e[i]);
           }
         }
       }
@@ -4146,20 +4247,20 @@ class SingularValueDecomposition {
 
     let p = Math.min(n, m + 1);
     if (nct < n) {
-      s[nct] = a.get(nct, nct);
+      s[nct] = at.get(nct, nct);
     }
     if (m < p) {
       s[p - 1] = 0;
     }
     if (nrt + 1 < p) {
-      e[nrt] = a.get(nrt, p - 1);
+      e[nrt] = at.get(p - 1, nrt);
     }
     e[p - 1] = 0;
 
     if (wantu) {
       for (let j = nct; j < nu; j++) {
         for (let i = 0; i < m; i++) {
-          U.set(i, j, 0);
+          U.set(j, i, 0);
         }
         U.set(j, j, 1);
       }
@@ -4168,23 +4269,23 @@ class SingularValueDecomposition {
           for (let j = k + 1; j < nu; j++) {
             let t = 0;
             for (let i = k; i < m; i++) {
-              t += U.get(i, k) * U.get(i, j);
+              t += U.get(k, i) * U.get(j, i);
             }
             t = -t / U.get(k, k);
             for (let i = k; i < m; i++) {
-              U.set(i, j, U.get(i, j) + t * U.get(i, k));
+              U.set(j, i, U.get(j, i) + t * U.get(k, i));
             }
           }
           for (let i = k; i < m; i++) {
-            U.set(i, k, -U.get(i, k));
+            U.set(k, i, -U.get(k, i));
           }
           U.set(k, k, 1 + U.get(k, k));
           for (let i = 0; i < k - 1; i++) {
-            U.set(i, k, 0);
+            U.set(k, i, 0);
           }
         } else {
           for (let i = 0; i < m; i++) {
-            U.set(i, k, 0);
+            U.set(k, i, 0);
           }
           U.set(k, k, 1);
         }
@@ -4197,16 +4298,16 @@ class SingularValueDecomposition {
           for (let j = k + 1; j < n; j++) {
             let t = 0;
             for (let i = k + 1; i < n; i++) {
-              t += V.get(i, k) * V.get(i, j);
+              t += V.get(k, i) * V.get(j, i);
             }
-            t = -t / V.get(k + 1, k);
+            t = -t / V.get(k, k + 1);
             for (let i = k + 1; i < n; i++) {
-              V.set(i, j, V.get(i, j) + t * V.get(i, k));
+              V.set(j, i, V.get(j, i) + t * V.get(k, i));
             }
           }
         }
         for (let i = 0; i < n; i++) {
-          V.set(i, k, 0);
+          V.set(k, i, 0);
         }
         V.set(k, k, 1);
       }
@@ -4270,9 +4371,9 @@ class SingularValueDecomposition {
             }
             if (wantv) {
               for (let i = 0; i < n; i++) {
-                t = cs * V.get(i, j) + sn * V.get(i, p - 1);
-                V.set(i, p - 1, -sn * V.get(i, j) + cs * V.get(i, p - 1));
-                V.set(i, j, t);
+                t = cs * V.get(j, i) + sn * V.get(p - 1, i);
+                V.set(p - 1, i, -sn * V.get(j, i) + cs * V.get(p - 1, i));
+                V.set(j, i, t);
               }
             }
           }
@@ -4290,9 +4391,9 @@ class SingularValueDecomposition {
             e[j] = cs * e[j];
             if (wantu) {
               for (let i = 0; i < m; i++) {
-                t = cs * U.get(i, j) + sn * U.get(i, k - 1);
-                U.set(i, k - 1, -sn * U.get(i, j) + cs * U.get(i, k - 1));
-                U.set(i, j, t);
+                t = cs * U.get(j, i) + sn * U.get(k - 1, i);
+                U.set(k - 1, i, -sn * U.get(j, i) + cs * U.get(k - 1, i));
+                U.set(j, i, t);
               }
             }
           }
@@ -4338,9 +4439,9 @@ class SingularValueDecomposition {
             s[j + 1] = cs * s[j + 1];
             if (wantv) {
               for (let i = 0; i < n; i++) {
-                t = cs * V.get(i, j) + sn * V.get(i, j + 1);
-                V.set(i, j + 1, -sn * V.get(i, j) + cs * V.get(i, j + 1));
-                V.set(i, j, t);
+                t = cs * V.get(j, i) + sn * V.get(j + 1, i);
+                V.set(j + 1, i, -sn * V.get(j, i) + cs * V.get(j + 1, i));
+                V.set(j, i, t);
               }
             }
             t = hypotenuse(f, g);
@@ -4354,9 +4455,9 @@ class SingularValueDecomposition {
             e[j + 1] = cs * e[j + 1];
             if (wantu && j < m - 1) {
               for (let i = 0; i < m; i++) {
-                t = cs * U.get(i, j) + sn * U.get(i, j + 1);
-                U.set(i, j + 1, -sn * U.get(i, j) + cs * U.get(i, j + 1));
-                U.set(i, j, t);
+                t = cs * U.get(j, i) + sn * U.get(j + 1, i);
+                U.set(j + 1, i, -sn * U.get(j, i) + cs * U.get(j + 1, i));
+                U.set(j, i, t);
               }
             }
           }
@@ -4368,7 +4469,7 @@ class SingularValueDecomposition {
             s[k] = s[k] < 0 ? -s[k] : 0;
             if (wantv) {
               for (let i = 0; i <= pp; i++) {
-                V.set(i, k, -V.get(i, k));
+                V.set(k, i, -V.get(k, i));
               }
             }
           }
@@ -4381,16 +4482,16 @@ class SingularValueDecomposition {
             s[k + 1] = t;
             if (wantv && k < n - 1) {
               for (let i = 0; i < n; i++) {
-                t = V.get(i, k + 1);
-                V.set(i, k + 1, V.get(i, k));
-                V.set(i, k, t);
+                t = V.get(k + 1, i);
+                V.set(k + 1, i, V.get(k, i));
+                V.set(k, i, t);
               }
             }
             if (wantu && k < m - 1) {
               for (let i = 0; i < m; i++) {
-                t = U.get(i, k + 1);
-                U.set(i, k + 1, U.get(i, k));
-                U.set(i, k, t);
+                t = U.get(k + 1, i);
+                U.set(k + 1, i, U.get(k, i));
+                U.set(k, i, t);
               }
             }
             k++;
@@ -4402,6 +4503,13 @@ class SingularValueDecomposition {
       }
     }
 
+    // Restore the logical (row-major) layout of the singular vectors, which were
+    // accumulated in transposed storage for cache-sequential inner loops. V is
+    // always square and U is square whenever the input is, so this is done in
+    // place (no allocation) in the common case.
+    U = U.isSquare() ? transposeSquareInPlace(U) : U.transpose();
+    V = transposeSquareInPlace(V);
+
     if (swapped) {
       let tmp = V;
       V = U;
@@ -4777,14 +4885,25 @@ class EigenvalueDecomposition {
     }
 
     if (isSymmetric) {
+      // tred2/tql2 access V almost exclusively down columns (the row index
+      // varies in the hot loops). Storing V transposed turns those into
+      // sequential row scans of the row-major backing store; we transpose it
+      // back to the logical layout before returning. V.get(j, i) holds the
+      // logical V(i, j).
       for (i = 0; i < n; i++) {
         for (j = 0; j < n; j++) {
-          V.set(i, j, value.get(i, j));
+          V.set(j, i, value.get(i, j));
         }
       }
       tred2(n, e, d, V);
       tql2(n, e, d, V);
+      // V is square; restore the logical layout in place (no allocation).
+      transposeSquareInPlace(V);
     } else {
+      // The non-symmetric path (orthes/hqr2) has two O(n^3) phases with opposite
+      // memory-layout preferences (the QR sweep favours column-major eigenvectors
+      // while the back-transform favours row-major), so a single transposed
+      // storage cannot help both. It is left in the original row-major layout.
       let H = new Matrix(n, n);
       let ort = new Float64Array(n);
       for (j = 0; j < n; j++) {
@@ -4839,7 +4958,7 @@ function tred2(n, e, d, V) {
   let f, g, h, i, j, k, hh, scale;
 
   for (j = 0; j < n; j++) {
-    d[j] = V.get(n - 1, j);
+    d[j] = V.get(j, n - 1);
   }
 
   for (i = n - 1; i > 0; i--) {
@@ -4852,9 +4971,9 @@ function tred2(n, e, d, V) {
     if (scale === 0) {
       e[i] = d[i - 1];
       for (j = 0; j < i; j++) {
-        d[j] = V.get(i - 1, j);
-        V.set(i, j, 0);
+        d[j] = V.get(j, i - 1);
         V.set(j, i, 0);
+        V.set(i, j, 0);
       }
     } else {
       for (k = 0; k < i; k++) {
@@ -4877,11 +4996,11 @@ function tred2(n, e, d, V) {
 
       for (j = 0; j < i; j++) {
         f = d[j];
-        V.set(j, i, f);
+        V.set(i, j, f);
         g = e[j] + V.get(j, j) * f;
         for (k = j + 1; k <= i - 1; k++) {
-          g += V.get(k, j) * d[k];
-          e[k] += V.get(k, j) * f;
+          g += V.get(j, k) * d[k];
+          e[k] += V.get(j, k) * f;
         }
         e[j] = g;
       }
@@ -4901,43 +5020,43 @@ function tred2(n, e, d, V) {
         f = d[j];
         g = e[j];
         for (k = j; k <= i - 1; k++) {
-          V.set(k, j, V.get(k, j) - (f * e[k] + g * d[k]));
+          V.set(j, k, V.get(j, k) - (f * e[k] + g * d[k]));
         }
-        d[j] = V.get(i - 1, j);
-        V.set(i, j, 0);
+        d[j] = V.get(j, i - 1);
+        V.set(j, i, 0);
       }
     }
     d[i] = h;
   }
 
   for (i = 0; i < n - 1; i++) {
-    V.set(n - 1, i, V.get(i, i));
+    V.set(i, n - 1, V.get(i, i));
     V.set(i, i, 1);
     h = d[i + 1];
     if (h !== 0) {
       for (k = 0; k <= i; k++) {
-        d[k] = V.get(k, i + 1) / h;
+        d[k] = V.get(i + 1, k) / h;
       }
 
       for (j = 0; j <= i; j++) {
         g = 0;
         for (k = 0; k <= i; k++) {
-          g += V.get(k, i + 1) * V.get(k, j);
+          g += V.get(i + 1, k) * V.get(j, k);
         }
         for (k = 0; k <= i; k++) {
-          V.set(k, j, V.get(k, j) - g * d[k]);
+          V.set(j, k, V.get(j, k) - g * d[k]);
         }
       }
     }
 
     for (k = 0; k <= i; k++) {
-      V.set(k, i + 1, 0);
+      V.set(i + 1, k, 0);
     }
   }
 
   for (j = 0; j < n; j++) {
-    d[j] = V.get(n - 1, j);
-    V.set(n - 1, j, 0);
+    d[j] = V.get(j, n - 1);
+    V.set(j, n - 1, 0);
   }
 
   V.set(n - 1, n - 1, 1);
@@ -5008,9 +5127,9 @@ function tql2(n, e, d, V) {
           d[i + 1] = h + s * (c * g + s * d[i]);
 
           for (k = 0; k < n; k++) {
-            h = V.get(k, i + 1);
-            V.set(k, i + 1, s * V.get(k, i) + c * h);
-            V.set(k, i, c * V.get(k, i) - s * h);
+            h = V.get(i + 1, k);
+            V.set(i + 1, k, s * V.get(i, k) + c * h);
+            V.set(i, k, c * V.get(i, k) - s * h);
           }
         }
 
@@ -5037,9 +5156,9 @@ function tql2(n, e, d, V) {
       d[k] = d[i];
       d[i] = p;
       for (j = 0; j < n; j++) {
-        p = V.get(j, i);
-        V.set(j, i, V.get(j, k));
-        V.set(j, k, p);
+        p = V.get(i, j);
+        V.set(i, j, V.get(k, j));
+        V.set(k, j, p);
       }
     }
   }