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

LA_EIGENQL may also be used for the generalized symmetric eigenproblems:

Az = λBz or ABz = λz or BAz = λz

where A and B are symmetric (or Hermitian) and B is positive definite.

LA_EIGENQL is based on the following LAPACK routines:

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

Examples

The example la_eigenql_doc.pro calculates the eigenvalues and eigenvectors for a symmetric array. This example file is installed in the IDL installation’s /examples/doc/language directory. To view the example code, enter .edit la_eigenql_doc.pro at the IDL command line. To execute the code, enter la_eigenql_doc at the IDL command line.

When this program is compiled and run, IDL prints:

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

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

The result is a real vector containing the eigenvalues in ascending order.

Arguments

A

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

B

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.

Note: For Hermitian input matrices, the resulting eigenvectors are transformed so that the first element of each is real.

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.

Note: Index numbers within FAILED start at 1.

GENERALIZED

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

  • GENERALIZED = 0 (the default): Solve Az = λBz.
  • GENERALIZED = 1: Solve ABz = λz.
  • GENERALIZED = 2: Solve BAz = λz.

This keyword is ignored if argument B is not present.

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.

Note: The RRR method may produce NaN and Infinity floating-point exception messages during normal execution.

  • 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.

Note: If the search range does not contain any eigenvalues, then Result, EIGENVECTORS, and FAILED will each be set to a scalar zero.

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.

For the generalized eigenproblem, possible nonzero values are:

  • 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.

Note: If STATUS is not specified, any error messages will be output to the screen.

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||1 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||1, or is unspecified, then a tolerance value of N*EPS*||T||1 will be used. For values of EPS and XMIN, see MACHAR. This keyword is ignored for METHOD = 2.

Tip: If the LA_EIGENQL routine fails to converge, try setting the TOLERANCE to a larger value.

Version History

5.6

Introduced

Resources and References

For details see Anderson et al., LAPACK Users' Guide, 3rd ed., SIAM, 1999.

See Also

EIGENQL, LA_TRIQL, LA_TRIRED