1CHEEVR(1) LAPACK driver routine (version 3.2) CHEEVR(1)
2
6 CHEEVR - computes selected eigenvalues and, optionally, eigenvectors of
7 a complex Hermitian matrix A
8
10 SUBROUTINE CHEEVR( 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 REAL ABSTOL, VL, VU
19 INTEGER ISUPPZ( * ), IWORK( * )
21 REAL RWORK( * ), W( * )
23 COMPLEX A( LDA, * ), WORK( * ), Z( LDZ, * )
25
27 CHEEVR 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 CHEEVR first reduces the matrix A to tridiagonal form T with a call to
32 CHETRD. Then, whenever possible, CHEEVR calls CSTEMR to compute the
33 eigenspectrum using Relatively Robust Representations. CSTEMR computes
34 eigenvalues by the dqds algorithm, while orthogonal eigenvectors are
35 computed from various "good" L D L^T representations (also known as
36 Relatively 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 : CHEEVR calls CSTEMR when the full spectrum is requested on
76 machines which conform to the ieee-754 floating point standard. CHEEVR
77 calls SSTEBZ and CSTEIN on non-ieee machines and
78 when partial spectrum requests are made.
79 Normal execution of CSTEMR 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 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) REAL
114 VU (input) REAL If RANGE='V', the lower and upper bounds
115 of the interval to be searched for eigenvalues. VL < VU. Not
116 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) REAL
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 SLAMCH( '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) REAL array, dimension (N)
149 The first M elements contain the selected eigenvalues in
150 ascending order.
151 Z (output) COMPLEX 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 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 CHETRD and for CUNMTR 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) REAL array, dimension (MAX(1,LRWORK))
185 On exit, if INFO = 0, RWORK(1) returns the optimal (and mini‐
186 mal) LRWORK. The length of the array RWORK. LRWORK >=
187 max(1,24*N). If LRWORK = -1, then a workspace query is
188 assumed; the routine only calculates the optimal sizes of the
189 WORK, RWORK and IWORK arrays, returns these values as the first
190 entries of the WORK, RWORK and IWORK arrays, and no error mes‐
191 sage related to LWORK or LRWORK or LIWORK is issued by XERBLA.
192 IWORK (workspace/output) INTEGER array, dimension (MAX(1,LIWORK))
194 On exit, if INFO = 0, IWORK(1) returns the optimal (and mini‐
195 mal) LIWORK. The dimension of the array IWORK. LIWORK >=
196 max(1,10*N). If LIWORK = -1, then a workspace query is
197 assumed; the routine only calculates the optimal sizes of the
198 WORK, RWORK and IWORK arrays, returns these values as the first
199 entries of the WORK, RWORK and IWORK arrays, and no error mes‐
200 sage related to LWORK or LRWORK or LIWORK is issued by XERBLA.
201 INFO (output) INTEGER
203 = 0: successful exit
204 < 0: if INFO = -i, the i-th argument had an illegal value
205 > 0: Internal error
206
208 Based on contributions by
209 Inderjit Dhillon, IBM Almaden, USA
210 Osni Marques, LBNL/NERSC, USA
211 Ken Stanley, Computer Science Division, University of
212 California at Berkeley, USA
213 Jason Riedy, Computer Science Division, University of
214 California at Berkeley, USA
215 LAPACK driver routine (version 3.N2o)vember 2008 CHEEVR(1)