mathjs 10.2.0 → 10.3.0

package/HISTORY.md

@@ -1,5 +1,17 @@
 # History
 
+# 2021-03-02, version 10.3.0
+
+- Fix #1260: implement function `symbolicEqual` (#2424). Thanks @gwhitney.
+- Fix #2441, #2442: support passing a function as argument to functions created
+  in the expression parser (#2443). Thanks @gwhitney.
+- Fix #2325: improve documentation of subset indices (#2446). Thanks @gwhitney.
+- Fix #2439: fix a bug in `complexEigs` in which real-valued norms were 
+  inadvertently being typed as complex numbers (#2445). Thanks @gwhitney.
+- Fix #2436: improve documentation and error message of function `map` (#2457).
+  Thanks @gwhitney.
+
+
 # 2022-03-01, version 10.2.0
 
 - Implemented context options to control simplifications allowed in `simplify`, 

package/docs/expressions/syntax.md

@@ -138,8 +138,8 @@ math.evaluate('log(10000, 3 + 7)')  // 4
 math.evaluate('sin(pi / 4)')        // 0.7071067811865475
 ```
 
-New functions can be defined using the `function` keyword. Functions can be
-defined with multiple variables. Function assignments are limited: they can
+New functions can be defined by "assigning" an expression to a function call
+with one or more variables. Such function assignments are limited: they can
 only be defined on a single line.
 
 ```js
@@ -153,6 +153,35 @@ parser.evaluate('g(x, y) = x ^ y')
 parser.evaluate('g(2, 3)')  // 8
 ```
 
+Note that these function assignments do _not_ create closures; put another way,
+all free variables in mathjs are dynamic:
+
+```js
+const parser = math.parser()
+
+parser.evaluate('x = 7')
+parser.evaluate('h(y) = x + y')
+parser.evaluate('h(3)')         // 10
+parser.evaluate('x = 3')
+parser.evaluate('h(3)')         // 6, *not* 10
+```
+
+It is however possible to pass functions as parameters:
+
+```js
+const parser = math.parser()
+
+parser.evaluate('twice(func, x) = func(func(x))')
+parser.evaluate('twice(square, 2)')    // 16
+parser.evaluate('f(x) = 3*x')
+parser.evaluate('twice(f, 2)')         // 18
+
+// a simplistic "numerical derivative":
+parser.evaluate('eps = 1e-10')
+parser.evaluate('nd(f, x) = (f(x+eps) - func(x-eps))/(2*eps)')
+parser.evaluate('nd(square,2)')        // 4.000000330961484
+```
+
 Math.js itself heavily uses typed functions, which ensure correct inputs and
 throws meaningful errors when the input arguments are invalid. One can create
 a [typed-function](https://github.com/josdejong/typed-function) in the

package/docs/reference/functions/map.md

@@ -2,8 +2,15 @@
 
 # Function map
 
-Create a new matrix or array with the results of the callback function executed on
-each entry of the matrix/array.
+Create a new matrix or array with the results of a callback function executed on
+each entry of a given matrix/array.
+
+For each entry of the input, the callback is invoked with three arguments:
+the value of the entry, the index at which that entry occurs, and the full
+matrix/array being traversed. Note that because the matrix/array might be
+multidimensional, the "index" argument is always an array of numbers giving
+the index in each dimension. This is true even for vectors: the "index"
+argument is an array of length 1, rather than simply a number.
 
 
 ## Syntax
@@ -16,14 +23,14 @@ math.map(x, callback)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Matrix | Array | The matrix to iterate on.
-`callback` | Function | The callback method is invoked with three parameters: the value of the element, the index of the element, and the matrix being traversed.
+`x` | Matrix | Array | The input to iterate on.
+`callback` | Function |  The function to call (as described above) on each entry of the input
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix | array | Transformed map of x
+Matrix | array |  Transformed map of x; always has the same type and shape as x
 
 
 ### Throws
@@ -38,6 +45,16 @@ Type | Description
 math.map([1, 2, 3], function(value) {
   return value * value
 })  // returns [1, 4, 9]
+
+// The calling convention for the callback can cause subtleties:
+math.map([1, 2, 3], math.format)
+// throws TypeError: map attempted to call 'format(1,[0])' but argument 2 of type Array does not match expected type number or function or Object or string or boolean
+// [This happens because `format` _can_ take a second argument,
+// but its semantics don't match that of the 2nd argument `map` provides]
+
+// To avoid this error, use a function that takes exactly the
+// desired arguments:
+math.map([1, 2, 3], x => math.format(x)) // returns ['1', '2', '3']
 ```
 
 

package/docs/reference/functions/subset.md

@@ -17,7 +17,7 @@ math.subset(value, index, replacement [, defaultValue])  // replace a subset
 Parameter | Type | Description
 --------- | ---- | -----------
 `matrix` | Array | Matrix | string | An array, matrix, or string
-`index` | Index | An index containing ranges for each dimension
+`index` | Index |  For each dimension of the target, specifies an index or a list of indices to fetch or set. `subset` uses the cartesian product of the indices specified in each dimension.
 `replacement` | * | An array, matrix, or scalar. If provided, the subset is replaced with replacement. If not provided, the subset is returned
 `defaultValue` | * | Default value, filled in on new entries when the matrix is resized. If not provided, math.matrix elements will be left undefined. Default value: undefined.
 
@@ -44,8 +44,16 @@ math.subset(d, math.index([0, 1], 1))   // returns [[2], [4]]
 
 // replace a subset
 const e = []
-const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 6]]
+const f = math.subset(e, math.index(0, [0, 2]), [5, 6])  // f = [[5, 6]] and e = [[5, 0, 6]]
 const g = math.subset(f, math.index(1, 1), 7, 0)         // g = [[5, 6], [0, 7]]
+
+// get submatrix using ranges
+const M = [
+  [1,2,3],
+  [4,5,6],
+  [7,8,9]
+]
+math.subset(M, math.index(math.range(0,2), math.range(0,3))) // [[1,2,3],[4,5,6]]
 ```
 
 

package/docs/reference/functions/symbolicEqual.md

@@ -0,0 +1,62 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function symbolicEqual
+
+Attempts to determine if two expressions are symbolically equal, i.e.
+one is the result of valid algebraic manipulations on the other.
+Currently, this simply checks if the difference of the two expressions
+simplifies down to 0. So there are two important caveats:
+1. whether two expressions are symbolically equal depends on the
+    manipulations allowed. Therefore, this function takes an optional
+    third argument, which are the options that control the behavior
+    as documented for the `simplify()` function.
+2. it is in general intractable to find the minimal simplification of
+    an arbitrarily complicated expression. So while a `true` value
+    of `symbolicEqual` ensures that the two expressions can be manipulated
+    to match each other, a `false` value does not absolutely rule this out.
+
+
+## Syntax
+
+```js
+symbolicEqual(expr1, expr2)
+symbolicEqual(expr1, expr2, options)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`expr1` | Node &#124; string | The first expression to compare
+`expr2` | Node &#124; string | The second expression to compare
+`options` | Object | Optional option object, passed to simplify
+
+### Returns
+
+Type | Description
+---- | -----------
+boolean |  Returns true if a valid manipulation making the expressions equal is found.
+
+
+### Throws
+
+Type | Description
+---- | -----------
+
+
+## Examples
+
+```js
+symbolicEqual('x*y', 'y*x') // true
+symbolicEqual('x*y', 'y*x', {context: {multiply: {commutative: false}}})
+    //false
+symbolicEqual('x/y', '(y*x^(-1))^(-1)') // true
+symbolicEqual('abs(x)','x') // false
+symbolicEqual('abs(x)','x', simplify.positiveContext) // true
+```
+
+
+## See also
+
+[simplify](simplify.md),
+[evaluate](evaluate.md)

package/docs/reference/functions.md

@@ -25,6 +25,7 @@ Function | Description
 [simplify(expr)](functions/simplify.md) | Simplify an expression tree.
 [simplifyCore(expr)](functions/simplifyCore.md) | simplifyCore() performs single pass simplification suitable for applications requiring ultimate performance.
 [math.slu(A, order, threshold)](functions/slu.md) | Calculate the Sparse Matrix LU decomposition with full pivoting.
+[symbolicEqual(expr1, expr2)](functions/symbolicEqual.md) | Attempts to determine if two expressions are symbolically equal, i.
 [math.usolve(U, b)](functions/usolve.md) | Finds one solution 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.
 
@@ -137,7 +138,7 @@ Function | Description
 [math.identity(n)](functions/identity.md) | Create a 2-dimensional identity matrix with size m x n or n x n.
 [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.map(x, callback)](functions/map.md) | Create a new matrix or array with the results of a callback function executed on each entry of a given 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.