nimble (version 0.7.0)

nimEigen: Spectral Decomposition of a Matrix

Description

Computes eigenvalues and eigenvectors of a numeric matrix.

Usage

nimEigen(x, symmetric = FALSE, only.values = FALSE)

Arguments

x

a numeric matrix (double or integer) whose spectral decomposition is to be computed.

symmetric

if TRUE, the matrix is guarranteed to be symmetric, and only its lower triangle (diagonal included) is used. Otherwise, the matrix is checked for symmetry. Default is FALSE.

only.values

if TRUE, only the eigenvalues are computed, otherwise both eigenvalues and eigenvectors are computed. Setting only.values = TRUE can speed up eigendecompositions, especially for large matrices. Default is FALSE.

Value

The spectral decomposition of x is returned as a nimbleList with elements:

• values vector containing the eigenvalues of x, sorted in decreasing order. Since x is required to be symmetric, all eigenvalues will be real numbers.

• vectors. matrix with columns containing the eigenvectors of x, or an empty matrix if only.values is TRUE.

Details

Computes the spectral decomposition of a numeric matrix using the Eigen C++ template library. In a nimbleFunction, eigen is identical to nimEigen. If the matrix is symmetric, a faster and more accurate algorithm will be used to compute the eigendecomposition. Note that non-symmetric matrices can have complex eigenvalues, which are not supported by NIMBLE. If a complex eigenvalue or a complex element of an eigenvector is detected, a warning will be issued and that element will be returned as NaN.

Additionally, returnType(eigenNimbleList()) can be used within a link{nimbleFunction} to specify that the function will return a nimbleList generated by the nimEigen function. eigenNimbleList() can also be used to define a nested nimbleList element. See the User Manual for usage examples.

See Also

nimSvd for singular value decompositions in NIMBLE.

Examples

# NOT RUN {
eigenvaluesDemoFunction <- nimbleFunction(
   setup = function(){
     demoMatrix <- diag(4) + 2
   },
   run = function(){
     eigenvalues <- eigen(demoMatrix, symmetric = TRUE)$values
     returnType(double(1))
     return(eigenvalues)
 })

# }