mathjs-min 11.7.2

package/lib/esm/function/matrix/sqrtm.js

@@ -0,0 +1,99 @@
+import { isMatrix } from '../../utils/is.js';
+import { format } from '../../utils/string.js';
+import { arraySize } from '../../utils/array.js';
+import { factory } from '../../utils/factory.js';
+var name = 'sqrtm';
+var dependencies = ['typed', 'abs', 'add', 'multiply', 'map', 'sqrt', 'subtract', 'inv', 'size', 'max', 'identity'];
+export var createSqrtm = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    typed,
+    abs,
+    add,
+    multiply,
+    map,
+    sqrt,
+    subtract,
+    inv,
+    size,
+    max,
+    identity
+  } = _ref;
+  var _maxIterations = 1e3;
+  var _tolerance = 1e-6;
+
+  /**
+   * Calculate the principal square root matrix using the Denman–Beavers iterative method
+   *
+   * https://en.wikipedia.org/wiki/Square_root_of_a_matrix#By_Denman–Beavers_iteration
+   *
+   * @param  {Array | Matrix} A   The square matrix `A`
+   * @return {Array | Matrix}     The principal square root of matrix `A`
+   * @private
+   */
+  function _denmanBeavers(A) {
+    var error;
+    var iterations = 0;
+    var Y = A;
+    var Z = identity(size(A));
+    do {
+      var Yk = Y;
+      Y = multiply(0.5, add(Yk, inv(Z)));
+      Z = multiply(0.5, add(Z, inv(Yk)));
+      error = max(abs(subtract(Y, Yk)));
+      if (error > _tolerance && ++iterations > _maxIterations) {
+        throw new Error('computing square root of matrix: iterative method could not converge');
+      }
+    } while (error > _tolerance);
+    return Y;
+  }
+
+  /**
+   * Calculate the principal square root of a square matrix.
+   * The principal square root matrix `X` of another matrix `A` is such that `X * X = A`.
+   *
+   * https://en.wikipedia.org/wiki/Square_root_of_a_matrix
+   *
+   * Syntax:
+   *
+   *     X = math.sqrtm(A)
+   *
+   * Examples:
+   *
+   *     math.sqrtm([[33, 24], [48, 57]]) // returns [[5, 2], [4, 7]]
+   *
+   * See also:
+   *
+   *     sqrt, pow
+   *
+   * @param  {Array | Matrix} A   The square matrix `A`
+   * @return {Array | Matrix}     The principal square root of matrix `A`
+   */
+  return typed(name, {
+    'Array | Matrix': function ArrayMatrix(A) {
+      var size = isMatrix(A) ? A.size() : arraySize(A);
+      switch (size.length) {
+        case 1:
+          // Single element Array | Matrix
+          if (size[0] === 1) {
+            return map(A, sqrt);
+          } else {
+            throw new RangeError('Matrix must be square ' + '(size: ' + format(size) + ')');
+          }
+        case 2:
+          {
+            // Two-dimensional Array | Matrix
+            var rows = size[0];
+            var cols = size[1];
+            if (rows === cols) {
+              return _denmanBeavers(A);
+            } else {
+              throw new RangeError('Matrix must be square ' + '(size: ' + format(size) + ')');
+            }
+          }
+        default:
+          // Multi dimensional array
+          throw new RangeError('Matrix must be at most two dimensional ' + '(size: ' + format(size) + ')');
+      }
+    }
+  });
+});

package/lib/esm/function/matrix/squeeze.js

@@ -0,0 +1,54 @@
+import { clone } from '../../utils/object.js';
+import { squeeze as arraySqueeze } from '../../utils/array.js';
+import { factory } from '../../utils/factory.js';
+var name = 'squeeze';
+var dependencies = ['typed', 'matrix'];
+export var createSqueeze = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    typed,
+    matrix
+  } = _ref;
+  /**
+   * Squeeze a matrix, remove inner and outer singleton dimensions from a matrix.
+   *
+   * Syntax:
+   *
+   *     math.squeeze(x)
+   *
+   * Examples:
+   *
+   *     math.squeeze([3])           // returns 3
+   *     math.squeeze([[3]])         // returns 3
+   *
+   *     const A = math.zeros(3, 1)    // returns [[0], [0], [0]] (size 3x1)
+   *     math.squeeze(A)             // returns [0, 0, 0] (size 3)
+   *
+   *     const B = math.zeros(1, 3)    // returns [[0, 0, 0]] (size 1x3)
+   *     math.squeeze(B)             // returns [0, 0, 0] (size 3)
+   *
+   *     // only inner and outer dimensions are removed
+   *     const C = math.zeros(2, 1, 3) // returns [[[0, 0, 0]], [[0, 0, 0]]] (size 2x1x3)
+   *     math.squeeze(C)             // returns [[[0, 0, 0]], [[0, 0, 0]]] (size 2x1x3)
+   *
+   * See also:
+   *
+   *     subset
+   *
+   * @param {Matrix | Array} x      Matrix to be squeezed
+   * @return {Matrix | Array} Squeezed matrix
+   */
+  return typed(name, {
+    Array: function Array(x) {
+      return arraySqueeze(clone(x));
+    },
+    Matrix: function Matrix(x) {
+      var res = arraySqueeze(x.toArray());
+      // FIXME: return the same type of matrix as the input
+      return Array.isArray(res) ? matrix(res) : res;
+    },
+    any: function any(x) {
+      // scalar
+      return clone(x);
+    }
+  });
+});

package/lib/esm/function/matrix/subset.js

@@ -0,0 +1,213 @@
+import { isIndex } from '../../utils/is.js';
+import { clone } from '../../utils/object.js';
+import { validateIndex } from '../../utils/array.js';
+import { getSafeProperty, setSafeProperty } from '../../utils/customs.js';
+import { DimensionError } from '../../error/DimensionError.js';
+import { factory } from '../../utils/factory.js';
+var name = 'subset';
+var dependencies = ['typed', 'matrix'];
+export var createSubset = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    typed,
+    matrix
+  } = _ref;
+  /**
+   * Get or set a subset of a matrix or string.
+   *
+   * Syntax:
+   *     math.subset(value, index)                                // retrieve a subset
+   *     math.subset(value, index, replacement [, defaultValue])  // replace a subset
+   *
+   * Examples:
+   *
+   *     // get a subset
+   *     const d = [[1, 2], [3, 4]]
+   *     math.subset(d, math.index(1, 0))        // returns 3
+   *     math.subset(d, math.index([0, 1], 1))   // returns [[2], [4]]
+   *
+   *     // replace a subset
+   *     const e = []
+   *     const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 6]]
+   *     const g = math.subset(f, math.index(1, 1), 7, 0)         // g = [[5, 6], [0, 7]]
+   *
+   *     // get submatrix using ranges
+   *     const M = [
+   *       [1,2,3],
+   *       [4,5,6],
+   *       [7,8,9]
+   *     ]
+   *     math.subset(M, math.index(math.range(0,2), math.range(0,3))) // [[1,2,3],[4,5,6]]
+   *
+   * See also:
+   *
+   *     size, resize, squeeze, index
+   *
+   * @param {Array | Matrix | string} matrix  An array, matrix, or string
+   * @param {Index} index
+   *    For each dimension of the target, specifies an index or a list of
+   *    indices to fetch or set. `subset` uses the cartesian product of
+   *    the indices specified in each dimension.
+   * @param {*} [replacement]                 An array, matrix, or scalar.
+   *                                          If provided, the subset is replaced with replacement.
+   *                                          If not provided, the subset is returned
+   * @param {*} [defaultValue=undefined]      Default value, filled in on new entries when
+   *                                          the matrix is resized. If not provided,
+   *                                          math.matrix elements will be left undefined.
+   * @return {Array | Matrix | string} Either the retrieved subset or the updated matrix.
+   */
+  return typed(name, {
+    // get subset
+    'Array, Index': function ArrayIndex(value, index) {
+      var m = matrix(value);
+      var subset = m.subset(index); // returns a Matrix
+      return index.isScalar() ? subset : subset.valueOf(); // return an Array (like the input)
+    },
+
+    'Matrix, Index': function MatrixIndex(value, index) {
+      return value.subset(index);
+    },
+    'Object, Index': _getObjectProperty,
+    'string, Index': _getSubstring,
+    // set subset
+    'Array, Index, any': function ArrayIndexAny(value, index, replacement) {
+      return matrix(clone(value)).subset(index, replacement, undefined).valueOf();
+    },
+    'Array, Index, any, any': function ArrayIndexAnyAny(value, index, replacement, defaultValue) {
+      return matrix(clone(value)).subset(index, replacement, defaultValue).valueOf();
+    },
+    'Matrix, Index, any': function MatrixIndexAny(value, index, replacement) {
+      return value.clone().subset(index, replacement);
+    },
+    'Matrix, Index, any, any': function MatrixIndexAnyAny(value, index, replacement, defaultValue) {
+      return value.clone().subset(index, replacement, defaultValue);
+    },
+    'string, Index, string': _setSubstring,
+    'string, Index, string, string': _setSubstring,
+    'Object, Index, any': _setObjectProperty
+  });
+});
+
+/**
+ * Retrieve a subset of a string
+ * @param {string} str            string from which to get a substring
+ * @param {Index} index           An index or list of indices (character positions)
+ * @returns {string} substring
+ * @private
+ */
+function _getSubstring(str, index) {
+  if (!isIndex(index)) {
+    // TODO: better error message
+    throw new TypeError('Index expected');
+  }
+  if (index.size().length !== 1) {
+    throw new DimensionError(index.size().length, 1);
+  }
+
+  // validate whether the range is out of range
+  var strLen = str.length;
+  validateIndex(index.min()[0], strLen);
+  validateIndex(index.max()[0], strLen);
+  var range = index.dimension(0);
+  var substr = '';
+  range.forEach(function (v) {
+    substr += str.charAt(v);
+  });
+  return substr;
+}
+
+/**
+ * Replace a substring in a string
+ * @param {string} str            string to be replaced
+ * @param {Index} index           An index or list of indices (character positions)
+ * @param {string} replacement    Replacement string
+ * @param {string} [defaultValue] Default value to be uses when resizing
+ *                                the string. is ' ' by default
+ * @returns {string} result
+ * @private
+ */
+function _setSubstring(str, index, replacement, defaultValue) {
+  if (!index || index.isIndex !== true) {
+    // TODO: better error message
+    throw new TypeError('Index expected');
+  }
+  if (index.size().length !== 1) {
+    throw new DimensionError(index.size().length, 1);
+  }
+  if (defaultValue !== undefined) {
+    if (typeof defaultValue !== 'string' || defaultValue.length !== 1) {
+      throw new TypeError('Single character expected as defaultValue');
+    }
+  } else {
+    defaultValue = ' ';
+  }
+  var range = index.dimension(0);
+  var len = range.size()[0];
+  if (len !== replacement.length) {
+    throw new DimensionError(range.size()[0], replacement.length);
+  }
+
+  // validate whether the range is out of range
+  var strLen = str.length;
+  validateIndex(index.min()[0]);
+  validateIndex(index.max()[0]);
+
+  // copy the string into an array with characters
+  var chars = [];
+  for (var i = 0; i < strLen; i++) {
+    chars[i] = str.charAt(i);
+  }
+  range.forEach(function (v, i) {
+    chars[v] = replacement.charAt(i[0]);
+  });
+
+  // initialize undefined characters with a space
+  if (chars.length > strLen) {
+    for (var _i = strLen - 1, _len = chars.length; _i < _len; _i++) {
+      if (!chars[_i]) {
+        chars[_i] = defaultValue;
+      }
+    }
+  }
+  return chars.join('');
+}
+
+/**
+ * Retrieve a property from an object
+ * @param {Object} object
+ * @param {Index} index
+ * @return {*} Returns the value of the property
+ * @private
+ */
+function _getObjectProperty(object, index) {
+  if (index.size().length !== 1) {
+    throw new DimensionError(index.size(), 1);
+  }
+  var key = index.dimension(0);
+  if (typeof key !== 'string') {
+    throw new TypeError('String expected as index to retrieve an object property');
+  }
+  return getSafeProperty(object, key);
+}
+
+/**
+ * Set a property on an object
+ * @param {Object} object
+ * @param {Index} index
+ * @param {*} replacement
+ * @return {*} Returns the updated object
+ * @private
+ */
+function _setObjectProperty(object, index, replacement) {
+  if (index.size().length !== 1) {
+    throw new DimensionError(index.size(), 1);
+  }
+  var key = index.dimension(0);
+  if (typeof key !== 'string') {
+    throw new TypeError('String expected as index to retrieve an object property');
+  }
+
+  // clone the object, and apply the property to the clone
+  var updated = clone(object);
+  setSafeProperty(updated, key, replacement);
+  return updated;
+}

package/lib/esm/function/matrix/trace.js

@@ -0,0 +1,128 @@
+import { clone } from '../../utils/object.js';
+import { format } from '../../utils/string.js';
+import { factory } from '../../utils/factory.js';
+var name = 'trace';
+var dependencies = ['typed', 'matrix', 'add'];
+export var createTrace = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    typed,
+    matrix,
+    add
+  } = _ref;
+  /**
+   * Calculate the trace of a matrix: the sum of the elements on the main
+   * diagonal of a square matrix.
+   *
+   * Syntax:
+   *
+   *    math.trace(x)
+   *
+   * Examples:
+   *
+   *    math.trace([[1, 2], [3, 4]]) // returns 5
+   *
+   *    const A = [
+   *      [1, 2, 3],
+   *      [-1, 2, 3],
+   *      [2, 0, 3]
+   *    ]
+   *    math.trace(A) // returns 6
+   *
+   * See also:
+   *
+   *    diag
+   *
+   * @param {Array | Matrix} x  A matrix
+   *
+   * @return {number} The trace of `x`
+   */
+  return typed('trace', {
+    Array: function _arrayTrace(x) {
+      // use dense matrix implementation
+      return _denseTrace(matrix(x));
+    },
+    SparseMatrix: _sparseTrace,
+    DenseMatrix: _denseTrace,
+    any: clone
+  });
+  function _denseTrace(m) {
+    // matrix size & data
+    var size = m._size;
+    var data = m._data;
+
+    // process dimensions
+    switch (size.length) {
+      case 1:
+        // vector
+        if (size[0] === 1) {
+          // return data[0]
+          return clone(data[0]);
+        }
+        throw new RangeError('Matrix must be square (size: ' + format(size) + ')');
+      case 2:
+        {
+          // two dimensional
+          var rows = size[0];
+          var cols = size[1];
+          if (rows === cols) {
+            // calulate sum
+            var sum = 0;
+            // loop diagonal
+            for (var i = 0; i < rows; i++) {
+              sum = add(sum, data[i][i]);
+            }
+            // return trace
+            return sum;
+          } else {
+            throw new RangeError('Matrix must be square (size: ' + format(size) + ')');
+          }
+        }
+      default:
+        // multi dimensional
+        throw new RangeError('Matrix must be two dimensional (size: ' + format(size) + ')');
+    }
+  }
+  function _sparseTrace(m) {
+    // matrix arrays
+    var values = m._values;
+    var index = m._index;
+    var ptr = m._ptr;
+    var size = m._size;
+    // check dimensions
+    var rows = size[0];
+    var columns = size[1];
+    // matrix must be square
+    if (rows === columns) {
+      // calulate sum
+      var sum = 0;
+      // check we have data (avoid looping columns)
+      if (values.length > 0) {
+        // loop columns
+        for (var j = 0; j < columns; j++) {
+          // k0 <= k < k1 where k0 = _ptr[j] && k1 = _ptr[j+1]
+          var k0 = ptr[j];
+          var k1 = ptr[j + 1];
+          // loop k within [k0, k1[
+          for (var k = k0; k < k1; k++) {
+            // row index
+            var i = index[k];
+            // check row
+            if (i === j) {
+              // accumulate value
+              sum = add(sum, values[k]);
+              // exit loop
+              break;
+            }
+            if (i > j) {
+              // exit loop, no value on the diagonal for column j
+              break;
+            }
+          }
+        }
+      }
+      // return trace
+      return sum;
+    }
+    throw new RangeError('Matrix must be square (size: ' + format(size) + ')');
+  }
+});

package/lib/esm/function/matrix/transpose.js

@@ -0,0 +1,161 @@
+import { clone } from '../../utils/object.js';
+import { format } from '../../utils/string.js';
+import { factory } from '../../utils/factory.js';
+var name = 'transpose';
+var dependencies = ['typed', 'matrix'];
+export var createTranspose = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    typed,
+    matrix
+  } = _ref;
+  /**
+   * Transpose a matrix. All values of the matrix are reflected over its
+   * main diagonal. Only applicable to two dimensional matrices containing
+   * a vector (i.e. having size `[1,n]` or `[n,1]`). One dimensional
+   * vectors and scalars return the input unchanged.
+   *
+   * Syntax:
+   *
+   *     math.transpose(x)
+   *
+   * Examples:
+   *
+   *     const A = [[1, 2, 3], [4, 5, 6]]
+   *     math.transpose(A)               // returns [[1, 4], [2, 5], [3, 6]]
+   *
+   * See also:
+   *
+   *     diag, inv, subset, squeeze
+   *
+   * @param {Array | Matrix} x  Matrix to be transposed
+   * @return {Array | Matrix}   The transposed matrix
+   */
+  return typed(name, {
+    Array: x => transposeMatrix(matrix(x)).valueOf(),
+    Matrix: transposeMatrix,
+    any: clone // scalars
+  });
+
+  function transposeMatrix(x) {
+    // matrix size
+    var size = x.size();
+
+    // result
+    var c;
+
+    // process dimensions
+    switch (size.length) {
+      case 1:
+        // vector
+        c = x.clone();
+        break;
+      case 2:
+        {
+          // rows and columns
+          var rows = size[0];
+          var columns = size[1];
+
+          // check columns
+          if (columns === 0) {
+            // throw exception
+            throw new RangeError('Cannot transpose a 2D matrix with no columns (size: ' + format(size) + ')');
+          }
+
+          // process storage format
+          switch (x.storage()) {
+            case 'dense':
+              c = _denseTranspose(x, rows, columns);
+              break;
+            case 'sparse':
+              c = _sparseTranspose(x, rows, columns);
+              break;
+          }
+        }
+        break;
+      default:
+        // multi dimensional
+        throw new RangeError('Matrix must be a vector or two dimensional (size: ' + format(size) + ')');
+    }
+    return c;
+  }
+  function _denseTranspose(m, rows, columns) {
+    // matrix array
+    var data = m._data;
+    // transposed matrix data
+    var transposed = [];
+    var transposedRow;
+    // loop columns
+    for (var j = 0; j < columns; j++) {
+      // initialize row
+      transposedRow = transposed[j] = [];
+      // loop rows
+      for (var i = 0; i < rows; i++) {
+        // set data
+        transposedRow[i] = clone(data[i][j]);
+      }
+    }
+    // return matrix
+    return m.createDenseMatrix({
+      data: transposed,
+      size: [columns, rows],
+      datatype: m._datatype
+    });
+  }
+  function _sparseTranspose(m, rows, columns) {
+    // matrix arrays
+    var values = m._values;
+    var index = m._index;
+    var ptr = m._ptr;
+    // result matrices
+    var cvalues = values ? [] : undefined;
+    var cindex = [];
+    var cptr = [];
+    // row counts
+    var w = [];
+    for (var x = 0; x < rows; x++) {
+      w[x] = 0;
+    }
+    // vars
+    var p, l, j;
+    // loop values in matrix
+    for (p = 0, l = index.length; p < l; p++) {
+      // number of values in row
+      w[index[p]]++;
+    }
+    // cumulative sum
+    var sum = 0;
+    // initialize cptr with the cummulative sum of row counts
+    for (var i = 0; i < rows; i++) {
+      // update cptr
+      cptr.push(sum);
+      // update sum
+      sum += w[i];
+      // update w
+      w[i] = cptr[i];
+    }
+    // update cptr
+    cptr.push(sum);
+    // loop columns
+    for (j = 0; j < columns; j++) {
+      // values & index in column
+      for (var k0 = ptr[j], k1 = ptr[j + 1], k = k0; k < k1; k++) {
+        // C values & index
+        var q = w[index[k]]++;
+        // C[j, i] = A[i, j]
+        cindex[q] = j;
+        // check we need to process values (pattern matrix)
+        if (values) {
+          cvalues[q] = clone(values[k]);
+        }
+      }
+    }
+    // return matrix
+    return m.createSparseMatrix({
+      values: cvalues,
+      index: cindex,
+      ptr: cptr,
+      size: [columns, rows],
+      datatype: m._datatype
+    });
+  }
+});