cgees(3S)

NAME
     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

IMPLEMENTATION
     These routines are part of the SCSL Scientific Library and can be loaded
     using either the -lscs or the -lscs_mp option.  The -lscs_mp option
     directs the linker to use the multi-processor version of the library.

     When linking to SCSL with -lscs or -lscs_mp, the default integer size is
     4 bytes (32 bits). Another version of SCSL is available in which integers
     are 8 bytes (64 bits).  This version allows the user access to larger
     memory sizes and helps when porting legacy Cray codes.  It can be loaded
     by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
     only one of the two versions; 4-byte integer and 8-byte integer library
     calls cannot be mixed.

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 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 complex matrix is in Schur form if it is upper triangular.


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': Eigenvalues 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 select eigenvalues to order to the
             top left of the Schur form.  IF SORT = 'N', SELECT is not
             referenced.  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 output 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 referenced.

     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 generally 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'.

     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; 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 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.

SEE ALSO
     INTRO_LAPACK(3S), INTRO_SCSL(3S)

     This man page is available only online.