ml-matrix 6.10.8 → 6.11.0

package/matrix.js

@@ -1472,6 +1472,16 @@ class AbstractMatrix {
     return false;
   }
 
+  isDistance() {
+    if (!this.isSymmetric()) return false;
+
+    for (let i = 0; i < this.rows; i++) {
+      if (this.get(i, i) !== 0) return false;
+    }
+
+    return true;
+  }
+
   isEchelonForm() {
     let i = 0;
     let j = 0;
@@ -2546,13 +2556,21 @@ class AbstractMatrix {
   }
 
   clone() {
-    let newMatrix = new Matrix(this.rows, this.columns);
-    for (let row = 0; row < this.rows; row++) {
-      for (let column = 0; column < this.columns; column++) {
-        newMatrix.set(row, column, this.get(row, column));
-      }
+    return this.constructor.copy(this, new Matrix(this.rows, this.columns));
+  }
+
+  /**
+   * @template {AbstractMatrix} M
+   * @param {AbstractMatrix} from
+   * @param {M} to
+   * @return {M}
+   */
+  static copy(from, to) {
+    for (const [row, column, value] of from.entries()) {
+      to.set(row, column, value);
     }
-    return newMatrix;
+
+    return to;
   }
 
   sum(by) {
@@ -2736,6 +2754,36 @@ class AbstractMatrix {
   toString(options) {
     return inspectMatrixWithOptions(this, options);
   }
+
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  /**
+   * iterator from left to right, from top to bottom
+   * yield [row, column, value]
+   * @returns {Generator<[number, number, number], void, *>}
+   */
+  *entries() {
+    for (let row = 0; row < this.rows; row++) {
+      for (let col = 0; col < this.columns; col++) {
+        yield [row, col, this.get(row, col)];
+      }
+    }
+  }
+
+  /**
+   * iterator from left to right, from top to bottom
+   * yield value
+   * @returns {Generator<number, void, *>}
+   */
+  *values() {
+    for (let row = 0; row < this.rows; row++) {
+      for (let col = 0; col < this.columns; col++) {
+        yield this.get(row, col);
+      }
+    }
+  }
 }
 
 AbstractMatrix.prototype.klass = 'Matrix';
@@ -2765,21 +2813,38 @@ AbstractMatrix.prototype.tensorProduct =
   AbstractMatrix.prototype.kroneckerProduct;
 
 class Matrix extends AbstractMatrix {
+  /**
+   * @type {Float64Array[]}
+   */
+  data;
+
+  /**
+   * Init an empty matrix
+   * @param {number} nRows
+   * @param {number} nColumns
+   */
+  #initData(nRows, nColumns) {
+    this.data = [];
+
+    if (Number.isInteger(nColumns) && nColumns >= 0) {
+      for (let i = 0; i < nRows; i++) {
+        this.data.push(new Float64Array(nColumns));
+      }
+    } else {
+      throw new TypeError('nColumns must be a positive integer');
+    }
+
+    this.rows = nRows;
+    this.columns = nColumns;
+  }
+
   constructor(nRows, nColumns) {
     super();
     if (Matrix.isMatrix(nRows)) {
-      // eslint-disable-next-line no-constructor-return
-      return nRows.clone();
+      this.#initData(nRows.rows, nRows.columns);
+      Matrix.copy(nRows, this);
     } else if (Number.isInteger(nRows) && nRows >= 0) {
-      // Create an empty matrix
-      this.data = [];
-      if (Number.isInteger(nColumns) && nColumns >= 0) {
-        for (let i = 0; i < nRows; i++) {
-          this.data.push(new Float64Array(nColumns));
-        }
-      } else {
-        throw new TypeError('nColumns must be a positive integer');
-      }
+      this.#initData(nRows, nColumns);
     } else if (isAnyArray.isAnyArray(nRows)) {
       // Copy the values from the 2D array
       const arrayData = nRows;
@@ -2791,6 +2856,7 @@ class Matrix extends AbstractMatrix {
         );
       }
       this.data = [];
+
       for (let i = 0; i < nRows; i++) {
         if (arrayData[i].length !== nColumns) {
           throw new RangeError('Inconsistent array dimensions');
@@ -2800,13 +2866,14 @@ class Matrix extends AbstractMatrix {
         }
         this.data.push(Float64Array.from(arrayData[i]));
       }
+
+      this.rows = nRows;
+      this.columns = nColumns;
     } else {
       throw new TypeError(
         'First argument must be a positive number or an array',
       );
     }
-    this.rows = nRows;
-    this.columns = nColumns;
   }
 
   set(rowIndex, columnIndex, value) {
@@ -2879,6 +2946,374 @@ class Matrix extends AbstractMatrix {
 
 installMathOperations(AbstractMatrix, Matrix);
 
+/**
+ * @typedef {0 | 1 | number | boolean} Mask
+ */
+
+class SymmetricMatrix extends AbstractMatrix {
+  /** @type {Matrix} */
+  #matrix;
+
+  get size() {
+    return this.#matrix.size;
+  }
+
+  get rows() {
+    return this.#matrix.rows;
+  }
+
+  get columns() {
+    return this.#matrix.columns;
+  }
+
+  get diagonalSize() {
+    return this.rows;
+  }
+
+  /**
+   * not the same as matrix.isSymmetric()
+   * Here is to check if it's instanceof SymmetricMatrix without bundling issues
+   *
+   * @param value
+   * @returns {boolean}
+   */
+  static isSymmetricMatrix(value) {
+    return Matrix.isMatrix(value) && value.klassType === 'SymmetricMatrix';
+  }
+
+  /**
+   * @param diagonalSize
+   * @return {SymmetricMatrix}
+   */
+  static zeros(diagonalSize) {
+    return new this(diagonalSize);
+  }
+
+  /**
+   * @param diagonalSize
+   * @return {SymmetricMatrix}
+   */
+  static ones(diagonalSize) {
+    return new this(diagonalSize).fill(1);
+  }
+
+  /**
+   * @param {number | AbstractMatrix | ArrayLike<ArrayLike<number>>} diagonalSize
+   * @return {this}
+   */
+  constructor(diagonalSize) {
+    super();
+
+    if (Matrix.isMatrix(diagonalSize)) {
+      if (!diagonalSize.isSymmetric()) {
+        throw new TypeError('not symmetric data');
+      }
+
+      this.#matrix = Matrix.copy(
+        diagonalSize,
+        new Matrix(diagonalSize.rows, diagonalSize.rows),
+      );
+    } else if (Number.isInteger(diagonalSize) && diagonalSize >= 0) {
+      this.#matrix = new Matrix(diagonalSize, diagonalSize);
+    } else {
+      this.#matrix = new Matrix(diagonalSize);
+
+      if (!this.isSymmetric()) {
+        throw new TypeError('not symmetric data');
+      }
+    }
+  }
+
+  clone() {
+    const matrix = new SymmetricMatrix(this.diagonalSize);
+
+    for (const [row, col, value] of this.upperRightEntries()) {
+      matrix.set(row, col, value);
+    }
+
+    return matrix;
+  }
+
+  toMatrix() {
+    return new Matrix(this);
+  }
+
+  get(rowIndex, columnIndex) {
+    return this.#matrix.get(rowIndex, columnIndex);
+  }
+  set(rowIndex, columnIndex, value) {
+    // symmetric set
+    this.#matrix.set(rowIndex, columnIndex, value);
+    this.#matrix.set(columnIndex, rowIndex, value);
+
+    return this;
+  }
+
+  removeCross(index) {
+    // symmetric remove side
+    this.#matrix.removeRow(index);
+    this.#matrix.removeColumn(index);
+
+    return this;
+  }
+
+  addCross(index, array) {
+    if (array === undefined) {
+      array = index;
+      index = this.diagonalSize;
+    }
+
+    const row = array.slice();
+    row.splice(index, 1);
+
+    this.#matrix.addRow(index, row);
+    this.#matrix.addColumn(index, array);
+
+    return this;
+  }
+
+  /**
+   * @param {Mask[]} mask
+   */
+  applyMask(mask) {
+    if (mask.length !== this.diagonalSize) {
+      throw new RangeError('Mask size do not match with matrix size');
+    }
+
+    // prepare sides to remove from matrix from mask
+    /** @type {number[]} */
+    const sidesToRemove = [];
+    for (const [index, passthroughs] of mask.entries()) {
+      if (passthroughs) continue;
+      sidesToRemove.push(index);
+    }
+    // to remove from highest to lowest for no mutation shifting
+    sidesToRemove.reverse();
+
+    // remove sides
+    for (const sideIndex of sidesToRemove) {
+      this.removeCross(sideIndex);
+    }
+
+    return this;
+  }
+
+  /**
+   * Compact format upper-right corner of matrix
+   * iterate from left to right, from top to bottom.
+   *
+   * ```
+   *   A B C D
+   * A 1 2 3 4
+   * B 2 5 6 7
+   * C 3 6 8 9
+   * D 4 7 9 10
+   * ```
+   *
+   * will return compact 1D array `[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]`
+   *
+   * length is S(i=0, n=sideSize) => 10 for a 4 sideSized matrix
+   *
+   * @returns {number[]}
+   */
+  toCompact() {
+    const { diagonalSize } = this;
+
+    /** @type {number[]} */
+    const compact = new Array((diagonalSize * (diagonalSize + 1)) / 2);
+    for (let col = 0, row = 0, index = 0; index < compact.length; index++) {
+      compact[index] = this.get(row, col);
+
+      if (++col >= diagonalSize) col = ++row;
+    }
+
+    return compact;
+  }
+
+  /**
+   * @param {number[]} compact
+   * @return {SymmetricMatrix}
+   */
+  static fromCompact(compact) {
+    const compactSize = compact.length;
+    // compactSize = (sideSize * (sideSize + 1)) / 2
+    // https://mathsolver.microsoft.com/fr/solve-problem/y%20%3D%20%20x%20%60cdot%20%20%20%60frac%7B%20%20%60left(%20x%2B1%20%20%60right)%20%20%20%20%7D%7B%202%20%20%7D
+    // sideSize = (Sqrt(8 × compactSize + 1) - 1) / 2
+    const diagonalSize = (Math.sqrt(8 * compactSize + 1) - 1) / 2;
+
+    if (!Number.isInteger(diagonalSize)) {
+      throw new TypeError(
+        `This array is not a compact representation of a Symmetric Matrix, ${JSON.stringify(
+          compact,
+        )}`,
+      );
+    }
+
+    const matrix = new SymmetricMatrix(diagonalSize);
+    for (let col = 0, row = 0, index = 0; index < compactSize; index++) {
+      matrix.set(col, row, compact[index]);
+      if (++col >= diagonalSize) col = ++row;
+    }
+
+    return matrix;
+  }
+
+  /**
+   * half iterator upper-right-corner from left to right, from top to bottom
+   * yield [row, column, value]
+   *
+   * @returns {Generator<[number, number, number], void, *>}
+   */
+  *upperRightEntries() {
+    for (let row = 0, col = 0; row < this.diagonalSize; void 0) {
+      const value = this.get(row, col);
+
+      yield [row, col, value];
+
+      // at the end of row, move cursor to next row at diagonal position
+      if (++col >= this.diagonalSize) col = ++row;
+    }
+  }
+
+  /**
+   * half iterator upper-right-corner from left to right, from top to bottom
+   * yield value
+   *
+   * @returns {Generator<[number, number, number], void, *>}
+   */
+  *upperRightValues() {
+    for (let row = 0, col = 0; row < this.diagonalSize; void 0) {
+      const value = this.get(row, col);
+
+      yield value;
+
+      // at the end of row, move cursor to next row at diagonal position
+      if (++col >= this.diagonalSize) col = ++row;
+    }
+  }
+}
+SymmetricMatrix.prototype.klassType = 'SymmetricMatrix';
+
+class DistanceMatrix extends SymmetricMatrix {
+  /**
+   * not the same as matrix.isSymmetric()
+   * Here is to check if it's instanceof SymmetricMatrix without bundling issues
+   *
+   * @param value
+   * @returns {boolean}
+   */
+  static isDistanceMatrix(value) {
+    return (
+      SymmetricMatrix.isSymmetricMatrix(value) &&
+      value.klassSubType === 'DistanceMatrix'
+    );
+  }
+
+  constructor(sideSize) {
+    super(sideSize);
+
+    if (!this.isDistance()) {
+      throw new TypeError('Provided arguments do no produce a distance matrix');
+    }
+  }
+
+  set(rowIndex, columnIndex, value) {
+    // distance matrix diagonal is 0
+    if (rowIndex === columnIndex) value = 0;
+
+    return super.set(rowIndex, columnIndex, value);
+  }
+
+  addCross(index, array) {
+    if (array === undefined) {
+      array = index;
+      index = this.diagonalSize;
+    }
+
+    // ensure distance
+    array = array.slice();
+    array[index] = 0;
+
+    return super.addCross(index, array);
+  }
+
+  toSymmetricMatrix() {
+    return new SymmetricMatrix(this);
+  }
+
+  clone() {
+    const matrix = new DistanceMatrix(this.diagonalSize);
+
+    for (const [row, col, value] of this.upperRightEntries()) {
+      if (row === col) continue;
+      matrix.set(row, col, value);
+    }
+
+    return matrix;
+  }
+
+  /**
+   * Compact format upper-right corner of matrix
+   * no diagonal (only zeros)
+   * iterable from left to right, from top to bottom.
+   *
+   * ```
+   *   A B C D
+   * A 0 1 2 3
+   * B 1 0 4 5
+   * C 2 4 0 6
+   * D 3 5 6 0
+   * ```
+   *
+   * will return compact 1D array `[1, 2, 3, 4, 5, 6]`
+   *
+   * length is S(i=0, n=sideSize-1) => 6 for a 4 side sized matrix
+   *
+   * @returns {number[]}
+   */
+  toCompact() {
+    const { diagonalSize } = this;
+    const compactLength = ((diagonalSize - 1) * diagonalSize) / 2;
+
+    /** @type {number[]} */
+    const compact = new Array(compactLength);
+    for (let col = 1, row = 0, index = 0; index < compact.length; index++) {
+      compact[index] = this.get(row, col);
+
+      if (++col >= diagonalSize) col = ++row + 1;
+    }
+
+    return compact;
+  }
+
+  /**
+   * @param {number[]} compact
+   */
+  static fromCompact(compact) {
+    const compactSize = compact.length;
+    // compactSize = (sideSize * (sideSize - 1)) / 2
+    // sideSize = (Sqrt(8 × compactSize + 1) + 1) / 2
+    const diagonalSize = (Math.sqrt(8 * compactSize + 1) + 1) / 2;
+
+    if (!Number.isInteger(diagonalSize)) {
+      throw new TypeError(
+        `This array is not a compact representation of a DistanceMatrix, ${JSON.stringify(
+          compact,
+        )}`,
+      );
+    }
+
+    const matrix = new this(diagonalSize);
+    for (let col = 1, row = 0, index = 0; index < compactSize; index++) {
+      matrix.set(col, row, compact[index]);
+      if (++col >= diagonalSize) col = ++row + 1;
+    }
+
+    return matrix;
+  }
+}
+DistanceMatrix.prototype.klassSubType = 'DistanceMatrix';
+
 class BaseView extends AbstractMatrix {
   constructor(matrix, rows, columns) {
     super();
@@ -5147,6 +5582,7 @@ class nipals {
 exports.AbstractMatrix = AbstractMatrix;
 exports.CHO = CholeskyDecomposition;
 exports.CholeskyDecomposition = CholeskyDecomposition;
+exports.DistanceMatrix = DistanceMatrix;
 exports.EVD = EigenvalueDecomposition;
 exports.EigenvalueDecomposition = EigenvalueDecomposition;
 exports.LU = LuDecomposition;
@@ -5167,6 +5603,7 @@ exports.QR = QrDecomposition;
 exports.QrDecomposition = QrDecomposition;
 exports.SVD = SingularValueDecomposition;
 exports.SingularValueDecomposition = SingularValueDecomposition;
+exports.SymmetricMatrix = SymmetricMatrix;
 exports.WrapperMatrix1D = WrapperMatrix1D;
 exports.WrapperMatrix2D = WrapperMatrix2D;
 exports.correlation = correlation;

package/matrix.mjs

@@ -3,6 +3,7 @@ import * as matrix from './matrix.js';
 export const AbstractMatrix = matrix.AbstractMatrix;
 export const CHO = matrix.CHO;
 export const CholeskyDecomposition = matrix.CholeskyDecomposition;
+export const DistanceMatrix = matrix.DistanceMatrix;
 export const EVD = matrix.EVD;
 export const EigenvalueDecomposition = matrix.EigenvalueDecomposition;
 export const LU = matrix.LU;
@@ -23,6 +24,7 @@ export const QR = matrix.QR;
 export const QrDecomposition = matrix.QrDecomposition;
 export const SVD = matrix.SVD;
 export const SingularValueDecomposition = matrix.SingularValueDecomposition;
+export const SymmetricMatrix = matrix.SymmetricMatrix;
 export const WrapperMatrix1D = matrix.WrapperMatrix1D;
 export const WrapperMatrix2D = matrix.WrapperMatrix2D;
 export const correlation = matrix.correlation;