Purpose ======= LA_GEES 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 Schur 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. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. 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). A complex matrix is in complex-Schur form if it is upper triangular. ========= SUBROUTINE LA_GEES( A, , VS=vs, SELECT=select, & SDIM=sdim, 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, 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 w(j) (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 w(j) is selected if SELECT(w(j)) has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT(w(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 size(A,1) + 2 (see INFO below). Note: Select must be present if SDIM is 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). 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 w 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.