Developer Reference for Intel® oneAPI Math Kernel Library for Fortran
?pteqr
Computes all eigenvalues and (optionally) all eigenvectors of a real symmetric positive-definite tridiagonal matrix.
Syntax
call spteqr ( compz , n , d , e , z , ldz , work , info )
call dpteqr ( compz , n , d , e , z , ldz , work , info )
call cpteqr ( compz , n , d , e , z , ldz , work , info )
call zpteqr ( compz , n , d , e , z , ldz , work , info )
call rpteqr ( d , e [ , z ] [ , compz ] [ , info ] )
call pteqr ( d , e [ , z ] [ , compz ] [ , info ] )
Include Files
mkl.fi , mkl_lapack.f90
Description
spteqr dpteqr cpteqr zpteqr rpteqr pteqr
The routine computes all the eigenvalues and (optionally) all the eigenvectors of a real symmetric positive-definite tridiagonal matrix T . In other words, the routine can compute the spectral factorization: T = Z*Λ*Z^{T} .
Here Λ is a diagonal matrix whose diagonal elements are the eigenvalues λ i ; Z is an orthogonal matrix whose columns are eigenvectors. Thus,
T*z_{i} = λ_{i}*z_{i} for i = 1, 2, ..., n .
(The routine normalizes the eigenvectors so that ||z_{i}||_{2} = 1 .)
You can also use the routine for computing the eigenvalues and eigenvectors of real symmetric (or complex Hermitian) positive-definite matrices A reduced to tridiagonal form T : A = Q*T*Q^{H} . In this case, the spectral factorization is as follows: A = Q*T*Q^{H} = (QZ)*Λ*(QZ)^{H} . Before calling ?pteqr , you must reduce A to tridiagonal form and generate the explicit matrix Q by calling the following routines:
for real matrices: |
for complex matrices: |
|
|---|---|---|
full storage |
?sytrd , ?orgtr |
?hetrd , ?ungtr |
packed storage |
?sptrd , ?opgtr |
?hptrd , ?upgtr |
band storage |
?sbtrd(vect = ‘V’ ) |
?hbtrd(vect = ‘V’ ) |
The routine first factorizes T as L*D*L:code:`H` where L is a unit lower bidiagonal matrix, and D is a diagonal matrix. Then it forms the bidiagonal matrix B = L*D^{1/2} and calls ?bdsqr to compute the singular values of B , which are the square roots of the eigenvalues of T .
Input Parameters
compz
CHARACTER*1 . Must be ‘N’ or ‘I’ or ‘V’ .
If compz = 'N' , the routine computes eigenvalues only. If compz = 'I' , the routine computes the eigenvalues and eigenvectors of the tridiagonal matrix T . If compz = 'V' , the routine computes the eigenvalues and eigenvectors of A (and the array z must contain the matrix Q on entry).
n
INTEGER . The order of the matrix T ( n≥ 0 ).
- d , e , work
-
REAL for single-precision flavors DOUBLE PRECISION for double-precision flavors. Arrays:
d (*) contains the diagonal elements of T .
The size of d must be at least max(1, n ).
e (*) contains the off-diagonal elements of T .
The size of e must be at least max(1, n -1). work (*) is a workspace array. The dimension of work must be: at least 1 if compz = 'N' ; at least max(1, 4* n -4) if compz = 'V' or ‘I’ .
- z
-
REAL for spteqr DOUBLE PRECISION for dpteqr COMPLEX for cpteqr DOUBLE COMPLEX for zpteqr .
Array, size ( ldz ,*)
If compz = 'N' or ‘I’ , z need not be set. If compz = 'V' , z must contain the orthogonal matrix used in the reduction to tridiagonal form.. The second dimension of z must be: at least 1 if compz = 'N' ; at least max(1, n ) if compz = 'V' or ‘I’ .
ldz
INTEGER . The leading dimension of z . Constraints:
ldz ≥ 1 if compz = 'N' ; ldz ≥ max(1, n ) if compz = 'V' or ‘I’ .
Output Parameters
- d
-
The n eigenvalues in descending order, unless info > 0 . See also info .
- e
-
On exit, the array is overwritten.
- z
-
If info = 0 , contains an n -by n matrix the columns of which are orthonormal eigenvectors. (The i -th column corresponds to the i -th eigenvalue.)
info
INTEGER .
If info = 0 , the execution is successful.
If info = i , the leading minor of order i (and hence T itself) is not positive-definite.
If info = n + i , the algorithm for computing singular values failed to converge; i off-diagonal elements have not converged to zero.
If info = -i , the i- th parameter had an illegal value.
Return Values
No return value, info is an Output Parameter.
LAPACK 95 Interface Notes
Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see LAPACK 95 Interface Conventions .
Specific details for the routine pteqr interface are the following:
d
Holds the vector of length n .
e
Holds the vector of length ( n- 1).
z
Holds the matrix Z of size ( n,n ).
compz
If omitted, this argument is restored based on the presence of argument z as follows:
compz = 'I' , if z is present,
compz = 'N' , if z is omitted.
If present, compz must be equal to ‘I’ or ‘V’ and the argument z must also be present. Note that there will be an error condition if compz is present and z omitted.
Note that two variants of Fortran 95 interface for pteqr routine are needed because of an ambiguous choice between real and complex cases appear when z is omitted. Thus, the name rpteqr is used in real cases (single or double precision), and the name pteqr is used in complex cases (single or double precision).
Application Notes
If λ i is an exact eigenvalue, and μ i is the corresponding computed value, then
\(|\mu_{i} - \lambda_{i}| \leq c(n) \varepsilon K \lambda_{i}\)
where c(n) is a modestly increasing function of n , \(\varepsilon\) is the machine precision, and \(K = ||DTD||_{2} ||(DTD)^{-1}||_{2}\) , \(D\) is diagonal with \(d_{ii} = t_{ii}^{-1/2}\) .
If zi is the corresponding exact eigenvector, and wi is the corresponding computed vector, then the angle \(\theta\) ( zi , wi ) between them is bounded as follows:
\(\theta(u_{i}, w_{i}) \leq c(n)\varepsilon K / min_{i\neq j}(|\lambda_{i} - \lambda_{j}|/|\lambda_{i} + \lambda_{j}|)\) .
Here \(min_{i\neq j}(|\lambda_{i} - \lambda_{j}|/|\lambda_{i} + \lambda_{j}|)\) is the relative gap between λ i and the other eigenvalues.
The total number of floating-point operations depends on how rapidly the algorithm converges.
Typically, it is about
\(30n^{2}\) if compz = 'N' ;
\(6n^{3}\) (for complex flavors, \(12n^{3}\) ) if compz = 'V' or ‘I’ .