SGEESX - 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 SGEESX( JOBVS,  SORT, SELECT, SENSE, N, A, LDA,
                          SDIM, WR, WI, VS, LDVS, RCONDE, RCONDV,
                          WORK, LWORK, IWORK, LIWORK, BWORK, INFO
                          )

           CHARACTER      JOBVS, SENSE, SORT

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

           REAL           RCONDE, RCONDV

           LOGICAL        BWORK( * )

           INTEGER        IWORK( * )

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

           LOGICAL        SELECT

           EXTERNAL       SELECT


PURPOSE

       SGEESX 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; computes a
       reciprocal  condition  number  for  the  average  of   the
       selected  eigenvalues  (RCONDE); and computes a reciprocal
       condition number for the right invariant  subspace  corre­
       sponding  to the selected eigenvalues (RCONDV).  The lead­
       ing columns of  Z  form  an  orthonormal  basis  for  this
       invariant subspace.

       For  further  explanation of the reciprocal condition num­
       bers RCONDE and RCONDV, see Section  4.10  of  the  LAPACK
       Users'  Guide (where these quantities are called s and sep
       respectively).

       A real 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  ]

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



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 two REAL arguments
               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 are.   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 eigenval­
               ues (especially if the  eigenvalue  is  ill-condi­
               tioned);  in this case INFO may be set to N+3 (see
               INFO below).

       SENSE   (input) CHARACTER*1
               Determines which reciprocal condition numbers  are
               computed.  = 'N': None are computed;
               =  'E': Computed for average of selected eigenval­
               ues only;
               = 'V': Computed for selected right invariant  sub­
               space only;
               =  'B': Computed for both.  If SENSE = 'E', 'V' or
               'B', SORT must equal 'S'.

       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  is
               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 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  appear  consecutively with the eigen­
               value 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,
               and if JOBVS = 'V', LDVS >= N.

       RCONDE  (output) REAL
               If  SENSE = 'E' or 'B', RCONDE contains the recip­
               rocal condition number  for  the  average  of  the
               selected  eigenvalues.   Not referenced if SENSE =
               'N' or 'V'.

       RCONDV  (output) REAL
               If SENSE = 'V' or 'B', RCONDV contains the  recip­
               rocal  condition  number  for  the  selected right
               invariant subspace.  Not referenced if SENSE = 'N'
               or 'E'.

       WORK    (workspace/output) REAL 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,3*N).   Also,  if SENSE = 'E' or 'V' or 'B',
               LWORK >= N+2*SDIM*(N-SDIM), where SDIM is the num­
               ber  of selected eigenvalues computed by this rou­
               tine.  Note  that  N+2*SDIM*(N-SDIM)  <=  N+N*N/2.
               For  good  performance,  LWORK  must  generally be
               larger.

       IWORK   (workspace/output) INTEGER array, dimension
               (LIWORK)
               Not referenced if SENSE = 'N' or 'E'.  On exit, if
               INFO = 0, IWORK(1) returns the optimal LIWORK.

       LIWORK  (input) INTEGER
               The dimension of the array IWORK.  LIWORK >= 1; if
               SENSE = 'V' or 'B', LIWORK >= SDIM*(N-SDIM).

               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  transformation
               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 eigen­
               values   in  the  Schur  form  no  longer  satisfy
               SELECT=.TRUE.  This could also be caused by under­
               flow due to scaling.


Man(1) output converted with man2html