1CGGES(1) LAPACK driver routine (version 3.1) CGGES(1)
2
6 CGGES - for a pair of N-by-N complex nonsymmetric matrices (A,B), the
7 generalized eigenvalues, the generalized complex Schur form (S, T), and
8 optionally left and/or right Schur vectors (VSL and VSR)
9
11 SUBROUTINE CGGES( JOBVSL, JOBVSR, SORT, SELCTG, N, A, LDA, B, LDB,
12 SDIM, ALPHA, BETA, VSL, LDVSL, VSR, LDVSR, WORK,
13 LWORK, RWORK, BWORK, INFO )
14 CHARACTER JOBVSL, JOBVSR, SORT
16 INTEGER INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N, SDIM
18 LOGICAL BWORK( * )
20 REAL RWORK( * )
22 COMPLEX A( LDA, * ), ALPHA( * ), B( LDB, * ), BETA( * ), VSL(
24 LDVSL, * ), VSR( LDVSR, * ), WORK( * )
25 LOGICAL SELCTG
27 EXTERNAL SELCTG
29
31 CGGES computes for a pair of N-by-N complex nonsymmetric matrices
32 (A,B), the generalized eigenvalues, the generalized complex Schur form
33 (S, T), and optionally left and/or right Schur vectors (VSL and VSR).
34 This gives the generalized Schur factorization
35 (A,B) = ( (VSL)*S*(VSR)**H, (VSL)*T*(VSR)**H )
37 where (VSR)**H is the conjugate-transpose of VSR.
39 Optionally, it also orders the eigenvalues so that a selected cluster
41 of eigenvalues appears in the leading diagonal blocks of the upper tri‐
42 angular matrix S and the upper triangular matrix T. The leading columns
43 of VSL and VSR then form an unitary basis for the corresponding left
44 and right eigenspaces (deflating subspaces).
45 (If only the generalized eigenvalues are needed, use the driver CGGEV
47 instead, which is faster.)
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, and even for both being zero.
53 A pair of matrices (S,T) is in generalized complex Schur form if S and
55 T are upper triangular and, in addition, the diagonal elements of T are
56 non-negative real numbers.
57
60 JOBVSL (input) CHARACTER*1
61 = 'N': do not compute the left Schur vectors;
62 = 'V': compute the left Schur vectors.
63 JOBVSR (input) CHARACTER*1
65 = 'N': do not compute the right Schur vectors;
66 = 'V': compute the right Schur vectors.
67 SORT (input) CHARACTER*1
69 Specifies whether or not to order the eigenvalues on the diago‐
70 nal of the generalized Schur form. = 'N': Eigenvalues are not
71 ordered;
72 = 'S': Eigenvalues are ordered (see SELCTG).
73 SELCTG (external procedure) LOGICAL FUNCTION of two COMPLEX arguments
75 SELCTG must be declared EXTERNAL in the calling subroutine. If
76 SORT = 'N', SELCTG is not referenced. If SORT = 'S', SELCTG is
77 used to select eigenvalues to sort to the top left of the Schur
78 form. An eigenvalue ALPHA(j)/BETA(j) is selected if
79 SELCTG(ALPHA(j),BETA(j)) is true.
80 Note that a selected complex eigenvalue may no longer satisfy
82 SELCTG(ALPHA(j),BETA(j)) = .TRUE. after ordering, since order‐
83 ing may change the value of complex eigenvalues (especially if
84 the eigenvalue is ill-conditioned), in this case INFO is set to
85 N+2 (See INFO below).
86 N (input) INTEGER
88 The order of the matrices A, B, VSL, and VSR. N >= 0.
89 A (input/output) COMPLEX array, dimension (LDA, N)
91 On entry, the first of the pair of matrices. On exit, A has
92 been overwritten by its generalized Schur form S.
93 LDA (input) INTEGER
95 The leading dimension of A. LDA >= max(1,N).
96 B (input/output) COMPLEX array, dimension (LDB, N)
98 On entry, the second of the pair of matrices. On exit, B has
99 been overwritten by its generalized Schur form T.
100 LDB (input) INTEGER
102 The leading dimension of B. LDB >= max(1,N).
103 SDIM (output) INTEGER
105 If SORT = 'N', SDIM = 0. If SORT = 'S', SDIM = number of ei‐
106 genvalues (after sorting) for which SELCTG is true.
107 ALPHA (output) COMPLEX array, dimension (N)
109 BETA (output) COMPLEX array, dimension (N) On exit,
110 ALPHA(j)/BETA(j), j=1,...,N, will be the generalized eigenval‐
111 ues. ALPHA(j), j=1,...,N and BETA(j), j=1,...,N are the
112 diagonals of the complex Schur form (A,B) output by CGGES. The
113 BETA(j) will be non-negative real.
114 Note: the quotients ALPHA(j)/BETA(j) may easily over- or under‐
116 flow, and BETA(j) may even be zero. Thus, the user should
117 avoid naively computing the ratio alpha/beta. However, ALPHA
118 will be always less than and usually comparable with norm(A) in
119 magnitude, and BETA always less than and usually comparable
120 with norm(B).
121 VSL (output) COMPLEX array, dimension (LDVSL,N)
123 If JOBVSL = 'V', VSL will contain the left Schur vectors. Not
124 referenced if JOBVSL = 'N'.
125 LDVSL (input) INTEGER
127 The leading dimension of the matrix VSL. LDVSL >= 1, and if
128 JOBVSL = 'V', LDVSL >= N.
129 VSR (output) COMPLEX array, dimension (LDVSR,N)
131 If JOBVSR = 'V', VSR will contain the right Schur vectors. Not
132 referenced if JOBVSR = 'N'.
133 LDVSR (input) INTEGER
135 The leading dimension of the matrix VSR. LDVSR >= 1, and if
136 JOBVSR = 'V', LDVSR >= N.
137 WORK (workspace/output) COMPLEX array, dimension (MAX(1,LWORK))
139 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
140 LWORK (input) INTEGER
142 The dimension of the array WORK. LWORK >= max(1,2*N). For
143 good performance, LWORK must generally be larger.
144 If LWORK = -1, then a workspace query is assumed; the routine
146 only calculates the optimal size of the WORK array, returns
147 this value as the first entry of the WORK array, and no error
148 message related to LWORK is issued by XERBLA.
149 RWORK (workspace) REAL array, dimension (8*N)
151 BWORK (workspace) LOGICAL array, dimension (N)
153 Not referenced if SORT = 'N'.
154 INFO (output) INTEGER
156 = 0: successful exit
157 < 0: if INFO = -i, the i-th argument had an illegal value.
158 =1,...,N: The QZ iteration failed. (A,B) are not in Schur
159 form, but ALPHA(j) and BETA(j) should be correct for
160 j=INFO+1,...,N. > N: =N+1: other than QZ iteration failed in
161 CHGEQZ
162 =N+2: after reordering, roundoff changed values of some complex
163 eigenvalues so that leading eigenvalues in the Generalized
164 Schur form no longer satisfy SELCTG=.TRUE. This could also be
165 caused due to scaling. =N+3: reordering falied in CTGSEN.
166 LAPACK driver routine (version 3.N1o)vember 2006 CGGES(1)