R: Find a Specified Number of Eigenvalues/vectors for Square...

eigs {RSpectra} | R Documentation

## Find a Specified Number of Eigenvalues/vectors for Square Matrix

### Description

Given an n by n matrix A, function `eigs()` can calculate a limited number of eigenvalues and eigenvectors of A. Users can specify the selection criteria by argument `which`, e.g., choosing the k largest or smallest eigenvalues and the corresponding eigenvectors.

Currently `eigs()` supports matrices of the following classes:

`matrix` | The most commonly used matrix type, defined in base package.
`dgeMatrix` | General matrix, equivalent to `matrix`, defined in Matrix package.
`dgCMatrix` | Column oriented sparse matrix, defined in Matrix package.
`dgRMatrix` | Row oriented sparse matrix, defined in Matrix package.
`dsyMatrix` | Symmetrix matrix, defined in Matrix package.
`function` | Implicitly specify the matrix through a function that has the effect of calculating f(x) = A * x. See section Function Interface for details.

`eigs_sym()` assumes the matrix is symmetric, and only the lower triangle (or upper triangle, which is controlled by the argument `lower`) is used for computation, which guarantees that the eigenvalues and eigenvectors are real, and in some cases reduces the workload. One exception is when `A` is a function, in which case the user is responsible for the symmetry of the operator.

`eigs_sym()` supports "matrix", "dgeMatrix", "dgCMatrix", "dgRMatrix" and "function" typed matrices.

### Usage

    eigs(A, k, which = "LM", sigma = NULL, opts = list(), ...)

    ## S3 method for class 'matrix'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ...)

    ## S3 method for class 'dgeMatrix'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ...)

    ## S3 method for class 'dgCMatrix'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ...)

    ## S3 method for class 'dgRMatrix'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ...)

    ## S3 method for class 'dsyMatrix'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ...)

    ## S3 method for class 'function'
    eigs(A, k, which = "LM", sigma = NULL, opts = list(),
      ..., n = NULL, args = NULL)

    eigs_sym(A, k, which = "LM", sigma = NULL, opts = list(),
       lower = TRUE, ...)

    ## S3 method for class 'function'
    eigs_sym(A, k, which = "LM", sigma = NULL,
      opts = list(), lower = TRUE, ..., n = NULL, args = NULL)

### Arguments

`A` | The matrix whose eigenvalues/vectors are to be computed. It can also be a function which receives a vector x and calculates A * x. See section Function Interface for details.
`k` | Number of eigenvalues requested.
`which` | Selection criteria. See Details below.
`sigma` | Shift parameter. See section Shift-And-Invert Mode.
`opts` | Control parameters related to the computing algorithm. See Details below.
`n` | Only used when `A` is a function, to specify the dimension of the implicit matrix. See section Function Interface for details.
`args` | Only used when `A` is a function. This argument will be passed to the `A` function when it is called. See section Function Interface for details.
`lower` | For symmetric matrices, should the lower triangle or upper triangle be used.
`...` | Arguments for specialized S3 function calls, for example `lower`, `n` and `args`.

### Details

The `which` argument is a character string that specifies the type of eigenvalues to be computed. Possible values are:

"LM" | The k eigenvalues with largest magnitude. Here the magnitude means the Euclidean norm of complex numbers.
"SM" | The k eigenvalues with smallest magnitude.
"LR" | The k eigenvalues with largest real part.
"SR" | The k eigenvalues with smallest real part.
"LI" | The k eigenvalues with largest imaginary part.
"SI" | The k eigenvalues with smallest imaginary part.
"LA" | The k largest (algebraic) eigenvalues, considering any negative sign.
"SA" | The k smallest (algebraic) eigenvalues, considering any negative sign.
"BE" | Compute k eigenvalues, half from each end of the spectrum. When k is odd, compute more from the high and then from the low end.

`eigs()` with matrix type "matrix", "dgeMatrix", "dgCMatrix" and "dgRMatrix" can use "LM", "SM", "LR", "SR", "LI" and "SI".

`eigs_sym()`, and `eigs()` with matrix type "dsyMatrix" can use "LM", "SM", "LA", "SA" and "BE".

The `opts` argument is a list that can supply any of the following parameters:

`ncv`

  Number of Lanzcos basis vectors to use. More vectors will result in faster convergence, but with greater memory use. For general matrix, `ncv` must satisfy k+2 <= ncv <= n, and for symmetric matrix, the constraint is k < ncv <= n. Default is `min(n, max(2*k+1, 20))`.

`tol`

  Precision parameter. Default is 1e-10.

`maxitr`

  Maximum number of iterations. Default is 1000.

`retvec`

  Whether to compute eigenvectors. If FALSE, only calculate and return eigenvalues.

### Value

A list of converged eigenvalues and eigenvectors.

`values` | Computed eigenvalues.
`vectors` | Computed eigenvectors. `vectors[, j]` corresponds to `values[j]`.
`nconv` | Number of converged eigenvalues.
`niter` | Number of iterations used in the computation.
`nops` | Number of matrix operations used in the computation.

### Shift-And-Invert Mode

The `sigma` argument is used in the shift-and-invert mode.

When `sigma` is not `NULL`, the selection criteria specified by argument `which` will apply to

1/(λ-σ)

where λ's are the eigenvalues of A. This mode is useful when user wants to find eigenvalues closest to a given number. For example, if σ=0, then `which = "LM"` will select the largest values of 1/|λ|, which turns out to select eigenvalues of A that have the smallest magnitude. The result of using `which = "LM", sigma = 0` will be the same as `which = "SM"`, but the former one is preferable in that `eigs()` is good at finding large eigenvalues rather than small ones. More explanation of the shift-and-invert mode can be found in the SciPy document, http://docs.scipy.org/doc/scipy/reference/tutorial/arpack.html.

### Function Interface

The matrix A can be specified through a function with the definition

    function(x, args)
    {
        ## should return A %*% x
    }

which receives a vector `x` as an argument and returns a vector of the same length. The function should have the effect of calculating A * x, and extra arguments can be passed in through the `args` parameter. In `eigs()`, user should also provide the dimension of the implicit matrix through the argument `n`.

### Author(s)

Yixuan Qiu http://statr.me

Jiali Mei vermouthmjl@gmail.com

### See Also

`eigen()`, `svd()`, `svds()`

### Examples

    library(Matrix)
    n = 20
    k = 5

    ## general matrices have complex eigenvalues
    set.seed(111)
    A1 = matrix(rnorm(n^2), n)  ## class "matrix"
    A2 = Matrix(A1)             ## class "dgeMatrix"

    eigs(A1, k)
    eigs(A2, k, opts = list(retvec = FALSE))  ## eigenvalues only

    ## Sparse matrices
    A1[sample(n^2, n^2 / 2)] = 0
    A3 = as(A1, "dgCMatrix")
    A4 = as(A1, "dgRMatrix")

    eigs(A3, k)
    eigs(A4, k)

    ## Function interface
    f = function(x, args)
    {
        as.numeric(args %*% x)
    }
    eigs(f, k, n = n, args = A3)

    ## Symmetric matrices have real eigenvalues
    A5 = crossprod(A1)
    eigs_sym(A5, k)

    ## Find the smallest (in absolute value) k eigenvalues of A5
    eigs_sym(A5, k, which = "SM")

    ## Another way to do this: use the sigma argument
    eigs_sym(A5, k, sigma = 0)

    ## The results should be the same,
    ## but the latter method is far more stable on large matrices

[Package RSpectra version 0.12-0 Index]