Previous Next Contents Generated Index Doc Set Home



Eigenvalues, Schur Form, and Schur Factorization of a General Matrix (Simple Driver)

The subroutines described in this section compute the eigenvalues and real Schur form T of a square general matrix A. Optionally they can also compute the matrix Z of Schur vectors, which gives the Schur factorization of A=ZTZT for a real A or A=ZTZH for a complex A. They can also optionally order the eigenvalues on the diagonal of the real Schur form with selected eigenvalues at the top left so that the leading columns of Z form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. Note that the expert driver xGEESX is also available.

Calling Sequence

CALL DGEES 
(JOBZ, SORTEV, SELECT, N, DA, LDA, NOUT, DWR, DWI, DZ, 
LDZ, DWORK, LDWORK, BWORK3, INFO)
CALL SGEES 
(JOBZ, SORTEV, SELECT, N, SA, LDA, NOUT, SWR, SWI, SZ, 
LDZ, SWORK, LDWORK, BWORK3, INFO)
CALL ZGEES 
(JOBZ, SORTEV, SELECT, N, ZA, LDA, NOUT, ZW, ZZ, LDZ, 
ZWORK, LDWORK, DWORK2, BWORK3, INFO)
CALL CGEES 
(JOBZ, SORTEV, SELECT, N, CA, LDA, NOUT, CW, CZ, LDZ, 
CWORK, LDWORK, SWORK2, BWORK3, INFO)






void dgees 
(char jobvs, char sort, L_fp select, int n, double *da, 
int lda, int *sdim, double *dwr, double *dwi, double 
*dz, int ldz, int *info)
void sgees 
(char jobvs, char sort, L_fp select, int n, float *sa, 
int lda, int *sdim, float *swr, float *swi, float *sz, 
int ldz, int *info)
void zgees 
(char jobvs, char sort, L_fp select, int n, 
doublecomplex *za, int lda, int *sdim, doublecomplex 
*zw, doublecomplex *zz, int ldz, int *info)
void cgees 
(char jobvs, char sort, L_fp select, int n, complex 
*ca, int lda, int *sdim, complex *cw, complex *cz, int 
ldz, int *info)

Arguments

JOBZ

Indicates whether or not the matrix Z of Schur vectors will be computed. The legal values for JOBZ are listed below. Any values not listed below are illegal.

'N' or 'n'

Z will not be computed.

'V' or 'v'

Z will be computed.

SORTEV

Indicates whether or not to order the eigenvalues on the diagonal of the Schur form. The legal values for SORTEV are listed below. Any values not listed below are illegal.

'N' or 'n'

Eigenvalues will not be ordered.

'S' or 's'

Eigenvalues will be ordered on the diagonal as determined by the argument SELECT.

SELECT

If SORTEV = 'S' or 's' then SELECT is used to select eigenvalues to sort to the top left of the Schur form. If SORTEV = 'N' or 'n' then SELECT is not used. SELECT is a function of logical type that must be declared in an EXTERNAL statement in the caller. SELECT may no longer return a value of true for a given eigenvalue after sorting because the process of ordering may change the value of complex eigenvalues, especially if the eigenvalue is ill-conditioned. If this happens, INFO is set to N+2 as described below. Aside from the description given here, the details of SELECT vary for real and complex subroutines; these two cases are described next.

For real subroutines, SELECT has two real arguments which are the real and imaginary parts of an eigenvalue. An eigenvalue is selected to be sorted to the top left of the real Schur form if SELECT returns a value of true. If one member of a complex conjugate pair of eigenvalues is selected, then both complex eigenvalues are selected.

For complex subroutines, SELECT has a single complex argument. The eigenvalue is selected to be sorted to the top left of the Schur form if SELECT returns a value of true.

N

Order of the matrix A. N 0.

xA

On entry, the matrix A.
On exit, A has been overwritten by its Schur form T.

LDA

Leading dimension of the array A as specified in a dimension or type statement. LDA max(1, N).

NOUT

On exit, the number of eigenvalues (after ordering) for which SELECT returns a value of true. For real subroutines, complex conjugate pairs for which SELECT is true for either eigenvalue count as 2.
If SORTEV = 'N' or 'n' then NOUT = 0.

xWR, xWI

(For real subroutines)
Real and imaginary parts, respectively, of the N 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.

xW

(For complex subroutines)
N 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.

xZ

On exit, if JOBZ = 'V' or 'v' then Z contains the orthogonal or unitary matrix Z of Schur vectors. If JOBZ = 'N' or 'n' then Z is not used.

LDZ

Leading dimension of the array Z as specified in a dimension or type statement. LDZ 1. If JOBZ = 'V' or 'v' then LDZ max(1, N).

xWORK

Scratch array with a dimension of LDWORK.

LDWORK

Leading dimension of the array WORK as specified in a dimension or type statement. LDWORK max(1, 3 × N) for real subroutines or max(1, 2 × N) for complex subroutines.

xWORK2

Scratch array with a dimension N for complex subroutines.

BWORK3

Scratch array BWORK3(N) of logical type.
If SORTEV = 'N' or 'n' then BWORK3 is not used.

INFO

On exit:

INFO = 0

Subroutine completed normally.

INFO < 0

The ith argument, where i = |INFO|, had an illegal value.

1 INFO N

Convergence failure.

INFO = N+1

The eigenvalues could not be reordered because some eigenvalues were too close to separate. It is likely that the problem is very ill-conditioned.

INFO = N+2

After reordering, roundoff changed values of some complex eigenvalues so that SELECT no longer returns a value of true for leading eigenvalues in the Schur form. This could also be caused by underflow due to scaling.

Sample Program




      PROGRAM TEST
      IMPLICIT NONE
C
      INTEGER           LDA, LDVS, LDWORK, N
      PARAMETER        (N = 2)
      PARAMETER        (LDA = N)
      PARAMETER        (LDVS = 2 * N)
      PARAMETER        (LDWORK = 3 * N)
C
      DOUBLE PRECISION  A(LDA,N), TEMP, VS(LDVS,N)
      DOUBLE PRECISION  WORK(LDWORK), WR(N), WI(N)
      INTEGER           I, ICOL, INFO, IROW, SORT
C
      EXTERNAL          DGEES, SELECT
      INTRINSIC         ABS
C
C     Initialize the array A to store the matrix A shown below.
C
C     A = 0  1
C        -6  5
C
      DATA A / 0.0D0, -6.0D0, 1.0D0, 5.0D0 /
C
C     Print the initial value of A.
C
      PRINT 1000
      PRINT 1010, ((A(IROW,ICOL), ICOL = 1, N), IROW = 1, N)
C
C     Compute the eigenvalues and Schur vectors of A.
C
      CALL DGEES ('VECTORS AND EIGENVALUES', 'NOT SORTED', SELECT,
     $            N, A, LDA, SORT, WR, WI, VS, LDVS, WORK, LDWORK,
     $            TEMP, INFO)
      IF (INFO .NE. 0) THEN
        IF (INFO .LT. 0) THEN
          PRINT 1020, ABS(INFO)
          STOP 1
        ELSEIF (INFO .LE. N) THEN
          PRINT 1030, INFO
          STOP 2
        ELSEIF (INFO .EQ. N + 1) THEN
          PRINT 1040
        ELSE
          PRINT 1050
        END IF
      END IF
C
C     Print the eigenvalues and Schur vectors.
C
      PRINT 1060
      DO 120, IROW = 1, N
        PRINT 1070, WR(IROW), (VS(I,IROW), I = 1, N)
  120 CONTINUE
C
 1000 FORMAT (1X, 'A:')
 1010 FORMAT (2(3X, F4.1))
 1020 FORMAT (/1X, 'Illegal argument to DGEES, argument #', I2)
 1030 FORMAT (/1X, 'QR failed to converge, INFO = ', I2)
 1040 FORMAT (/1X, 'Eigenvalues could not be reordered; problem',
     $        /1X, 'is very ill-conditioned.')
 1050 FORMAT (/1X, 'Leading eigenvalues in the Schur form no',
     $        /1X, 'longer satisfy SELECT = .TRUE.')
 1060 FORMAT (/1X, 'Eigenvalue', 4X, 'Schur vector**T')
 1070 FORMAT (1X, F5.2, 10X, '[', F4.2, ', ', F4.2, ']')
C
      END



      LOGICAL FUNCTION SELECT (ARG1, ARG2)
      IMPLICIT NONE
C
      DOUBLE PRECISION ARG1, ARG2
      INTRINSIC INT
C
C     The value computed is always .TRUE.  It is computed in
C     the peculiar way below to avoid compiler messages about
C     unused function arguments.
C
      PRINT 1000
      SELECT = (ARG1 .EQ. ARG2)
      STOP
C
 1000 FORMAT (///1X, '**** ERROR:  ',
     $   'SELECT FUNCTION CALLED BUT NOT AVAILABLE. ****')
C
      END



Sample Output

 
 A:
    0.0    1.0
   -6.0    5.0



 Eigenvalue    Schur vector**T
  2.00          [0.45, 0.89]
  3.00          [-.89, 0.45]






Previous Next Contents Generated Index Doc Set Home