MATLAB Function Reference
eigs

Find a few eigenvalues and eigenvectors of a square large sparse matrix

Syntax

• ```d = eigs(A)
d = eigs(A,B)
d = eigs(A,k)
d = eigs(A,B,k)
d = eigs(A,k,`sigma`)
d = eigs(A,B,k,`sigma`)
d = eigs(A,k,`sigma`,options)
d = eigs(A,B,k,`sigma`,options)
d = eigs(Afun,n)
d = eigs(Afun,n,B)
d = eigs(Afun,n,k)
d = eigs(Afun,n,B,k)
d = eigs(Afun,n,k,`sigma`)
d = eigs(Afun,n,B,k,`sigma`)
d = eigs(Afun,n,k,`sigma`,options)
d = eigs(Afun,n,B,k,`sigma`,options)
d = eigs(Afun,n,k,`sigma`,options,p1,p2...)
d = eigs(Afun,n,B,k,`sigma`,options,p1,p2...)
[V,D] = eigs(A,...)
[V,D] = eigs(Afun,n,...)
[V,D,flag] = eigs(A,...)
[V,D,flag] = eigs(Afun,n,...)
```

Description

```d = eigs(A) ``` returns a vector of `A`'s six largest magnitude eigenvalues.

```[V,D] = eigs(A) ``` returns a diagonal matrix `D` of `A`'s six largest magnitude eigenvalues and a matrix `V` whose columns are the corresponding eigenvectors.

```[V,D,flag] = eigs(A) ``` also returns a convergence flag. If `flag` is `0` then all the eigenvalues converged; otherwise not all converged.

```eigs(A,B) ``` solves the generalized eigenvalue problem `A*V == B*V*D`. `B` must be symmetric (or Hermitian) positive definite and the same size as `A`. `eigs(A,[],...)` indicates the standard eigenvalue problem `A*V == V*D`.

```eigs(A,k) and eigs(A,B,k) ``` return the `k` largest magnitude eigenvalues.

```eigs(A,k,sigma) and eigs(A,B,k,sigma) ``` return `k` eigenvalues based on `sigma`, which can take any of the following values:

 scalar (real or complex, including 0) The eigenvalues closest to `sigma`. If `A` is a function, `Afun` must return `Y = (A-``sigma``*B)\x` (i.e., `Y = A\x` when `sigma`` = 0`). Note, `B` need only be symmetric (Hermitian) positive semi-definite. `'lm'` Largest magnitude (default). `'sm'` Smallest magnitude. Same as `sigma`` = 0`. If `A` is a function, `Afun` must return `Y = A\x`. Note, `B` need only be symmetric (Hermitian) positive semi-definite. For real symmetric problems, the following are also options: `'la'` Largest algebraic (`'lr'` in MATLAB 5) `'sa'` Smallest algebraic (`'sr'` in MATLAB 5) `'be'` Both ends (one more from high end if `k` is odd) For nonsymmetric and complex problems, the following are also options: `'lr'` Largest real part `'sr'` Smallest real part `'li'` Largest imaginary part `'si'` Smallest imaginary part

 Note    The MATLAB 5 value `sigma`` = 'be'` is obsolete for nonsymmetric and complex problems.

```eigs(A,K,sigma,opts) and eigs(A,B,k,sigma,opts) ``` specify an options structure. Default values are shown in brackets (`{}`).

 Parameter Description Values `options.issym` `1` if `A` or `A-``sigma``*B` represented by `Afun` is symmetric, `0` otherwise. `[{0} | 1]` `options.isreal` `1` if `A` or `A-``sigma``*B` represented by `Afun` is real, `0` otherwise. `[0 | {1}]` `options.tol` Convergence: Ritz estimate residual `<= tol*norm(A)`. `[scalar | {eps}]` `options.maxit` Maximum number of iterations. `[integer | {300}]` `options.p` Number of basis vectors. `p >= 2k` (`p >= 2k+1` real nonsymmetric) advised. Note: `p` must satisfy `k < p <= n` for real symmetric, `k+1 < p <= n` otherwise. `[integer | 2*k]` `options.v0` Starting vector. `Randomly generated by ARPACK` `options.disp` Diagnostic information display level. `[0 | {1} | 2]` `options.cholB` `1` if `B` is really its Cholesky factor `chol(B)`, `0` otherwise. `[{0} | 1]` `options.permB` Permutation vector `permB` if sparse `B` is really `chol(B(permB,permB))`. `[permB | {1:n}]`

 Note    MATLAB 5 options `stagtol` and `cheb` are no longer allowed.

```eigs(Afun,n,...) ``` accepts the function `Afun` instead of the matrix `A`. `y = Afun(x)` should return:

 `A*x` if `sigma` is not specified, or is a string other than `'sm'` `A\x` if `sigma` is `0` or `'sm'` `(A-sigma*I)\x` if `sigma` is a nonzero scalar (standard eigenvalue problem). `I` is an identity matrix of the same size as `A`. `(A-sigma*B)\x` if `sigma` is a nonzero scalar (generalized eigenvalue problem)

`n` is the size of `A`. The matrix `A`, `A-``sigma``*I` or `A-``sigma``*B` represented by `Afun` is assumed to be real and nonsymmetric unless specified otherwise by `opts.isreal` and `opts.issym`. In all the `eigs` syntaxes, `eigs(A,...)` can be replaced by `eigs(Afun,n,...)`.

```eigs(Afun,n,k,sigma,opts,p1,p2,...) and eigs(Afun,n,B,k,sigma,opts,p1,p2,...) ``` provide for additional arguments which are passed to `Afun(x,p1,p2,...)`.

Remarks

`d = eigs(A,k)` is not a substitute for

• ```d = eig(full(A))
d = sort(d)
d = d(end-k+1:end)
```

but is most appropriate for large sparse matrices. If the problem fits into memory, it may be quicker to use `eig(full(A))`.

Algorithm

`eigs` provides the reverse communication required by the Fortran library ARPACK, namely the routines `DSAUPD`, `DSEUPD`, `DNAUPD`, `DNEUPD`, `ZNAUPD`, and `ZNEUPD`.

Examples

Example 1: This example shows the use of function handles.

• ```A = delsq(numgrid('C',15));
d1 = eigs(A,5,'sm');
```

Equivalently, if `dnRk` is the following one-line function:

• ```function y = dnRk(x,R,k)
y = (delsq(numgrid(R,k))) \ x;
```

then pass `dnRk`'s additional arguments, `'C'` and `15`, to `eigs`.

• ```n = size(A,1);
opts.issym = 1;
d2 = eigs(@dnRk,n,5,'sm',opts,'C',15);
```

Example 2: `west0479` is a real 479-by-479 sparse matrix with both real and pairs of complex conjugate eigenvalues. `eig` computes all 479 eigenvalues. `eigs` easily picks out the largest magnitude eigenvalues.

This plot shows the 8 largest magnitude eigenvalues of `west0479` as computed by `eig` and `eigs`.

• ```load west0479
d = eig(full(west0479))
dlm = eigs(west0479,8)
[dum,ind] = sort(abs(d));
plot(dlm,'k+')
hold on
plot(d(ind(end-7:end)),'ks')
hold off
legend('eigs(west0479,8)','eig(full(west0479))')

```

Example 3: `A = delsq(numgrid('C',30))` is a symmetric positive definite matrix of size 632 with eigenvalues reasonably well-distributed in the interval (0 8), but with 18 eigenvalues repeated at 4. The `eig` function computes all 632 eigenvalues. It computes and plots the six largest and smallest magnitude eigenvalues of `A` successfully with:

• ```A = delsq(numgrid('C',30));
d = eig(full(A));
[dum,ind] = sort(abs(d));
dlm = eigs(A);
dsm = eigs(A,6,'sm');

subplot(2,1,1)
plot(dlm,'k+')
hold on
plot(d(ind(end:-1:end-5)),'ks')
hold off
legend('eigs(A)','eig(full(A))',3)
set(gca,'XLim',[0.5 6.5])

subplot(2,1,2)
plot(dsm,'k+')
hold on
plot(d(ind(1:6)),'ks')
hold off
legend('eigs(A,6,''sm'')','eig(full(A))',2)
set(gca,'XLim',[0.5 6.5])

```

However, the repeated eigenvalue at 4 must be handled more carefully. The call `eigs(A,18,4.0)` to compute 18 eigenvalues near 4.0 tries to find eigenvalues of `A - 4.0*I`. This involves divisions of the form `1/(lambda - 4.0)`, where `lambda` is an estimate of an eigenvalue of `A`. As `lambda` gets closer to 4.0, `eigs `fails. We must use `sigma` near but not equal to 4 to find those 18 eigenvalues.

• ```sigma = 4 - 1e-6
[V,D] = eigs(A,18,sigma)
```

The plot shows the 20 eigenvalues closest to 4 that were computed by `eig`, along with the 18 eigenvalues closest to `4 - 1e-6` that were computed by `eigs`.

`arpackc`, `eig`, `svds`