1SGGESX(1) LAPACK driver routine (version 3.1) SGGESX(1)
2
6 SGGESX - for a pair of N-by-N real nonsymmetric matrices (A,B), the
7 generalized eigenvalues, the real Schur form (S,T), and,
8
10 SUBROUTINE SGGESX( 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 REAL A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B( LDB, * ),
24 BETA( * ), RCONDE( 2 ), RCONDV( 2 ), VSL( LDVSL, *
25 ), VSR( LDVSR, * ), WORK( * )
26 LOGICAL SELCTG
28 EXTERNAL SELCTG
30
32 SGGESX 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 )
38 Optionally, it also orders the eigenvalues so that a selected cluster
40 of eigenvalues appears in the leading diagonal blocks of the upper
41 quasi-triangular matrix S and the upper triangular matrix T; computes a
42 reciprocal condition number for the average of the selected eigenvalues
43 (RCONDE); and computes a reciprocal condition number for the right and
44 left deflating subspaces corresponding to the selected eigenvalues
45 (RCONDV). The leading columns of VSL and VSR then form an orthonormal
46 basis for the corresponding left and right eigenspaces (deflating sub‐
47 spaces).
48 A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or
50 a ratio alpha/beta = w, such that A - w*B is singular. It is usually
51 represented as the pair (alpha,beta), as there is a reasonable inter‐
52 pretation for beta=0 or for both being zero.
53 A pair of matrices (S,T) is in generalized real Schur form if T is
55 upper triangular with non-negative diagonal and S is block upper trian‐
56 gular with 1-by-1 and 2-by-2 blocks. 1-by-1 blocks correspond to real
57 generalized eigenvalues, while 2-by-2 blocks of S will be "standard‐
58 ized" by making the corresponding elements of T have the form:
59 [ a 0 ]
60 [ 0 b ]
61 and the pair of corresponding 2-by-2 blocks in S and T will have a com‐
63 plex conjugate pair of generalized eigenvalues.
64
68 JOBVSL (input) CHARACTER*1
69 = 'N': do not compute the left Schur vectors;
70 = 'V': compute the left Schur vectors.
71 JOBVSR (input) CHARACTER*1
73 = 'N': do not compute the right Schur vectors;
74 = 'V': compute the right Schur vectors.
75 SORT (input) CHARACTER*1
77 Specifies whether or not to order the eigenvalues on the diago‐
78 nal of the generalized Schur form. = 'N': Eigenvalues are not
79 ordered;
80 = 'S': Eigenvalues are ordered (see SELCTG).
81 SELCTG (external procedure) LOGICAL FUNCTION of three REAL arguments
83 SELCTG must be declared EXTERNAL in the calling subroutine. If
84 SORT = 'N', SELCTG is not referenced. If SORT = 'S', SELCTG is
85 used to select eigenvalues to sort to the top left of the Schur
86 form. An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected
87 if SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either
88 one of a complex conjugate pair of eigenvalues is selected,
89 then both complex eigenvalues are selected. Note that a
90 selected complex eigenvalue may no longer satisfy
91 SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering,
92 since ordering may change the value of complex eigenvalues
93 (especially if the eigenvalue is ill-conditioned), in this case
94 INFO is set to N+3.
95 SENSE (input) CHARACTER*1
97 Determines which reciprocal condition numbers are computed. =
98 'N' : None are computed;
99 = 'E' : Computed for average of selected eigenvalues only;
100 = 'V' : Computed for selected deflating subspaces only;
101 = 'B' : Computed for both. If SENSE = 'E', 'V', or 'B', SORT
102 must equal 'S'.
103 N (input) INTEGER
105 The order of the matrices A, B, VSL, and VSR. N >= 0.
106 A (input/output) REAL array, dimension (LDA, N)
108 On entry, the first of the pair of matrices. On exit, A has
109 been overwritten by its generalized Schur form S.
110 LDA (input) INTEGER
112 The leading dimension of A. LDA >= max(1,N).
113 B (input/output) REAL array, dimension (LDB, N)
115 On entry, the second of the pair of matrices. On exit, B has
116 been overwritten by its generalized Schur form T.
117 LDB (input) INTEGER
119 The leading dimension of B. LDB >= max(1,N).
120 SDIM (output) INTEGER
122 If SORT = 'N', SDIM = 0. If SORT = 'S', SDIM = number of ei‐
123 genvalues (after sorting) for which SELCTG is true. (Complex
124 conjugate pairs for which SELCTG is true for either eigenvalue
125 count as 2.)
126 ALPHAR (output) REAL array, dimension (N)
128 ALPHAI (output) REAL array, dimension (N) BETA (output)
129 REAL array, dimension (N) On exit, (ALPHAR(j) +
130 ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the generalized eigen‐
131 values. ALPHAR(j) + ALPHAI(j)*i and BETA(j),j=1,...,N are the
132 diagonals of the complex Schur form (S,T) that would result if
133 the 2-by-2 diagonal blocks of the real Schur form of (A,B) were
134 further reduced to triangular form using 2-by-2 complex unitary
135 transformations. If ALPHAI(j) is zero, then the j-th eigenval‐
136 ue is real; if positive, then the j-th and (j+1)-st eigenvalues
137 are a complex conjugate pair, with ALPHAI(j+1) negative.
138 Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
140 easily over- or underflow, and BETA(j) may even be zero. Thus,
141 the user should avoid naively computing the ratio. However,
142 ALPHAR and ALPHAI will be always less than and usually compara‐
143 ble with norm(A) in magnitude, and BETA always less than and
144 usually comparable with norm(B).
145 VSL (output) REAL array, dimension (LDVSL,N)
147 If JOBVSL = 'V', VSL will contain the left Schur vectors. Not
148 referenced if JOBVSL = 'N'.
149 LDVSL (input) INTEGER
151 The leading dimension of the matrix VSL. LDVSL >=1, and if JOB‐
152 VSL = 'V', LDVSL >= N.
153 VSR (output) REAL array, dimension (LDVSR,N)
155 If JOBVSR = 'V', VSR will contain the right Schur vectors. Not
156 referenced if JOBVSR = 'N'.
157 LDVSR (input) INTEGER
159 The leading dimension of the matrix VSR. LDVSR >= 1, and if
160 JOBVSR = 'V', LDVSR >= N.
161 RCONDE (output) REAL array, dimension ( 2 )
163 If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the
164 reciprocal condition numbers for the average of the selected
165 eigenvalues. Not referenced if SENSE = 'N' or 'V'.
166 RCONDV (output) REAL array, dimension ( 2 )
168 If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the
169 reciprocal condition numbers for the selected deflating sub‐
170 spaces. Not referenced if SENSE = 'N' or 'E'.
171 WORK (workspace/output) REAL array, dimension (MAX(1,LWORK))
173 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
174 LWORK (input) INTEGER
176 The dimension of the array WORK. If N = 0, LWORK >= 1, else if
177 SENSE = 'E', 'V', or 'B', LWORK >= max( 8*N, 6*N+16, 2*SDIM*(N-
178 SDIM) ), else LWORK >= max( 8*N, 6*N+16 ). Note that
179 2*SDIM*(N-SDIM) <= N*N/2. Note also that an error is only
180 returned if LWORK < max( 8*N, 6*N+16), but if SENSE = 'E' or
181 'V' or 'B' this may not be large enough.
182 If LWORK = -1, then a workspace query is assumed; the routine
184 only calculates the bound on the optimal size of the WORK array
185 and the minimum size of the IWORK array, returns these values
186 as the first entries of the WORK and IWORK arrays, and no error
187 message related to LWORK or LIWORK is issued by XERBLA.
188 IWORK (workspace) INTEGER array, dimension (MAX(1,LIWORK))
190 On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.
191 LIWORK (input) INTEGER
193 The dimension of the array IWORK. If SENSE = 'N' or N = 0,
194 LIWORK >= 1, otherwise LIWORK >= N+6.
195 If LIWORK = -1, then a workspace query is assumed; the routine
197 only calculates the bound on the optimal size of the WORK array
198 and the minimum size of the IWORK array, returns these values
199 as the first entries of the WORK and IWORK arrays, and no error
200 message related to LWORK or LIWORK is issued by XERBLA.
201 BWORK (workspace) LOGICAL array, dimension (N)
203 Not referenced if SORT = 'N'.
204 INFO (output) INTEGER
206 = 0: successful exit
207 < 0: if INFO = -i, the i-th argument had an illegal value.
208 = 1,...,N: The QZ iteration failed. (A,B) are not in Schur
209 form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct
210 for j=INFO+1,...,N. > N: =N+1: other than QZ iteration failed
211 in SHGEQZ
212 =N+2: after reordering, roundoff changed values of some complex
213 eigenvalues so that leading eigenvalues in the Generalized
214 Schur form no longer satisfy SELCTG=.TRUE. This could also be
215 caused due to scaling. =N+3: reordering failed in STGSEN.
216 Further details ===============
218 An approximate (asymptotic) bound on the average absolute error
220 of the selected eigenvalues is
221 EPS * norm((A, B)) / RCONDE( 1 ).
223 An approximate (asymptotic) bound on the maximum angular error
225 in the computed deflating subspaces is
226 EPS * norm((A, B)) / RCONDV( 2 ).
228 See LAPACK User's Guide, section 4.11 for more information.
230 LAPACK driver routine (version 3.N1o)vember 2006 SGGESX(1)