## EIGS Sparse Matrix Eigendecomposition

Section: Sparse Matrix Support

### Usage

Computes the eigendecomsition of a sparse square matrix. The `eigs` function has several forms. The most general form is
```  [V,D] = eigs(A,k,sigma)
```

where `A` is the matrix to analyze, `k` is the number of eigenvalues to compute and `sigma` determines which eigenvallues to solve for. Valid values for `sigma` are 'lm' - largest magnitude 'sm' - smallest magnitude 'la' - largest algebraic (for real symmetric problems) 'sa' - smallest algebraic (for real symmetric problems) 'be' - both ends (for real symmetric problems) 'lr' - largest real part 'sr' - smallest real part 'li' - largest imaginary part 'si' - smallest imaginary part scalar - find the eigenvalues closest to `sigma`. The returned matrix `V` contains the eigenvectors, and `D` stores the eigenvalues. The related form

```   d = eigs(A,k,sigma)
```

computes only the eigenvalues and not the eigenvectors. If `sigma` is omitted, as in the forms

```  [V,D] = eigs(A,k)
```

and

```  d = eigs(A,k)
```

then `eigs` returns the largest magnitude eigenvalues (and optionally the associated eigenvectors). As an even simpler form, the forms

```  [V,D] = eigs(A)
```

and

```  d = eigs(A)
```

then `eigs` returns the six largest magnitude eigenvalues of `A` and optionally the eigenvectors. The `eigs` function uses ARPACK to compute the eigenvectors and/or eigenvalues. Note that due to a limitation in the interface into ARPACK from FreeMat, the number of eigenvalues that are to be computed must be strictly smaller than the number of columns (or rows) in the matrix.

### Example

Here is an example of using `eigs` to calculate eigenvalues of a matrix, and a comparison of the results with `eig`
```--> a = sparse(rand(9));
--> eigs(a)

ans =
4.2673 +  0.0000i
-0.8372 +  0.0000i
-0.7445 +  0.3406i
-0.7445 -  0.3406i
0.6653 +  0.2082i
0.6653 -  0.2082i

--> eig(full(a))

ans =
4.2673 +  0.0000i
-0.8372 +  0.0000i
-0.7445 +  0.3406i
-0.7445 -  0.3406i
0.1634 +  0.4595i
0.1634 -  0.4595i
0.6653 +  0.2082i
0.6653 -  0.2082i
0.0479 +  0.0000i
```

Next, we exercise some of the variants of `eigs`:

```--> eigs(a,4,'sm')

ans =
0.0479 +  0.0000i
0.1634 -  0.4595i
0.1634 +  0.4595i
0.6653 -  0.2082i

--> eigs(a,4,'lr')

ans =
4.2673 +  0.0000i
0.6653 -  0.2082i
0.6653 +  0.2082i
0.1634 -  0.4595i

--> eigs(a,4,'sr')

ans =
-0.8372 +  0.0000i
-0.7445 -  0.3406i
-0.7445 +  0.3406i
0.0479 +  0.0000i
```