Previous Next Contents Generated Index Doc Set Home



Eigenvalues and Eigenvectors of a Symmetric Matrix (Expert Driver)

The subroutines described in this section compute the eigenvalues and, optionally, the eigenvectors of a symmetric matrix A. The eigenvectors are normalized to have a Euclidean norm of 1. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues. Note that the simple driver xSYEV is also available.

Calling Sequence

CALL DSYEVX 
(JOBZ, RANGE, UPLO, N, DA, LDA, DVL, DVU, IL, IU, 
DABTOL, NFOUND, DW, DZ, LDZ, DWORK, LDWORK, IWORK2, 
IFAIL, INFO)
CALL SSYEVX 
(JOBZ, RANGE, UPLO, N, SA, LDA, SVL, SVU, IL, IU, 
SABTOL, NFOUND, SW, SZ, LDZ, SWORK, LDWORK, IWORK2, 
IFAIL, INFO)






void dsyevx 
(char jobz, char range, char uplo, int n, double *da, 
int lda, double dvl, double dvu, int il, int iu, double 
dabtol, int *nfound, double *dw, double *dz, int ldz, 
int *ifail, int *info)
void ssyevx 
(char jobz, char range, char uplo, int n, float *sa, 
int lda, float svl, float svu, int il, int iu, float 
sabtol, int *nfound, float *sw, float *sz, int ldz, int 
*ifail, int *info)

Arguments

JOBZ

Indicates whether to compute eigenvalues only or to compute both eigenvalues and eigenvectors. The legal values for JOBZ are listed below. Any values not listed below are illegal.

'N' or 'n'

Compute eigenvalues only.

'V' or 'v'

Compute both eigenvalues and eigenvectors.

RANGE

Indicates whether to compute all eigenvalues or some subset. Legal values for RANGE are shown below. Any values not shown below are illegal.

'A' or 'a'

All eigenvalues will be computed.

'I' or 'i'

The ILth through IUth eigenvalues will be computed; see the descriptions of the IL and IU arguments below.

'V' or 'v'

All eigenvalues in the half-open interval (VL,VU] will be computed; see the descriptions of the VL and VU arguments below.

UPLO

Indicates whether xA contains the upper or lower triangle of the matrix. The legal values for UPLO are listed below. Any values not listed below are illegal.

'U' or 'u'

xA contains the upper triangle.

'L' or 'l'

xA contains the lower triangle.

N

Order of the matrix A. N 0.

xA

On entry, the upper or lower triangle of the matrix A.
On exit, the upper or lower triangle of A including the diagonal has been overwritten.

LDA

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

xVL, xVU

If RANGE = 'V' or 'v' then only eigenvalues in the half-open interval (VL,VU] will be computed. Otherwise not used.

IL, IU

If RANGE = 'I' or 'i' then only the ILth through IUth eigenvalues will be computed. Otherwise not used. 1 IL IU N.

xABTOL

The absolute error tolerance for the eigenvalues. An approximate eigenvalue is considered to have converged when it lies in an interval [a,b] of width less than or equal to ABTOL + × max(|a|, |b|) where is machine precision. If ABTOL 0 then × ||T||1 will be used in its place, where ||T||1 is the 1-norm of the tridiagonal matrix obtained by reducing A to tridiagonal form.

NFOUND

On exit, the total number of eigenvalues found. 0 NFOUND N.
If RANGE = 'A' or 'a' then NFOUND = N. If RANGE = 'I' or 'i' then NFOUND = IU - IL + 1.

xW

On exit, W(1:NFOUND) contains the computed eigenvalues in ascending order.

xZ

On exit, if JOBZ = 'V' or 'v' then the first NFOUND columns of Z contain the orthonormal eigenvectors corresponding to the selected eigenvalues. If an eigenvector fails to converge then the corresponding column of Z contains an approximation to that eigenvector and its index is returned in IFAIL. If JOBZ = 'N' or 'n' then Z is not used.

Note that Z must have at least NFOUND columns. If RANGE = 'V' or 'v' then NFOUND may not be known in advance and an upper bound must be used. For A(LDZ,K) where NFOUND > K, the eigenvectors will be stored into memory with unpredictable results.

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, 8 × N).

IWORK2

Scratch array with a dimension of 5 × N.

IFAIL

On exit, an N-element array that indicates which eigenvectors that failed to converge. If JOBZ = 'V' or 'v' and INFO = 0 then all N elements contain zero. If INFO > 0 then IFAIL contains the indices of the eigenvectors that failed to converge. If JOBZ = 'N' or 'n' then IFAIL is not used.

INFO

On exit:

INFO = 0

Subroutine completed normally.

INFO < 0

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

INFO > 0

There were i eigenvectors, where i = INFO, that failed to converge. Their indices are stored in IFAIL.

Sample Program




      PROGRAM TEST
      IMPLICIT NONE
C
      INTEGER           LDA, LDEVEC, LDIWRK, LDWORK, N
      PARAMETER        (N = 3)
      PARAMETER        (LDA = N)
      PARAMETER        (LDEVEC = N)
      PARAMETER        (LDIWRK = 5 * N)
      PARAMETER        (LDWORK = 8 * N)
C
      DOUBLE PRECISION  A(LDA,N), TEMP, EVALS(N), EVECS(LDEVEC,N)
      DOUBLE PRECISION  WORK(LDWORK)
      INTEGER           ICOL, IFAIL(N), INFO, IROW, ITEMP
      INTEGER           IWORK(LDIWRK), NFOUND
C
      EXTERNAL          DSYEVX
C
C     Initialize the array A to store the matrix A shown below.
C
C         9  1  1
C     A = 1  9  1
C         1  1  9
C
      DATA A / 9.0D0, 8D8, 8D8, 1.0D0, 9.0D0, 8D8, 1.0D0, 1.0D0,
     $         9.0D0 /
C
      PRINT 1000
      DO 100, IROW = 1, N
        PRINT 1010, (A(ICOL,IROW), ICOL = 1, IROW - 1),
     $              (A(IROW,ICOL), ICOL = IROW, N)
  100 CONTINUE
      PRINT 1020
      DO 110, IROW = 1, N
        PRINT 1010, (A(IROW,ICOL), ICOL = 1, N)
  110 CONTINUE
C
C     Compute the eigenvalues and eigenvectors of A.
C
C     Arguments 7 - 10 are not used because RANGE (argument 2)
C     indicates that all eigenvalues should be found.  Note
C     however that the scratch values passed into DSYEVX for
C     arguments 7 - 10 are of the correct type.  Arguments 7 
C     and 8 take the place of double precision values, so TEMP
C     is declared double precision. Arguments 9 and 10 take the
C     place of integer arguments, so ITEMP is declared integer. 
C     Even though these arguments are not referenced, passing
C     arguments of the wrong type may cause run time errors due 
C     to the alignment of the arguments in memory.
C
      CALL DSYEVX ('VALUES AND VECTORS', 'ALL EIGENVALUES',
     $             'UPPER TRIANGULAR A', N, A, LDA, TEMP, TEMP,
     $             ITEMP, ITEMP, 0.0D0, NFOUND, EVALS, EVECS,
     $             LDEVEC, WORK, LDWORK, IWORK, IFAIL, INFO)
      IF (INFO .NE. 0) THEN
        IF (INFO .LT. 0) THEN
          PRINT 1030, -INFO
          STOP 1
        ELSE
          PRINT 1040, INFO
          STOP 2
        END IF
      END IF
C
C     Print the eigenvalues and eigenvectors.
C
      PRINT 1050
      DO 120, ICOL = 1, N
        PRINT 1060, EVALS(ICOL), (EVECS(IROW,ICOL), IROW = 1, N)
  120 CONTINUE
C
 1000 FORMAT (1X, 'A in full form:')
 1010 FORMAT (3(3X, F4.1))
 1020 FORMAT (/1X, 'A in symmetric form:  (* in unused elements)')
 1030 FORMAT (/1X, 'Illegal argument to DSYEVX, argument #', I2)
 1040 FORMAT (/1X, 'Convergence failure, INFO = ', I2)
 1050 FORMAT (/1X, 'Eigenvalue', 4X, 'Eigenvector**T')
 1060 FORMAT (1X, F7.2, 5X, '[', F4.2, ', ', F4.2, ', ',
     $        F4.2, ']')
C
      END
 

Sample Output

 
 A in full form:
    9.0    1.0    1.0
    1.0    9.0    1.0
    1.0    1.0    9.0



 A in symmetric form:  (* in unused elements)
    9.0    1.0    1.0
   ****    9.0    1.0
   ****   ****    9.0



 Eigenvalue    Eigenvector**T
    8.00     [0.04, -.73, 0.69]
    8.00     [0.82, -.37, -.44]
   11.00     [0.58, 0.58, 0.58]






Previous Next Contents Generated Index Doc Set Home