mathjs 9.2.0 → 9.4.0

package/HISTORY.md

@@ -1,6 +1,52 @@
 # History
 
-# 2020-02-03, version 9.2.0
+# 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. 
+  Regression introduced in `v9.3.1`.
+
+
+# 2021-04-10, version 9.3.1
+
+- Fix #2133: strongly improved the performance of `isPrime`, see #2139. 
+  Thanks @Yaffle.
+- Fix #2150: give a clear error "Error: Undefined function ..." instead when
+  evaluating a non-existing function.
+- Fix #660: expose internal functions `FunctionNode.onUndefinedFunction(name)` 
+  and `SymbolNode.onUndefinedSymbol(name)`, allowing to override the behavior.
+  By default, an Error is thrown.
+
+
+# 2021-03-10, version 9.3.0
+
+- Implemented support for parsing non decimal numbers with radix point,
+  see #2122, #2121. Thanks @clnhlzmn.
+- Fix #2128: typo in docs of `luSolveAll` and `usolveAll`.
+
+
+# 2021-02-03, version 9.2.0
 
 - Implemented function `count` to count the total elements in a matrix, 
   see #2085. Thanks @Josef37.

package/README.md

@@ -10,7 +10,8 @@ Math.js is an extensive math library for JavaScript and Node.js. It features a f
 [![Maintenance](https://img.shields.io/maintenance/yes/2021.svg)](https://github.com/josdejong/mathjs/graphs/commit-activity)
 [![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)
-[![Slack](https://slack.bri.im/badge.svg)](https://slack.bri.im)
+[![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
 
@@ -102,7 +103,7 @@ Then, the project can be build by executing the build script via npm:
 
     npm run build
 
-This will build ESM output, CommonJS output, and the bundle math.js 
+This will build ESM output, CommonJS output, and the bundle math.js
 from the source files and put them in the folder lib.
 
 
@@ -116,8 +117,8 @@ The code of `mathjs` is written in ES modules, and requires all files to have a
 
 ### Architecture
 
-What mathjs tries to achieve is to offer an environment where you can do calculations with mixed data types, 
-like multiplying a regular `number` with a `Complex` number or a `BigNumber`, and work with all of those in matrices. 
+What mathjs tries to achieve is to offer an environment where you can do calculations with mixed data types,
+like multiplying a regular `number` with a `Complex` number or a `BigNumber`, and work with all of those in matrices.
 Mathjs also allows to add a new data type, like say `BigInt`, with little effort.
 
 The solution that mathjs uses has two main ingredients:
@@ -130,7 +131,7 @@ At the lowest level, mathjs has immutable factory functions which create immutab
 
 ### Build scripts
 
-The build script currently generates two types of output: 
+The build script currently generates two types of output:
 
 - **any**, generate entry points to create full versions of all functions
 - **number**: generating and entry points to create lightweight functions just supporting `number`

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/datatypes/matrices.md

@@ -184,6 +184,21 @@ const c = [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
 math.size(c)                                  // Array, [2, 2, 3]
 ```
 
+Note that the dimensions themselves do not have a meaning attached. 
+When creating and printing a two dimensional matrix, the first dimension is 
+normally rendered as the _column_, and the second dimension is rendered as 
+the _row_. For example:
+
+```js
+console.table(math.zeros([2, 4]))
+// 0 0 0 0
+// 0 0 0 0
+```
+
+If you have a matrix where the first dimension means `x` and the second 
+means `y`, this will look confusing since `x` is printed as _column_ 
+(vertically) and `y` as _row_ (horizontally).
+
 
 ## Resizing
 

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/expressions/syntax.md

@@ -299,6 +299,13 @@ math.evaluate('0xffffffffi32')  //  -1
 math.evaluate('0xfffffffffi32') //  SyntaxError: String "0xfffffffff" is out of range
 ```
 
+Non decimal numbers can include a radix point:
+```js
+math.evaluate('0b1.1')         // 1.5
+math.evaluate('0o1.4')         // 1.5
+math.evaluate('0x1.8')         // 1.5
+```
+
 Numbers can be formatted as binary, octal, and hex strings using the `notation` option of the `format` function:
 
 ```js

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/lsolveAll.md

@@ -10,7 +10,7 @@ Finds all solutions of a linear equation system by forwards substitution. Matrix
 ## Syntax
 
 ```js
-math.lsolve(L, b)
+math.lsolveAll(L, b)
 ```
 
 ### Parameters
@@ -32,7 +32,7 @@ DenseMatrix[] | Array[] | An array of affine-independent column vectors (x)
 ```js
 const a = [[-2, 3], [2, 1]]
 const b = [11, 9]
-const x = lsolve(a, b)  // [ [[-5.5], [20]] ]
+const x = lsolveAll(a, b)  // [ [[-5.5], [20]] ]
 ```
 
 

package/docs/reference/functions/matrixFromColumns.md

@@ -0,0 +1,43 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function matrixFromColumns
+
+Create a dense matrix from vectors as individual columns.
+If you pass row vectors, they will be transposed (but not conjugated!)
+
+
+## Syntax
+
+```js
+math.matrixFromColumns(...arr)
+math.matrixFromColumns(col1, col2)
+math.matrixFromColumns(col1, col2, col3)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`cols` | ... Array &#124; Matrix | Multiple columns
+
+### Returns
+
+Type | Description
+---- | -----------
+number[][] &#124; Matrix | if at least one of the arguments is an array, an array will be returned
+
+
+## Examples
+
+```js
+math.matrixFromColumns([1, 2, 3], [[4],[5],[6]])
+math.matrixFromColumns(...vectors)
+```
+
+
+## See also
+
+[matrix](matrix.md),
+[matrixFromRows](matrixFromRows.md),
+[matrixFromFunction](matrixFromFunction.md),
+[zeros](zeros.md)

package/docs/reference/functions/matrixFromFunction.md

@@ -0,0 +1,48 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# 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
+
+```js
+math.matrixFromFunction(size, fn)
+math.matrixFromFunction(size, fn, format)
+math.matrixFromFunction(size, fn, format, datatype)
+math.matrixFromFunction(size, format, fn)
+math.matrixFromFunction(size, format, datatype, fn)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`size` | Array &#124; 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 &#124; Matrix | Returns the created matrix
+
+
+## Examples
+
+```js
+math.matrixFromFunction([3,3], i => i[0] - i[1]) // an antisymmetric matrix
+math.matrixFromFunction([100, 100], 'sparse', i => i[0] - i[1] === 1 ? 4 : 0) // a sparse subdiagonal matrix
+math.matrixFromFunction([5], i => math.random()) // a random vector
+```
+
+
+## See also
+
+[matrix](matrix.md),
+[zeros](zeros.md)

package/docs/reference/functions/matrixFromRows.md

@@ -0,0 +1,43 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function matrixFromRows
+
+Create a dense matrix from vectors as individual rows.
+If you pass column vectors, they will be transposed (but not conjugated!)
+
+
+## Syntax
+
+```js
+math.matrixFromRows(...arr)
+math.matrixFromRows(row1, row2)
+math.matrixFromRows(row1, row2, row3)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`rows` | ... Array &#124; Matrix | Multiple rows
+
+### Returns
+
+Type | Description
+---- | -----------
+number[][] &#124; Matrix | if at least one of the arguments is an array, an array will be returned
+
+
+## Examples
+
+```js
+math.matrixFromRows([1, 2, 3], [[4],[5],[6]])
+math.matrixFromRows(...vectors)
+```
+
+
+## See also
+
+[matrix](matrix.md),
+[matrixFromColumns](matrixFromColumns.md),
+[matrixFromFunction](matrixFromFunction.md),
+[zeros](zeros.md)

package/docs/reference/functions/usolveAll.md

@@ -10,7 +10,7 @@ Finds all solutions of a linear equation system by backward substitution. Matrix
 ## Syntax
 
 ```js
-math.usolve(U, b)
+math.usolveAll(U, b)
 ```
 
 ### Parameters
@@ -32,7 +32,7 @@ DenseMatrix[] | Array[] | An array of affine-independent column vectors (x)
 ```js
 const a = [[-2, 3], [2, 1]]
 const b = [11, 9]
-const x = usolve(a, b)  // [ [[8], [9]] ]
+const x = usolveAll(a, b)  // [ [[8], [9]] ]
 ```
 
 

package/docs/reference/functions.md

@@ -15,7 +15,7 @@ Function | Description
 ---- | -----------
 [derivative(expr, variable)](functions/derivative.md) | Takes the derivative of an expression expressed in parser Nodes.
 [math.lsolve(L, b)](functions/lsolve.md) | Finds one solution of a linear equation system by forwards substitution.
-[math.lsolve(L, b)](functions/lsolveAll.md) | Finds all solutions of a linear equation system by forwards substitution.
+[math.lsolveAll(L, b)](functions/lsolveAll.md) | Finds all solutions of a linear equation system by forwards substitution.
 [math.lup(A)](functions/lup.md) | Calculate the Matrix LU decomposition with partial pivoting.
 [math.lusolve(A, b)](functions/lusolve.md) | Solves the linear system `A * x = b` where `A` is an [n x n] matrix and `b` is a [n] column vector.
 [math.qr(A)](functions/qr.md) | Calculate the Matrix QR decomposition.
@@ -23,7 +23,7 @@ Function | Description
 [simplify(expr)](functions/simplify.md) | Simplify an expression tree.
 [math.slu(A, order, threshold)](functions/slu.md) | Calculate the Sparse Matrix LU decomposition with full pivoting.
 [math.usolve(U, b)](functions/usolve.md) | Finds one solution of a linear equation system by backward substitution.
-[math.usolve(U, b)](functions/usolveAll.md) | Finds all solutions of a linear equation system by backward substitution.
+[math.usolveAll(U, b)](functions/usolveAll.md) | Finds all solutions of a linear equation system by backward substitution.
 
 ## Arithmetic functions
 
@@ -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.