# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# svds

Subset of singular values and vectors

## Syntax

• ``s = svds(A)``
example
• ``s = svds(A,k)``
example
• ``s = svds(A,k,sigma)``
example
• ``s = svds(A,k,sigma,opts)``
example
• ``s = svds(Afun,n,___)``
example
• ``````[U,S,V] = svds(___)``````
example
• ``````[U,S,V,flag] = svds(___)``````
example

## Description

example

````s = svds(A)` returns a vector of the six largest singular values of matrix `A`.```

example

````s = svds(A,k)` returns the `k` largest singular values.```

example

````s = svds(A,k,sigma)` returns `k` singular values based on the value of `sigma`. For example, `svds(A,k,'smallest')` returns the `k` smallest singular values.```

example

````s = svds(A,k,sigma,opts)` additionally specifies options using a structure.```

example

````s = svds(Afun,n,___)` specifies a function handle `Afun` instead of a matrix `A`. You can optionally specify `k`, `sigma`, or `opts` as additional input arguments.```

example

``````[U,S,V] = svds(___)``` returns the left singular vectors `U`, diagonal matrix `S` of singular values, and right singular vectors `V`. You can use any of the input argument combinations in previous syntaxes.```

example

``````[U,S,V,flag] = svds(___)``` also returns a convergence flag. If `flag` is `0`, then all the singular values converged.```

## Examples

collapse all

Compute the six largest singular values of a sparse matrix.

```A = delsq(numgrid('C',15)); s = svds(A) ```
```s = 7.8666 7.7324 7.6531 7.5213 7.4480 7.3517 ```

Specify a second input to compute a specific number of the largest singular values.

```s = svds(A,3) ```
```s = 7.8666 7.7324 7.6531 ```

Compute the five smallest singular values of a sparse matrix.

```A = delsq(numgrid('C',15)); s = svds(A,5,'smallest') ```
```s = 0.5520 0.4787 0.3469 0.2676 0.1334 ```

Create a sparse 100-by-100 Neumann matrix.

```C = gallery('neumann',100); ```

Compute the ten smallest singular values.

```ss = svds(C,10,'smallest') ```
```ss = 0.9828 0.9049 0.5625 0.5625 0.4541 0.4506 0.2256 0.1139 0.1139 0 ```

Compute the 10 smallest nonzero singular values. Since the matrix has a singlular value that is equal to zero, the `'smallestnz'` option omits it.

```snz = svds(C,10,'smallestnz') ```
```snz = 0.9828 0.9828 0.9049 0.5625 0.5625 0.4541 0.4506 0.2256 0.1139 0.1139 ```

Create two matrices representing the upper-right and lower-left nonzero blocks in a sparse matrix.

```n = 500; B = rand(500); C = rand(500); ```

Save `Afun` in your current directory so that it is available for use with `svds`.

```function y = Afun(x,tflag,B,C,n) if strcmp(tflag,'notransp') y = [B*x(n+1:end); C*x(1:n)]; else y = [C'*x(n+1:end); B'*x(1:n)]; end ```

The function `Afun` uses `B` and `C` to compute either `A*x` or `A'*x` (depending on the specified flag) without actually forming the entire sparse matrix `A = [zeros(n) B; C zeros(n)]`. This exploits the sparsity pattern of the matrix to save memory in the computation of `A*x` and `A'*x`.

Use `Afun` to calculate the 10 largest singular values of `A`. Pass `B`, `C`, and `n` as additional inputs to `Afun`.

```s = svds(@(x,tflag) Afun(x,tflag,B,C,n),[1000 1000],10) ```
```s = 250.3248 249.9914 12.7627 12.7232 12.6988 12.6608 12.6166 12.5643 12.5419 12.4512 ```

Directly compute the 10 largest singular values of `A` to compare the results.

```A = [zeros(n) B; C zeros(n)]; s = svds(A,10) ```
```s = 250.3248 249.9914 12.7627 12.7232 12.6988 12.6608 12.6166 12.5643 12.5419 12.4512 ```

`west0479` is a real-valued 479-by-479 sparse matrix. The matrix has a few large singular values, and many small singular values.

Load `west0479` and store it as `A`.

```load west0479 A = west0479; ```

Compute the singular value decomposition of `A`, returning the six largest singular values and the corresponding singular vectors. Specify a fourth output argument to check convergence of the singular values.

```[U,S,V,cflag] = svds(A); cflag ```
```cflag = 0 ```

`cflag` indicates that all of the singular values converged. The singular values are on the diagonal of the output matrix `S`.

```s = diag(S) ```
```s = 1.0e+05 * 3.1895 3.1725 3.1695 3.1685 3.1669 0.3038 ```

Check the results by computing the full singular value decomposition of `A`. Convert `A` to a full matrix and use `svd`.

```[U1,S1,V1] = svd(full(A)); ```

Plot all of the singular values of `A` using a logarithmic scale.

```semilogy(diag(S1),'r.') title('Singular Values of west0479') ```

Create a sparse diagonal matrix and calculate the six largest singular values.

```A = diag(sparse([1e4*ones(1, 8) 1e4:-1:1])); s = svds(A) ```
```Warning: Maximum number of iterations reached. Results may be inaccurate. s = 1.0e+04 * 1.0000 0.9999 0.9998 0.9997 0.9996 0.9995 ```

The `svds` algorithm produces a warning since the maximum number of iterations were performed but the tolerance could not be met.

The most effective way to address convergence problems is to increase the maximum size of the Krylov subspace used in the calculation by using a larger value for `p`. Do this by passing an options structure to `svds` that specifies `p = 50`.

```opts.p = 50; s = svds(A,6,'largest',opts) ```
```Warning: Maximum number of iterations reached. Results may be inaccurate. s = 1.0e+04 * 1.0000 1.0000 1.0000 1.0000 1.0000 1.0000 ```

Compute the 10 smallest singular values of a nearly singular matrix.

```rng default format shortg B = spdiags([repelem([1; 1e-7], [198, 2]) ones(200, 1)], [0 1], 200, 200); s1 = svds(B,10,'smallest') ```
```Warning: Large residual norm detected. This is likely due to bad condition of the input matrix (condition number 1.0008e+16). s1 = 7.0945 7.0945 7.0945 7.0945 7.0945 7.0945 7.0945 7.0945 0.25927 7.0888e-16 ```

The warning indicates that `svds` fails to calculate the proper singular values. The failure with `svds` is because of the gap between the smallest and second smallest singular values. `svds(...,'smallest')` needs to invert `B`, which leads to large numerical error.

For comparison, compute the exact singular values using `svd`.

```s = svd(full(B)); s = s(end-9:end) ```
```s = 0.14196 0.12621 0.11045 0.094686 0.078914 0.063137 0.047356 0.031572 0.015787 7.0888e-16 ```

In order to reproduce this calculation with `svds`, do a QR decomposition of `B`. The singular values of the triangular matrix `R` are the same as for `B`.

```[Q,R,p] = qr(B,0); ```

Plot the norm of each row of `R`.

```rownormR = sqrt(diag(R*R')); semilogy(rownormR) hold on; semilogy(size(R, 1), rownormR(end), 'ro') ```

The last entry in `R` is nearly zero, which causes instability in the solution.

Prevent this entry from corrupting the good parts of the solution by setting the last row of `R` to be exactly zero.

```R(end,:) = 0; ```

Use `svds` to find the 10 smallest singular values of `R`. The results are comparable to those obtained by `svd`.

```sr = svds(R,10,'smallest') ```
```sr = 0.14196 0.12621 0.11045 0.094686 0.078914 0.063137 0.047356 0.031572 0.015787 0 ```

To compute the singular vectors of `B` using this method, transform the left and right singular vectors using `Q` and the permutation vector `p`.

```[U,S,V] = svds(R,20,'s'); U = Q*U; V(p,:) = V; ```

## Input Arguments

collapse all

Input matrix. `A` is typically, but not always, a large and sparse matrix.

Data Types: `double`
Complex Number Support: Yes

Number of singular values to compute, specified as a positive scalar integer. `svds` returns fewer singular values than requested if either of these conditions are met:

• `k` is larger than `min(m,n)`

• `sigma = 'smallestnz'` and `k` is larger than the number of nonzero singular values of `A`

If `k` is too large, then `svds` replaces it with the maximum valid value of `k`.

Example: `svds(A,2)` returns the two largest singular values of `A`.

Type of singular values, specified as one of these values:

OptionDescription

`'largest'`

(default)
Largest singular values

`'smallest'`

Smallest singular values

`'smallestnz`

Smallest nonzero singular values

scalar

Singular values closest to a scalar shift

Example: `svds(A,k,'smallest')` computes the `k` smallest singular values.

Example: `svds(A,k,100)` computes the `k` singular values closest to `100`.

Options structure, specified as a structure containing one or more of the fields in this table.

Option FieldDescriptionDefault
`opts.tol`

Convergence tolerance

`1e-10`
`opts.maxit`

Maximum number of iterations

`100`
`opts.p`

Maximum size of Krylov subspace

`max(3*K,15)`
`opts.u0`

Left initial starting vector

You can provide at most one of `opts.u0` or `opts.v0`. If neither option is specified, then for an m-by-n matrix `A`, the default is:

• `m < n````opts.u0 = randn(m,1);```

• `m >= n````opts.v0 = randn(n,1);```

 Note:   `svds` selects `u0` and `v0` in a reproducible manner using a private random number stream. Changing the random number seed does not affect this use of `randn`.
`opts.v0`

Right initial starting vector

 Note:   `svds` ignores the option `p` when using a numeric scalar shift `sigma`.

Example: `opts.tol = 1e-6, opts.maxit = 500` creates a structure with values set for the fields `tol` and `maxit`.

Data Types: `struct`

Matrix function, specified as a function handle. The function `Afun` must satisfy these conditions:

• `Afun(x,'notransp')` accepts a vector `x` and returns the product `A*x`.

• `Afun(x,'transp')` accepts a vector `x` and returns the product `A'*x`.

 Note:   Use function handles only in the case where ```sigma = 'largest'``` (which is the default).

Example: `svds(Afun,[1000 1200])`

Data Types: `function_handle`

Size of matrix `A` that is used by `Afun`, specified as a two-element size vector `[m n]`.

Example: `svds(Afun,[1000 1200])`

## Output Arguments

collapse all

Singular values, returned as a column vector. The singular values are nonnegative real numbers listed in decreasing order.

Left singular vectors, returned as the columns of a matrix. If `A` is an `m`-by-`n` matrix and you request `k` singular values, then `U` is an `m`-by-`k` matrix with orthonormal columns.

Singular values, returned as a diagonal matrix. The diagonal elements of `S` are nonnegative singular values. If `A` is an `m`-by-`n` matrix and you request `k` singular values, then `S` is `k`-by-`k`.

Right singular vectors, returned as the columns of a matrix. If `A` is an `m`-by-`n` matrix and you request `k` singular values, then `V` is an `n`-by-`k` matrix with orthonormal columns.

Convergence flag, returned as a scalar. A value of `0` indicates that all the singular values converged. Otherwise, not all the singular values converged.

collapse all

### Tips

• `svds` generates the default starting vectors `opts.u0` and `opts.v0` using a private random number stream to ensure reproducibility across runs. Setting the random number generator state using `rng` before calling `svds` does not affect the output.

• Using `svds` is not the most efficient way to find a few singular values of small, dense matrices. If the problem fits into memory, it might be quicker to use `svd(full(A))`. For example, finding three singular values in a 500-by-500 matrix is a relatively small problem that is easily handled with `svd`.

• If `svds` fails to converge for a given matrix, increase the size of the Krylov subspace by increasing the value of `opts.p`. As secondary options, adjusting the maximum number of iterations, `opts.maxit`, and the convergence tolerance, `opts.tol`, can also help with convergence behavior.

• For faster performance, it sometimes works to increase `k`, especially when there are repeated singular values.

## References

[1] Baglama, J. and L. Reichel, "Augmented Implicitly Restarted Lanczos Bidiagonalization Methods." SIAM Journal on Scientific Computing. Vol. 27, 2005, pp. 19–42.

[2] Larsen, R. M. "Lanczos Bidiagonalization with partial reorthogonalization." Dept. of Computer Science, Aarhus University. DAIMI PB-357, 1998.