# numeric::singularvectors

Numerical singular value decomposition of a matrix

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

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

## Description

`numeric::singularvectors(A)` and the equivalent call `numeric::svd(A)` return numerical singular values and singular vectors of the matrix `A`.

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

`Cat::Matrix` objects, i.e., matrices `A` of a matrix domain such as `Dom::Matrix(…)` or `Dom::SquareMatrix(…)` are internally converted to arrays over expressions via `expr(A)`.

The list `[U, d, V, resU, resV]` returned by `numeric::singularvectors` corresponds to the singular data of an m×n matrix A as described below.

Let VH denote the Hermitian transpose of the matrix V, i.e., the complex conjugate of the transpose. The singular value decomposition of an m×n matrix A is a factorization A = UDVH. D is an m×n "diagonal" matrix with real nonnegative entries Dii = di, i = 1, …, p where p = min(m, n):

or

,

respectively. The list d = [d1, …, dp] returned by `numeric::singularvectors` are the "singular values" of A. They are sorted by `numeric::sort`, i.e., d1 ≥ … ≥ dp ≥ 0.0.

U is a unitary m×m matrix. Its i-th column is an eigenvector of AAH associated with the eigenvalue di2 (di = 0 for i > p). These are the "left singular vectors" of A. They are returned by `numeric::singularvectors` as a matrix of floating-point numbers.

V is a unitary n×n matrix. Its i-th column is an eigenvector of AHA associated with the eigenvalue di2 (di = 0 for i > p). These are the "right singular vectors" of A. They are returned by `numeric::singularvectors` as an array of floating-point numbers. The matrix `V` is normalized such that, in each column, the first entry of absolute size larger than is real and positive.

If no return type is specified via the option ```ReturnType = t```, the domain type of the singular vectors U and V depends on the type of the input matrix `A`:

• The singular vectors of an array are returned as arrays.

• The singular vectors of an hfarray are returned as hfarrays.

• The singular vectors of a dense matrix of type `Dom::DenseMatrix()` are returned as dense matrices of type `Dom::DenseMatrix()` over the ring of MuPAD® expressions.

• For all other matrices of category `Cat::Matrix`, the singular vectors 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.

resU = [resU1, …, resUm] is a list of float residues associated with the left singular vectors:

.

Here, ui is the (normalized) i-th column of `U`, is the usual complex Euclidean scalar product and di = 0 for p < im.

resV = [resV1, …, resVn] is a list of float residues associated with the right singular vectors:

.

Here, vi is the (normalized) i-th column of `V`, di = 0 for p < in.

The residues resU, resV vanish for exact singular data U, d, V. Their sizes indicate the quality of the numerical data ```U, d, V```.

 Note:   Singular values are approximated with an absolute precision of , where r is the largest singular value of `A`. Consequently, large singular values should be computed correctly to `DIGITS` decimal places. The numerical approximations of small singular values are less accurate.

The singular values computed by `numeric::singularvectors` are identical to those computed by `numeric::svd`.

Singular data may also be computed via ```[d2, U, resU] := numeric::eigenvectors(A*A^H)``` or ```[d2, V, resV] := numeric::eigenvectors(A^H*A)```, respectively. The list `d2` is related to the singular values by

.

The use of `numeric::singularvectors` avoids the costs of the matrix multiplication. Further, the eigenvector routine requires about twice as many `DIGITS` to compute the data associated with small singular values with the same precision as `numeric::singularvectors`. Also note that the normalization of `U` and `V` may be different.

## Environment Interactions

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

## Examples

### Example 1

Numerical expressions are converted to floats:

```DIGITS := 5: A := array(1..3, 1..2, [[1, PI], [2, 3], [3, exp(sqrt(2))]]): [U, d, V, resU, resV] := numeric::singularvectors(A):```

The singular data are:

`U, d, V`

The small residues indicate that these results are not severely affected by roundoff:

`resU, resV`

`delete DIGITS, A, U, d, V, resU, resV:`

### Example 2

We demonstrate how to reconstruct a matrix from its singular data. With the specified `ReturnType`, the singular vectors are returned as matrices of type `Dom::Matrix()` and can be handled with the overloaded arithmetic:

```DIGITS := 3: A := array(1..2, 1..3, [[1.0, I, PI], [2, 3, I]]): [U, d, V, resU, resV] := numeric::singularvectors(A, NoResidues, ReturnType = Dom::Matrix())```

A "diagonal" matrix is built from the singular values:

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

We use the methods `conjugate` and `transpose` of the matrix domain to compute the Hermitian transpose of `V` and reconstruct `A`. Numerical roundoff is eliminated via `numeric::complexRound`:

```VH := V::dom::conjugate(V::dom::transpose(V)): map(U*d*VH, numeric::complexRound)```

`delete DIGITS, A, U, d, V, resU, resV, VH:`

### Example 3

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

```A := array(1..2, 1..3, [[1, 2, 3], [30, 60, 90]]): [U1, d1, V1, resU1, resV1] := numeric::singularvectors(A, HardwareFloats): [U2, d2, V2, resU2, resV2] := numeric::singularvectors(A, SoftwareFloats): V1, V2```

`delete A, U1, d1, V1, resU1, resV1, U2, d2, V2, resU2, resV2:`

## Parameters

 `A` A numerical matrix of domain type `DOM_ARRAY`, `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 result is subject to roundoff errors. The results returned with `HardwareFloats` and `SoftwareFloats` may differ! See Example 3.

`NoLeftVectors`

Suppresses the computation of left singular vectors

If only right singular vectors are required, this option may be used to suppress the computation of `U` and the corresponding residues `resU`. The return values for these data are `NIL`.

Depending on the size of `U`, this option may speed up the computation considerably.

`NoRightVectors`

Suppresses the computation of right singular vectors

If only left singular vectors are required, this option may be used to suppress the computation of `V` and the corresponding residues `resV`. The return values for these data are `NIL`.

Depending on the size of `V`, this option may speed up the computation considerably.

`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 `resU` and `resV`. 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 left and right singular vectors as matrices of domain type `t`. The following return types t are available: `DOM_ARRAY`, or `DOM_HFARRAY`, or `Dom::Matrix()`, or `Dom::DenseMatrix()`.

This option determines the domain type of the matrices containing the singular vectors.

`NoWarning`

Suppresses warnings

## Return Values

List `[U, d, V, resU, resV]`. `U` is a unitary square float matrix whose columns are left singular vectors. The list `d` contains the singular values. `V` is a unitary square float matrix whose columns are right singular vectors. The lists of float residues `resU` and `resV` provide error estimates for the numerical data.

Get trial now