--- name: "ggesx" section: "3" platform: "linux" package: "lapack-doc" version: "3.12.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ggesx" --- # ggesx(3) ggesx: Schur form, expert ## NAME ggesx - ggesx: Schur form, expert ## SYNOPSIS ### Functions subroutine **cggesx** (jobvsl, jobvsr, sort, selctg, sense, n, a, lda, b, ldb, sdim, alpha, beta, vsl, ldvsl, vsr, ldvsr, rconde, rcondv, work, lwork, rwork, iwork, liwork, bwork, info)\ **CGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** subroutine **dggesx** (jobvsl, jobvsr, sort, selctg, sense, n, a, lda, b, ldb, sdim, alphar, alphai, beta, vsl, ldvsl, vsr, ldvsr, rconde, rcondv, work, lwork, iwork, liwork, bwork, info)\ **DGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** subroutine **sggesx** (jobvsl, jobvsr, sort, selctg, sense, n, a, lda, b, ldb, sdim, alphar, alphai, beta, vsl, ldvsl, vsr, ldvsr, rconde, rcondv, work, lwork, iwork, liwork, bwork, info)\ **SGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** subroutine **zggesx** (jobvsl, jobvsr, sort, selctg, sense, n, a, lda, b, ldb, sdim, alpha, beta, vsl, ldvsl, vsr, ldvsr, rconde, rcondv, work, lwork, rwork, iwork, liwork, bwork, info)\ **ZGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** ## Detailed Description ## Function Documentation ### subroutine cggesx (character jobvsl, character jobvsr, character sort, external selctg, character sense, integer n, complex, dimension( lda, \* ) a, integer lda, complex, dimension( ldb, \* ) b, integer ldb, integer sdim, complex, dimension( \* ) alpha, complex, dimension( \* ) beta, complex, dimension( ldvsl, \* ) vsl, integer ldvsl, complex, dimension( ldvsr, \* ) vsr, integer ldvsr, real, dimension( 2 ) rconde, real, dimension( 2 ) rcondv, complex, dimension( \* ) work, integer lwork, real, dimension( \* ) rwork, integer, dimension( \* ) iwork, integer liwork, logical, dimension( \* ) bwork, integer info) **CGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** **Purpose:** ``` !> !> CGGESX computes for a pair of N-by-N complex nonsymmetric matrices !> (A,B), the generalized eigenvalues, the complex Schur form (S,T), !> and, optionally, the left and/or right matrices of Schur vectors (VSL !> and VSR). This gives the generalized Schur factorization !> !> (A,B) = ( (VSL) S (VSR)**H, (VSL) T (VSR)**H ) !> !> where (VSR)**H is the conjugate-transpose of VSR. !> !> Optionally, it also orders the eigenvalues so that a selected cluster !> of eigenvalues appears in the leading diagonal blocks of the upper !> triangular matrix S and the upper triangular matrix T; computes !> a reciprocal condition number for the average of the selected !> eigenvalues (RCONDE); and computes a reciprocal condition number for !> the right and left deflating subspaces corresponding to the selected !> eigenvalues (RCONDV). The leading columns of VSL and VSR then form !> an orthonormal basis for the corresponding left and right eigenspaces !> (deflating subspaces). !> !> A generalized eigenvalue for a pair of matrices (A,B) is a scalar w !> or a ratio alpha/beta = w, such that A - w*B is singular. It is !> usually represented as the pair (alpha,beta), as there is a !> reasonable interpretation for beta=0 or for both being zero. !> !> A pair of matrices (S,T) is in generalized complex Schur form if T is !> upper triangular with non-negative diagonal and S is upper !> triangular. !> ``` **Parameters** *JOBVSL* ``` !> JOBVSL is CHARACTER*1 !> = 'N': do not compute the left Schur vectors; !> = 'V': compute the left Schur vectors. !> ``` *JOBVSR* ``` !> JOBVSR is CHARACTER*1 !> = 'N': do not compute the right Schur vectors; !> = 'V': compute the right Schur vectors. !> ``` *SORT* ``` !> SORT is CHARACTER*1 !> Specifies whether or not to order the eigenvalues on the !> diagonal of the generalized Schur form. !> = 'N': Eigenvalues are not ordered; !> = 'S': Eigenvalues are ordered (see SELCTG). !> ``` *SELCTG* ``` !> SELCTG is a LOGICAL FUNCTION of two COMPLEX arguments !> SELCTG must be declared EXTERNAL in the calling subroutine. !> If SORT = 'N', SELCTG is not referenced. !> If SORT = 'S', SELCTG is used to select eigenvalues to sort !> to the top left of the Schur form. !> Note that a selected complex eigenvalue may no longer satisfy !> SELCTG(ALPHA(j),BETA(j)) = .TRUE. after ordering, since !> ordering may change the value of complex eigenvalues !> (especially if the eigenvalue is ill-conditioned), in this !> case INFO is set to N+3 see INFO below). !> ``` *SENSE* ``` !> SENSE is CHARACTER*1 !> Determines which reciprocal condition numbers are computed. !> = 'N': None are computed; !> = 'E': Computed for average of selected eigenvalues only; !> = 'V': Computed for selected deflating subspaces only; !> = 'B': Computed for both. !> If SENSE = 'E', 'V', or 'B', SORT must equal 'S'. !> ``` *N* ``` !> N is INTEGER !> The order of the matrices A, B, VSL, and VSR. N >= 0. !> ``` *A* ``` !> A is COMPLEX array, dimension (LDA, N) !> On entry, the first of the pair of matrices. !> On exit, A has been overwritten by its generalized Schur !> form S. !> ``` *LDA* ``` !> LDA is INTEGER !> The leading dimension of A. LDA >= max(1,N). !> ``` *B* ``` !> B is COMPLEX array, dimension (LDB, N) !> On entry, the second of the pair of matrices. !> On exit, B has been overwritten by its generalized Schur !> form T. !> ``` *LDB* ``` !> LDB is INTEGER !> The leading dimension of B. LDB >= max(1,N). !> ``` *SDIM* ``` !> SDIM is INTEGER !> If SORT = 'N', SDIM = 0. !> If SORT = 'S', SDIM = number of eigenvalues (after sorting) !> for which SELCTG is true. !> ``` *ALPHA* ``` !> ALPHA is COMPLEX array, dimension (N) !> ``` *BETA* ``` !> BETA is COMPLEX array, dimension (N) !> On exit, ALPHA(j)/BETA(j), j=1,...,N, will be the !> generalized eigenvalues. ALPHA(j) and BETA(j),j=1,...,N are !> the diagonals of the complex Schur form (S,T). BETA(j) will !> be non-negative real. !> !> Note: the quotients ALPHA(j)/BETA(j) may easily over- or !> underflow, and BETA(j) may even be zero. Thus, the user !> should avoid naively computing the ratio alpha/beta. !> However, ALPHA will be always less than and usually !> comparable with norm(A) in magnitude, and BETA always less !> than and usually comparable with norm(B). !> ``` *VSL* ``` !> VSL is COMPLEX array, dimension (LDVSL,N) !> If JOBVSL = 'V', VSL will contain the left Schur vectors. !> Not referenced if JOBVSL = 'N'. !> ``` *LDVSL* ``` !> LDVSL is INTEGER !> The leading dimension of the matrix VSL. LDVSL >=1, and !> if JOBVSL = 'V', LDVSL >= N. !> ``` *VSR* ``` !> VSR is COMPLEX array, dimension (LDVSR,N) !> If JOBVSR = 'V', VSR will contain the right Schur vectors. !> Not referenced if JOBVSR = 'N'. !> ``` *LDVSR* ``` !> LDVSR is INTEGER !> The leading dimension of the matrix VSR. LDVSR >= 1, and !> if JOBVSR = 'V', LDVSR >= N. !> ``` *RCONDE* ``` !> RCONDE is REAL array, dimension ( 2 ) !> If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the !> reciprocal condition numbers for the average of the selected !> eigenvalues. !> Not referenced if SENSE = 'N' or 'V'. !> ``` *RCONDV* ``` !> RCONDV is REAL array, dimension ( 2 ) !> If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the !> reciprocal condition number for the selected deflating !> subspaces. !> Not referenced if SENSE = 'N' or 'E'. !> ``` *WORK* ``` !> WORK is COMPLEX array, dimension (MAX(1,LWORK)) !> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !> ``` *LWORK* ``` !> LWORK is INTEGER !> The dimension of the array WORK. !> If N = 0, LWORK >= 1, else if SENSE = 'E', 'V', or 'B', !> LWORK >= MAX(1,2*N,2*SDIM*(N-SDIM)), else !> LWORK >= MAX(1,2*N). Note that 2*SDIM*(N-SDIM) <= N*N/2. !> Note also that an error is only returned if !> LWORK < MAX(1,2*N), but if SENSE = 'E' or 'V' or 'B' this may !> not be large enough. !> !> If LWORK = -1, then a workspace query is assumed; the routine !> only calculates the bound on the optimal size of the WORK !> array and the minimum size of the IWORK array, returns these !> values as the first entries of the WORK and IWORK arrays, and !> no error message related to LWORK or LIWORK is issued by !> XERBLA. !> ``` *RWORK* ``` !> RWORK is REAL array, dimension ( 8*N ) !> Real workspace. !> ``` *IWORK* ``` !> IWORK is INTEGER array, dimension (MAX(1,LIWORK)) !> On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK. !> ``` *LIWORK* ``` !> LIWORK is INTEGER !> The dimension of the array WORK. !> If SENSE = 'N' or N = 0, LIWORK >= 1, otherwise !> LIWORK >= N+2. !> !> If LIWORK = -1, then a workspace query is assumed; the !> routine only calculates the bound on the optimal size of the !> WORK array and the minimum size of the IWORK array, returns !> these values as the first entries of the WORK and IWORK !> arrays, and no error message related to LWORK or LIWORK is !> issued by XERBLA. !> ``` *BWORK* ``` !> BWORK is LOGICAL array, dimension (N) !> Not referenced if SORT = 'N'. !> ``` *INFO* ``` !> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value. !> = 1,...,N: !> The QZ iteration failed. (A,B) are not in Schur !> form, but ALPHA(j) and BETA(j) should be correct for !> j=INFO+1,...,N. !> > N: =N+1: other than QZ iteration failed in CHGEQZ !> =N+2: after reordering, roundoff changed values of !> some complex eigenvalues so that leading !> eigenvalues in the Generalized Schur form no !> longer satisfy SELCTG=.TRUE. This could also !> be caused due to scaling. !> =N+3: reordering failed in CTGSEN. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. Definition at line **326** of file **cggesx.f**. ### subroutine dggesx (character jobvsl, character jobvsr, character sort, external selctg, character sense, integer n, double precision, dimension( lda, \* ) a, integer lda, double precision, dimension( ldb, \* ) b, integer ldb, integer sdim, double precision, dimension( \* ) alphar, double precision, dimension( \* ) alphai, double precision, dimension( \* ) beta, double precision, dimension( ldvsl, \* ) vsl, integer ldvsl, double precision, dimension( ldvsr, \* ) vsr, integer ldvsr, double precision, dimension( 2 ) rconde, double precision, dimension( 2 ) rcondv, double precision, dimension( \* ) work, integer lwork, integer, dimension( \* ) iwork, integer liwork, logical, dimension( \* ) bwork, integer info) **DGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** **Purpose:** ``` !> !> DGGESX computes for a pair of N-by-N real nonsymmetric matrices !> (A,B), the generalized eigenvalues, the real Schur form (S,T), and, !> optionally, the left and/or right matrices of Schur vectors (VSL and !> VSR). This gives the generalized Schur factorization !> !> (A,B) = ( (VSL) S (VSR)**T, (VSL) T (VSR)**T ) !> !> Optionally, it also orders the eigenvalues so that a selected cluster !> of eigenvalues appears in the leading diagonal blocks of the upper !> quasi-triangular matrix S and the upper triangular matrix T; computes !> a reciprocal condition number for the average of the selected !> eigenvalues (RCONDE); and computes a reciprocal condition number for !> the right and left deflating subspaces corresponding to the selected !> eigenvalues (RCONDV). The leading columns of VSL and VSR then form !> an orthonormal basis for the corresponding left and right eigenspaces !> (deflating subspaces). !> !> A generalized eigenvalue for a pair of matrices (A,B) is a scalar w !> or a ratio alpha/beta = w, such that A - w*B is singular. It is !> usually represented as the pair (alpha,beta), as there is a !> reasonable interpretation for beta=0 or for both being zero. !> !> A pair of matrices (S,T) is in generalized real Schur form if T is !> upper triangular with non-negative diagonal and S is block upper !> triangular with 1-by-1 and 2-by-2 blocks. 1-by-1 blocks correspond !> to real generalized eigenvalues, while 2-by-2 blocks of S will be !> by making the corresponding elements of T have the !> form: !> [ a 0 ] !> [ 0 b ] !> !> and the pair of corresponding 2-by-2 blocks in S and T will have a !> complex conjugate pair of generalized eigenvalues. !> !> ``` **Parameters** *JOBVSL* ``` !> JOBVSL is CHARACTER*1 !> = 'N': do not compute the left Schur vectors; !> = 'V': compute the left Schur vectors. !> ``` *JOBVSR* ``` !> JOBVSR is CHARACTER*1 !> = 'N': do not compute the right Schur vectors; !> = 'V': compute the right Schur vectors. !> ``` *SORT* ``` !> SORT is CHARACTER*1 !> Specifies whether or not to order the eigenvalues on the !> diagonal of the generalized Schur form. !> = 'N': Eigenvalues are not ordered; !> = 'S': Eigenvalues are ordered (see SELCTG). !> ``` *SELCTG* ``` !> SELCTG is a LOGICAL FUNCTION of three DOUBLE PRECISION arguments !> SELCTG must be declared EXTERNAL in the calling subroutine. !> If SORT = 'N', SELCTG is not referenced. !> If SORT = 'S', SELCTG is used to select eigenvalues to sort !> to the top left of the Schur form. !> An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if !> SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either !> one of a complex conjugate pair of eigenvalues is selected, !> then both complex eigenvalues are selected. !> Note that a selected complex eigenvalue may no longer satisfy !> SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering, !> since ordering may change the value of complex eigenvalues !> (especially if the eigenvalue is ill-conditioned), in this !> case INFO is set to N+3. !> ``` *SENSE* ``` !> SENSE is CHARACTER*1 !> Determines which reciprocal condition numbers are computed. !> = 'N': None are computed; !> = 'E': Computed for average of selected eigenvalues only; !> = 'V': Computed for selected deflating subspaces only; !> = 'B': Computed for both. !> If SENSE = 'E', 'V', or 'B', SORT must equal 'S'. !> ``` *N* ``` !> N is INTEGER !> The order of the matrices A, B, VSL, and VSR. N >= 0. !> ``` *A* ``` !> A is DOUBLE PRECISION array, dimension (LDA, N) !> On entry, the first of the pair of matrices. !> On exit, A has been overwritten by its generalized Schur !> form S. !> ``` *LDA* ``` !> LDA is INTEGER !> The leading dimension of A. LDA >= max(1,N). !> ``` *B* ``` !> B is DOUBLE PRECISION array, dimension (LDB, N) !> On entry, the second of the pair of matrices. !> On exit, B has been overwritten by its generalized Schur !> form T. !> ``` *LDB* ``` !> LDB is INTEGER !> The leading dimension of B. LDB >= max(1,N). !> ``` *SDIM* ``` !> SDIM is INTEGER !> If SORT = 'N', SDIM = 0. !> If SORT = 'S', SDIM = number of eigenvalues (after sorting) !> for which SELCTG is true. (Complex conjugate pairs for which !> SELCTG is true for either eigenvalue count as 2.) !> ``` *ALPHAR* ``` !> ALPHAR is DOUBLE PRECISION array, dimension (N) !> ``` *ALPHAI* ``` !> ALPHAI is DOUBLE PRECISION array, dimension (N) !> ``` *BETA* ``` !> BETA is DOUBLE PRECISION array, dimension (N) !> On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will !> be the generalized eigenvalues. ALPHAR(j) + ALPHAI(j)*i !> and BETA(j),j=1,...,N are the diagonals of the complex Schur !> form (S,T) that would result if the 2-by-2 diagonal blocks of !> the real Schur form of (A,B) were further reduced to !> triangular form using 2-by-2 complex unitary transformations. !> If ALPHAI(j) is zero, then the j-th eigenvalue is real; if !> positive, then the j-th and (j+1)-st eigenvalues are a !> complex conjugate pair, with ALPHAI(j+1) negative. !> !> Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) !> may easily over- or underflow, and BETA(j) may even be zero. !> Thus, the user should avoid naively computing the ratio. !> However, ALPHAR and ALPHAI will be always less than and !> usually comparable with norm(A) in magnitude, and BETA always !> less than and usually comparable with norm(B). !> ``` *VSL* ``` !> VSL is DOUBLE PRECISION array, dimension (LDVSL,N) !> If JOBVSL = 'V', VSL will contain the left Schur vectors. !> Not referenced if JOBVSL = 'N'. !> ``` *LDVSL* ``` !> LDVSL is INTEGER !> The leading dimension of the matrix VSL. LDVSL >=1, and !> if JOBVSL = 'V', LDVSL >= N. !> ``` *VSR* ``` !> VSR is DOUBLE PRECISION array, dimension (LDVSR,N) !> If JOBVSR = 'V', VSR will contain the right Schur vectors. !> Not referenced if JOBVSR = 'N'. !> ``` *LDVSR* ``` !> LDVSR is INTEGER !> The leading dimension of the matrix VSR. LDVSR >= 1, and !> if JOBVSR = 'V', LDVSR >= N. !> ``` *RCONDE* ``` !> RCONDE is DOUBLE PRECISION array, dimension ( 2 ) !> If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the !> reciprocal condition numbers for the average of the selected !> eigenvalues. !> Not referenced if SENSE = 'N' or 'V'. !> ``` *RCONDV* ``` !> RCONDV is DOUBLE PRECISION array, dimension ( 2 ) !> If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the !> reciprocal condition numbers for the selected deflating !> subspaces. !> Not referenced if SENSE = 'N' or 'E'. !> ``` *WORK* ``` !> WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)) !> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !> ``` *LWORK* ``` !> LWORK is INTEGER !> The dimension of the array WORK. !> If N = 0, LWORK >= 1, else if SENSE = 'E', 'V', or 'B', !> LWORK >= max( 8*N, 6*N+16, 2*SDIM*(N-SDIM) ), else !> LWORK >= max( 8*N, 6*N+16 ). !> Note that 2*SDIM*(N-SDIM) <= N*N/2. !> Note also that an error is only returned if !> LWORK < max( 8*N, 6*N+16), but if SENSE = 'E' or 'V' or 'B' !> this may not be large enough. !> !> If LWORK = -1, then a workspace query is assumed; the routine !> only calculates the bound on the optimal size of the WORK !> array and the minimum size of the IWORK array, returns these !> values as the first entries of the WORK and IWORK arrays, and !> no error message related to LWORK or LIWORK is issued by !> XERBLA. !> ``` *IWORK* ``` !> IWORK is INTEGER array, dimension (MAX(1,LIWORK)) !> On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK. !> ``` *LIWORK* ``` !> LIWORK is INTEGER !> The dimension of the array IWORK. !> If SENSE = 'N' or N = 0, LIWORK >= 1, otherwise !> LIWORK >= N+6. !> !> If LIWORK = -1, then a workspace query is assumed; the !> routine only calculates the bound on the optimal size of the !> WORK array and the minimum size of the IWORK array, returns !> these values as the first entries of the WORK and IWORK !> arrays, and no error message related to LWORK or LIWORK is !> issued by XERBLA. !> ``` *BWORK* ``` !> BWORK is LOGICAL array, dimension (N) !> Not referenced if SORT = 'N'. !> ``` *INFO* ``` !> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value. !> = 1,...,N: !> The QZ iteration failed. (A,B) are not in Schur !> form, but ALPHAR(j), ALPHAI(j), and BETA(j) should !> be correct for j=INFO+1,...,N. !> > N: =N+1: other than QZ iteration failed in DHGEQZ !> =N+2: after reordering, roundoff changed values of !> some complex eigenvalues so that leading !> eigenvalues in the Generalized Schur form no !> longer satisfy SELCTG=.TRUE. This could also !> be caused due to scaling. !> =N+3: reordering failed in DTGSEN. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. **Further Details:** ``` !> !> An approximate (asymptotic) bound on the average absolute error of !> the selected eigenvalues is !> !> EPS * norm((A, B)) / RCONDE( 1 ). !> !> An approximate (asymptotic) bound on the maximum angular error in !> the computed deflating subspaces is !> !> EPS * norm((A, B)) / RCONDV( 2 ). !> !> See LAPACK User's Guide, section 4.11 for more information. !> ``` Definition at line **361** of file **dggesx.f**. ### subroutine sggesx (character jobvsl, character jobvsr, character sort, external selctg, character sense, integer n, real, dimension( lda, \* ) a, integer lda, real, dimension( ldb, \* ) b, integer ldb, integer sdim, real, dimension( \* ) alphar, real, dimension( \* ) alphai, real, dimension( \* ) beta, real, dimension( ldvsl, \* ) vsl, integer ldvsl, real, dimension( ldvsr, \* ) vsr, integer ldvsr, real, dimension( 2 ) rconde, real, dimension( 2 ) rcondv, real, dimension( \* ) work, integer lwork, integer, dimension( \* ) iwork, integer liwork, logical, dimension( \* ) bwork, integer info) **SGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** **Purpose:** ``` !> !> SGGESX computes for a pair of N-by-N real nonsymmetric matrices !> (A,B), the generalized eigenvalues, the real Schur form (S,T), and, !> optionally, the left and/or right matrices of Schur vectors (VSL and !> VSR). This gives the generalized Schur factorization !> !> (A,B) = ( (VSL) S (VSR)**T, (VSL) T (VSR)**T ) !> !> Optionally, it also orders the eigenvalues so that a selected cluster !> of eigenvalues appears in the leading diagonal blocks of the upper !> quasi-triangular matrix S and the upper triangular matrix T; computes !> a reciprocal condition number for the average of the selected !> eigenvalues (RCONDE); and computes a reciprocal condition number for !> the right and left deflating subspaces corresponding to the selected !> eigenvalues (RCONDV). The leading columns of VSL and VSR then form !> an orthonormal basis for the corresponding left and right eigenspaces !> (deflating subspaces). !> !> A generalized eigenvalue for a pair of matrices (A,B) is a scalar w !> or a ratio alpha/beta = w, such that A - w*B is singular. It is !> usually represented as the pair (alpha,beta), as there is a !> reasonable interpretation for beta=0 or for both being zero. !> !> A pair of matrices (S,T) is in generalized real Schur form if T is !> upper triangular with non-negative diagonal and S is block upper !> triangular with 1-by-1 and 2-by-2 blocks. 1-by-1 blocks correspond !> to real generalized eigenvalues, while 2-by-2 blocks of S will be !> by making the corresponding elements of T have the !> form: !> [ a 0 ] !> [ 0 b ] !> !> and the pair of corresponding 2-by-2 blocks in S and T will have a !> complex conjugate pair of generalized eigenvalues. !> !> ``` **Parameters** *JOBVSL* ``` !> JOBVSL is CHARACTER*1 !> = 'N': do not compute the left Schur vectors; !> = 'V': compute the left Schur vectors. !> ``` *JOBVSR* ``` !> JOBVSR is CHARACTER*1 !> = 'N': do not compute the right Schur vectors; !> = 'V': compute the right Schur vectors. !> ``` *SORT* ``` !> SORT is CHARACTER*1 !> Specifies whether or not to order the eigenvalues on the !> diagonal of the generalized Schur form. !> = 'N': Eigenvalues are not ordered; !> = 'S': Eigenvalues are ordered (see SELCTG). !> ``` *SELCTG* ``` !> SELCTG is a LOGICAL FUNCTION of three REAL arguments !> SELCTG must be declared EXTERNAL in the calling subroutine. !> If SORT = 'N', SELCTG is not referenced. !> If SORT = 'S', SELCTG is used to select eigenvalues to sort !> to the top left of the Schur form. !> An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if !> SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either !> one of a complex conjugate pair of eigenvalues is selected, !> then both complex eigenvalues are selected. !> Note that a selected complex eigenvalue may no longer satisfy !> SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering, !> since ordering may change the value of complex eigenvalues !> (especially if the eigenvalue is ill-conditioned), in this !> case INFO is set to N+3. !> ``` *SENSE* ``` !> SENSE is CHARACTER*1 !> Determines which reciprocal condition numbers are computed. !> = 'N': None are computed; !> = 'E': Computed for average of selected eigenvalues only; !> = 'V': Computed for selected deflating subspaces only; !> = 'B': Computed for both. !> If SENSE = 'E', 'V', or 'B', SORT must equal 'S'. !> ``` *N* ``` !> N is INTEGER !> The order of the matrices A, B, VSL, and VSR. N >= 0. !> ``` *A* ``` !> A is REAL array, dimension (LDA, N) !> On entry, the first of the pair of matrices. !> On exit, A has been overwritten by its generalized Schur !> form S. !> ``` *LDA* ``` !> LDA is INTEGER !> The leading dimension of A. LDA >= max(1,N). !> ``` *B* ``` !> B is REAL array, dimension (LDB, N) !> On entry, the second of the pair of matrices. !> On exit, B has been overwritten by its generalized Schur !> form T. !> ``` *LDB* ``` !> LDB is INTEGER !> The leading dimension of B. LDB >= max(1,N). !> ``` *SDIM* ``` !> SDIM is INTEGER !> If SORT = 'N', SDIM = 0. !> If SORT = 'S', SDIM = number of eigenvalues (after sorting) !> for which SELCTG is true. (Complex conjugate pairs for which !> SELCTG is true for either eigenvalue count as 2.) !> ``` *ALPHAR* ``` !> ALPHAR is REAL array, dimension (N) !> ``` *ALPHAI* ``` !> ALPHAI is REAL array, dimension (N) !> ``` *BETA* ``` !> BETA is REAL array, dimension (N) !> On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will !> be the generalized eigenvalues. ALPHAR(j) + ALPHAI(j)*i !> and BETA(j),j=1,...,N are the diagonals of the complex Schur !> form (S,T) that would result if the 2-by-2 diagonal blocks of !> the real Schur form of (A,B) were further reduced to !> triangular form using 2-by-2 complex unitary transformations. !> If ALPHAI(j) is zero, then the j-th eigenvalue is real; if !> positive, then the j-th and (j+1)-st eigenvalues are a !> complex conjugate pair, with ALPHAI(j+1) negative. !> !> Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) !> may easily over- or underflow, and BETA(j) may even be zero. !> Thus, the user should avoid naively computing the ratio. !> However, ALPHAR and ALPHAI will be always less than and !> usually comparable with norm(A) in magnitude, and BETA always !> less than and usually comparable with norm(B). !> ``` *VSL* ``` !> VSL is REAL array, dimension (LDVSL,N) !> If JOBVSL = 'V', VSL will contain the left Schur vectors. !> Not referenced if JOBVSL = 'N'. !> ``` *LDVSL* ``` !> LDVSL is INTEGER !> The leading dimension of the matrix VSL. LDVSL >=1, and !> if JOBVSL = 'V', LDVSL >= N. !> ``` *VSR* ``` !> VSR is REAL array, dimension (LDVSR,N) !> If JOBVSR = 'V', VSR will contain the right Schur vectors. !> Not referenced if JOBVSR = 'N'. !> ``` *LDVSR* ``` !> LDVSR is INTEGER !> The leading dimension of the matrix VSR. LDVSR >= 1, and !> if JOBVSR = 'V', LDVSR >= N. !> ``` *RCONDE* ``` !> RCONDE is REAL array, dimension ( 2 ) !> If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the !> reciprocal condition numbers for the average of the selected !> eigenvalues. !> Not referenced if SENSE = 'N' or 'V'. !> ``` *RCONDV* ``` !> RCONDV is REAL array, dimension ( 2 ) !> If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the !> reciprocal condition numbers for the selected deflating !> subspaces. !> Not referenced if SENSE = 'N' or 'E'. !> ``` *WORK* ``` !> WORK is REAL array, dimension (MAX(1,LWORK)) !> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !> ``` *LWORK* ``` !> LWORK is INTEGER !> The dimension of the array WORK. !> If N = 0, LWORK >= 1, else if SENSE = 'E', 'V', or 'B', !> LWORK >= max( 8*N, 6*N+16, 2*SDIM*(N-SDIM) ), else !> LWORK >= max( 8*N, 6*N+16 ). !> Note that 2*SDIM*(N-SDIM) <= N*N/2. !> Note also that an error is only returned if !> LWORK < max( 8*N, 6*N+16), but if SENSE = 'E' or 'V' or 'B' !> this may not be large enough. !> !> If LWORK = -1, then a workspace query is assumed; the routine !> only calculates the bound on the optimal size of the WORK !> array and the minimum size of the IWORK array, returns these !> values as the first entries of the WORK and IWORK arrays, and !> no error message related to LWORK or LIWORK is issued by !> XERBLA. !> ``` *IWORK* ``` !> IWORK is INTEGER array, dimension (MAX(1,LIWORK)) !> On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK. !> ``` *LIWORK* ``` !> LIWORK is INTEGER !> The dimension of the array IWORK. !> If SENSE = 'N' or N = 0, LIWORK >= 1, otherwise !> LIWORK >= N+6. !> !> If LIWORK = -1, then a workspace query is assumed; the !> routine only calculates the bound on the optimal size of the !> WORK array and the minimum size of the IWORK array, returns !> these values as the first entries of the WORK and IWORK !> arrays, and no error message related to LWORK or LIWORK is !> issued by XERBLA. !> ``` *BWORK* ``` !> BWORK is LOGICAL array, dimension (N) !> Not referenced if SORT = 'N'. !> ``` *INFO* ``` !> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value. !> = 1,...,N: !> The QZ iteration failed. (A,B) are not in Schur !> form, but ALPHAR(j), ALPHAI(j), and BETA(j) should !> be correct for j=INFO+1,...,N. !> > N: =N+1: other than QZ iteration failed in SHGEQZ !> =N+2: after reordering, roundoff changed values of !> some complex eigenvalues so that leading !> eigenvalues in the Generalized Schur form no !> longer satisfy SELCTG=.TRUE. This could also !> be caused due to scaling. !> =N+3: reordering failed in STGSEN. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. **Further Details:** ``` !> !> An approximate (asymptotic) bound on the average absolute error of !> the selected eigenvalues is !> !> EPS * norm((A, B)) / RCONDE( 1 ). !> !> An approximate (asymptotic) bound on the maximum angular error in !> the computed deflating subspaces is !> !> EPS * norm((A, B)) / RCONDV( 2 ). !> !> See LAPACK User's Guide, section 4.11 for more information. !> ``` Definition at line **361** of file **sggesx.f**. ### subroutine zggesx (character jobvsl, character jobvsr, character sort, external selctg, character sense, integer n, complex\*16, dimension( lda, \* ) a, integer lda, complex\*16, dimension( ldb, \* ) b, integer ldb, integer sdim, complex\*16, dimension( \* ) alpha, complex\*16, dimension( \* ) beta, complex\*16, dimension( ldvsl, \* ) vsl, integer ldvsl, complex\*16, dimension( ldvsr, \* ) vsr, integer ldvsr, double precision, dimension( 2 ) rconde, double precision, dimension( 2 ) rcondv, complex\*16, dimension( \* ) work, integer lwork, double precision, dimension( \* ) rwork, integer, dimension( \* ) iwork, integer liwork, logical, dimension( \* ) bwork, integer info) **ZGGESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices** **Purpose:** ``` !> !> ZGGESX computes for a pair of N-by-N complex nonsymmetric matrices !> (A,B), the generalized eigenvalues, the complex Schur form (S,T), !> and, optionally, the left and/or right matrices of Schur vectors (VSL !> and VSR). This gives the generalized Schur factorization !> !> (A,B) = ( (VSL) S (VSR)**H, (VSL) T (VSR)**H ) !> !> where (VSR)**H is the conjugate-transpose of VSR. !> !> Optionally, it also orders the eigenvalues so that a selected cluster !> of eigenvalues appears in the leading diagonal blocks of the upper !> triangular matrix S and the upper triangular matrix T; computes !> a reciprocal condition number for the average of the selected !> eigenvalues (RCONDE); and computes a reciprocal condition number for !> the right and left deflating subspaces corresponding to the selected !> eigenvalues (RCONDV). The leading columns of VSL and VSR then form !> an orthonormal basis for the corresponding left and right eigenspaces !> (deflating subspaces). !> !> A generalized eigenvalue for a pair of matrices (A,B) is a scalar w !> or a ratio alpha/beta = w, such that A - w*B is singular. It is !> usually represented as the pair (alpha,beta), as there is a !> reasonable interpretation for beta=0 or for both being zero. !> !> A pair of matrices (S,T) is in generalized complex Schur form if T is !> upper triangular with non-negative diagonal and S is upper !> triangular. !> ``` **Parameters** *JOBVSL* ``` !> JOBVSL is CHARACTER*1 !> = 'N': do not compute the left Schur vectors; !> = 'V': compute the left Schur vectors. !> ``` *JOBVSR* ``` !> JOBVSR is CHARACTER*1 !> = 'N': do not compute the right Schur vectors; !> = 'V': compute the right Schur vectors. !> ``` *SORT* ``` !> SORT is CHARACTER*1 !> Specifies whether or not to order the eigenvalues on the !> diagonal of the generalized Schur form. !> = 'N': Eigenvalues are not ordered; !> = 'S': Eigenvalues are ordered (see SELCTG). !> ``` *SELCTG* ``` !> SELCTG is a LOGICAL FUNCTION of two COMPLEX*16 arguments !> SELCTG must be declared EXTERNAL in the calling subroutine. !> If SORT = 'N', SELCTG is not referenced. !> If SORT = 'S', SELCTG is used to select eigenvalues to sort !> to the top left of the Schur form. !> Note that a selected complex eigenvalue may no longer satisfy !> SELCTG(ALPHA(j),BETA(j)) = .TRUE. after ordering, since !> ordering may change the value of complex eigenvalues !> (especially if the eigenvalue is ill-conditioned), in this !> case INFO is set to N+3 see INFO below). !> ``` *SENSE* ``` !> SENSE is CHARACTER*1 !> Determines which reciprocal condition numbers are computed. !> = 'N': None are computed; !> = 'E': Computed for average of selected eigenvalues only; !> = 'V': Computed for selected deflating subspaces only; !> = 'B': Computed for both. !> If SENSE = 'E', 'V', or 'B', SORT must equal 'S'. !> ``` *N* ``` !> N is INTEGER !> The order of the matrices A, B, VSL, and VSR. N >= 0. !> ``` *A* ``` !> A is COMPLEX*16 array, dimension (LDA, N) !> On entry, the first of the pair of matrices. !> On exit, A has been overwritten by its generalized Schur !> form S. !> ``` *LDA* ``` !> LDA is INTEGER !> The leading dimension of A. LDA >= max(1,N). !> ``` *B* ``` !> B is COMPLEX*16 array, dimension (LDB, N) !> On entry, the second of the pair of matrices. !> On exit, B has been overwritten by its generalized Schur !> form T. !> ``` *LDB* ``` !> LDB is INTEGER !> The leading dimension of B. LDB >= max(1,N). !> ``` *SDIM* ``` !> SDIM is INTEGER !> If SORT = 'N', SDIM = 0. !> If SORT = 'S', SDIM = number of eigenvalues (after sorting) !> for which SELCTG is true. !> ``` *ALPHA* ``` !> ALPHA is COMPLEX*16 array, dimension (N) !> ``` *BETA* ``` !> BETA is COMPLEX*16 array, dimension (N) !> On exit, ALPHA(j)/BETA(j), j=1,...,N, will be the !> generalized eigenvalues. ALPHA(j) and BETA(j),j=1,...,N are !> the diagonals of the complex Schur form (S,T). BETA(j) will !> be non-negative real. !> !> Note: the quotients ALPHA(j)/BETA(j) may easily over- or !> underflow, and BETA(j) may even be zero. Thus, the user !> should avoid naively computing the ratio alpha/beta. !> However, ALPHA will be always less than and usually !> comparable with norm(A) in magnitude, and BETA always less !> than and usually comparable with norm(B). !> ``` *VSL* ``` !> VSL is COMPLEX*16 array, dimension (LDVSL,N) !> If JOBVSL = 'V', VSL will contain the left Schur vectors. !> Not referenced if JOBVSL = 'N'. !> ``` *LDVSL* ``` !> LDVSL is INTEGER !> The leading dimension of the matrix VSL. LDVSL >=1, and !> if JOBVSL = 'V', LDVSL >= N. !> ``` *VSR* ``` !> VSR is COMPLEX*16 array, dimension (LDVSR,N) !> If JOBVSR = 'V', VSR will contain the right Schur vectors. !> Not referenced if JOBVSR = 'N'. !> ``` *LDVSR* ``` !> LDVSR is INTEGER !> The leading dimension of the matrix VSR. LDVSR >= 1, and !> if JOBVSR = 'V', LDVSR >= N. !> ``` *RCONDE* ``` !> RCONDE is DOUBLE PRECISION array, dimension ( 2 ) !> If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the !> reciprocal condition numbers for the average of the selected !> eigenvalues. !> Not referenced if SENSE = 'N' or 'V'. !> ``` *RCONDV* ``` !> RCONDV is DOUBLE PRECISION array, dimension ( 2 ) !> If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the !> reciprocal condition number for the selected deflating !> subspaces. !> Not referenced if SENSE = 'N' or 'E'. !> ``` *WORK* ``` !> WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) !> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !> ``` *LWORK* ``` !> LWORK is INTEGER !> The dimension of the array WORK. !> If N = 0, LWORK >= 1, else if SENSE = 'E', 'V', or 'B', !> LWORK >= MAX(1,2*N,2*SDIM*(N-SDIM)), else !> LWORK >= MAX(1,2*N). Note that 2*SDIM*(N-SDIM) <= N*N/2. !> Note also that an error is only returned if !> LWORK < MAX(1,2*N), but if SENSE = 'E' or 'V' or 'B' this may !> not be large enough. !> !> If LWORK = -1, then a workspace query is assumed; the routine !> only calculates the bound on the optimal size of the WORK !> array and the minimum size of the IWORK array, returns these !> values as the first entries of the WORK and IWORK arrays, and !> no error message related to LWORK or LIWORK is issued by !> XERBLA. !> ``` *RWORK* ``` !> RWORK is DOUBLE PRECISION array, dimension ( 8*N ) !> Real workspace. !> ``` *IWORK* ``` !> IWORK is INTEGER array, dimension (MAX(1,LIWORK)) !> On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK. !> ``` *LIWORK* ``` !> LIWORK is INTEGER !> The dimension of the array IWORK. !> If SENSE = 'N' or N = 0, LIWORK >= 1, otherwise !> LIWORK >= N+2. !> !> If LIWORK = -1, then a workspace query is assumed; the !> routine only calculates the bound on the optimal size of the !> WORK array and the minimum size of the IWORK array, returns !> these values as the first entries of the WORK and IWORK !> arrays, and no error message related to LWORK or LIWORK is !> issued by XERBLA. !> ``` *BWORK* ``` !> BWORK is LOGICAL array, dimension (N) !> Not referenced if SORT = 'N'. !> ``` *INFO* ``` !> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value. !> = 1,...,N: !> The QZ iteration failed. (A,B) are not in Schur !> form, but ALPHA(j) and BETA(j) should be correct for !> j=INFO+1,...,N. !> > N: =N+1: other than QZ iteration failed in ZHGEQZ !> =N+2: after reordering, roundoff changed values of !> some complex eigenvalues so that leading !> eigenvalues in the Generalized Schur form no !> longer satisfy SELCTG=.TRUE. This could also !> be caused due to scaling. !> =N+3: reordering failed in ZTGSEN. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. Definition at line **326** of file **zggesx.f**. ## Author Generated automatically by Doxygen for LAPACK from the source code.