Purpose ======= LA_GEESX computes for a real/complex square matrix A, the eigenvalues, the real-Schur/complex-Schur form T , and, optionally, the matrix of Schur vectors Z, where Z is orthogonal/unitary. This gives the factorization A = Z*T*Z^H. Optionally, it also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left, computes a reciprocal condition number for the average of the selected eigenvalues and computes a reciprocal condition number for the right invariant subspace corresponding to the selected eigenvalues. The leading columns of Z form an orthonormal basis for this invariant subspace. A real matrix is in real-Schur form if it is block upper triangular with 1 by 1 and 2 by 2 blocks along the main diagonal. 2 by 2 blocks are standardized in the form [ a b ] [ c a ] where b*c < 0. The eigenvalues of such a block are a +/- Sqrt(b*c). ========= SUBROUTINE LA_GEESX( A, , VS=vs, SELECT=select, SDIM=sdim, & RCONDE=rconde, RCONDV=rcondv, INFO=info ) (), INTENT(INOUT) :: A(:,:) (), INTENT(OUT) :: (), INTENT(OUT), OPTIONAL :: VS(:,:) INTERFACE LOGICAL FUNCTION SELECT() (), INTENT(IN) :: END FUNCTION SELECT END INTERFACE OPTIONAL :: SELECT INTEGER, INTENT(OUT), OPTIONAL :: SDIM REAL(), INTENT(OUT), OPTIONAL :: RCONDE, RCONDV INTEGER, INTENT(OUT), OPTIONAL :: INFO where ::= REAL | COMPLEX ::= KIND(1.0) | KIND(1.0D0) ::= WR, WI | W ::= WR(:), WI(:) | W(:) ::= WR(j), WI(j) | W(j) Arguments ========= A (input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the Schur form T . (output) REAL or COMPLEX array, shape (:) with size(w) = size(A,1). The computed eigenvalues in the order in which they appear on the diagonal of the Schur form T. ::= WR(:), WI(:) | W(:), where WR(:), WI(:) are of REAL type (for the real and imaginary parts) and W(:) is of COMPLEX type. Note: If A is real, then a complex-conjugate pair appear consecutively, with the eigenvalue having the positive imaginary part appearing first. VS Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VS,1) = size(A,1). The matrix Z of Schur vectors. SELECT Optional (input) LOGICAL FUNCTION LOGICAL FUNCTION SELECT( ) (), INTENT(IN) :: where ::= REAL | COMPLEX ::= KIND(1.0) | KIND(1.0D0) ::= WR(j), WI(j) | W(j) 1. SELECT must be declared as EXTERNAL or as an explicit interface in the calling (sub)program. 2. SELECT is called by LA_GEES for every computed eigenvalue (but only once for a complex conjugate pair when A is real). It is used to select the eigenvalues that will be ordered to the top left of the Schur form. The eigenvalue is selected if SELECT() has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT() = .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 size(A,1) + 2 (see INFO below). Note: Select must be present if SDIM, RCONDE and RCONDF are desired. SDIM Optional (output) INTEGER. The number of eigenvalues (after sorting) for which SELECT = .TRUE. (If A is real, complex conjugate pairs for which SELECT = .TRUE. for either eigenvalue count as 2). RCONDE Optional (output) REAL. The reciprocal condition number for the average of the selected eigenvalues. RCONDV Optional (output) REAL. The reciprocal condition number for the selected right invariant subspace. INFO Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = -i, the i-th argument had an illegal value. > 0: if INFO = i, and i is <= n: the QR algorithm failed to compute all the eigenvalues; elements 1:ilo-1 and i+1:n of contain those eigenvalues which have converged. VS contains the matrix which reduces A to its partially converged Schur form. = n+1: the eigenvalues could not be reordered because some eigenvalues were not sufficiently separated (the problem is very ill-conditioned). = n+2: after reordering, some leading complex eigenvalues in the Schur form no longer satisfy SELECT = .TRUE. This can be caused by ordinary roundoff or underflow due to scaling. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.