mathjs 11.12.0 → 12.1.0

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/function/probability/pickRandom.js

@@ -52,8 +52,8 @@ export var createPickRandom = /* #__PURE__ */factory(name, dependencies, _ref =>
    * @param {Array | Matrix} array     A one dimensional array
    * @param {Int} number               An int or float
    * @param {Array | Matrix} weights   An array of ints or floats
-   * @return {number | Array}          Returns a single random value from array when number is 1 or undefined.
-   *                                   Returns an array with the configured number of elements when number is > 1.
+   * @return {number | Array}          Returns a single random value from array when number is undefined.
+   *                                   Returns an array with the configured number of elements when number is defined.
    */
   return typed(name, {
     'Array | Matrix': function ArrayMatrix(possibles) {

package/lib/esm/type/number.js

@@ -43,7 +43,7 @@ function makeNumberFromNonDecimalParts(parts) {
   }
   var result = n + f;
   if (isNaN(result)) {
-    throw new SyntaxError('String "' + parts.input + '" is no valid number');
+    throw new SyntaxError('String "' + parts.input + '" is not a valid number');
   }
   return result;
 }
@@ -99,7 +99,7 @@ export var createNumber = /* #__PURE__ */factory(name, dependencies, _ref => {
       }
       var num = Number(x);
       if (isNaN(num)) {
-        throw new SyntaxError('String "' + x + '" is no valid number');
+        throw new SyntaxError('String "' + x + '" is not a valid number');
       }
       if (wordSizeSuffixMatch) {
         // x is a signed bin, oct, or hex literal

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.1.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.1.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",
@@ -36,29 +36,29 @@
     "typed-function": "^4.1.1"
   },
   "devDependencies": {
-    "@babel/core": "7.23.2",
-    "@babel/plugin-transform-object-assign": "7.22.5",
-    "@babel/plugin-transform-runtime": "7.23.2",
-    "@babel/preset-env": "7.23.2",
+    "@babel/core": "7.23.3",
+    "@babel/plugin-transform-object-assign": "7.23.3",
+    "@babel/plugin-transform-runtime": "7.23.3",
+    "@babel/preset-env": "7.23.3",
     "@babel/register": "7.22.15",
-    "@types/assert": "1.5.8",
-    "@types/mocha": "10.0.3",
-    "@typescript-eslint/eslint-plugin": "6.9.0",
-    "@typescript-eslint/parser": "6.9.0",
+    "@types/assert": "1.5.9",
+    "@types/mocha": "10.0.4",
+    "@typescript-eslint/eslint-plugin": "6.11.0",
+    "@typescript-eslint/parser": "6.11.0",
     "assert": "2.1.0",
     "babel-loader": "9.1.3",
     "benchmark": "2.1.4",
     "c8": "8.0.1",
     "codecov": "3.8.3",
-    "core-js": "3.33.1",
+    "core-js": "3.33.2",
     "del": "6.1.1",
     "dtslint": "4.2.1",
-    "eslint": "8.52.0",
+    "eslint": "8.53.0",
     "eslint-config-prettier": "9.0.0",
     "eslint-config-standard": "17.1.0",
     "eslint-plugin-import": "2.29.0",
     "eslint-plugin-mocha": "10.2.0",
-    "eslint-plugin-n": "16.2.0",
+    "eslint-plugin-n": "16.3.1",
     "eslint-plugin-prettier": "5.0.1",
     "eslint-plugin-promise": "6.1.1",
     "expect-type": "0.17.3",
@@ -85,7 +85,7 @@
     "ndarray-pack": "1.2.1",
     "numericjs": "1.2.6",
     "pad-right": "0.2.2",
-    "prettier": "3.0.3",
+    "prettier": "3.1.0",
     "process": "0.11.10",
     "sylvester": "0.0.21",
     "ts-node": "10.9.1",
@@ -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>
+```