mathjs 9.3.2 → 9.4.0

package/HISTORY.md

@@ -1,5 +1,27 @@
 # History
 
+# 2021-05-16, version 9.4.0
+
+- Implemented support to use objects with a `Map` interface as scope, 
+  see #2143, #2166. Thanks @jhugman.
+- Extend `eigs` to support general complex matrices, see #1741. Thanks @m93a.
+- DenseMatrix and SparseMatrix are now iterable, see #1184. Thanks @m93a.
+- Implemented utility functions `matrixFromRows`, `matrixFromColumns`, and 
+  `matrixFromFunction`, see #2155, #2153. Thanks @m93a.
+- Added TypeScript definitions to the project, making it redundant to install
+  `@types/mathjs`, and making it easier to improve the definitions. See #2187, 
+  #2192. Thanks @CatsMiaow.
+- Upgraded dependencies
+  - `complex.js@2.0.13` (fixing #2211). Thanks @infusion
+  - `fraction.js@4.1.0` (`pow` now supporting rational exponents).
+- Fix #2174: function `pickRandom` having no name. Thanks @HK-SHAO.
+- Fix #2019: VSCode auto import keeps adding import { null } from 'mathjs'.
+- Fix #2185: Fix TypeScript definition of unit division, which can also return 
+  a number.
+- Fix #2123: add type definitions for functions `row` and `column`.
+- Fix some files not exposed in the package, see #2213. Thanks @javiermarinros.
+
+
 # 2021-04-12, version 9.3.2
 
 - Fix #2169: mathjs requesting `@babel/runtime` dependency. 

package/README.md

@@ -11,6 +11,7 @@ Math.js is an extensive math library for JavaScript and Node.js. It features a f
 [![License](https://img.shields.io/github/license/josdejong/mathjs.svg)](https://github.com/josdejong/mathjs/blob/master/LICENSE)
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs?ref=badge_shield)
 [![Codecov](https://codecov.io/gh/josdejong/mathjs/branch/develop/graph/badge.svg)](https://codecov.io/gh/josdejong/mathjs)
+[![Github Sponsor](https://camo.githubusercontent.com/7d9333b097b2f54a8957d126ab82937811489c9b75c3850f609985cf94cd29fe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2532302d53706f6e736f722532306d652532306f6e2532304769744875622d6f72616e6765)](https://github.com/sponsors/josdejong)
 
 ## Features
 

package/bin/cli.js

@@ -45,9 +45,10 @@
  * the License.
  */
 
-let scope = {}
 const fs = require('fs')
 const path = require('path')
+const { createEmptyMap } = require('../lib/cjs/utils/map.js')
+let scope = createEmptyMap()
 
 const PRECISION = 14 // decimals
 
@@ -95,11 +96,9 @@ function completer (text) {
     keyword = m[0]
 
     // scope variables
-    for (const def in scope) {
-      if (hasOwnProperty(scope, def)) {
-        if (def.indexOf(keyword) === 0) {
-          matches.push(def)
-        }
+    for (const def in scope.keys()) {
+      if (def.indexOf(keyword) === 0) {
+        matches.push(def)
       }
     }
 
@@ -199,7 +198,7 @@ function runStream (input, output, mode, parenthesis) {
         break
       case 'clear':
         // clear memory
-        scope = {}
+        scope = createEmptyMap()
         console.log('memory cleared')
 
         // get next input
@@ -231,16 +230,17 @@ function runStream (input, output, mode, parenthesis) {
                 if (math.isAssignmentNode(node)) {
                   const name = findSymbolName(node)
                   if (name !== null) {
-                    scope.ans = scope[name]
-                    console.log(name + ' = ' + format(scope[name]))
+                    const value = scope.get(name)
+                    scope.set('ans', value)
+                    console.log(name + ' = ' + format(value))
                   } else {
-                    scope.ans = res
+                    scope.set('ans', res)
                     console.log(format(res))
                   }
                 } else if (math.isHelp(res)) {
                   console.log(res.toString())
                 } else {
-                  scope.ans = res
+                  scope.set('ans', res)
                   console.log(format(res))
                 }
               }

package/docs/expressions/parsing.md

@@ -22,8 +22,8 @@ math.evaluate([expr1, expr2, expr3, ...], scope)
 
 Function `evaluate` accepts a single expression or an array with
 expressions as the first argument and has an optional second argument
-containing a scope with variables and functions. The scope is a regular
-JavaScript Object. The scope will be used to resolve symbols, and to write
+containing a scope with variables and functions. The scope can be a regular
+JavaScript Object, or Map. The scope will be used to resolve symbols, and to write
 assigned variables or function.
 
 The following code demonstrates how to evaluate expressions.
@@ -70,7 +70,7 @@ const result = code.evaluate([scope]) // evaluate the code with an optional scop
 An expression needs to be compiled only once, after which the
 expression can be evaluated repeatedly and against different scopes.
 The optional scope is used to resolve symbols and to write assigned
-variables or functions. Parameter `scope` is a regular Object.
+variables or functions. Parameter [`scope`](#scope) can be a regular Object, or Map.
 
 Example usage:
 
@@ -107,7 +107,7 @@ The API of nodes is described in detail on the page
 An expression needs to be parsed and compiled only once, after which the
 expression can be evaluated repeatedly. On evaluation, an optional scope
 can be provided, which is used to resolve symbols and to write assigned
-variables or functions. Parameter `scope` is a regular Object.
+variables or functions. Parameter [`scope`](#scope) is a regular Object or Map.
 
 Example usage:
 
@@ -205,3 +205,20 @@ parser.evaluate('hello("user")')        // "hello, user!"
 // clear defined functions and variables
 parser.clear()
 ```
+
+## Scope
+
+The scope is a data-structure used to store and lookup variables and functions defined and used by expressions.
+
+It is passed to mathjs via calls to [`math.evaluate`](#evaluate) or `simplify`.
+
+For ease of use, it can be a Plain Javascript Object; for safety it can be a plain `Map` and for flexibility, any object that has
+the methods `get`/`set`/`has`/`keys`, seen on `Map`.
+
+Some care is taken to mutate the same object that is passed into mathjs, so they can collect the definitions from mathjs scripts and expressions.
+
+`evaluate` will fail if the expression uses a blacklisted symbol, preventing mathjs expressions to escape into Javascript. This is enforced by access to the scope.
+
+For less reliance on this blacklist, scope can also be a `Map`, which allows mathjs expressions to define variables and functions of any name.
+
+For more, see [examples of custom scopes][../../examples/advanced/custom_scope_objects.js.html].

package/docs/reference/functions/complex.md

@@ -2,60 +2,16 @@
 
 # Function complex
 
-Create a complex value or convert a value to a complex value.
 
 
-## Syntax
-
-```js
-math.complex()                           // creates a complex value with zero
-                                         // as real and imaginary part.
-math.complex(re : number, im : string)   // creates a complex value with provided
-                                         // values for real and imaginary part.
-math.complex(re : number)                // creates a complex value with provided
-                                         // real value and zero imaginary part.
-math.complex(complex : Complex)          // clones the provided complex value.
-math.complex(arg : string)               // parses a string into a complex value.
-math.complex(array : Array)              // converts the elements of the array
-                                         // or matrix element wise into a
-                                         // complex value.
-math.complex({re: number, im: number})   // creates a complex value with provided
-                                         // values for real an imaginary part.
-math.complex({r: number, phi: number})   // creates a complex value with provided
-                                         // polar coordinates
-```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`args` | * | Array | Matrix |  Arguments specifying the real and imaginary part of the complex number
-
-### Returns
-
-Type | Description
----- | -----------
-Complex | Array | Matrix | Returns a complex value
-
-
-## Examples
-
-```js
-const a = math.complex(3, -4)     // a = Complex 3 - 4i
-a.re = 5                          // a = Complex 5 - 4i
-const i = a.im                    // Number -4
-const b = math.complex('2 + 6i')  // Complex 2 + 6i
-const c = math.complex()          // Complex 0 + 0i
-const d = math.add(a, b)          // Complex 5 + 2i
-```
-
-
-## See also
+`arr` | number[][] | the matrix to find eigenvalues of
+`N` | number | size of the matrix
+`prec` | number | BigNumber | precision, anything lower will be considered zero
+`type` | 'number' | 'BigNumber' | 'Complex' | 
+`findVectors` | boolean | should we find eigenvectors?
 
-[bignumber](bignumber.md),
-[boolean](boolean.md),
-[index](index.md),
-[matrix](matrix.md),
-[number](number.md),
-[string](string.md),
-[unit](unit.md)

package/docs/reference/functions/eigs.md

@@ -2,19 +2,17 @@
 
 # Function eigs
 
-Compute eigenvalue and eigenvector of a real symmetric matrix.
-Only applicable to two dimensional symmetric matrices. Uses Jacobi
-Algorithm. Matrix containing mixed type ('number', 'bignumber', 'fraction')
-of elements are not supported. Input matrix or 2D array should contain all elements
-of either 'number', 'bignumber' or 'fraction' type. For 'number' and 'fraction', the
-eigenvalues are of 'number' type. For 'bignumber' the eigenvalues are of ''bignumber' type.
-Eigenvectors are always of 'number' type.
+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
+in `err.values` and `err.vectors`.
 
 
 ## Syntax
 
 ```js
-math.eigs(x)
+math.eigs(x, [prec])
 ```
 
 ### Parameters
@@ -22,23 +20,25 @@ math.eigs(x)
 Parameter | Type | Description
 --------- | ---- | -----------
 `x` | Array | Matrix | Matrix to be diagonalized
+`prec` | number | BigNumber | Precision, default value: 1e-15
 
 ### Returns
 
 Type | Description
 ---- | -----------
-{values: Array, vectors: Array} | {values: Matrix, vectors: Matrix} | Object containing eigenvalues (Array or Matrix) and eigenvectors (2D Array/Matrix with eigenvectors as columns).
+{values: Array | Matrix, vectors: Array | Matrix} | Object containing an array of eigenvalues and a matrix with eigenvectors as columns.
 
 
 ## Examples
 
 ```js
+const { eigs, multiply, column, transpose } = math
 const H = [[5, 2.3], [2.3, 1]]
-const ans = math.eigs(H) // returns {values: [E1,E2...sorted], vectors: [v1,v2.... corresponding vectors as columns]}
+const ans = eigs(H) // returns {values: [E1,E2...sorted], vectors: [v1,v2.... corresponding vectors as columns]}
 const E = ans.values
 const U = ans.vectors
-math.multiply(H, math.column(U, 0)) // returns math.multiply(E[0], math.column(U, 0))
-const UTxHxU = math.multiply(math.transpose(U), H, U) // rotates H to the eigen-representation
+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
 ```
 

package/docs/reference/functions/flatten.md

@@ -3,6 +3,7 @@
 # Function flatten
 
 Flatten a multi dimensional matrix into a single dimensional matrix.
+It is guaranteed to always return a clone of the argument.
 
 
 ## Syntax

package/docs/reference/functions/matrixFromColumns.md

@@ -18,7 +18,7 @@ math.matrixFromColumns(col1, col2, col3)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`cols` | ...Array | ...Matrix | 
+`cols` | ... Array | Matrix | Multiple columns
 
 ### Returns
 

package/docs/reference/functions/matrixFromFunction.md

@@ -3,6 +3,8 @@
 # Function matrixFromFunction
 
 Create a matrix by evaluating a generating function at each index.
+The simplest overload returns a multi-dimensional array as long as `size` is an array.
+Passing `size` as a Matrix or specifying a `format` will result in returning a Matrix.
 
 
 ## Syntax
@@ -19,6 +21,16 @@ math.matrixFromFunction(size, format, datatype, fn)
 
 Parameter | Type | Description
 --------- | ---- | -----------
+`size` | Array | Matrix | The size of the matrix to be created
+`fn` | function | Callback function invoked for every entry in the matrix
+`format` | string | The Matrix storage format, either `'dense'` or `'sparse'`
+`datatype` | string | Type of the values
+
+### Returns
+
+Type | Description
+---- | -----------
+Array | Matrix | Returns the created matrix
 
 
 ## Examples

package/docs/reference/functions/matrixFromRows.md

@@ -18,7 +18,7 @@ math.matrixFromRows(row1, row2, row3)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`rows` | ...Array | ...Matrix | 
+`rows` | ... Array | Matrix | Multiple rows
 
 ### Returns
 

package/docs/reference/functions.md

@@ -124,7 +124,7 @@ Function | Description
 [math.diag(X)](functions/diag.md) | Create a diagonal matrix or retrieve the diagonal of a matrix  When `x` is a vector, a matrix with vector `x` on the diagonal will be returned.
 [math.diff(arr)](functions/diff.md) | Create a new matrix or array of the difference between elements of the given array The optional dim parameter lets you specify the dimension to evaluate the difference of If no dimension parameter is passed it is assumed as dimension 0  Dimension is zero-based in javascript and one-based in the parser and can be a number or bignumber Arrays must be 'rectangular' meaning arrays like [1, 2] If something is passed as a matrix it will be returned as a matrix but other than that all matrices are converted to arrays.
 [math.dot(x, y)](functions/dot.md) | Calculate the dot product of two vectors.
-[math.eigs(x)](functions/eigs.md) | Compute eigenvalue and eigenvector of a real symmetric matrix.
+[math.eigs(x, [prec])](functions/eigs.md) | Compute eigenvalues and eigenvectors of a matrix.
 [math.expm(x)](functions/expm.md) | Compute the matrix exponential, expm(A) = e^A.
 [math.filter(x, test)](functions/filter.md) | Filter the items in an array or one dimensional matrix.
 [math.flatten(x)](functions/flatten.md) | Flatten a multi dimensional matrix into a single dimensional matrix.
@@ -134,6 +134,9 @@ Function | Description
 [math.inv(x)](functions/inv.md) | Calculate the inverse of a square matrix.
 [math.kron(x, y)](functions/kron.md) | Calculates the kronecker product of 2 matrices or vectors.
 [math.map(x, callback)](functions/map.md) | Create a new matrix or array with the results of the callback function executed on each entry of the matrix/array.
+[math.matrixFromColumns(...arr)](functions/matrixFromColumns.md) | Create a dense matrix from vectors as individual columns.
+[math.matrixFromFunction(size, fn)](functions/matrixFromFunction.md) | Create a matrix by evaluating a generating function at each index.
+[math.matrixFromRows(...arr)](functions/matrixFromRows.md) | Create a dense matrix from vectors as individual rows.
 [math.ones(m, n, p, ...)](functions/ones.md) | Create a matrix filled with ones.
 [math.partitionSelect(x, k)](functions/partitionSelect.md) | Partition-based selection of an array or 1D matrix.
 [math.range(start, end [, step])](functions/range.md) | Create an array from a range.

package/examples/advanced/custom_scope_objects.js

@@ -0,0 +1,115 @@
+const { create, all } = require('../..')
+
+const math = create(all)
+
+// The expression evaluator accepts an optional scope object.
+// This is the symbol table for variable defintions and function declations.
+
+// Scope can be a bare object.
+function withObjectScope () {
+  const scope = { x: 3 }
+
+  math.evaluate('x', scope) // 1
+  math.evaluate('y = 2 x', scope)
+  math.evaluate('scalar = 1', scope)
+  math.evaluate('area(length, width) = length * width * scalar', scope)
+  math.evaluate('A = area(x, y)', scope)
+
+  console.log('Object scope:', scope)
+}
+
+// Where flexibility is important, scope can duck type appear to be a Map.
+function withMapScope (scope, name) {
+  scope.set('x', 3)
+
+  math.evaluate('x', scope) // 1
+  math.evaluate('y = 2 x', scope)
+  math.evaluate('scalar = 1', scope)
+  math.evaluate('area(length, width) = length * width * scalar', scope)
+  math.evaluate('A = area(x, y)', scope)
+
+  console.log(`Map-like scope (${name}):`, scope.localScope)
+}
+
+// This is a minimal set of functions to look like a Map.
+class MapScope {
+  constructor () {
+    this.localScope = new Map()
+  }
+
+  get (key) {
+    // Remember to sanitize your inputs, or use
+    // a datastructure that isn't a footgun.
+    return this.localScope.get(key)
+  }
+
+  set (key, value) {
+    return this.localScope.set(key, value)
+  }
+
+  has (key) {
+    return this.localScope.has(key)
+  }
+
+  keys () {
+    return this.localScope.keys()
+  }
+}
+
+/*
+ * This is a more fully featured example, with all methods
+ * used in mathjs.
+ *
+ */
+class AdvancedMapScope extends MapScope {
+  constructor (parent) {
+    super()
+    this.parentScope = parent
+  }
+
+  get (key) {
+    return this.localScope.get(key) ?? this.parentScope?.get(key)
+  }
+
+  has (key) {
+    return this.localScope.has(key) ?? this.parentScope?.get(key)
+  }
+
+  keys () {
+    if (this.parentScope) {
+      return new Set([...this.localScope.keys(), ...this.parentScope.keys()])
+    } else {
+      return this.localScope.keys()
+    }
+  }
+
+  delete () {
+    return this.localScope.delete()
+  }
+
+  clear () {
+    return this.localScope.clear()
+  }
+
+  /**
+   * Creates a child scope from this one. This is used in function calls.
+   *
+   * @returns a new Map scope that has access to the symbols in the parent, but
+   * cannot overwrite them.
+   */
+  createSubScope () {
+    return new AdvancedMapScope(this)
+  }
+
+  toString () {
+    return this.localScope.toString()
+  }
+}
+
+withObjectScope()
+// Where safety is important, scope can also be a Map
+withMapScope(new Map(), 'simple Map')
+// Where flexibility is important, scope can duck type appear to be a Map.
+withMapScope(new MapScope(), 'MapScope example')
+// Extra methods allow even finer grain control.
+withMapScope(new AdvancedMapScope(), 'AdvancedScope example')