1CGGESX(1) LAPACK driver routine (version 3.1) CGGESX(1)
2
6 CGGESX - for a pair of N-by-N complex nonsymmetric matrices (A,B), the
7 generalized eigenvalues, the complex Schur form (S,T),
8
10 SUBROUTINE CGGESX( JOBVSL, JOBVSR, SORT, SELCTG, SENSE, N, A, LDA, B,
11 LDB, SDIM, ALPHA, BETA, VSL, LDVSL, VSR, LDVSR,
12 RCONDE, RCONDV, WORK, LWORK, RWORK, 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 REAL RCONDE( 2 ), RCONDV( 2 ), RWORK( * )
24 COMPLEX A( LDA, * ), ALPHA( * ), B( LDB, * ), BETA( * ),
26 VSL( LDVSL, * ), VSR( LDVSR, * ), WORK( * )
27 LOGICAL SELCTG
29 EXTERNAL SELCTG
31
33 CGGESX computes for a pair of N-by-N complex nonsymmetric matrices
34 (A,B), the generalized eigenvalues, the complex Schur form (S,T), and,
35 optionally, the left and/or right matrices of Schur vectors (VSL and
36 VSR). This gives the generalized Schur factorization
37 (A,B) = ( (VSL) S (VSR)**H, (VSL) T (VSR)**H )
39 where (VSR)**H is the conjugate-transpose of VSR.
41 Optionally, it also orders the eigenvalues so that a selected cluster
43 of eigenvalues appears in the leading diagonal blocks of the upper tri‐
44 angular matrix S and the upper triangular matrix T; computes a recipro‐
45 cal condition number for the average of the selected eigenvalues
46 (RCONDE); and computes a reciprocal condition number for the right and
47 left deflating subspaces corresponding to the selected eigenvalues
48 (RCONDV). The leading columns of VSL and VSR then form an orthonormal
49 basis for the corresponding left and right eigenspaces (deflating sub‐
50 spaces).
51 A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or
53 a ratio alpha/beta = w, such that A - w*B is singular. It is usually
54 represented as the pair (alpha,beta), as there is a reasonable inter‐
55 pretation for beta=0 or for both being zero.
56 A pair of matrices (S,T) is in generalized complex Schur form if T is
58 upper triangular with non-negative diagonal and S is upper triangular.
59
62 JOBVSL (input) CHARACTER*1
63 = 'N': do not compute the left Schur vectors;
64 = 'V': compute the left Schur vectors.
65 JOBVSR (input) CHARACTER*1
67 = 'N': do not compute the right Schur vectors;
68 = 'V': compute the right Schur vectors.
69 SORT (input) CHARACTER*1
71 Specifies whether or not to order the eigenvalues on the diago‐
72 nal of the generalized Schur form. = 'N': Eigenvalues are not
73 ordered;
74 = 'S': Eigenvalues are ordered (see SELCTG).
75 SELCTG (external procedure) LOGICAL FUNCTION of two COMPLEX 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. Note that a selected complex eigenvalue may no longer
81 satisfy SELCTG(ALPHA(j),BETA(j)) = .TRUE. after ordering, since
82 ordering may change the value of complex eigenvalues (espe‐
83 cially if the eigenvalue is ill-conditioned), in this case INFO
84 is set to N+3 see INFO below).
85 SENSE (input) CHARACTER*1
87 Determines which reciprocal condition numbers are computed. =
88 'N' : None are computed;
89 = 'E' : Computed for average of selected eigenvalues only;
90 = 'V' : Computed for selected deflating subspaces only;
91 = 'B' : Computed for both. If SENSE = 'E', 'V', or 'B', SORT
92 must equal 'S'.
93 N (input) INTEGER
95 The order of the matrices A, B, VSL, and VSR. N >= 0.
96 A (input/output) COMPLEX array, dimension (LDA, N)
98 On entry, the first of the pair of matrices. On exit, A has
99 been overwritten by its generalized Schur form S.
100 LDA (input) INTEGER
102 The leading dimension of A. LDA >= max(1,N).
103 B (input/output) COMPLEX array, dimension (LDB, N)
105 On entry, the second of the pair of matrices. On exit, B has
106 been overwritten by its generalized Schur form T.
107 LDB (input) INTEGER
109 The leading dimension of B. LDB >= max(1,N).
110 SDIM (output) INTEGER
112 If SORT = 'N', SDIM = 0. If SORT = 'S', SDIM = number of ei‐
113 genvalues (after sorting) for which SELCTG is true.
114 ALPHA (output) COMPLEX array, dimension (N)
116 BETA (output) COMPLEX array, dimension (N) On exit,
117 ALPHA(j)/BETA(j), j=1,...,N, will be the generalized eigenval‐
118 ues. ALPHA(j) and BETA(j),j=1,...,N are the diagonals of the
119 complex Schur form (S,T). BETA(j) will be non-negative real.
120 Note: the quotients ALPHA(j)/BETA(j) may easily over- or under‐
122 flow, and BETA(j) may even be zero. Thus, the user should
123 avoid naively computing the ratio alpha/beta. However, ALPHA
124 will be always less than and usually comparable with norm(A) in
125 magnitude, and BETA always less than and usually comparable
126 with norm(B).
127 VSL (output) COMPLEX array, dimension (LDVSL,N)
129 If JOBVSL = 'V', VSL will contain the left Schur vectors. Not
130 referenced if JOBVSL = 'N'.
131 LDVSL (input) INTEGER
133 The leading dimension of the matrix VSL. LDVSL >=1, and if JOB‐
134 VSL = 'V', LDVSL >= N.
135 VSR (output) COMPLEX array, dimension (LDVSR,N)
137 If JOBVSR = 'V', VSR will contain the right Schur vectors. Not
138 referenced if JOBVSR = 'N'.
139 LDVSR (input) INTEGER
141 The leading dimension of the matrix VSR. LDVSR >= 1, and if
142 JOBVSR = 'V', LDVSR >= N.
143 RCONDE (output) REAL array, dimension ( 2 )
145 If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the
146 reciprocal condition numbers for the average of the selected
147 eigenvalues. Not referenced if SENSE = 'N' or 'V'.
148 RCONDV (output) REAL array, dimension ( 2 )
150 If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the
151 reciprocal condition number for the selected deflating sub‐
152 spaces. Not referenced if SENSE = 'N' or 'E'.
153 WORK (workspace/output) COMPLEX array, dimension (MAX(1,LWORK))
155 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
156 LWORK (input) INTEGER
158 The dimension of the array WORK. If N = 0, LWORK >= 1, else if
159 SENSE = 'E', 'V', or 'B', LWORK >= MAX(1,2*N,2*SDIM*(N-SDIM)),
160 else LWORK >= MAX(1,2*N). Note that 2*SDIM*(N-SDIM) <= N*N/2.
161 Note also that an error is only returned if LWORK < MAX(1,2*N),
162 but if SENSE = 'E' or 'V' or 'B' this may not be large enough.
163 If LWORK = -1, then a workspace query is assumed; the routine
165 only calculates the bound on the optimal size of the WORK array
166 and the minimum size of the IWORK array, returns these values
167 as the first entries of the WORK and IWORK arrays, and no error
168 message related to LWORK or LIWORK is issued by XERBLA.
169 RWORK (workspace) REAL array, dimension ( 8*N )
171 Real workspace.
172 IWORK (workspace/output) INTEGER array, dimension (MAX(1,LIWORK))
174 On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.
175 LIWORK (input) INTEGER
177 The dimension of the array WORK. If SENSE = 'N' or N = 0,
178 LIWORK >= 1, otherwise LIWORK >= N+2.
179 If LIWORK = -1, then a workspace query is assumed; the routine
181 only calculates the bound on the optimal size of the WORK array
182 and the minimum size of the IWORK array, returns these values
183 as the first entries of the WORK and IWORK arrays, and no error
184 message related to LWORK or LIWORK is issued by XERBLA.
185 BWORK (workspace) LOGICAL array, dimension (N)
187 Not referenced if SORT = 'N'.
188 INFO (output) INTEGER
190 = 0: successful exit
191 < 0: if INFO = -i, the i-th argument had an illegal value.
192 = 1,...,N: The QZ iteration failed. (A,B) are not in Schur
193 form, but ALPHA(j) and BETA(j) should be correct for
194 j=INFO+1,...,N. > N: =N+1: other than QZ iteration failed in
195 CHGEQZ
196 =N+2: after reordering, roundoff changed values of some complex
197 eigenvalues so that leading eigenvalues in the Generalized
198 Schur form no longer satisfy SELCTG=.TRUE. This could also be
199 caused due to scaling. =N+3: reordering failed in CTGSEN.
200 LAPACK driver routine (version 3.N1o)vember 2006 CGGESX(1)