# svd

Fixed-point Golub-Kahan-Reinsch singular value decomposition

Since R2022b

## Syntax

``S = svd(A)``
``[U,S,V] = svd(A)``
``[___] = svd(A,"econ")``
``[___] = svd(A,0)``
``[___] = svd(___,sigmaForm)``

## Description

example

````S = svd(A)` returns the singular values of matrix `A` in descending order.```

example

````[U,S,V] = svd(A)` performs a singular value decomposition of matrix `A`, such that `A = U*S*V'`. `S` is a diagonal matrix of the same dimension as `A` with nonnegative diagonal elements in decreasing order. `U` and `V` are unitary matrices.```

example

````[___] = svd(A,"econ")` produces an economy-size decomposition of `A`. If `A` is an m-by-n matrix, then:m > n — Only the first n columns of `U` are computed and `S` is n-by-n.m = n — `svd(A,"econ")` is equivalent to `svd(A)`.m < n — Only the first m columns of `V` are computed, and `S` is m-by-m.```

example

````[___] = svd(A,0)` produces a different economy-size decomposition of `A`. If `A` is an m-by-n matrix, then:m > n — `svd(A,0)` is equivalent to `svd(A,"econ")`.m <= n — `svd(A,0)` is equivalent to `svd(A)`.Syntax is not recommended. Use the `"econ"` option instead.```

example

````[___] = svd(___,sigmaForm)` optionally specifies the output format for the singular values. You can use this option with any of the previous input or output combinations. Specify `"vector"` to return the singular values as a column vector. Specify `"matrix"` to return the singular values in a diagonal matrix.```

## Examples

collapse all

Compute the singular values of a full rank fixed-point matrix.

`A = fi([1 0 1; -1 -2 0; 0 1 -1])`
```A = 1 0 1 -1 -2 0 0 1 -1 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 14 ```

Compute the singular values.

`s = svd(A)`
```s = 2.4605 1.6996 0.2391 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```

The singular values are returned in a column vector in decreasing order.

Find the singular value decomposition of the rectangular fixed-point matrix `A`.

Define the rectangular matrix `A`.

```m = 4; n = 2; rng('default'); A = fi(10*randn(m,n))```
```A = 5.3770 3.1875 18.3389 -13.0771 -22.5889 -4.3359 8.6221 3.4258 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 10 ```

Find the singular value decomposition of the fixed-point matrix `A`.

`[U,S,V] = svd(A)`
```U = 0.1590 0.2717 -0.9387 -0.1403 0.6397 -0.7548 -0.1219 0.0790 -0.7049 -0.5057 -0.3224 0.3786 0.2619 0.3174 0 0.9114 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```
```S = 31.0148 0 0 14.1292 0 0 0 0 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```
```V = 0.9920 0.1259 -0.1259 0.9920 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```

Confirm the relation `A = U*S*V'`.

`U*S*V'`
```ans = 5.3770 3.1875 18.3390 -13.0774 -22.5890 -4.3361 8.6221 3.4258 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 99 FractionLength: 76 ```

Calculate the complete and economy-size decomposition of a rectangular fixed-point matrix.

Define the fixed-point matrix `A`.

```m = 5; n = 3; rng('default'); A = fi(10*randn(m,n))```
```A = 5.3770 -13.0762 -13.4980 18.3379 -4.3359 30.3496 -22.5879 3.4258 7.2539 8.6211 35.7832 -0.6309 3.1875 27.6953 7.1465 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 9 ```

Compute the complete decomposition.

`[U,S,V] = svd(A)`
```U = 0.3081 -0.0950 0.4507 0.7929 0.2534 -0.1437 0.9533 -0.0877 0.2415 -0.0675 -0.0224 -0.2106 -0.8423 0.4887 -0.0831 -0.7299 -0.1909 0.2773 0.2722 -0.5290 -0.5926 -0.0375 -0.0541 0 0.8028 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```
```S = 48.4486 0 0 0 36.6721 0 0 0 26.9112 0 0 0 0 0 0 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```
```V = -0.1786 0.5443 0.8196 -0.9497 -0.3131 0.0010 -0.2571 0.7783 -0.5729 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```

Compute the economy-size decomposition.

`[U,S,V] = svd(A,"econ")`
```U = 0.3082 -0.0950 0.4507 -0.1437 0.9533 -0.0878 -0.0224 -0.2106 -0.8423 -0.7299 -0.1909 0.2773 -0.5926 -0.0375 -0.0541 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```
```S = 48.4487 0 0 0 36.6720 0 0 0 26.9111 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```
```V = -0.1786 0.5444 0.8196 -0.9497 -0.3131 0.0010 -0.2571 0.7782 -0.5729 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```

Use the expected result `A = U*S*V'` to determine the relative error of the calculation.

`relativeError = norm(double(U*S*V'-A))/norm(double(A))`
```relativeError = 1.3361e-05 ```

Create a 3-by-3 magic square matrix and calculate the singular value decomposition. By default, the `svd` function returns the singular values in a diagonal matrix when you specify multiple outputs.

Define the matrix `A`.

```m = 3; n = m; A = fi(magic(m))```
```A = 8 1 6 3 5 7 4 9 2 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 11 ```

Compute the singular value decomposition.

`[U,S,V] = svd(A)`
```U = 0.5774 -0.7071 -0.4082 0.5773 0.0000 0.8165 0.5773 0.7071 -0.4083 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```
```S = 15.0000 0 0 0 6.9282 0 0 0 3.4640 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```
```V = 0.5774 -0.4083 -0.7071 0.5773 0.8165 -0.0000 0.5773 -0.4082 0.7071 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```

Specify the `"vector"` option to return the singular values in a column vector.

`[U,S,V] = svd(A,"vector")`
```U = 0.5774 -0.7071 -0.4082 0.5773 0.0000 0.8165 0.5773 0.7071 -0.4083 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```
```S = 15.0000 6.9282 3.4640 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 16 ```
```V = 0.5774 -0.4083 -0.7071 0.5773 0.8165 -0.0000 0.5773 -0.4082 0.7071 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 30 ```

If you specify one output argument, such as `S = svd(A)`, then `svd` switches behavior to return the singular values in a column vector by default. In that case, you can specify the `"matrix"` option to return the singular values as a diagonal matrix.

## Input Arguments

collapse all

Input matrix, specified as a matrix. `A` can be a fixed-point or scaled double `fi` data type.

Data Types: `fi`
Complex Number Support: Yes

Output format of singular values, specified as one of these values:

• `"vector"``S` is a column vector. This behavior is the default when you specify one output, ```S = svd(A)```.

• `"matrix"``S` is a diagonal matrix. This behavior is the default when you specify multiple outputs, ```[U,S,V] = svd(A)```.

Example: `[U,S,V] = svd(X,"vector")` returns `S` as a column vector instead of a diagonal matrix.

Example: `S = svd(X,"matrix")` returns `S` as a diagonal matrix instead of a column vector.

Data Types: `char` | `string`

## Output Arguments

collapse all

Left singular vectors, returned as the columns of a matrix.

The fixed-point data type is adjusted to avoid overflow and increase precision. For more information, see Algorithms.

Singular values, returned as a diagonal matrix or column vector. The singular values are nonnegative and returned in decreasing order.

The fixed-point data type is adjusted to avoid overflow and increase precision. For more information, see Algorithms.

Right singular vectors, returned as the columns of a matrix.

The fixed-point data type is adjusted to avoid overflow and increase precision. For more information, see Algorithms.

## Tips

To have full control over the fixed-point types, use the `fixed.svd` function.

## Algorithms

collapse all

### Data Type Propagation

The `svd` function adjusts the data type of a fixed-point input to avoid overflow and increase precision. The fraction length of the singular vectors `S` is adjusted to a minimum of `16`, and the word length is increased to avoid overflow with a minimum of `32`. The word length of the left and right singular vectors `U` and `V` are the same as the word length of `S`. The fraction length of `U` and `V` is two less than the word length.

### Golub-Kahan-Reinsch

The Golub-Kahan-Reinsch algorithm is a sequential method that performs well on serial computers. For parallel computing, as in FPGA and ASIC applications, use the `fixed.jacobiSVD` function.

## Version History

Introduced in R2022b