mathjs 10.1.0 → 10.3.0

package/HISTORY.md

@@ -1,5 +1,43 @@
 # 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`, 
+  see #2399, #2391. Thanks @gwhitney.
+- Implemented function `leafCount` as a first simple measure of the complexity 
+  of an expression, see #2411, #2389. Thanks @gwhitney.
+- Fix #2413: improve `combinations` to return an integer result without rounding
+  errors for larger values, see #2414. Thanks @gwhitney.
+- Fix #2385: function `rotate` missing in TypeScript definitions. 
+  Thanks @DIVYA-19.
+- Fix #2450: Add BigNumber to parameter type in `math.unit` and add TypeScript
+  types for `Unit.simplify` and `Unit.units` (#2353). Thanks @joshhansen.
+- Fix #2383: detect infinite loops in `simplify` (#2405). Thanks @gwhitney.
+- Fix #1423: collect like factors and cancel like terms in sums (#2388). 
+  Thanks @gwhitney.
+
+
+# 2022-02-02, version 10.1.1
+
+- Improvements and fixes in function `simplify`, thanks @gwhitney:
+  - Fix #2393: regression bug in `simplify('2-(x+1)')`.
+  - Ad option `consoleDebug` to `simplify` to see what is going on.
+- Fix TypeScript definition of `ConfigOptions`, which was missing option 
+  `predictable`.
+
+
 # 2022-01-15, version 10.1.0
 
 - Implemented function `invmod`, see #2368, #1744. Thanks @thetazero.

package/docs/expressions/algebra.md

@@ -27,6 +27,33 @@ console.log(simplified.toString())       // '3 * x'
 console.log(simplified.evaluate({x: 4})) // 12
 ```
 
+Note that `simplify` has an optional argument `scope` that allows the definitions of variables in the expression (as numeric values, or as further expressions) to be specified and used in the simplification, e.g. continuing the previous example,
+
+```js
+console.log(math.simplify(f, {x: 4}).toString()) // 12
+console.log(math.simplify(f, {x: math.parse('y+z')}).toString()) // '3*(y+z)'
+```
+
+In general, simplification is an inherently dfficult problem; in fact, for certain classes of expressions and algebraic equivalences, it is undecidable whether a given expression is equivalent to zero. Moreover, simplification generally depends on the properties of the operations involved; since multiplication (for example) may have different properties (e.g., it might or might not be commutative) depending on the domain under consideration, different simplifications might be appropriate.
+
+As a result, `simplify()` has an additional optional argument, `options`, which controls its behavior. This argument is an object specifying any of various properties concerning the simplification process. See the [detailed documentation](../reference/functions/simplify.md) for a complete list, but currently the two most important properties are as follows. Note that the `options` argument may only be specified if the `scope` is as well.
+
+- `exactFractions` - a boolean which specifies whether non-integer numerical constants should be simplified to rational numbers when possible (true), or always converted to decimal notation (false).
+- `context` - an object whose keys are the names of operations ('add', 'multiply', etc.) and whose values specify algebraic properties of the corresponding operation (currently any of 'total', 'trivial', 'commutative', and 'associative'). Simplifications will only be performed if the properties they rely on are true in the given context. For example,
+```js
+const expr = math.parse('x*y-y*x')
+console.log(math.simplify(expr).toString())  // 0; * is commutative by default
+console.log(math.simplify(expr, {}, {context: {multiply: {commutative: false}}}))
+  // 'x*y-y*x'; the order of the right multiplication can't be reversed.
+```
+
+Note that the default context is very permissive (allows a lot of simplifications) but that there is also a `math.simplify.realContext` that only allows simplifications that are guaranteed to preserve the value of the expression on all real numbers:
+```js
+const rational = math.parse('(x-1)*x/(x-1)')
+console.log(math.simplify(expr, {}, {context: math.simplify.realContext})
+  // '(x-1)*x/(x-1)'; canceling the 'x-1' makes the expression defined at 1
+```
+
 For more details on the theory of expression simplification, see:
 
 - [Strategies for simplifying math expressions (Stackoverflow)](https://stackoverflow.com/questions/7540227/strategies-for-simplifying-math-expressions)

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

@@ -25,6 +25,12 @@ Type | Description
 number | BigNumber | Fraction | Complex | Array | Matrix | Unit |  Absolute value of `x`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acos.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Complex | Array | Matrix | The arc cosine of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acosh.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arccosine of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acot.md

@@ -26,6 +26,12 @@ Type | Description
 number | Complex | Array | Matrix | The arc cotangent of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acoth.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arccotangent of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acsc.md

@@ -26,6 +26,12 @@ Type | Description
 number | Complex | Array | Matrix | The arc cosecant of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/acsch.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arccosecant of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/add.md

@@ -27,6 +27,12 @@ Type | Description
 number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Sum of `x` and `y`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/and.md

@@ -26,6 +26,12 @@ Type | Description
 boolean | Array | Matrix |  Returns true when both inputs are defined with a nonzero/nonempty value.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/apply.md

@@ -32,6 +32,12 @@ Type | Description
 Array | Matrix | res    The residual matrix with the function applied over some dimension.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/arg.md

@@ -27,6 +27,12 @@ Type | Description
 number | BigNumber | Array | Matrix | The argument of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/asec.md

@@ -26,6 +26,12 @@ Type | Description
 number | Complex | Array | Matrix | The arc secant of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/asech.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arcsecant of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/asin.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Complex | Array | Matrix | The arc sine of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/asinh.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arcsine of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/atan.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Complex | Array | Matrix | The arc tangent of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/atan2.md

@@ -29,6 +29,12 @@ Type | Description
 number | Array | Matrix | Four-quadrant inverse tangent
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/atanh.md

@@ -27,6 +27,12 @@ Type | Description
 number | Complex | Array | Matrix | Hyperbolic arctangent of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bellNumbers.md

@@ -26,6 +26,12 @@ Type | Description
 Number | BigNumber | B(n)
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bin.md

@@ -25,6 +25,12 @@ Type | Description
 string | The formatted value
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bitAnd.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Array | Matrix | AND of `x` and `y`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bitNot.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Array | Matrix | NOT of `x`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bitOr.md

@@ -27,6 +27,12 @@ Type | Description
 number | BigNumber | Array | Matrix | OR of `x` and `y`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/bitXor.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Array | Matrix | XOR of `x` and `y`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/catalan.md

@@ -26,6 +26,12 @@ Type | Description
 Number | BigNumber | Cn(n)
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/cbrt.md

@@ -28,6 +28,12 @@ Type | Description
 number | BigNumber | Complex | Unit | Array | Matrix |  Returns the cubic root of `x`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/ceil.md

@@ -28,6 +28,12 @@ Type | Description
 number | BigNumber | Fraction | Complex | Array | Matrix | Rounded value
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/clone.md

@@ -24,6 +24,12 @@ Type | Description
 * | A clone of object x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/column.md

@@ -25,6 +25,12 @@ Type | Description
 Array | Matrix | The retrieved column
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/combinations.md

@@ -29,6 +29,12 @@ Type | Description
 number | BigNumber | Number of possible combinations.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/combinationsWithRep.md

@@ -29,6 +29,12 @@ Type | Description
 number | BigNumber | Number of possible combinations with replacement.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/compare.md

@@ -32,6 +32,12 @@ Type | Description
 number &#124; BigNumber &#124; Fraction &#124; Array &#124; Matrix | Returns the result of the comparison: 1 when x > y, -1 when x < y, and 0 when x == y.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/compareNatural.md

@@ -47,6 +47,12 @@ Type | Description
 number | Returns the result of the comparison: 1 when x > y, -1 when x < y, and 0 when x == y.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/compareText.md

@@ -28,6 +28,12 @@ Type | Description
 number &#124; Array &#124; DenseMatrix | Returns the result of the comparison: 1 when x > y, -1 when x < y, and 0 when x == y.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/compile.md

@@ -27,6 +27,12 @@ Type | Description
 {evaluate: Function} | Array.<{evaluate: Function}> | code An object with the compiled expression
 
 
+### Throws
+
+Type | Description
+---- | -----------
+Error | 
+
 ## Examples
 
 ```js

package/docs/reference/functions/composition.md

@@ -28,6 +28,12 @@ Type | Description
 Number | BigNumber | Returns the composition counts of n into k parts.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/concat.md

@@ -30,6 +30,12 @@ Type | Description
 Array | Matrix | Concatenated matrix
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/conj.md

@@ -27,6 +27,12 @@ Type | Description
 number | BigNumber | Complex | Array | Matrix |  The complex conjugate of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/cos.md

@@ -26,6 +26,12 @@ Type | Description
 number | BigNumber | Complex | Array | Matrix | Cosine of x
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js