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

Calling Sequence

CALL DGEESX	(JOBZ, SORTEV, SELECT, SENSE, N, DA, LDA, NOUT, DWR, DWI, DZ, LDZ, SRCONE, DRCONV, DWORK, LDWORK, IWORK2, LDWRK2, BWORK3, INFO)
CALL SGEESX	(JOBZ, SORTEV, SELECT, SENSE, N, SA, LDA, NOUT, SWR, SWI, SZ, LDZ, SRCONE, SRCONV, SWORK, LDWORK, IWORK2, LDWRK2, BWORK3, INFO)
CALL ZGEESX	(JOBZ, SORTEV, SELECT, SENSE, N, ZA, LDA, NOUT, ZW, ZZ, LDZ, DRCONE, DRCONV, ZWORK, LDWORK, DWORK2, BWORK3, INFO)
CALL CGEESX	(JOBZ, SORTEV, SELECT, SENSE, N, CA, LDA, NOUT, CW, CZ, LDZ, SRCONE, SRCONV, CWORK, LDWORK, SWORK2, BWORK3, INFO)
void dgeesx	(char jobvs, char sort, L_fp select, char sense, int n, double *da, int lda, int *sdim, double *dwr, double *dwi, double *dz, int ldz, double *drcone, double *drconv, int *info)
void sgeesx	(char jobvs, char sort, L_fp select, char sense, int n, float *sa, int lda, int *sdim, float *swr, float *swi, float *sz, int ldz, float *srcone, float *srconv, int *info)
void zgeesx	(char jobvs, char sort, L_fp select, char sense, int n, doublecomplex *za, int lda, int *sdim, doublecomplex *zw, doublecomplex *zz, int ldz, double *drcone, double *drconv, int *info)
void cgeesx	(char jobvs, char sort, L_fp select, char sense, int n, complex *ca, int lda, int *sdim, complex *cw, complex *cz, int ldz, float *srcone, float *srconv, 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 are not ordered.
	'S' or 's'	Eigenvalues are 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 then 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.
SENSE	Indicates which reciprocal condition numbers will be computed. The legal values for SENSE are listed below. Any values not shown below are illegal.
	'B' or 'b'	Computed for both the eigenvalues and the selected right invariant subspace.
	'E' or 'e'	Computed for the average of selected eigenvalues only.
	'N' or 'n'	None computed.
	'V' or 'v'	Computed for the selected right invariant subspace only.
	If SENSE = 'B', 'b', 'E', 'e', 'V', or 'v' then SORTEV must be 'S' or 's'.
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) On exit, the 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) On exit, 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.
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.
	Values for LDWORK vary as shown below:
	LDWORK max(1, 3 × N) for real subroutines,
	LDWORK max(1, 2 × N) for complex subroutines.
	If SENSE = 'E', 'e', 'V', 'v', 'B', or 'b' then LDWORK must also satisfy the following:
	LDWORK N + 2 × NOUT × (N - NOUT) for real subroutines;
	LDWORK 2 × NOUT × (N - NOUT) for complex subroutines.
xWORK2	Scratch array with a dimension of LDWRK2 for real subroutines or N for complex subroutines.
LDWRK2	Leading dimension of the array WORK2 as specified in a dimension or type statement. LDWRK2 1. If SENSE = 'B', 'b', 'V', or 'v' then LDWRK2 must also satisfy: LDWRK2 NOUT × (N - NOUT).
BWORK3	Scratch array of logical type and dimension of N. 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.
	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, LDIWRK, LDWORK, N

PARAMETER (N = 2)

PARAMETER (LDA = N)

PARAMETER (LDVS = 2 * N)

PARAMETER (LDIWRK = N)

PARAMETER (LDWORK = 3 * N)

C

DOUBLE PRECISION A(LDA,N), RCONDE, RCONDV, SCRATCH

DOUBLE PRECISION VS(LDVS,N) , WORK(LDWORK), WR(N), WI(N)

INTEGER I, ICOL, INFO, IROW, IWORK(LDIWRK), SORT

C

EXTERNAL DGEESX, 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, condition numbers, and Schur

C vectors of A.

C

CALL DGEESX ('VECTORS AND EIGENVALUES', 'SORTED', SELECT,

$ 'BOTH CONDITION NUMBERS', N, A, LDA, SORT, WR,

$ WI, VS, LDVS, RCONDE, RCONDV, WORK, LDWORK,

$ IWORK, LDIWRK, SCRATCH, 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, condition numbers, and Schur vectors.

C

PRINT 1060, 1.0D0 / RCONDE

PRINT 1070, 1.0D0 / RCONDV

PRINT 1080

DO 120, IROW = 1, N

PRINT 1090, 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, 'Condition number of the eigenvalues: ', F6.1)

1070 FORMAT (1X, 'Condition number of the subspace: ', F6.1)

1080 FORMAT (/1X, 'Eigenvalue', 4X, 'Schur vector**T')

1090 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

SELECT = (ARG1 .EQ. ARG2)

C

END

Sample Output

A:

0.0 1.0

-6.0 5.0

Condition number of the eigenvalues: 1.0

Condition number of the subspace: 0.1

Eigenvalue Schur vector**T

2.00 [0.45, 0.89]

3.00 [-.89, 0.45]