!-----------------------------------------------------------------
!
! Purpose
! =======
!
!  LA_GEES computes for an n-by-n complex nonsymmetric matrix A, the
!  eigenvalues, the Schur form T, and, optionally, the matrix of Schur
!  vectors Z.  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 matrix is in real Schur form if it is upper quasi-triangular with
!  1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be standardized in the
!  form
!          [  a  b  ]
!          [  c  a  ]
!
!  A complex matrix is in Schur form if it is upper triangular.
!
! =======
!
!   SUBROUTINE LA_GEES( A, <w>, VS, SELECT, SDIM, INFO )
!      <type>(<wp>), INTENT(INOUT) :: A(:,:)
!      <type>(<wp>), INTENT(OUT) :: <w'>
!      <type>(<wp>), INTENT(OUT), OPTIONAL :: VS(:,:)
!      INTERFACE
!         LOGICAL FUNCTION SELECT(<w>)
!            <type>(<wp>), INTENT(IN) :: <w>
!         END FUNCTION SELECT
!      END INTERFACE
!      OPTIONAL :: SELECT
!      INTEGER, INTENT(OUT), OPTIONAL :: SDIM, INFO
!    where
!       <type> ::= REAL | COMPLEX
!       <wp>   ::= KIND(1.0) | KIND(1.0D0)
!       <w>    ::= WR, WI | W
!       <w'>   ::= WR(:), WI(:) | W(:)
!
! Arguments
! =========
!
! A    (input/output) REAL | COMPLEX array, shape (:,:),
!      SIZE(A,1) == SIZE(A,2) == n.
!      On entry, the n-by-n matrix A.
!      On exit, A has been overwritten by its Schur form T.
!
! WR, WI Only real case, (output) REAL arrays, shape (:),
!      SIZE(WR) == SIZE(WI) == n (real and imaginary parts).
! W    Only complex case, (output) COMPLEX array, shape (:),
!      SIZE(W) == n.
!      WR, WI | W contain(s) the computed eigenvalues, in the
!      same order that they appear on the diagonal of the output
!      Schur form T.
!
! VS   Optional (output) REAL | COMPLEX array, shape (:,:),
!      SIZE(VS,1) == SIZE(VS,2) == n.
!      VS contains the unitary matrix Z of Schur vectors.
!
! SELECT Optional (input) LOGICAL FUNCTION of two | one
!      REAL | COMPLEX argument(s). SELECT either must be declared
!      EXTERNAL or must have an explicit interface in the calling
!      procedure. SELECT is used to select eigenvalues to order to
!      the top left of the Schur form. The eigenvalue
!      WR(j)+sqrt(-1)*WI(j) | W(j) is selected if
!      SELECT(WR(j),WI(j)) | SELECT(W(j)) is true.
!      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
!      SELECT(WR(j),WI(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+2 (see INFO below). 1 <= j <= n.
!
! SDIM Optional (output) INTEGER
!      SDIM = number of eigenvalues for which SELECT is true.
!
! INFO (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 too close to separate (the
!                  problem is very ill-conditioned);
!           = n+2: after reordering, roundoff changed values of
!                  some complex eigenvalues so that leading
!                  eigenvalues in the Schur form no longer satisfy
!                  SELECT = .TRUE..  This could also be caused by
!                  underflow due to scaling.
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!-----------------------------------------------------------------------

.