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


SYNOPSIS

       SUBROUTINE SGEES( JOBVS,  SORT,  SELECT,  N, A, LDA, SDIM,
                         WR, WI, VS, LDVS,  WORK,  LWORK,  BWORK,
                         INFO )

           CHARACTER     JOBVS, SORT

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

           LOGICAL       BWORK( * )

           REAL          A(  LDA,  *  ),  VS( LDVS, * ), WI( * ),
                         WORK( * ), WR( * )

           LOGICAL       SELECT

           EXTERNAL      SELECT


PURPOSE

       SGEES computes for an N-by-N real nonsymmetric  matrix  A,
       the  eigenvalues,  the real Schur form T, and, optionally,
       the matrix of Schur vectors Z. This gives the  Schur  fac­
       torization A = Z*T*(Z**T).  Optionally, it also orders the
       eigenvalues on the diagonal of the real 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 matrix is in real Schur form if it is upper quasi-trian­
       gular with 1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be
       standardized in the form
               [  a  b  ]
               [  c  a  ]

       where b*c < 0. The eigenvalues of such a block  are  a  +-
       sqrt(bc).


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  must  be  declared EXTERNAL in the calling
               subroutine.  If SORT =  'S',  SELECT  is  used  to
               select  eigenvalues to sort to the top left of the
               Schur form.  If SORT = 'N', SELECT is  not  refer­
               enced.    An  eigenvalue  WR(j)+sqrt(-1)*WI(j)  is
               selected if SELECT(WR(j),WI(j)) is true; i.e.,  if
               either  one  of a complex conjugate pair of eigen­
               values is selected, then both complex  eigenvalues
               are selected.  Note that a selected complex eigen­
               value 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).

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

       A       (input/output) REAL array, dimension (LDA,N)
               On entry, the N-by-N matrix A.   On  exit,  A  has
               been overwritten by its real 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  (after sorting) for which
               SELECT is true. (Complex conjugate pairs for which
               SELECT  is true for either eigenvalue count as 2.)

       WR      (output) REAL array, dimension (N)
               WI      (output) REAL array, dimension (N) WR  and
               WI  contain  the real and imaginary parts, respec­
               tively, of the computed eigenvalues  in  the  same
               order that they appear on the diagonal of the out­
               put Schur form  T.   Complex  conjugate  pairs  of
               eigenvalues  will  appear  consecutively  with the
               eigenvalue  having  the  positive  imaginary  part
               first.

       VS      (output) REAL array, dimension (LDVS,N)
               If  JOBVS = 'V', VS contains the orthogonal matrix
               Z of Schur vectors.  If JOBVS =  'N',  VS  is  not
               referenced.

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

       WORK    (workspace/output) REAL array, dimension (LWORK)
               On exit, if INFO = 0, WORK(1) contains the optimal


       LWORK   (input) INTEGER
               The   dimension  of  the  array  WORK.   LWORK  >=
               max(1,3*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.

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

       INFO    (output) INTEGER
               = 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 WR  and
               WI contain 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 sepa­
               rate (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.


Man(1) output converted with man2html