1DGGESX(1) LAPACK driver routine (version 3.2) DGGESX(1)
2
6 DGGESX - computes for a pair of N-by-N real nonsymmetric matrices
7 (A,B), the generalized eigenvalues, the real Schur form (S,T), and,
8
10 SUBROUTINE DGGESX( JOBVSL, JOBVSR, SORT, SELCTG, SENSE, N, A, LDA, B,
11 LDB, SDIM, ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR,
12 LDVSR, RCONDE, RCONDV, WORK, LWORK, IWORK, LIWORK,
13 BWORK, INFO )
14 CHARACTER JOBVSL, JOBVSR, SENSE, SORT
16 INTEGER INFO, LDA, LDB, LDVSL, LDVSR, LIWORK, LWORK, N, SDIM
18 LOGICAL BWORK( * )
20 INTEGER IWORK( * )
22 DOUBLE PRECISION A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B(
24 LDB, * ), BETA( * ), RCONDE( 2 ), RCONDV( 2 ), VSL(
25 LDVSL, * ), VSR( LDVSR, * ), WORK( * )
26 LOGICAL SELCTG
28 EXTERNAL SELCTG
30
32 DGGESX computes for a pair of N-by-N real nonsymmetric matrices (A,B),
33 the generalized eigenvalues, the real Schur form (S,T), and, option‐
34 ally, the left and/or right matrices of Schur vectors (VSL and VSR).
35 This gives the generalized Schur factorization
36 (A,B) = ( (VSL) S (VSR)**T, (VSL) T (VSR)**T )
37 Optionally, it also orders the eigenvalues so that a selected cluster
38 of eigenvalues appears in the leading diagonal blocks of the upper
39 quasi-triangular matrix S and the upper triangular matrix T; computes a
40 reciprocal condition number for the average of the selected eigenvalues
41 (RCONDE); and computes a reciprocal condition number for the right and
42 left deflating subspaces corresponding to the selected eigenvalues
43 (RCONDV). The leading columns of VSL and VSR then form an orthonormal
44 basis for the corresponding left and right eigenspaces (deflating sub‐
45 spaces).
46 A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or
47 a ratio alpha/beta = w, such that A - w*B is singular. It is usually
48 represented as the pair (alpha,beta), as there is a reasonable inter‐
49 pretation for beta=0 or for both being zero. A pair of matrices (S,T)
50 is in generalized real Schur form if T is upper triangular with non-
51 negative diagonal and S is block upper triangular with 1-by-1 and
52 2-by-2 blocks. 1-by-1 blocks correspond to real generalized eigenval‐
53 ues, while 2-by-2 blocks of S will be "standardized" by making the cor‐
54 responding elements of T have the form:
55 [ a 0 ]
56 [ 0 b ]
57 and the pair of corresponding 2-by-2 blocks in S and T will have a com‐
58 plex conjugate pair of generalized eigenvalues.
59
61 JOBVSL (input) CHARACTER*1
62 = 'N': do not compute the left Schur vectors;
63 = 'V': compute the left Schur vectors.
64 JOBVSR (input) CHARACTER*1
66 = 'N': do not compute the right Schur vectors;
67 = 'V': compute the right Schur vectors.
68 SORT (input) CHARACTER*1
70 Specifies whether or not to order the eigenvalues on the diago‐
71 nal of the generalized Schur form. = 'N': Eigenvalues are not
72 ordered;
73 = 'S': Eigenvalues are ordered (see SELCTG).
74 SELCTG (external procedure) LOGICAL FUNCTION of three DOUBLE PRECISION
76 arguments
77 SELCTG must be declared EXTERNAL in the calling subroutine. If
78 SORT = 'N', SELCTG is not referenced. If SORT = 'S', SELCTG is
79 used to select eigenvalues to sort to the top left of the Schur
80 form. An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected
81 if SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either
82 one of a complex conjugate pair of eigenvalues is selected,
83 then both complex eigenvalues are selected. Note that a
84 selected complex eigenvalue may no longer satisfy
85 SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering,
86 since ordering may change the value of complex eigenvalues
87 (especially if the eigenvalue is ill-conditioned), in this case
88 INFO is set to N+3.
89 SENSE (input) CHARACTER*1
91 Determines which reciprocal condition numbers are computed. =
92 'N' : None are computed;
93 = 'E' : Computed for average of selected eigenvalues only;
94 = 'V' : Computed for selected deflating subspaces only;
95 = 'B' : Computed for both. If SENSE = 'E', 'V', or 'B', SORT
96 must equal 'S'.
97 N (input) INTEGER
99 The order of the matrices A, B, VSL, and VSR. N >= 0.
100 A (input/output) DOUBLE PRECISION array, dimension (LDA, N)
102 On entry, the first of the pair of matrices. On exit, A has
103 been overwritten by its generalized Schur form S.
104 LDA (input) INTEGER
106 The leading dimension of A. LDA >= max(1,N).
107 B (input/output) DOUBLE PRECISION array, dimension (LDB, N)
109 On entry, the second of the pair of matrices. On exit, B has
110 been overwritten by its generalized Schur form T.
111 LDB (input) INTEGER
113 The leading dimension of B. LDB >= max(1,N).
114 SDIM (output) INTEGER
116 If SORT = 'N', SDIM = 0. If SORT = 'S', SDIM = number of ei‐
117 genvalues (after sorting) for which SELCTG is true. (Complex
118 conjugate pairs for which SELCTG is true for either eigenvalue
119 count as 2.)
120 ALPHAR (output) DOUBLE PRECISION array, dimension (N)
122 ALPHAI (output) DOUBLE PRECISION array, dimension (N) BETA
123 (output) DOUBLE PRECISION array, dimension (N) On exit,
124 (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the gen‐
125 eralized eigenvalues. ALPHAR(j) + ALPHAI(j)*i and
126 BETA(j),j=1,...,N are the diagonals of the complex Schur form
127 (S,T) that would result if the 2-by-2 diagonal blocks of the
128 real Schur form of (A,B) were further reduced to triangular
129 form using 2-by-2 complex unitary transformations. If
130 ALPHAI(j) is zero, then the j-th eigenvalue is real; if posi‐
131 tive, then the j-th and (j+1)-st eigenvalues are a complex con‐
132 jugate pair, with ALPHAI(j+1) negative. Note: the quotients
133 ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may easily over- or
134 underflow, and BETA(j) may even be zero. Thus, the user should
135 avoid naively computing the ratio. However, ALPHAR and ALPHAI
136 will be always less than and usually comparable with norm(A) in
137 magnitude, and BETA always less than and usually comparable
138 with norm(B).
139 VSL (output) DOUBLE PRECISION array, dimension (LDVSL,N)
141 If JOBVSL = 'V', VSL will contain the left Schur vectors. Not
142 referenced if JOBVSL = 'N'.
143 LDVSL (input) INTEGER
145 The leading dimension of the matrix VSL. LDVSL >=1, and if JOB‐
146 VSL = 'V', LDVSL >= N.
147 VSR (output) DOUBLE PRECISION array, dimension (LDVSR,N)
149 If JOBVSR = 'V', VSR will contain the right Schur vectors. Not
150 referenced if JOBVSR = 'N'.
151 LDVSR (input) INTEGER
153 The leading dimension of the matrix VSR. LDVSR >= 1, and if
154 JOBVSR = 'V', LDVSR >= N.
155 RCONDE (output) DOUBLE PRECISION array, dimension ( 2 )
157 If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the
158 reciprocal condition numbers for the average of the selected
159 eigenvalues. Not referenced if SENSE = 'N' or 'V'.
160 RCONDV (output) DOUBLE PRECISION array, dimension ( 2 )
162 If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the
163 reciprocal condition numbers for the selected deflating sub‐
164 spaces. Not referenced if SENSE = 'N' or 'E'.
165 WORK (workspace/output) DOUBLE PRECISION array, dimension
167 (MAX(1,LWORK))
168 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
169 LWORK (input) INTEGER
171 The dimension of the array WORK. If N = 0, LWORK >= 1, else if
172 SENSE = 'E', 'V', or 'B', LWORK >= max( 8*N, 6*N+16, 2*SDIM*(N-
173 SDIM) ), else LWORK >= max( 8*N, 6*N+16 ). Note that
174 2*SDIM*(N-SDIM) <= N*N/2. Note also that an error is only
175 returned if LWORK < max( 8*N, 6*N+16), but if SENSE = 'E' or
176 'V' or 'B' this may not be large enough. If LWORK = -1, then a
177 workspace query is assumed; the routine only calculates the
178 bound on the optimal size of the WORK array and the minimum
179 size of the IWORK array, returns these values as the first
180 entries of the WORK and IWORK arrays, and no error message
181 related to LWORK or LIWORK is issued by XERBLA.
182 IWORK (workspace) INTEGER array, dimension (MAX(1,LIWORK))
184 On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.
185 LIWORK (input) INTEGER
187 The dimension of the array IWORK. If SENSE = 'N' or N = 0,
188 LIWORK >= 1, otherwise LIWORK >= N+6. If LIWORK = -1, then a
189 workspace query is assumed; the routine only calculates the
190 bound on the optimal size of the WORK array and the minimum
191 size of the IWORK array, returns these values as the first
192 entries of the WORK and IWORK arrays, and no error message
193 related to LWORK or LIWORK is issued by XERBLA.
194 BWORK (workspace) LOGICAL array, dimension (N)
196 Not referenced if SORT = 'N'.
197 INFO (output) INTEGER
199 = 0: successful exit
200 < 0: if INFO = -i, the i-th argument had an illegal value.
201 = 1,...,N: The QZ iteration failed. (A,B) are not in Schur
202 form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct
203 for j=INFO+1,...,N. > N: =N+1: other than QZ iteration failed
204 in DHGEQZ
205 =N+2: after reordering, roundoff changed values of some complex
206 eigenvalues so that leading eigenvalues in the Generalized
207 Schur form no longer satisfy SELCTG=.TRUE. This could also be
208 caused due to scaling. =N+3: reordering failed in DTGSEN.
209
211 An approximate (asymptotic) bound on the average absolute error of the
212 selected eigenvalues is
213 EPS * norm((A, B)) / RCONDE( 1 ).
214 An approximate (asymptotic) bound on the maximum angular error in the
215 computed deflating subspaces is
216 EPS * norm((A, B)) / RCONDV( 2 ).
217 See LAPACK User's Guide, section 4.11 for more information.
218 LAPACK driver routine (version 3.N2o)vember 2008 DGGESX(1)