Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

LAPACK routines
[Non-member C-style functions]

Collaboration diagram for LAPACK routines:

Interfaces to sophisticated linear algebraic algorithms from LAPACK. More...

Functions

template<typename T>
bool EigenFactor (DenseMatrix< T > &matrix, DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &L_ev, DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &R_ev, DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &evals)
 Computes the eigenvalues and eigenvectors of a general matrix.
template<typename T>
bool RightEigenVectors (DenseMatrix< T > &matrix, DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &R_ev, DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &evals)
 Computes the eigenvalues and right eigenvectors only of a general matrix.
template<typename T>
bool LeftEigenVectors (DenseMatrix< T > &matrix, DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &L_ev, DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &evals)
 Computes the eigenvalues and right eigenvectors only of a general matrix.
template<typename T>
bool EigenValues (DenseMatrix< T > &matrix, DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &evals)
 Computes the eigenvalues of a general matrix.
bool EigenFactorSymmetric (DenseMatrix< double > &matrix, DenseMatrix< double > &ev, DenseVector< double > &evals)
 Computes the eigenvalues and eigenvectors of a symmetric real matrix.
bool EigenValuesSymmetric (DenseMatrix< double > &matrix, DenseVector< double > &evals)
bool EigenFactorHermitian (DenseMatrix< complex > &matrix, DenseMatrix< complex > &ev, DenseVector< double > &evals)
 Computes the eigenvalues and eigenvectors of a Hermitian complex matrix.
bool EigenValuesHermitian (DenseMatrix< complex > &matrix, DenseVector< double > &evals)
 Computes the eigenvalues (only) of a Hermitian complex matrix.

Detailed Description

Interfaces to sophisticated linear algebraic algorithms from LAPACK.

Just as LinAlg relies on BLAS for basic linear algebra functionality, it relies on LAPACK for more complicated tasks. The difference is that the BLAS routines are mostly available through operators, whereas LAPACK routines involve function calls.

As of 6/2006, LinAlg provides algorithms to do two high level operations:

The LAPACK routines should be used with some care; they typically do things that are computationally difficult ($ O(n^3) $ in many cases), so calling them when not necessary will slow your program down substantially. They are also optimized for speed and to minimize storage requirements, which means that in many cases they overwrite their inputs! Check the documentation, and if you need to preserve the input, make a copy and apply the LAPACK routine to the copy.

Cholesky Factorization

The Cholesky factorization of a positive semi-definite matrix $ M $ is an upper-triangular matrix $ U $ , with positive real diagonal entries, such that $ U^\dagger U = M $ . Another way to see this factorization is as a lower-triangular matrix $ L $ such that $ L L^\dagger = M $ . The matrix $ M $ must be Hermitian positive definite, or symmetric positive definite for real matrices. The factorization is unique -- there are many matrices that satisfy the condition $ S^\dagger S = M $ , but only one is upper-triangular with positive real diagonal entries.

The LinAlg routine CholeskyFactor() is overloaded to take a reference to a DenseMatrix<double> or a DenseMatrix<complex> as its first argument. An optional boolean second argument determines whether the upper-triangular or lower-triangular factorization is computed (default is upper-triangular). The original argument is overwritten by the factor.

Eigenvalues and Eigenvectors

The eigenvectors of a matrix $ M $ are the vectors such that $ M \cdot \vec{e_i} = \lambda_i \vec{e_i} $ for some scalar $ \lambda_i $ . The eigenvalues are the scalars $ \{\lambda_i\} $ . A detailed discussion of spectral theory is beyond this document, but if a matrix is normal, then it can be written as $ M = U \Lambda U^\dagger $ , where $ \Lambda $ is a diagonal matrix ($ \Lambda_{ij} = \delta_{ij}\lambda_i $ , and $ U $ is a unitary matrix. The diagonal entries of $ \Lambda $ are the eigenvalues of $ M $ , and the columns of $ U $ are the corresponding normalized eigenvectors.

This factorization is unique only if the eigenvalues are nondegenerate; if they are degenerate, then the eigenvectors corresponding to equal eigenvalues can be rearranged as arbitrary linear combinations of each other. It's more appropriate to speak in this case of eigen-spaces.

Hermitian or real-symmetric matrices are always normal. If the matrix is not normal, then it may not be decomposable in this way. However, every matrix can be decomposed as $ M = U \Lambda V^\dagger $ , where $ U $ and $ V $ are (possibly different) unitary matrices. The columns of $ V $ are the right eigenvectors of $ M $ , and those of $ U $ are the left eigenvectors of $ M $ .

The eigenfactorization routines in LinAlg compute this factorization, or part of it. The factorization is returned in objects that you create and pass to the function: eigenvalues are returned in a DenseVector; eigenvectors are returned in one or two DenseMatrix objects. These will be resized if necessary -- but only to make them larger; if they are larger than necessary, the eigenfactoring routines will just fill the relevant portion. The input matrix is overwritten. The actual return value from the function is a boolean that identifies success (TRUE) or failure (FALSE).

Which routine to use depends on what you know about the matrix, and what you want to accomplish. If you only want the eigenvalues, it will be much faster to avoid computing eigenvectors.

Function Documentation

template<typename T>
bool EigenFactor (  DenseMatrix< T > &  matrix,
DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &  L_ev,
DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &  R_ev,
DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &  evals
) 
 

Computes the eigenvalues and eigenvectors of a general matrix.

Both left and right eigenvectors are computed, along with eigenvalues. The eigendecomposition is returned via references passed to EigenFactor. In other words, you must declare a DenseVector of the appropriate type (to hold the returned eigenvalues), and two DenseMatrix objects (to hold the left and right eigenvectors). These will be resized by EigenFactor(), if necessary to hold the return values. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

template<typename T>
bool RightEigenVectors (  DenseMatrix< T > &  matrix,
DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &  R_ev,
DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &  evals
) 
 

Computes the eigenvalues and right eigenvectors only of a general matrix.

Only right eigenvectors are computed, along with eigenvalues. The eigendecomposition is returned via references passed to RightEigenVectors. In other words, you must declare a DenseVector of the appropriate type (to hold the returned eigenvalues), and a DenseMatrix (to hold the eigenvectors). These will be resized by RightEigenVectors(), if necessary to hold the return values. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

template<typename T>
bool LeftEigenVectors (  DenseMatrix< T > &  matrix,
DenseMatrix< typename linalg_traits< T >::general_eigenvector_type > &  L_ev,
DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &  evals
) 
 

Computes the eigenvalues and right eigenvectors only of a general matrix.

Only left eigenvectors are computed, along with eigenvalues. The eigendecomposition is returned via references passed to LeftEigenVectors. In other words, you must declare a DenseVector of the appropriate type (to hold the returned eigenvalues), and a DenseMatrix (to hold the eigenvectors). These will be resized by LeftEigenVectors(), if necessary to hold the return values. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

template<typename T>
bool EigenValues (  DenseMatrix< T > &  matrix,
DenseVector< typename linalg_traits< T >::general_eigenvalue_type > &  evals
) 
 

Computes the eigenvalues of a general matrix.

Only the eigenvalues are computed. They are returned in a reference passed to EigenValues. In other words, you must declare a DenseVector of the appropriate type (to hold the returned eigenvalues). This will be resized by EigenValues(), if necessary to hold the eigenvalues. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

bool EigenFactorSymmetric (  DenseMatrix< double > &  matrix,
DenseMatrix< double > &  ev,
DenseVector< double > &  evals
) 
 

Computes the eigenvalues and eigenvectors of a symmetric real matrix.

The matrix is assumed to be symmetric (the lower triangle will be ignored). Left and right eigenvectors therefore coincide. The eigendecomposition is returned via references passed to EigenFactorSymmetric. In other words, you must declare a DenseVector<double> (to hold the returned eigenvalues), and a DenseMatrix<double> (to hold the eigenvectors). These will be resized by EigenFactorSymmetric(), if necessary to hold the result. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

bool EigenValuesSymmetric (  DenseMatrix< double > &  matrix,
DenseVector< double > &  evals
) 
 

Computes the eigenvalues (only) of a symmetric real matrix.

The matrix is assumed to be symmetric (the lower triangle will be ignored). The eigenvalues are returned via a reference passed to EigenValuesSymmetric. In other words, you must declare a DenseVector<double> (to hold the returned eigenvalues). This will be resized by EigenFactorSymmetric(), if necessary to hold the result. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

bool EigenFactorHermitian (  DenseMatrix< complex > &  matrix,
DenseMatrix< complex > &  ev,
DenseVector< double > &  evals
) 
 

Computes the eigenvalues and eigenvectors of a Hermitian complex matrix.

The matrix is assumed to be Hermitian (the lower triangle will be ignored). Left and right eigenvectors therefore coincide. The eigendecomposition is returned via references passed to EigenFactorSymmetric. In other words, you must declare a DenseVector<double> (to hold the returned eigenvalues), and a DenseMatrix<complex> (to hold the eigenvectors). These will be resized by EigenFactorHermitian(), if necessary to hold the result. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

bool EigenValuesHermitian (  DenseMatrix< complex > &  matrix,
DenseVector< double > &  evals
) 
 

Computes the eigenvalues (only) of a Hermitian complex matrix.

The matrix is assumed to be Hermitian (the lower triangle will be ignored). The eigenvalues are returned via a reference passed to EigenValuesSymmetric. In other words, you must declare a DenseVector<double> (to hold the returned eigenvalues). This will be resized by EigenFactorSymmetric(), if necessary to hold the result. The return value is "TRUE" unless the routine failed.

IMPORTANT NOTE: The input matrix will be overwritten by garbage! Store a copy elsewhere before using the eigen-routines.

Generated on Wed Jun 14 22:25:33 2006 for linalg by  doxygen 1.4.4