diff --git a/docs/reference/functions.md b/docs/reference/functions.md index 8ed712887..0679e9ef7 100644 --- a/docs/reference/functions.md +++ b/docs/reference/functions.md @@ -138,7 +138,7 @@ Function | Description [math.diag(X)](functions/diag.html) | 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.html) | 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.html) | Calculate the dot product of two vectors. -[math.eigs(x, [prec])](functions/eigs.html) | Compute eigenvalues and eigenvectors of a matrix. +[math.eigs(x, [prec])](functions/eigs.html) | Compute eigenvalues and optionally eigenvectors of a square matrix. [math.expm(x)](functions/expm.html) | Compute the matrix exponential, expm(A) = e^A. [math.fft(arr)](functions/fft.html) | Calculate N-dimensional fourier transform. [math.filter(x, test)](functions/filter.html) | Filter the items in an array or one dimensional matrix. diff --git a/docs/reference/functions/eigs.md b/docs/reference/functions/eigs.md index ab8245f09..fc7ea5048 100644 --- a/docs/reference/functions/eigs.md +++ b/docs/reference/functions/eigs.md @@ -6,17 +6,41 @@ layout: default

Function eigs #

-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 +Compute eigenvalues and optionally eigenvectors of a square matrix. +The eigenvalues are sorted by their absolute value, ascending, and +returned as a vector in the `values` property of the returned project. +An eigenvalue with algebraic multiplicity k will be listed k times, so +that the returned `values` vector always has length equal to the size +of the input matrix. + +The `eigenvectors` property of the return value provides the eigenvectors. +It is an array of plain objects: the `value` property of each gives the +associated eigenvalue, and the `vector` property gives the eigenvector +itself. Note that the same `value` property will occur as many times in +the list provided by `eigenvectors` as the geometric multiplicity of +that value. + +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`. +Note that the 'precision' option does not directly specify the _accuracy_ +of the returned eigenvalues. Rather, it determines how small an entry +of the iterative approximations to an upper triangular matrix must be +in order to be considered zero. The actual accuracy of the returned +eigenvalues may be greater or less than the precision, depending on the +conditioning of the matrix and how far apart or close the actual +eigenvalues are. Note that currently, relatively simple, "traditional" +methods of eigenvalue computation are being used; this is not a modern, +high-precision eigenvalue computation. That said, it should typically +produce fairly reasonable results. +

Syntax #

```js math.eigs(x, [prec]) +math.eigs(x, {options}) ```

Parameters #

@@ -24,13 +48,13 @@ math.eigs(x, [prec]) Parameter | Type | Description --------- | ---- | ----------- `x` | Array | Matrix | Matrix to be diagonalized -`prec` | number | BigNumber | Precision, default value: 1e-15 +`opts` | number | BigNumber | OptsObject | Object with keys `precision`, defaulting to config.epsilon, and `eigenvectors`, defaulting to true and specifying whether to compute eigenvectors. If just a number, specifies precision.

Returns #

Type | Description ---- | ----------- -{values: Array | Matrix, vectors: Array | Matrix} | Object containing an array of eigenvalues and a matrix with eigenvectors as columns. +{values: Array | Matrix, eigenvectors?: Array<EVobj>}} Object containing an array of eigenvalues and an array of {value: number | BigNumber, vector: Array | Matrix | objects. The eigenvectors property is undefined if eigenvectors were not requested.

Throws #

@@ -42,14 +66,18 @@ Type | Description

Examples #

```js -const { eigs, multiply, column, transpose } = math +const { eigs, multiply, column, transpose, matrixFromColumns } = math const H = [[5, 2.3], [2.3, 1]] -const ans = eigs(H) // returns {values: [E1,E2...sorted], vectors: [v1,v2.... corresponding vectors as columns]} +const ans = eigs(H) // returns {values: [E1,E2...sorted], eigenvectors: [{value: E1, vector: v2}, {value: e, vector: v2}, ...] const E = ans.values -const U = ans.vectors -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 +const V = ans.eigenvectors +multiply(H, V[0].vector)) // returns multiply(E[0], V[0].vector)) +const U = matrixFromColumns(...V.map(obj => obj.vector)) +const UTxHxU = multiply(transpose(U), H, U) // diagonalizes H if possible +E[0] == UTxHxU[0][0] // returns true always + +// Compute only approximate eigenvalues: +const {values} = eigs(H, {eigenvectors: false, precision: 1e-6}) ``` diff --git a/download.md b/download.md index 1ff9d0eca..5d4dc4917 100644 --- a/download.md +++ b/download.md @@ -27,7 +27,7 @@ Math.js can be downloaded or linked from various content delivery networks: unpkg - https://unpkg.com/mathjs@11.12.0/ + https://unpkg.com/mathjs@12.0.0/ cdnjs @@ -48,9 +48,9 @@ Or download the full bundle directly from [unpkg](https://unpkg.com):

math.js (version 11.12.0, 199 kB, minified and gzipped) - and if needed the source map + href="https://unpkg.com/mathjs@12.0.0/lib/browser/math.js" + >math.js (version 12.0.0, 199 kB, minified and gzipped) + and if needed the source map

Too large for you? Create your own [custom bundle](docs/custom_bundling.html). diff --git a/examples/browser/angle_configuration.html b/examples/browser/angle_configuration.html index a5401af0d..f71048620 100644 --- a/examples/browser/angle_configuration.html +++ b/examples/browser/angle_configuration.html @@ -15,7 +15,7 @@ } - + diff --git a/examples/browser/angle_configuration.html.md b/examples/browser/angle_configuration.html.md index 73ef5e614..566f78ce9 100644 --- a/examples/browser/angle_configuration.html.md +++ b/examples/browser/angle_configuration.html.md @@ -24,7 +24,7 @@ File: [angle_configuration.html](angle_configuration.html) (click for a live dem } - + diff --git a/examples/browser/basic_usage.html b/examples/browser/basic_usage.html index cb444519c..dc95e1666 100644 --- a/examples/browser/basic_usage.html +++ b/examples/browser/basic_usage.html @@ -3,7 +3,7 @@ math.js | basic usage - + diff --git a/examples/browser/basic_usage.html.md b/examples/browser/basic_usage.html.md index 5d7f36f7d..daf2ba2e7 100644 --- a/examples/browser/basic_usage.html.md +++ b/examples/browser/basic_usage.html.md @@ -12,7 +12,7 @@ File: [basic_usage.html](basic_usage.html) (click for a live demo) math.js | basic usage - + diff --git a/examples/browser/currency_conversion.html b/examples/browser/currency_conversion.html index ee87a403f..5032551af 100644 --- a/examples/browser/currency_conversion.html +++ b/examples/browser/currency_conversion.html @@ -4,7 +4,7 @@ math.js | currency conversion - + - + diff --git a/examples/browser/custom_separators.html.md b/examples/browser/custom_separators.html.md index 4d6bfdf2c..3ea6d146c 100644 --- a/examples/browser/custom_separators.html.md +++ b/examples/browser/custom_separators.html.md @@ -24,7 +24,7 @@ File: [custom_separators.html](custom_separators.html) (click for a live demo) } - + diff --git a/examples/browser/lorenz.html b/examples/browser/lorenz.html index f370fa1fe..c4c84d65b 100644 --- a/examples/browser/lorenz.html +++ b/examples/browser/lorenz.html @@ -4,7 +4,7 @@ math.js | Lorenz Attractor - + diff --git a/examples/browser/lorenz.html.md b/examples/browser/lorenz.html.md index df6fbfed2..7f0501489 100644 --- a/examples/browser/lorenz.html.md +++ b/examples/browser/lorenz.html.md @@ -13,7 +13,7 @@ File: [lorenz.html](lorenz.html) (click for a live demo) math.js | Lorenz Attractor - + diff --git a/examples/browser/plot.html b/examples/browser/plot.html index 15f97efb0..a466ae228 100644 --- a/examples/browser/plot.html +++ b/examples/browser/plot.html @@ -3,7 +3,7 @@ math.js | plot - + diff --git a/examples/browser/plot.html.md b/examples/browser/plot.html.md index e9e3fa63b..d91b2fc28 100644 --- a/examples/browser/plot.html.md +++ b/examples/browser/plot.html.md @@ -12,7 +12,7 @@ File: [plot.html](plot.html) (click for a live demo) math.js | plot - + diff --git a/examples/browser/pretty_printing_with_mathjax.html b/examples/browser/pretty_printing_with_mathjax.html index d52a9da57..dc1e5c1a9 100644 --- a/examples/browser/pretty_printing_with_mathjax.html +++ b/examples/browser/pretty_printing_with_mathjax.html @@ -4,7 +4,7 @@ math.js | pretty printing with MathJax - + diff --git a/examples/browser/pretty_printing_with_mathjax.html.md b/examples/browser/pretty_printing_with_mathjax.html.md index c8bd66f9a..0c23ae203 100644 --- a/examples/browser/pretty_printing_with_mathjax.html.md +++ b/examples/browser/pretty_printing_with_mathjax.html.md @@ -13,7 +13,7 @@ File: [pretty_printing_with_mathjax.html](pretty_printing_with_mathjax.html) (cl math.js | pretty printing with MathJax - + diff --git a/examples/browser/printing_html.html b/examples/browser/printing_html.html index 55e81a541..7db26086e 100644 --- a/examples/browser/printing_html.html +++ b/examples/browser/printing_html.html @@ -4,7 +4,7 @@ math.js | printing HTML - +