LA_EIGENQL

The LA_EIGENQL function computes selected eigenvalues l and eigenvectors z ¹ 0 of an n-by-n real symmetric or complex Hermitian array A, for the eigenproblem Az = lz.


Output Type	Standard Eigenproblem	Generalized
Float	ssyevx, ssyevr, ssyevd	ssygvx, ssygvd
Double	dsyevx, dsyevr, dsyevd	dsygvx, dsygvd
Complex	cheevx, cheevr, cheevd	chegvx, chegvd
Double complex	zheevx, zheevr, zheevd	zhegvx, zhegvd

Syntax

Result = LA_EIGENQL( A [, B] [, /DOUBLE] [, EIGENVECTORS=variable] [, FAILED=variable] [, GENERALIZED=value] [, METHOD=value] [, RANGE=vector] [, SEARCH_RANGE=vector] [, STATUS=variable] [, TOLERANCE=value] )

Return Value

Arguments

The real or complex n-by-n array for which to compute eigenvalues and eigenvectors. A must be symmetric (or Hermitian).

An optional real or complex n-by-n array used for the generalized eigenproblem. B must be symmetric (or Hermitian) and positive definite. The elements of B are converted to the same type as A before computation.

Keywords

DOUBLE

Set this keyword to use double-precision for computations and to return a double-precision (real or complex) result. Set DOUBLE = 0 to use single-precision for computations and to return a single-precision (real or complex) result. The default is /DOUBLE if A is double precision, otherwise the default is DOUBLE = 0.

EIGENVECTORS

Set this keyword to a named variable in which the eigenvectors will be returned as a set of row vectors. If this variable is omitted then eigenvectors will not be computed. All eigenvectors will be returned unless the RANGE or SEARCH_RANGE keywords are used to restrict the eigenvalue range.

FAILED

Set this keyword to a named variable in which to return the indices of eigenvectors that did not converge. This keyword is only available for METHOD = 0, and will be ignored for other methods.

GENERALIZED

For the generalized eigenproblem with the optional B argument, set this keyword to indicate which problem to solve. Possible values are:

METHOD

Set this keyword to indicate which computation method to use. Possible values are:

METHOD = 0 (the default): Use tridiagonal decomposition to compute some or all of the eigenvalues and (optionally) eigenvectors.

METHOD = 1: Use the Relatively Robust Representation (RRR) algorithm to compute some or all of the eigenvalues and (optionally) eigenvectors. This method is unavailable for the generalized eigenproblem with the optional B argument, and will default to METHOD = 0.

METHOD = 2: Use a divide-and-conquer algorithm to compute all of the eigenvalues and (optionally) all eigenvectors. This method is available for either the standard or generalized eigenproblems. For METHOD = 2 the RANGE, SEARCH_RANGE, and TOLERANCE keywords are ignored, and all eigenvalues are returned.

RANGE

Set this keyword to a two-element vector containing the indices of the smallest and largest eigenvalues to be returned. The default is [0, n-1], which returns all eigenvalues and eigenvectors. This keyword is ignored for METHOD = 2.

SEARCH_RANGE

Set this keyword to a two-element floating-point vector containing the lower and upper bounds of the interval to be searched for eigenvalues. The default is to return all eigenvalues and eigenvectors. This keyword is ignored for METHOD = 2. If both RANGE and SEARCH_RANGE are specified, only the SEARCH_RANGE values are used.

STATUS

Set this keyword to a named variable that will contain the status of the computation. In all cases STATUS = 0 indicates successful computation. For the standard eigenproblem, possible nonzero values are:

METHOD = 0, STATUS > 0: STATUS eigenvectors failed to converge. The FAILED keyword contains the indices of the eigenvectors that did not converge.

METHOD = 1, STATUS < 0 or STATUS > 0: An internal error occurred during the computation.

METHOD = 2, STATUS > 0: STATUS off-diagonal elements of an intermediate tridiagonal matrix did not converge to zero.

METHOD = 0, 0 < STATUS £ n: STATUS eigenvectors failed to converge. The FAILED keyword contains the indices of the eigenvectors that did not converge.

METHOD = 0, STATUS > n: The factorization of B could not be completed and the computation failed. The value of (STATUS - n) specifies the order of the leading minor of B which is not positive definite.

METHOD = 2, 0 < STATUS £ n: STATUS off-diagonal elements of an intermediate tridiagonal matrix did not converge to zero.

METHOD = 2, STATUS > n: The factorization of B could not be completed and the computation failed. The value of (STATUS - n) specifies the order of the leading minor of B which is not positive definite.

TOLERANCE

Set this keyword to a scalar giving the absolute error tolerance for the eigenvalues and eigenvectors. For the most accurate eigenvalues, TOLERANCE should be set to 2*XMIN, where XMIN is the magnitude of the smallest usable floating-point value. For METHOD = 0, if TOLERANCE is less than or equal to zero, or is unspecified, then a tolerance value of EPS*||T||₁ will be used, where T is the tridiagonal matrix obtained from A. For METHOD = 1, if TOLERANCE is less than or equal to N*EPS*||T||₁, or is unspecified, then a tolerance value of N*EPS*||T||₁ will be used. For values of EPS and XMIN, see the MACHAR. This keyword is ignored for METHOD = 2.

Examples

Find the eigenvalues and eigenvectors for a symmetric array using the following program:

PRO ExLA_EIGENQL 
; Create a random symmetric array: 
n = 10 
seed = 12321 
array = RANDOMN(seed, n, n) 
array = array + TRANSPOSE(array) 
 
; Compute all eigenvalues and eigenvectors: 
eigenvalues = LA_EIGENQL(array, $ 
     EIGENVECTORS=eigenvectors) 
 
; Check the results using the eigenvalue equation: 
maxErr = 0d 
FOR i=0,n-1 DO BEGIN 
; a*z = lambda*z 
alhs = array ## eigenvectors[*,i] 
arhs = eigenvalues[i]*eigenvectors[*,i] 
maxErr = maxErr > MAX(ABS(alhs - arhs)) 
ENDFOR 
PRINT, 'LA_EIGENQL error:', maxErr 
 
; Compute the three largest eigenvalues: 
eigenvalues = LA_EIGENQL(array, $ 
     EIGENVECTORS = eigenvectors, $ 
     RANGE = [n-3,n-1]) 
PRINT, 'LA_EIGENQL eigenvalues:', eigenvalues 
 
; Now try the generalized eigenproblem: 
b = IDENTITY(n) + 0.01*RANDOMN(seed,n,n) 
; Make B symmetric and positive definite: 
b = b ## TRANSPOSE(b) 
 
; Compute the three largest generalized eigenvalues: 
eigenvalues = LA_EIGENQL(array, b, RANGE=[n-3,n-1]) 
PRINT, 'LA_EIGENQL Generalized Eigenvalues:' 
PRINT, Eigenvalues 
END

LA_EIGENQL error:   1.3560057e-06 
LA_EIGENQL eigenvalues:      3.82993      4.69785      5.61567 
LA_EIGENQL generalized eigenvalues: 
3.83750      4.74803      5.57692