mathjs 11.12.0 → 12.0.0

package/lib/esm/function/matrix/eigs/{realSymetric.js → realSymmetric.js}

@@ -23,25 +23,29 @@ export function createRealSymmetric(_ref) {
   function main(arr, N) {
     var prec = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : config.epsilon;
     var type = arguments.length > 3 ? arguments[3] : undefined;
+    var computeVectors = arguments.length > 4 ? arguments[4] : undefined;
     if (type === 'number') {
-      return diag(arr, prec);
+      return diag(arr, prec, computeVectors);
     }
     if (type === 'BigNumber') {
-      return diagBig(arr, prec);
+      return diagBig(arr, prec, computeVectors);
     }
     throw TypeError('Unsupported data type: ' + type);
   }
 
   // diagonalization implementation for number (efficient)
-  function diag(x, precision) {
+  function diag(x, precision, computeVectors) {
     var N = x.length;
     var e0 = Math.abs(precision / N);
     var psi;
-    var Sij = new Array(N);
-    // Sij is Identity Matrix
-    for (var i = 0; i < N; i++) {
-      Sij[i] = createArray(N, 0);
-      Sij[i][i] = 1.0;
+    var Sij;
+    if (computeVectors) {
+      Sij = new Array(N);
+      // Sij is Identity Matrix
+      for (var i = 0; i < N; i++) {
+        Sij[i] = Array(N).fill(0);
+        Sij[i][i] = 1.0;
+      }
     }
     // initial error
     var Vab = getAij(x);
@@ -50,26 +54,29 @@ export function createRealSymmetric(_ref) {
       var j = Vab[0][1];
       psi = getTheta(x[_i][_i], x[j][j], x[_i][j]);
       x = x1(x, psi, _i, j);
-      Sij = Sij1(Sij, psi, _i, j);
+      if (computeVectors) Sij = Sij1(Sij, psi, _i, j);
       Vab = getAij(x);
     }
-    var Ei = createArray(N, 0); // eigenvalues
+    var Ei = Array(N).fill(0); // eigenvalues
     for (var _i2 = 0; _i2 < N; _i2++) {
       Ei[_i2] = x[_i2][_i2];
     }
-    return sorting(clone(Ei), clone(Sij));
+    return sorting(clone(Ei), Sij, computeVectors);
   }
 
   // diagonalization implementation for bigNumber
-  function diagBig(x, precision) {
+  function diagBig(x, precision, computeVectors) {
     var N = x.length;
     var e0 = abs(precision / N);
     var psi;
-    var Sij = new Array(N);
-    // Sij is Identity Matrix
-    for (var i = 0; i < N; i++) {
-      Sij[i] = createArray(N, 0);
-      Sij[i][i] = 1.0;
+    var Sij;
+    if (computeVectors) {
+      Sij = new Array(N);
+      // Sij is Identity Matrix
+      for (var i = 0; i < N; i++) {
+        Sij[i] = Array(N).fill(0);
+        Sij[i][i] = 1.0;
+      }
     }
     // initial error
     var Vab = getAijBig(x);
@@ -78,15 +85,15 @@ export function createRealSymmetric(_ref) {
       var j = Vab[0][1];
       psi = getThetaBig(x[_i3][_i3], x[j][j], x[_i3][j]);
       x = x1Big(x, psi, _i3, j);
-      Sij = Sij1Big(Sij, psi, _i3, j);
+      if (computeVectors) Sij = Sij1Big(Sij, psi, _i3, j);
       Vab = getAijBig(x);
     }
-    var Ei = createArray(N, 0); // eigenvalues
+    var Ei = Array(N).fill(0); // eigenvalues
     for (var _i4 = 0; _i4 < N; _i4++) {
       Ei[_i4] = x[_i4][_i4];
     }
     // return [clone(Ei), clone(Sij)]
-    return sorting(clone(Ei), clone(Sij));
+    return sorting(clone(Ei), Sij, computeVectors);
   }
 
   // get angle
@@ -114,8 +121,8 @@ export function createRealSymmetric(_ref) {
     var N = Sij.length;
     var c = Math.cos(theta);
     var s = Math.sin(theta);
-    var Ski = createArray(N, 0);
-    var Skj = createArray(N, 0);
+    var Ski = Array(N).fill(0);
+    var Skj = Array(N).fill(0);
     for (var k = 0; k < N; k++) {
       Ski[k] = c * Sij[k][i] - s * Sij[k][j];
       Skj[k] = s * Sij[k][i] + c * Sij[k][j];
@@ -131,8 +138,8 @@ export function createRealSymmetric(_ref) {
     var N = Sij.length;
     var c = cos(theta);
     var s = sin(theta);
-    var Ski = createArray(N, bignumber(0));
-    var Skj = createArray(N, bignumber(0));
+    var Ski = Array(N).fill(bignumber(0));
+    var Skj = Array(N).fill(bignumber(0));
     for (var k = 0; k < N; k++) {
       Ski[k] = subtract(multiplyScalar(c, Sij[k][i]), multiplyScalar(s, Sij[k][j]));
       Skj[k] = addScalar(multiplyScalar(s, Sij[k][i]), multiplyScalar(c, Sij[k][j]));
@@ -151,8 +158,8 @@ export function createRealSymmetric(_ref) {
     var s = bignumber(sin(theta));
     var c2 = multiplyScalar(c, c);
     var s2 = multiplyScalar(s, s);
-    var Aki = createArray(N, bignumber(0));
-    var Akj = createArray(N, bignumber(0));
+    var Aki = Array(N).fill(bignumber(0));
+    var Akj = Array(N).fill(bignumber(0));
     // 2cs Hij
     var csHij = multiply(bignumber(2), c, s, Hij[i][j]);
     //  Aii
@@ -187,8 +194,8 @@ export function createRealSymmetric(_ref) {
     var s = Math.sin(theta);
     var c2 = c * c;
     var s2 = s * s;
-    var Aki = createArray(N, 0);
-    var Akj = createArray(N, 0);
+    var Aki = Array(N).fill(0);
+    var Akj = Array(N).fill(0);
     //  Aii
     var Aii = c2 * Hij[i][i] - 2 * c * s * Hij[i][j] + s2 * Hij[j][j];
     var Ajj = s2 * Hij[i][i] + 2 * c * s * Hij[i][j] + c2 * Hij[j][j];
@@ -247,12 +254,15 @@ export function createRealSymmetric(_ref) {
   }
 
   // sort results
-  function sorting(E, S) {
+  function sorting(E, S, computeVectors) {
     var N = E.length;
     var values = Array(N);
-    var vectors = Array(N);
-    for (var k = 0; k < N; k++) {
-      vectors[k] = Array(N);
+    var vecs;
+    if (computeVectors) {
+      vecs = Array(N);
+      for (var k = 0; k < N; k++) {
+        vecs[k] = Array(N);
+      }
     }
     for (var i = 0; i < N; i++) {
       var minID = 0;
@@ -264,30 +274,24 @@ export function createRealSymmetric(_ref) {
         }
       }
       values[i] = E.splice(minID, 1)[0];
-      for (var _k5 = 0; _k5 < N; _k5++) {
-        vectors[_k5][i] = S[_k5][minID];
-        S[_k5].splice(minID, 1);
+      if (computeVectors) {
+        for (var _k5 = 0; _k5 < N; _k5++) {
+          vecs[i][_k5] = S[_k5][minID];
+          S[_k5].splice(minID, 1);
+        }
       }
     }
+    if (!computeVectors) return {
+      values
+    };
+    var eigenvectors = vecs.map((vector, i) => ({
+      value: values[i],
+      vector
+    }));
     return {
       values,
-      vectors
+      eigenvectors
     };
   }
-
-  /**
-   * Create an array of a certain size and fill all items with an initial value
-   * @param {number} size
-   * @param {number} value
-   * @return {number[]}
-   */
-  function createArray(size, value) {
-    // TODO: as soon as all browsers support Array.fill, use that instead (IE doesn't support it)
-    var array = new Array(size);
-    for (var i = 0; i < size; i++) {
-      array[i] = value;
-    }
-    return array;
-  }
   return main;
 }

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

@@ -1,12 +1,13 @@
+import _extends from "@babel/runtime/helpers/extends";
 import { factory } from '../../utils/factory.js';
 import { format } from '../../utils/string.js';
 import { createComplexEigs } from './eigs/complexEigs.js';
-import { createRealSymmetric } from './eigs/realSymetric.js';
+import { createRealSymmetric } from './eigs/realSymmetric.js';
 import { typeOf, isNumber, isBigNumber, isComplex, isFraction } from '../../utils/is.js';
 var name = 'eigs';
 
 // The absolute state of math.js's dependency system:
-var dependencies = ['config', 'typed', 'matrix', 'addScalar', 'equal', 'subtract', 'abs', 'atan', 'cos', 'sin', 'multiplyScalar', 'divideScalar', 'inv', 'bignumber', 'multiply', 'add', 'larger', 'column', 'flatten', 'number', 'complex', 'sqrt', 'diag', 'qr', 'usolve', 'usolveAll', 'im', 're', 'smaller', 'matrixFromColumns', 'dot'];
+var dependencies = ['config', 'typed', 'matrix', 'addScalar', 'equal', 'subtract', 'abs', 'atan', 'cos', 'sin', 'multiplyScalar', 'divideScalar', 'inv', 'bignumber', 'multiply', 'add', 'larger', 'column', 'flatten', 'number', 'complex', 'sqrt', 'diag', 'size', 'reshape', 'qr', 'usolve', 'usolveAll', 'im', 're', 'smaller', 'matrixFromColumns', 'dot'];
 export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
   var {
     config,
@@ -32,6 +33,8 @@ export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
     complex,
     sqrt,
     diag,
+    size,
+    reshape,
     qr,
     usolve,
     usolveAll,
@@ -41,7 +44,7 @@ export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
     matrixFromColumns,
     dot
   } = _ref;
-  var doRealSymetric = createRealSymmetric({
+  var doRealSymmetric = createRealSymmetric({
     config,
     addScalar,
     subtract,
@@ -71,6 +74,8 @@ export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
     abs,
     bignumber,
     diag,
+    size,
+    reshape,
     qr,
     inv,
     usolve,
@@ -84,26 +89,54 @@ export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
   });
 
   /**
-   * Compute eigenvalues and eigenvectors of a matrix. The eigenvalues are sorted by their absolute value, ascending.
-   * An eigenvalue with multiplicity k will be listed k times. The eigenvectors are returned as columns of a matrix –
-   * the eigenvector that belongs to the j-th eigenvalue in the list (eg. `values[j]`) is the j-th column (eg. `column(vectors, j)`).
-   * If the algorithm fails to converge, it will throw an error – in that case, however, you may still find useful information
+   * Compute eigenvalues and optionally eigenvectors of a square matrix.
+   * The eigenvalues are sorted by their absolute value, ascending, and
+   * returned as a vector in the `values` property of the returned project.
+   * An eigenvalue with algebraic multiplicity k will be listed k times, so
+   * that the returned `values` vector always has length equal to the size
+   * of the input matrix.
+   *
+   * The `eigenvectors` property of the return value provides the eigenvectors.
+   * It is an array of plain objects: the `value` property of each gives the
+   * associated eigenvalue, and the `vector` property gives the eigenvector
+   * itself. Note that the same `value` property will occur as many times in
+   * the list provided by `eigenvectors` as the geometric multiplicity of
+   * that value.
+   *
+   * If the algorithm fails to converge, it will throw an error –
+   * in that case, however, you may still find useful information
    * in `err.values` and `err.vectors`.
    *
+   * Note that the 'precision' option does not directly specify the _accuracy_
+   * of the returned eigenvalues. Rather, it determines how small an entry
+   * of the iterative approximations to an upper triangular matrix must be
+   * in order to be considered zero. The actual accuracy of the returned
+   * eigenvalues may be greater or less than the precision, depending on the
+   * conditioning of the matrix and how far apart or close the actual
+   * eigenvalues are. Note that currently, relatively simple, "traditional"
+   * methods of eigenvalue computation are being used; this is not a modern,
+   * high-precision eigenvalue computation. That said, it should typically
+   * produce fairly reasonable results.
+   *
    * Syntax:
    *
    *     math.eigs(x, [prec])
+   *     math.eigs(x, {options})
    *
    * Examples:
    *
-   *     const { eigs, multiply, column, transpose } = math
+   *     const { eigs, multiply, column, transpose, matrixFromColumns } = math
    *     const H = [[5, 2.3], [2.3, 1]]
-   *     const ans = eigs(H) // returns {values: [E1,E2...sorted], vectors: [v1,v2.... corresponding vectors as columns]}
+   *     const ans = eigs(H) // returns {values: [E1,E2...sorted], eigenvectors: [{value: E1, vector: v2}, {value: e, vector: v2}, ...]
    *     const E = ans.values
-   *     const U = ans.vectors
-   *     multiply(H, column(U, 0)) // returns multiply(E[0], column(U, 0))
-   *     const UTxHxU = multiply(transpose(U), H, U) // diagonalizes H
-   *     E[0] == UTxHxU[0][0]  // returns true
+   *     const V = ans.eigenvectors
+   *     multiply(H, V[0].vector)) // returns multiply(E[0], V[0].vector))
+   *     const U = matrixFromColumns(...V.map(obj => obj.vector))
+   *     const UTxHxU = multiply(transpose(U), H, U) // diagonalizes H if possible
+   *     E[0] == UTxHxU[0][0]  // returns true always
+   *
+   *     // Compute only approximate eigenvalues:
+   *     const {values} = eigs(H, {eigenvectors: false, precision: 1e-6})
    *
    * See also:
    *
@@ -111,59 +144,98 @@ export var createEigs = /* #__PURE__ */factory(name, dependencies, _ref => {
    *
    * @param {Array | Matrix} x  Matrix to be diagonalized
    *
-   * @param {number | BigNumber} [prec] Precision, default value: 1e-15
-   * @return {{values: Array|Matrix, vectors: Array|Matrix}} Object containing an array of eigenvalues and a matrix with eigenvectors as columns.
+   * @param {number | BigNumber | OptsObject} [opts] Object with keys `precision`, defaulting to config.epsilon, and `eigenvectors`, defaulting to true and specifying whether to compute eigenvectors. If just a number, specifies precision.
+   * @return {{values: Array|Matrix, eigenvectors?: Array<EVobj>}} Object containing an array of eigenvalues and an array of {value: number|BigNumber, vector: Array|Matrix} objects. The eigenvectors property is undefined if eigenvectors were not requested.
    *
    */
   return typed('eigs', {
+    // The conversion to matrix in the first two implementations,
+    // just to convert back to an array right away in
+    // computeValuesAndVectors, is unfortunate, and should perhaps be
+    // streamlined. It is done because the Matrix object carries some
+    // type information about its entries, and so constructing the matrix
+    // is a roundabout way of doing type detection.
     Array: function Array(x) {
-      var mat = matrix(x);
-      return computeValuesAndVectors(mat);
+      return doEigs(matrix(x));
     },
     'Array, number|BigNumber': function ArrayNumberBigNumber(x, prec) {
-      var mat = matrix(x);
-      return computeValuesAndVectors(mat, prec);
+      return doEigs(matrix(x), {
+        precision: prec
+      });
+    },
+    'Array, Object'(x, opts) {
+      return doEigs(matrix(x), opts);
     },
     Matrix: function Matrix(mat) {
-      var {
-        values,
-        vectors
-      } = computeValuesAndVectors(mat);
-      return {
-        values: matrix(values),
-        vectors: matrix(vectors)
-      };
+      return doEigs(mat, {
+        matricize: true
+      });
     },
     'Matrix, number|BigNumber': function MatrixNumberBigNumber(mat, prec) {
-      var {
-        values,
-        vectors
-      } = computeValuesAndVectors(mat, prec);
-      return {
-        values: matrix(values),
-        vectors: matrix(vectors)
+      return doEigs(mat, {
+        precision: prec,
+        matricize: true
+      });
+    },
+    'Matrix, Object': function MatrixObject(mat, opts) {
+      var useOpts = {
+        matricize: true
       };
+      _extends(useOpts, opts);
+      return doEigs(mat, useOpts);
     }
   });
-  function computeValuesAndVectors(mat, prec) {
-    if (prec === undefined) {
-      prec = config.epsilon;
+  function doEigs(mat) {
+    var _opts$precision;
+    var opts = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var computeVectors = 'eigenvectors' in opts ? opts.eigenvectors : true;
+    var prec = (_opts$precision = opts.precision) !== null && _opts$precision !== void 0 ? _opts$precision : config.epsilon;
+    var result = computeValuesAndVectors(mat, prec, computeVectors);
+    if (opts.matricize) {
+      result.values = matrix(result.values);
+      if (computeVectors) {
+        result.eigenvectors = result.eigenvectors.map(_ref2 => {
+          var {
+            value,
+            vector
+          } = _ref2;
+          return {
+            value,
+            vector: matrix(vector)
+          };
+        });
+      }
+    }
+    if (computeVectors) {
+      Object.defineProperty(result, 'vectors', {
+        enumerable: false,
+        // to make sure that the eigenvectors can still be
+        // converted to string.
+        get: () => {
+          throw new Error('eigs(M).vectors replaced with eigs(M).eigenvectors');
+        }
+      });
     }
-    var size = mat.size();
-    if (size.length !== 2 || size[0] !== size[1]) {
-      throw new RangeError('Matrix must be square (size: ' + format(size) + ')');
+    return result;
+  }
+  function computeValuesAndVectors(mat, prec, computeVectors) {
+    var arr = mat.toArray(); // NOTE: arr is guaranteed to be unaliased
+    // and so safe to modify in place
+    var asize = mat.size();
+    if (asize.length !== 2 || asize[0] !== asize[1]) {
+      throw new RangeError("Matrix must be square (size: ".concat(format(asize), ")"));
     }
-    var arr = mat.toArray();
-    var N = size[0];
+    var N = asize[0];
     if (isReal(arr, N, prec)) {
-      coerceReal(arr, N);
+      coerceReal(arr, N); // modifies arr by side effect
+
       if (isSymmetric(arr, N, prec)) {
-        var _type = coerceTypes(mat, arr, N);
-        return doRealSymetric(arr, N, prec, _type);
+        var _type = coerceTypes(mat, arr, N); // modifies arr by side effect
+        return doRealSymmetric(arr, N, prec, _type, computeVectors);
       }
     }
-    var type = coerceTypes(mat, arr, N);
-    return doComplexEigs(arr, N, prec, type);
+    var type = coerceTypes(mat, arr, N); // modifies arr by side effect
+    return doComplexEigs(arr, N, prec, type, computeVectors);
   }
 
   /** @return {boolean} */

package/lib/esm/utils/number.js

@@ -583,7 +583,7 @@ export function nearlyEqual(x, y, epsilon) {
   if (isFinite(x) && isFinite(y)) {
     // check numbers are very close, needed when comparing numbers near zero
     var diff = Math.abs(x - y);
-    if (diff < DBL_EPSILON) {
+    if (diff <= DBL_EPSILON) {
       return true;
     } else {
       // use relative error

package/lib/esm/version.js

@@ -1,3 +1,3 @@
-export var version = '11.12.0';
+export var version = '12.0.0';
 // Note: This file is automatically generated when building math.js.
 // Changes made in this file will be overwritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mathjs",
-  "version": "11.12.0",
+  "version": "12.0.0",
   "description": "Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser with support for symbolic computation, comes with a large set of built-in functions and constants, and offers an integrated solution to work with different data types like numbers, big numbers, complex numbers, fractions, units, and matrices.",
   "author": "Jos de Jong <wjosdejong@gmail.com> (https://github.com/josdejong)",
   "homepage": "https://mathjs.org",
@@ -169,7 +169,7 @@
     "mathjs": "./bin/cli.js"
   },
   "engines": {
-    "node": ">= 14"
+    "node": ">= 18"
   },
   "bugs": {
     "url": "https://github.com/josdejong/mathjs/issues"

package/types/EXPLANATION.md

@@ -0,0 +1,54 @@
+# Mathjs TypeScript types
+
+The code base of Mathjs is writting in JavaScript. The TypeScript definitions are maintained separately. 
+
+## Library structure
+
+The over all structure is:
+
+- The library exports the core function `create` which creates a MathJS instance and returns `MathJsInstance`.
+- Mathjs has a special function `chain`, which allows you to use the functions in a chained way, like `chain(2).add(3).done()`. The function `chain` returns an interface `MathJsChain`, which contains all mathjs functions and constants as a method. Unlike the static functions, these methods are defined with the chain instance `this` as first argument.
+- The library exports collections with factory functions of all functions and their dependencies. To create an instance of the function `add`, one can do `create(addDependencies)` for example. To import all functions, one can do `create(all)`.
+- The library also returns a static instance, which can directly be used like `import { add } from 'mathjs'`.
+
+## Defining the types of a new function
+
+Maintaining the TypeScript types is done manually. When adding a function, one has to create the following TypeScript definitions:
+
+1. Add a normal definition inside `interface MathJsInstance {...}`
+2. Add a chained definition inside `interface MathJsChain {...}`
+3. Add a static definition inside `export const {...} : MathJsInstance`
+4. Add a dependencies definition inside `export const {...} : Record<string, FactoryFunctionMap>`
+
+For exampe for the function `add`, we can have the following definitions:
+
+```ts 
+// instance
+export interface MathJsInstance extends MathJsFactory {
+  //...
+  add<T extends MathType>(x: T, y: T): T
+  //...
+}
+
+// chain
+export interface MathJsChain<TValue> {
+  //...  
+  add<T extends MathType>(this: MathJsChain<T>, y: T): MathJsChain<T>
+  //...
+}
+
+// static
+export const {
+  // ...
+  add,
+  // ...
+} : MathJsInstance
+
+
+// dependencies
+export const {
+  // ...
+  addDependencies,
+  // ...
+} : Record<string, FactoryFunctionMap>
+```