DGEES  - 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 DGEES( 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( * )

           DOUBLE        PRECISION  A(  LDA,  * ), VS( LDVS, * ),
                         WI( * ), WORK( * ), WR( * )

           LOGICAL       SELECT

           EXTERNAL      SELECT


PURPOSE

       DGEES 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).

               PRECISION argu­ ments
               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) DOUBLE PRECISION 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) DOUBLE PRECISION array, dimension (N)
               WI      (output) DOUBLE PRECISION array, dimension
               (N) WR and  WI  contain  the  real  and  imaginary
               parts,  respectively,  of the computed eigenvalues
               in the same order that they appear on the diagonal
               of  the  output  Schur  form T.  Complex conjugate
               pairs of  eigenvalues  will  appear  consecutively
               with  the eigenvalue having the positive imaginary
               part first.

       VS      (output) DOUBLE PRECISION 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.

               dimension (LWORK)
               On exit, if INFO = 0, WORK(1) contains the optimal
               LWORK.

       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