1ZHEEVR(1) LAPACK driver routine (version 3.2) ZHEEVR(1)
2
6 ZHEEVR - computes selected eigenvalues and, optionally, eigenvectors of
7 a complex Hermitian matrix A
8
10 SUBROUTINE ZHEEVR( JOBZ, RANGE, UPLO, N, A, LDA, VL, VU, IL, IU,
11 ABSTOL, M, W, Z, LDZ, ISUPPZ, WORK, LWORK, RWORK,
12 LRWORK, IWORK, LIWORK, INFO )
13 CHARACTER JOBZ, RANGE, UPLO
15 INTEGER IL, INFO, IU, LDA, LDZ, LIWORK, LRWORK, LWORK, M, N
17 DOUBLE PRECISION ABSTOL, VL, VU
19 INTEGER ISUPPZ( * ), IWORK( * )
21 DOUBLE PRECISION RWORK( * ), W( * )
23 COMPLEX*16 A( LDA, * ), WORK( * ), Z( LDZ, * )
25
27 ZHEEVR computes selected eigenvalues and, optionally, eigenvectors of a
28 complex Hermitian matrix A. Eigenvalues and eigenvectors can be
29 selected by specifying either a range of values or a range of indices
30 for the desired eigenvalues.
31 ZHEEVR first reduces the matrix A to tridiagonal form T with a call to
32 ZHETRD. Then, whenever possible, ZHEEVR calls ZSTEMR to compute eigen‐
33 spectrum using Relatively Robust Representations. ZSTEMR computes ei‐
34 genvalues by the dqds algorithm, while orthogonal eigenvectors are com‐
35 puted from various "good" L D L^T representations (also known as Rela‐
36 tively Robust Representations). Gram-Schmidt orthogonalization is
37 avoided as far as possible. More specifically, the various steps of the
38 algorithm are as follows.
39 For each unreduced block (submatrix) of T,
40 (a) Compute T - sigma I = L D L^T, so that L and D
41 define all the wanted eigenvalues to high relative accuracy.
42 This means that small relative changes in the entries of D and L
43 cause only small relative changes in the eigenvalues and
44 eigenvectors. The standard (unfactored) representation of the
45 tridiagonal matrix T does not have this property in general.
46 (b) Compute the eigenvalues to suitable accuracy.
47 If the eigenvectors are desired, the algorithm attains full
48 accuracy of the computed eigenvalues only right before
49 the corresponding vectors have to be computed, see steps c) and
50 d).
51 (c) For each cluster of close eigenvalues, select a new
52 shift close to the cluster, find a new factorization, and refine
53 the shifted eigenvalues to suitable accuracy.
54 (d) For each eigenvalue with a large enough relative separation com‐
55 pute
56 the corresponding eigenvector by forming a rank revealing
57 twisted
58 factorization. Go back to (c) for any clusters that remain. The
59 desired accuracy of the output can be specified by the input parameter
60 ABSTOL.
61 For more details, see DSTEMR's documentation and:
62 - Inderjit S. Dhillon and Beresford N. Parlett: "Multiple representa‐
63 tions
64 to compute orthogonal eigenvectors of symmetric tridiagonal matri‐
65 ces,"
66 Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
67 - Inderjit Dhillon and Beresford Parlett: "Orthogonal Eigenvectors and
68 Relative Gaps," SIAM Journal on Matrix Analysis and Applications,
69 Vol. 25,
70 2004. Also LAPACK Working Note 154.
71 - Inderjit Dhillon: "A new O(n^2) algorithm for the symmetric
72 tridiagonal eigenvalue/eigenvector problem",
73 Computer Science Division Technical Report No. UCB/CSD-97-971,
74 UC Berkeley, May 1997.
75 Note 1 : ZHEEVR calls ZSTEMR when the full spectrum is requested on
76 machines which conform to the ieee-754 floating point standard. ZHEEVR
77 calls DSTEBZ and ZSTEIN on non-ieee machines and
78 when partial spectrum requests are made.
79 Normal execution of ZSTEMR may create NaNs and infinities and hence may
80 abort due to a floating point exception in environments which do not
81 handle NaNs and infinities in the ieee standard default manner.
82
84 JOBZ (input) CHARACTER*1
85 = 'N': Compute eigenvalues only;
86 = 'V': Compute eigenvalues and eigenvectors.
87 RANGE (input) CHARACTER*1
89 = 'A': all eigenvalues will be found.
90 = 'V': all eigenvalues in the half-open interval (VL,VU] will
91 be found. = 'I': the IL-th through IU-th eigenvalues will be
92 found.
93 UPLO (input) CHARACTER*1
95 = 'U': Upper triangle of A is stored;
96 = 'L': Lower triangle of A is stored.
97 N (input) INTEGER
99 The order of the matrix A. N >= 0.
100 A (input/output) COMPLEX*16 array, dimension (LDA, N)
102 On entry, the Hermitian matrix A. If UPLO = 'U', the leading
103 N-by-N upper triangular part of A contains the upper triangular
104 part of the matrix A. If UPLO = 'L', the leading N-by-N lower
105 triangular part of A contains the lower triangular part of the
106 matrix A. On exit, the lower triangle (if UPLO='L') or the
107 upper triangle (if UPLO='U') of A, including the diagonal, is
108 destroyed.
109 LDA (input) INTEGER
111 The leading dimension of the array A. LDA >= max(1,N).
112 VL (input) DOUBLE PRECISION
114 VU (input) DOUBLE PRECISION If RANGE='V', the lower and
115 upper bounds of the interval to be searched for eigenvalues. VL
116 < VU. Not referenced if RANGE = 'A' or 'I'.
117 IL (input) INTEGER
119 IU (input) INTEGER If RANGE='I', the indices (in ascending
120 order) of the smallest and largest eigenvalues to be returned.
121 1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0. Not
122 referenced if RANGE = 'A' or 'V'.
123 ABSTOL (input) DOUBLE PRECISION
125 The absolute error tolerance for the eigenvalues. An approxi‐
126 mate eigenvalue is accepted as converged when it is determined
127 to lie in an interval [a,b] of width less than or equal to
128 ABSTOL + EPS * max( |a|,|b| ) , where EPS is the machine pre‐
129 cision. If ABSTOL is less than or equal to zero, then EPS*|T|
130 will be used in its place, where |T| is the 1-norm of the
131 tridiagonal matrix obtained by reducing A to tridiagonal form.
132 See "Computing Small Singular Values of Bidiagonal Matrices
133 with Guaranteed High Relative Accuracy," by Demmel and Kahan,
134 LAPACK Working Note #3. If high relative accuracy is impor‐
135 tant, set ABSTOL to DLAMCH( 'Safe minimum' ). Doing so will
136 guarantee that eigenvalues are computed to high relative accu‐
137 racy when possible in future releases. The current code does
138 not make any guarantees about high relative accuracy, but
139 furutre releases will. See J. Barlow and J. Demmel, "Computing
140 Accurate Eigensystems of Scaled Diagonally Dominant Matrices",
141 LAPACK Working Note #7, for a discussion of which matrices
142 define their eigenvalues to high relative accuracy.
143 M (output) INTEGER
145 The total number of eigenvalues found. 0 <= M <= N. If RANGE
146 = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
147 W (output) DOUBLE PRECISION array, dimension (N)
149 The first M elements contain the selected eigenvalues in
150 ascending order.
151 Z (output) COMPLEX*16 array, dimension (LDZ, max(1,M))
153 If JOBZ = 'V', then if INFO = 0, the first M columns of Z con‐
154 tain the orthonormal eigenvectors of the matrix A corresponding
155 to the selected eigenvalues, with the i-th column of Z holding
156 the eigenvector associated with W(i). If JOBZ = 'N', then Z is
157 not referenced. Note: the user must ensure that at least
158 max(1,M) columns are supplied in the array Z; if RANGE = 'V',
159 the exact value of M is not known in advance and an upper bound
160 must be used.
161 LDZ (input) INTEGER
163 The leading dimension of the array Z. LDZ >= 1, and if JOBZ =
164 'V', LDZ >= max(1,N).
165 ISUPPZ (output) INTEGER array, dimension ( 2*max(1,M) )
167 The support of the eigenvectors in Z, i.e., the indices indi‐
168 cating the nonzero elements in Z. The i-th eigenvector is
169 nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ).
170 WORK (workspace/output) COMPLEX*16 array, dimension (MAX(1,LWORK))
172 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
173 LWORK (input) INTEGER
175 The length of the array WORK. LWORK >= max(1,2*N). For opti‐
176 mal efficiency, LWORK >= (NB+1)*N, where NB is the max of the
177 blocksize for ZHETRD and for ZUNMTR as returned by ILAENV. If
178 LWORK = -1, then a workspace query is assumed; the routine only
179 calculates the optimal sizes of the WORK, RWORK and IWORK
180 arrays, returns these values as the first entries of the WORK,
181 RWORK and IWORK arrays, and no error message related to LWORK
182 or LRWORK or LIWORK is issued by XERBLA.
183 RWORK (workspace/output) DOUBLE PRECISION array, dimension
185 (MAX(1,LRWORK))
186 On exit, if INFO = 0, RWORK(1) returns the optimal (and mini‐
187 mal) LRWORK. The length of the array RWORK. LRWORK >=
188 max(1,24*N). If LRWORK = -1, then a workspace query is
189 assumed; the routine only calculates the optimal sizes of the
190 WORK, RWORK and IWORK arrays, returns these values as the first
191 entries of the WORK, RWORK and IWORK arrays, and no error mes‐
192 sage related to LWORK or LRWORK or LIWORK is issued by XERBLA.
193 IWORK (workspace/output) INTEGER array, dimension (MAX(1,LIWORK))
195 On exit, if INFO = 0, IWORK(1) returns the optimal (and mini‐
196 mal) LIWORK. The dimension of the array IWORK. LIWORK >=
197 max(1,10*N). If LIWORK = -1, then a workspace query is
198 assumed; the routine only calculates the optimal sizes of the
199 WORK, RWORK and IWORK arrays, returns these values as the first
200 entries of the WORK, RWORK and IWORK arrays, and no error mes‐
201 sage related to LWORK or LRWORK or LIWORK is issued by XERBLA.
202 INFO (output) INTEGER
204 = 0: successful exit
205 < 0: if INFO = -i, the i-th argument had an illegal value
206 > 0: Internal error
207
209 Based on contributions by
210 Inderjit Dhillon, IBM Almaden, USA
211 Osni Marques, LBNL/NERSC, USA
212 Ken Stanley, Computer Science Division, University of
213 California at Berkeley, USA
214 Jason Riedy, Computer Science Division, University of
215 California at Berkeley, USA
216 LAPACK driver routine (version 3.N2o)vember 2008 ZHEEVR(1)