mathjs 10.4.2 → 10.5.1

package/HISTORY.md

@@ -1,5 +1,41 @@
 # History
 
+# 2022-05-02 version 10.5.1
+
+- Fix #2526, #2529: improve TypeScript definitions of function `round`, `fix`,
+  `floor`, `ceil`, and `nthRoot`, and improved the number only implementations 
+  of those functions  (#2531, #2539). Thanks @simlaticak and @gwhitney.
+- Fix #2532: matrix index symbol `end` not working when used inside
+  a sub-expression.
+- Fix #2524: In generating AUTHORS list, ignore a list of specific commits
+  (e.g., to avoid spurious duplicates in list). (#2543)
+- Add type definitions of function `resolve` (#2536). Thanks @mattvague.
+
+
+# 2022-04-19, version 10.5.0
+
+- Implement #1563: function `pinv`, Moore–Penrose inverse (#2521). 
+  Thanks @HanchaiN.
+- Optimize function `det` for integers by switching to the Bareiss algorithm: 
+  no more round-off errors for integer input (#2516). Thanks @HanchaiN.
+- Implement #2463: allow negative integer powers of invertible square matrices
+  (#2517). Thanks @HanchaiN.
+- Implement the `lgamma` function (defined as log(gamma(z))) for number and
+  Complex types. Supersedes #320. (#2417). Thanks @yifanwww.
+- Fix #2523: update to the latest complex.js to improve `sin(z)` for small
+  `im(z)` (#2525). Thanks @gwhitney.
+- Fix #2526: update TypeScript definition of `ceil` (#2531). Thanks @simlaticak
+- Change mocha reporter to 'dot' to avoid excessively long log files. (#2520)
+
+
+# 2022-04-08, version 10.4.3
+
+- Fix #2508: improve the precision of stirlingS2 (#2509). Thanks @gwhitney.
+- Fix #2514: implement optional argument `base` in the number implementation
+  of function `log` (#2515). Thanks @gwhitney.
+- Improve the documentation on operator `;` (#2512). Thanks @gwhitney.
+
+
 # 2022-03-29, version 10.4.2
 
 - Fix #2499: different behavior for unit conversion "degC" and "K" (#2501).

package/docs/datatypes/matrices.md

@@ -342,6 +342,23 @@ const m1 = math.matrix([[0, 1], [0, 0]], 'sparse')
 const m2 = math.identity(1000, 1000, 'sparse')
 ```
 
+You can also coerce an array or matrix into sparse storage format with the
+`sparse` function.
+```js
+const md = math.matrix([[0, 1], [0,0]])  // dense
+const ms = math.sparse(md)               // sparse
+```
+
+Caution: `sparse` called on a JavaScript array of _n_ plain numbers produces
+a matrix with one column and _n_ rows -- in contrast to `matrix`, which
+produces a 1-dimensional matrix object with _n_ entries, i.e., a vector
+(_not_ a 1 by _n_ "row vector" nor an _n_ by 1 "column vector", but just a plain
+vector of length _n_).
+```js
+const mv = math.matrix([0, 0, 1])  // Has size [3]
+const mc = math.sparse([0, 0, 1])  // A "column vector," has size [3, 1]
+```
+
 ## API
 
 All relevant functions in math.js support Matrices and Arrays. Functions like `math.add` and `math.subtract`, `math.sqrt` handle matrices element wise. There is a set of functions specifically for creating or manipulating matrices, such as:

package/docs/expressions/syntax.md

@@ -24,7 +24,11 @@ the lower level syntax of math.js. Differences are:
   not bitwise xor.
 - Implicit multiplication, like `2 pi`, is supported and has special rules.
 - Relational operators (`<`, `>`, `<=`, `>=`, `==`, and `!=`) are chained, so the expression `5 < x < 10` is equivalent to `5 < x and x < 10`.
-
+- Multi-expression constructs like `a = 1; b = 2; a + b` or
+  `"a = 1;\n cos(a)\n sin(a)"` (where `\n` denotes newline)
+  produce a collection ("ResultSet") of values. Those expressions
+  terminated by `;` are evaluated for side effect only and their values
+  are suppressed from the result.
 
 ## Operators
 
@@ -545,8 +549,11 @@ can be replaced by using indexes. Indexes are enclosed in square brackets, and
 contain a number or a range for each of the matrix dimensions. A range can have
 its start and/or end undefined. When the start is undefined, the range will start
 at 1, when the end is undefined, the range will end at the end of the matrix.
+
 There is a context variable `end` available as well to denote the end of the
-matrix.
+matrix. This variable cannot be used in multiple nested indices. In that case,
+`end` will be resolved as the end of the innermost matrix. To solve this, 
+resolving of the nested index needs to be split in two separate operations.
 
 *IMPORTANT: matrix indexes and ranges work differently from the math.js indexes
 in JavaScript: They are one-based with an included upper-bound, similar to most
@@ -651,7 +658,7 @@ Parentheses are parsed as a function call when there is a symbol or accessor on
 the left hand side, like `sqrt(4)` or `obj.method(4)`. In other cases the
 parentheses are interpreted as an implicit multiplication.
 
-Math.js will always evaluate implicit multiplication before explicit multiplication `*`, so that the expression `x * y z` is parsed as `x * (y * z)`. Math.js also gives implicit multiplication higher precedence than division, *except* when the division matches the pattern `[number] / [number] [symbol]` or `[number] / [number] [left paren]`. In that special case, the division is evaluated first:
+Math.js will always evaluate implicit multiplication before explicit multiplication `*`, so that the expression `x * y z` is parsed as `x * (y * z)`. Math.js also gives implicit multiplication higher precedence than division, *except* when the division matches the pattern `[unaryPrefixOp]?[number] / [number] [symbol]` or `[unaryPrefixOp]?[number] / [number] [left paren]`. In that special case, the division is evaluated first:
 
 ```js
 math.evaluate('20 kg / 4 kg')   // 5      Evaluated as (20 kg) / (4 kg)
@@ -661,7 +668,7 @@ math.evaluate('20 / 4 kg')      // 5 kg   Evaluated as (20 / 4) kg
 The behavior of implicit multiplication can be summarized by these operator precedence rules, listed from highest to lowest precedence:
 
 - Function calls: `[symbol] [left paren]`
-- Explicit division `/` when the division matches this pattern: `[number] / [number] [symbol]` or `[number] / [number] [left paren]`
+- Explicit division `/` when the division matches this pattern: `[+-~]?[number] / [+-~]?[number] [symbol]` or `[number] / [number] [left paren]`
 - Implicit multiplication
 - All other division `/` and multiplication `*`
 

package/docs/reference/functions/fix.md

@@ -10,6 +10,7 @@ For matrices, the function is evaluated element wise.
 
 ```js
 math.fix(x)
+math.fix(x,n)
 ```
 
 ### Parameters

package/docs/reference/functions/floor.md

@@ -52,6 +52,10 @@ math.floor(c, 1)              // returns Complex 3.2 - 2.8i
 
 math.floor([3.2, 3.8, -4.7])       // returns Array [3, 3, -5]
 math.floor([3.21, 3.82, -4.71], 1)  // returns Array [3.2, 3.8, -4.8]
+
+math.floor(math.tau, [2, 3])  // returns Array [6.28, 6.283]
+
+// Note that floor(array, array) currently not implemented.
 ```
 
 

package/docs/reference/functions/lgamma.md

@@ -0,0 +1,46 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function lgamma
+
+Logarithm of the gamma function for real, positive numbers and complex numbers,
+using Lanczos approximation for numbers and Stirling series for complex numbers.
+
+
+## Syntax
+
+```js
+math.lgamma(n)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`n` | number &#124; Complex | A real or complex number
+
+### Returns
+
+Type | Description
+---- | -----------
+number &#124; Complex | The log gamma of `n`
+
+
+### Throws
+
+Type | Description
+---- | -----------
+
+
+## Examples
+
+```js
+math.lgamma(5)       // returns 3.178053830347945
+math.lgamma(0)       // returns Infinity
+math.lgamma(-0.5)    // returns NaN
+math.lgamma(math.i)  // returns -0.6509231993018536 - 1.8724366472624294i
+```
+
+
+## See also
+
+[gamma](gamma.md)

package/docs/reference/functions/pinv.md

@@ -0,0 +1,44 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function pinv
+
+Calculate the Moore–Penrose inverse of a matrix.
+
+
+## Syntax
+
+```js
+math.pinv(x)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`x` | number &#124; Complex &#124; Array &#124; Matrix | Matrix to be inversed
+
+### Returns
+
+Type | Description
+---- | -----------
+number &#124; Complex &#124; Array &#124; Matrix | The inverse of `x`.
+
+
+### Throws
+
+Type | Description
+---- | -----------
+
+
+## Examples
+
+```js
+math.pinv([[1, 2], [3, 4]])          // returns [[-2, 1], [1.5, -0.5]]
+math.pinv([[1, 0], [0, 1], [0, 1]])  // returns [[1, 0, 0], [0, 0.5, 0.5]]
+math.pinv(4)                         // returns 0.25
+```
+
+
+## See also
+
+[inv](inv.md)

package/docs/reference/functions/pow.md

@@ -3,8 +3,11 @@
 # Function pow
 
 Calculates the power of x to y, `x ^ y`.
-Matrix exponentiation is supported for square matrices `x`, and positive
-integer exponents `y`.
+
+Matrix exponentiation is supported for square matrices `x` and integers `y`:
+when `y` is nonnegative, `x` may be any square matrix; and when `y` is
+negative, `x` must be invertible, and then this function returns
+inv(x)^(-y).
 
 For cubic roots of negative numbers, the function returns the principal
 root by default. In order to let the function return the real root,
@@ -48,6 +51,9 @@ math.pow(a, 2)                // returns Complex -5 + 12i
 
 const b = [[1, 2], [4, 3]]
 math.pow(b, 2)               // returns Array [[9, 8], [16, 17]]
+
+const c = [[1, 2], [4, 3]]
+math.pow(c, -1)               // returns Array [[-0.6, 0.4], [0.8, -0.2]]
 ```
 
 

package/docs/reference/functions/resolve.md

@@ -15,14 +15,14 @@ resolve(expr, scope)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`node` | Node |  The expression tree to be simplified
+`node` | Node | Node[] |  The expression tree (or trees) to be simplified
 `scope` | Object |  Scope specifying variables to be resolved
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Node | Returns `node` with variables recursively substituted.
+Node | Node[] | Returns `node` with variables recursively substituted.
 
 
 ### Throws

package/docs/reference/functions/simplifyConstant.md

@@ -0,0 +1,52 @@
+<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
+
+# Function simplifyConstant
+
+simplifyConstant() takes a mathjs expression (either a Node representing
+a parse tree or a string which it parses to produce a node), and replaces
+any subexpression of it consisting entirely of constants with the computed
+value of that subexpression.
+
+
+## Syntax
+
+```js
+simplifyConstant(expr)
+simplifyConstant(expr, options)
+```
+
+### Parameters
+
+Parameter | Type | Description
+--------- | ---- | -----------
+`node` | Node &#124; string |  The expression to be simplified
+`options` | Object |  Simplification options, as per simplify()
+
+### Returns
+
+Type | Description
+---- | -----------
+Node | Returns expression with constant subexpressions evaluated
+
+
+### Throws
+
+Type | Description
+---- | -----------
+
+
+## Examples
+
+```js
+math.simplifyConstant('x + 4*3/6')  // Node "x + 2"
+math.simplifyConstant('z cos(0)')   // Node "z 1"
+math.simplifyConstant('(5.2 + 1.08)t', {exactFractions: false})  // Node "6.28 t"
+```
+
+
+## See also
+
+[simplify](simplify.md),
+[simplifyCore](simplifyCore.md),
+[resolve](resolve.md),
+[derivative](derivative.md)

package/docs/reference/functions/stirlingS2.md

@@ -7,7 +7,11 @@ a set of n labelled objects into k nonempty unlabelled subsets.
 stirlingS2 only takes integer arguments.
 The following condition must be enforced: k <= n.
 
- If n = k or k = 1, then s(n,k) = 1
+ If n = k or k = 1 <= n, then s(n,k) = 1
+ If k = 0 < n, then s(n,k) = 0
+
+Note that if either n or k is supplied as a BigNumber, the result will be
+as well.
 
 
 ## Syntax

package/docs/reference/functions.md

@@ -144,6 +144,7 @@ Function | Description
 [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.pinv(x)](functions/pinv.md) | Calculate the Moore–Penrose inverse of a matrix.
 [math.range(start, end [, step])](functions/range.md) | Create an array from a range.
 [math.reshape(x, sizes)](functions/reshape.md) | Reshape a multi dimensional array to fit the specified dimensions.
 [math.resize(x, size [, defaultValue])](functions/resize.md) | Resize a matrix.
@@ -168,6 +169,7 @@ Function | Description
 [math.factorial(n)](functions/factorial.md) | Compute the factorial of a value  Factorial only supports an integer value as argument.
 [math.gamma(n)](functions/gamma.md) | Compute the gamma function of a value using Lanczos approximation for small values, and an extended Stirling approximation for large values.
 [math.kldivergence(x, y)](functions/kldivergence.md) | Calculate the Kullback-Leibler (KL) divergence  between two distributions.
+[math.lgamma(n)](functions/lgamma.md) | Logarithm of the gamma function for real, positive numbers and complex numbers, using Lanczos approximation for numbers and Stirling series for complex numbers.
 [math.multinomial(a)](functions/multinomial.md) | Multinomial Coefficients compute the number of ways of picking a1, a2, .
 [math.permutations(n [, k])](functions/permutations.md) | Compute the number of ways of obtaining an ordered subset of `k` elements from a set of `n` elements.
 [math.pickRandom(array)](functions/pickRandom.md) | Random pick one or more values from a one dimensional array.