CGEES  - compute for an N-by-N complex nonsymmetric matrix
       A, the eigenvalues, the Schur form T, and, optionally, the
       matrix of Schur vectors Z


SYNOPSIS

       SUBROUTINE CGEES( JOBVS, SORT, SELECT, N, A, LDA, SDIM, W,
                         VS, LDVS,  WORK,  LWORK,  RWORK,  BWORK,
                         INFO )

           CHARACTER     JOBVS, SORT

           INTEGER       INFO, LDA, LDVS, LWORK, N, SDIM

           LOGICAL       BWORK( * )

           REAL          RWORK( * )

           COMPLEX       A(  LDA,  *  ),  VS(  LDVS, * ), W( * ),
                         WORK( * )

           LOGICAL       SELECT

           EXTERNAL      SELECT


PURPOSE

       CGEES 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 factoriza­
       tion  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 eigenval­
       ues.

       A complex matrix is in Schur form if it is upper  triangu­
       lar.


ARGUMENTS

       JOBVS   (input) CHARACTER*1
               = 'N': Schur vectors are not computed;
               = 'V': Schur vectors are computed.

       SORT    (input) CHARACTER*1
               Specifies  whether or not to order the eigenvalues
               on the diagonal of the Schur form.  = 'N':  Eigen­
               values are not ordered:
               = 'S': Eigenvalues are ordered (see SELECT).

       SELECT  (input) LOGICAL FUNCTION of one COMPLEX argument
               SELECT  must  be  declared EXTERNAL in the calling
               subroutine.  If SORT =  'S',  SELECT  is  used  to

               Schur form.  IF SORT = 'N', SELECT is  not  refer­
               enced.    The   eigenvalue  W(j)  is  selected  if
               SELECT(W(j)) is true.

       N       (input) INTEGER
               The order of the matrix A. N >= 0.

       A       (input/output) COMPLEX array, dimension (LDA,N)
               On entry, the N-by-N matrix A.   On  exit,  A  has
               been overwritten by its Schur form T.

       LDA     (input) INTEGER
               The  leading  dimension  of  the  array A.  LDA >=
               max(1,N).

       SDIM    (output) INTEGER
               If SORT = 'N', SDIM = 0.  If SORT =  'S',  SDIM  =
               number of eigenvalues for which SELECT is true.

       W       (output) COMPLEX array, dimension (N)
               W  contains  the computed eigenvalues, in the same
               order that they appear on the diagonal of the out­
               put Schur form T.

       VS      (output) COMPLEX array, dimension (LDVS,N)
               If  JOBVS  = 'V', VS contains the unitary matrix Z
               of Schur vectors.  If JOBVS = 'N', VS is not  ref­
               erenced.

       LDVS    (input) INTEGER
               The leading dimension of the array VS.  LDVS >= 1;
               if JOBVS = 'V', LDVS >= N.

       WORK    (workspace/output) COMPLEX array, dimension
               (LWORK)
               On  exit, if INFO = 0, WORK(1) returns the optimal
               LWORK.

       LWORK   (input) INTEGER
               The  dimension  of  the  array  WORK.   LWORK   >=
               max(1,2*N).  For good performance, LWORK must gen­
               erally be larger.

               If LWORK = -1, then a workspace query is  assumed;
               the  routine  only  calculates the optimal size of
               the WORK array, returns this value  as  the  first
               entry  of  the  WORK  array,  and no error message
               related to LWORK is issued by XERBLA.

       RWORK   (workspace) REAL array, dimension (N)

       BWORK   (workspace) LOGICAL array, dimension (N)
               Not referenced if SORT = 'N'.

               = 0: successful exit
               < 0: if INFO = -i, the i-th argument had an  ille­
               gal 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 con­
               tain those eigenvalues which  have  converged;  if
               JOBVS  = 'V', 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  com­
               plex  eigenvalues  so  that leading eigenvalues in
               the Schur form no longer satisfy SELECT =  .TRUE..
               This  could  also  be  caused  by underflow due to
               scaling.


Man(1) output converted with man2html