mathjs 10.1.1 → 10.2.0

package/HISTORY.md

@@ -1,5 +1,22 @@
 # History
 
+# 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:

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/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

package/docs/reference/functions/cosh.md

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

package/docs/reference/functions/cot.md

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

package/docs/reference/functions/coth.md

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

package/docs/reference/functions/count.md

@@ -24,6 +24,12 @@ Type | Description
 number | An integer with the elements in `x`.
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js

package/docs/reference/functions/cross.md

@@ -36,6 +36,12 @@ Type | Description
 Array | Matrix | Returns the cross product of `x` and `y`
 
 
+### Throws
+
+Type | Description
+---- | -----------
+
+
 ## Examples
 
 ```js