mathjs 11.11.2 → 12.0.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/type/unit/Unit.js

@@ -9,13 +9,13 @@ import { endsWith } from '../../utils/string.js';
 import { clone, hasOwnProperty } from '../../utils/object.js';
 import { createBigNumberPi as createPi } from '../../utils/bignumber/constants.js';
 var name = 'Unit';
-var dependencies = ['?on', 'config', 'addScalar', 'subtract', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'number', 'Complex', 'BigNumber', 'Fraction'];
+var dependencies = ['?on', 'config', 'addScalar', 'subtractScalar', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'number', 'Complex', 'BigNumber', 'Fraction'];
 export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref => {
   var {
     on,
     config,
     addScalar,
-    subtract,
+    subtractScalar,
     multiplyScalar,
     divideScalar,
     pow,
@@ -741,7 +741,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
         var unitValue = convert(ret.units[0].unit.value);
         var nominalOffset = convert(ret.units[0].unit.offset);
         var unitOffset = multiplyScalar(unitValue, nominalOffset);
-        ret.value = subtract(abs(addScalar(ret.value, unitOffset)), unitOffset);
+        ret.value = subtractScalar(abs(addScalar(ret.value, unitOffset)), unitOffset);
       }
     }
     for (var i in ret.units) {
@@ -786,7 +786,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
       var otherUnitValue = other.units[0].unit.value;
       var otherNominalOffset = other.units[0].unit.offset;
       var otherUnitOffset = multiplyScalar(otherUnitValue, otherNominalOffset);
-      other.value = addScalar(value, convert(subtract(thisUnitOffset, otherUnitOffset)));
+      other.value = addScalar(value, convert(subtractScalar(thisUnitOffset, otherUnitOffset)));
     }
     other.fixPrefix = true;
     other.skipAutomaticSimplification = true;
@@ -1162,7 +1162,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
       }
       var y = new Unit(xFixed, parts[i].toString());
       ret.push(y);
-      x = subtract(x, y);
+      x = subtractScalar(x, y);
     }
 
     // This little bit fixes a bug where the remainder should be 0 but is a little bit off.

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/utils/object.js

@@ -1,4 +1,4 @@
-import { isBigNumber } from './is.js';
+import { isBigNumber, isObject } from './is.js';
 
 /**
  * Clone an object
@@ -32,10 +32,12 @@ export function clone(x) {
   }
   if (x instanceof Date) return new Date(x.valueOf());
   if (isBigNumber(x)) return x; // bignumbers are immutable
-  if (x instanceof RegExp) throw new TypeError('Cannot clone ' + x); // TODO: clone a RegExp
 
   // object
-  return mapObject(x, clone);
+  if (isObject(x)) {
+    return mapObject(x, clone);
+  }
+  throw new TypeError("Cannot clone: unknown type of value (value: ".concat(x, ")"));
 }
 
 /**

package/lib/esm/utils/snapshot.js

@@ -131,7 +131,7 @@ export function createSnapshotFromFactories(factories) {
       embeddedDocs[name] = 'Object';
     }
   });
-  embeddedDocs = exclude(embeddedDocs, ['equalScalar', 'apply', 'addScalar', 'multiplyScalar', 'print', 'divideScalar', 'parse', 'compile', 'parser', 'chain', 'reviver', 'replacer']);
+  embeddedDocs = exclude(embeddedDocs, ['equalScalar', 'apply', 'addScalar', 'subtractScalar', 'multiplyScalar', 'print', 'divideScalar', 'parse', 'compile', 'parser', 'chain', 'reviver', 'replacer']);
   var allTypeChecks = {};
   Object.keys(allIsFunctions).forEach(name => {
     if (name.indexOf('is') === 0) {

package/lib/esm/utils/string.js

@@ -81,7 +81,7 @@ function _format(value, options) {
     return formatArray(value, options);
   }
   if (isString(value)) {
-    return '"' + value + '"';
+    return stringify(value);
   }
   if (typeof value === 'function') {
     return value.syntax ? String(value.syntax) : 'function';
@@ -94,7 +94,7 @@ function _format(value, options) {
       return value.toString(options);
     } else {
       var entries = Object.keys(value).map(key => {
-        return '"' + key + '": ' + format(value[key], options);
+        return stringify(key) + ': ' + format(value[key], options);
       });
       return '{' + entries.join(', ') + '}';
     }
@@ -114,24 +114,20 @@ export function stringify(value) {
   var i = 0;
   while (i < text.length) {
     var c = text.charAt(i);
-    if (c === '\\') {
-      escaped += c;
-      i++;
-      c = text.charAt(i);
-      if (c === '' || '"\\/bfnrtu'.indexOf(c) === -1) {
-        escaped += '\\'; // no valid escape character -> escape it
-      }
-
-      escaped += c;
-    } else if (c === '"') {
-      escaped += '\\"';
-    } else {
-      escaped += c;
-    }
+    escaped += c in controlCharacters ? controlCharacters[c] : c;
     i++;
   }
   return '"' + escaped + '"';
 }
+var controlCharacters = {
+  '"': '\\"',
+  '\\': '\\\\',
+  '\b': '\\b',
+  '\f': '\\f',
+  '\n': '\\n',
+  '\r': '\\r',
+  '\t': '\\t'
+};
 
 /**
  * Escape special HTML characters

package/lib/esm/version.js

@@ -1,3 +1,3 @@
-export var version = '11.11.2';
+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.11.2",
+  "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",
@@ -25,7 +25,7 @@
     "unit"
   ],
   "dependencies": {
-    "@babel/runtime": "^7.23.1",
+    "@babel/runtime": "^7.23.2",
     "complex.js": "^2.1.1",
     "decimal.js": "^10.4.3",
     "escape-latex": "^1.2.0",
@@ -36,27 +36,27 @@
     "typed-function": "^4.1.1"
   },
   "devDependencies": {
-    "@babel/core": "7.23.0",
+    "@babel/core": "7.23.2",
     "@babel/plugin-transform-object-assign": "7.22.5",
-    "@babel/plugin-transform-runtime": "7.22.15",
-    "@babel/preset-env": "7.22.20",
+    "@babel/plugin-transform-runtime": "7.23.2",
+    "@babel/preset-env": "7.23.2",
     "@babel/register": "7.22.15",
-    "@types/assert": "1.5.7",
-    "@types/mocha": "10.0.2",
-    "@typescript-eslint/eslint-plugin": "6.7.5",
-    "@typescript-eslint/parser": "6.7.5",
+    "@types/assert": "1.5.8",
+    "@types/mocha": "10.0.3",
+    "@typescript-eslint/eslint-plugin": "6.9.0",
+    "@typescript-eslint/parser": "6.9.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.0",
+    "core-js": "3.33.1",
     "del": "6.1.1",
     "dtslint": "4.2.1",
-    "eslint": "8.51.0",
+    "eslint": "8.52.0",
     "eslint-config-prettier": "9.0.0",
     "eslint-config-standard": "17.1.0",
-    "eslint-plugin-import": "2.28.1",
+    "eslint-plugin-import": "2.29.0",
     "eslint-plugin-mocha": "10.2.0",
     "eslint-plugin-n": "16.2.0",
     "eslint-plugin-prettier": "5.0.1",
@@ -90,7 +90,7 @@
     "sylvester": "0.0.21",
     "ts-node": "10.9.1",
     "typescript": "5.2.2",
-    "webpack": "5.88.2",
+    "webpack": "5.89.0",
     "zeros": "1.0.0"
   },
   "type": "module",
@@ -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>
+```