# numeric::eigenvectors

Numerical eigenvalues and eigenvectors of a matrix

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```numeric::eigenvectors(`A`, `options`)
```

## Description

`numeric::eigenvectors(A)` returns numerical eigenvalues and eigenvectors of the matrix `A`.

All entries of the matrix must be numerical. Numerical expressions such as etc. are accepted and converted to floats. Non-numerical symbolic entries lead to an error.

The eigenvalues are sorted by `numeric::sort`.

The matrix `X` provides the eigenvectors: the i-th column of `X` is a numerical eigenvector corresponding to the eigenvalue `di`. Each column is either zero or normalized to the Euclidean length 1.0.

For matrices with multiple eigenvalues and an insufficient number of eigenvectors, some of the eigenvectors may coincide or may be zero, i.e., `X` is not necessarily invertible.

The list of residues res = [res1, res2, …] provides some control over the quality of the numerical spectral data. The residues are given by

,

where xi is the normalized eigenvector (the i-th column of `X`) associated with the numerical eigenvalue di. For Hermitian matrices, resi provides an upper bound for the absolute error of di.

With the option `NoResidues`, the computation of the residues is suppressed, the returned value is `NIL`.

If no return type is specified via the option ```ReturnType = t```, the domain type of the eigenvector matrix `X` depends on the type of the input matrix `A`:

• The eigenvectors of an array are returned as an array.

• The eigenvectors of an hfarray are returned as an hfarray.

• The eigenvectors of a dense matrix of type `Dom::DenseMatrix()` are returned as a dense matrix of type `Dom::DenseMatrix()` over the ring of expressions.

• For all other matrices of category `Cat::Matrix`, the eigenvectors are returned as matrices of type `Dom::Matrix()` over the ring of MuPAD® expressions. This includes input matrices `A` of type `Dom::Matrix(...)`, `Dom::SquareMatrix(...)`, `Dom::MatrixGroup(...)` etc.

 Note:   Matrices `A` of a matrix domain such as `Dom::Matrix(...)` or `Dom::SquareMatrix(...)` are internally converted to arrays over expressions via `expr(A)`. Note that `linalg::eigenvectors` must be used, when the eigenvalues/vectors are to be computed over the component domain. Cf. Example 3.
 Note:   Eigenvalues are approximated with an absolute precision of , where r is the spectral radius of `A` (i.e., r is the maximal singular value of `A`). Consequently, large eigenvalues should be computed correctly to `DIGITS` decimal places. The numerical approximations of the small eigenvalues are less accurate.
 Note:   For a numerical algorithm, it is not possible to distinguish between badly separated distinct eigenvalues and multiple eigenvalues. For this reason, `numeric::eigenvectors` and `linalg::eigenvectors` use different return formats: the latter can provide information on the multiplicity of eigenvalues due to its internal exact arithmetic.

Use `numeric::eigenvalues` if only eigenvalues are to be computed.

## Environment Interactions

The function is sensitive to the environment variable `DIGITS`, which determines the numerical working precision.

## Examples

### Example 1

We compute the spectral data of the 2×2 Hilbert matrix:

`A := linalg::hilbert(2)`

`[d, X, res] := numeric::eigenvectors(A):`

The eigenvalues:

`d`

The eigenvectors:

` X`

Hilbert matrices are Hermitian, i.e., computing the spectral data is a numerically stable process. This is confirmed by the small residues:

`res`

The routine `linalg::hilbert` provides the input as a matrix of type `Dom::Matrix()`. Consequently, the eigenvectors also consist of such a matrix. For further processing, we convert the list of eigenvalues to a diagonal matrix:

`d := matrix(2, 2, d, Diagonal):`

We reconstruct the matrix from its spectral data:

`X*d*X^(-1)`

We extract an eigenvector from the matrix `X` and doublecheck its numerical quality:

```eigenvector1 := X::dom::col(X, 1); norm(A*eigenvector1 - d[1, 1]*eigenvector1)```

`delete A, d, X, res, eigenvector1:`

### Example 2

We demonstrate a numerically ill-conditioned case. The following matrix has only one eigenvector and cannot be diagonalized. Numerically, the zero vector is returned as the second column of the eigenvector matrix:

```A := array(1..2, 1..2, [[5, -1], [4, 1]]): DIGITS := 6: numeric::eigenvectors(A)```

`delete A, DIGITS:`

### Example 3

The following matrix has domain components:

`A := Dom::Matrix(Dom::IntegerMod(7))([[6, -1], [0, 3]])`

Note that `numeric::eigenvectors` computes the spectral data of the following matrix:

`expr(A)`

`numeric::eigenvectors(A, NoResidues)`

The routine `linalg::eigenvectors` should be used if the spectral data are to be computed over the component domain `Dom::IntegerMod``(7)`:

`linalg::eigenvectors(A)`

`delete A:`

### Example 4

We demonstrate the use of hardware floats. The following matrix is degenerate: it has rank 1. For the double eigenvalue 0, different base vectors of the corresponding eigenspace are returned with `HardwareFloats` and `SoftwareFloats`, respectively:

```A := array(1..3, 1..3, [[1, 2, 3], [2, 4, 6], [3*10^12, 6*10^12, 9*10^12]]): [d1, X1, res1] := numeric::eigenvectors(A, HardwareFloats): d1, X1```

```[d2, X2, res2] := numeric::eigenvectors(A, SoftwareFloats): d2, X2```

`delete A, d1, X1, res1, d2, X2, res2:`

## Parameters

 `A` A numerical matrix of domain type `DOM_ARRAY`, or `DOM_HFARRAY`, or of category `Cat::Matrix`.

## Options

`Hard`, `HardwareFloats`, `Soft`, `SoftwareFloats`

With `Hard` (or `HardwareFloats`), computations are done using fast hardware float arithmetic from within a MuPAD session. `Hard` and `HardwareFloats` are equivalent. With this option, the input data are converted to hardware floats and processed by compiled C code. The result is reconverted to MuPAD floats and returned to the MuPAD session.

With `Soft` (or `SoftwareFloats`) computations are dome using software float arithmetic provided by the MuPAD kernel. `Soft` and `SoftwareFloats` are equivalent. `SoftwareFloats` is used by default if the current value of `DIGITS` is larger than 15 and the input matrix `A` is not of domain type `DOM_HFARRAY`.

Compared to the `SoftwareFloats` used by the MuPAD kernel, the computation with `HardwareFloats` may be many times faster. Note, however, that the precision of hardware arithmetic is limited to about 15 digits. Further, the size of floating-point numbers may not be larger than approximately 10308 and not smaller than approximately 10- 308.

If no `HardwareFloats` or `SoftwareFloats` are requested explicitly, the following strategy is used: If the current value of `DIGITS` is smaller than 16 or if the matrix `A` is a hardware float array of domain type `DOM_HFARRAY`, then hardware arithmetic is tried. If this is successful, the result is returned.

If the result cannot be computed with hardware floats, software arithmetic by the MuPAD kernel is tried.

If the current value of `DIGITS` is larger than 15 and the input matrix `A` is not of domain type `DOM_HFARRAY`, or if one of the options `Soft`, `SoftwareFloats` or `Symbolic` is specified, MuPAD computes the result with its software arithmetic without trying to use hardware floats first.

There may be several reasons for hardware arithmetic to fail:

• The current value of `DIGITS` is larger than 15.

• The data contains symbolic objects.

• The data contains numbers larger than 10308 or smaller than 10- 308 that cannot be represented by hardware floats.

If neither `HardwareFloats` nor `SoftwareFloats` is specified, the user is not informed whether hardware floats or software floats are used.

If `HardwareFloats` are specified but fail due to one of the reasons above, a warning is issued that the (much slower) software floating-point arithmetic of the MuPAD kernel is used.

Note that `HardwareFloats` can only be used if all input data can be converted to floating-point numbers.

The trailing digits in floating-point results computed with `HardwareFloats` and `SoftwareFloats` may differ.

 Note:   For ill conditioned matrices the results returned with `HardwareFloats` and `SoftwareFloats` may differ significantly! See Example 4.

`NoResidues`

Suppresses the computation of error estimates

If no error estimates are required, this option may be used to suppress the computation of the residues `res`. The return values for these data are `NIL`.

The alternative option name `NoErrors` used in previous MuPAD versions is still available.

`ReturnType`

Option, specified as `ReturnType = t`

Return the eigenvectors as a matrix of domain type `t`. The following return types t are available: `DOM_ARRAY`, `DOM_HFARRAY`, `Dom::Matrix()`, or `Dom::DenseMatrix()`.

`NoWarning`

Suppresses warnings

## Return Values

List `[d, X, res]`. The list ```d = [d1, d2, …]``` contains the numerical eigenvalue. The i-th column of the matrix `X` is the eigenvector associated with the eigenvalue `di`. The list of residues ```res = [res1, res2, …]``` provides error estimates for the numerical eigenvalues.

## Algorithms

The routine implements standard numerical algorithms from the Handbook of Automatic Computation by Wilkinson and Reinsch.