Engineering and Scientific Subroutine Library for AIX Version 3 Release 3: Guide and Reference

SSPEV, DSPEV, CHPEV, and ZHPEV--Eigenvalues and, Optionally, the Eigenvectors of a Real Symmetric Matrix or a Complex Hermitian Matrix

SSPEV and DSPEV compute the eigenvalues and, optionally, the eigenvectors of real symmetric matrix A, stored in lower- or upper-packed storage mode. CHPEV and ZHPEV compute the eigenvalues and, optionally, the eigenvectors of complex Hermitian matrix A, stored in lower- or upper-packed storage mode. Eigenvalues are returned in vector w, and eigenvectors are returned in matrix Z:

Az = wz

where A = A^T or A = A^H.

Table 124. Data Types

Note:

For compatibility with earlier releases of ESSL, you can use the names SSLEV, DSLEV, CHLEV, and ZHLEV for SSPEV, DSPEV, CHPEV, and ZHPEV, respectively.

Syntax

On Entry

iopt

indicates the type of computation to be performed, where:

If iopt = 0 or 20, eigenvalues only are computed.

If iopt = 1 or 21, eigenvalues and eigenvectors are computed.

Specified as: a fullword integer; iopt = 0, 1, 20, or 21.

ap

is the real symmetric or complex Hermitian matrix A of order n, whose eigenvalues and, optionally, eigenvectors are computed. It is stored in an array, referred to as AP, where:

If iopt = 0 or 1, it is stored in lower-packed storage mode.

If iopt = 20 or 21, it is stored in upper-packed storage mode.

Specified as: a one-dimensional array of (at least) length n(n+1)/2, containing numbers of the data type indicated in Table 124. On output, for SSPEV and DSPEV if iopt = 0 or 20, and for CHPEV and ZHPEV, AP is overwritten; that is, the original input is not preserved.

w

See On Return.

z

See On Return.

ldz

has the following meaning, where:

If iopt = 0 or 20, it is not used in the computation.

If iopt = 1 or 21, it is the leading dimension of the output array specified for z.

Specified as: a fullword integer. It must have the following value, where:

If iopt = 0 or 20, ldz > 0.

If iopt = 1 or 21, ldz > 0 and ldz >= n.

n

is the order of matrix A. Specified as: a fullword integer; n >= 0.

aux

has the following meaning:

If naux = 0 and error 2015 is unrecoverable, aux is ignored.

Otherwise, it is a storage work area used by this subroutine. Its size is specified by naux.

Specified as: an area of storage, containing numbers of the data type indicated in Table 124. On output, the contents are overwritten.

naux

is the size of the work area specified by aux--that is, the number of elements in aux. Specified as: a fullword integer, where:

If naux = 0 and error 2015 is unrecoverable, SSPEV, DSPEV, CHPEV, and ZHPEV dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, It must have the following value, where:

For SSPEV and DSPEV:

If iopt = 0 or 20, naux >= n.

If iopt = 1 or 21, naux >= 2n.

For CHPEV and ZHPEV:

If iopt = 0 or 20, naux >= 3n.

If iopt = 1 or 21, naux >= 4n.

On Return

w

is the vector w of length n, containing the eigenvalues of A in ascending order. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 124.

z

has the following meaning, where:

If iopt = 0 or 20, it is not used in the computation.

If iopt = 1 or 21, it is the matrix Z of order n, containing the orthonormal eigenvectors of matrix A. The eigenvector in column i of matrix Z corresponds to the eigenvalue w_i.

Returned as: an ldz by (at least) n array, containing numbers of the data type indicated in Table 124.

Notes

1. When you specify iopt = 0 or 20, you must specify:
   • A positive value for ldz
   • A dummy argument for z (see Example 1)
2. The following items must have no common elements: matrix A, matrix Z, vector w, and the data area specified for aux; otherwise, results are unpredictable. See Concepts.
3. On input, the imaginary parts of the diagonal elements of the complex Hermitian matrix A are assumed to be zero, so you do not have to set these values.
4. For a description of how real symmetric matrices are stored in lower- or upper-packed storage mode, see Lower-Packed Storage Mode or Upper-Packed Storage Mode, respectively.

   For a description of how complex Hermitian matrices are stored in lower- or upper-packed storage mode, see Complex Hermitian Matrix.

5. You have the option of having the minimum required value for naux dynamically returned to your program. For details, see Using Auxiliary Storage in ESSL.

Function

The next two sections describe the methods used to compute the eigenvalues and, optionally, the eigenvectors for either a real symmetric matrix or a complex Hermitian matrix. For more information on these methods, see references [39], [43], [63], [87], [97], and [99]. If n is 0, no computation is performed. The results of the computations using short- and long-precision data can vary in accuracy. See Example 3 and Example 4 for an illustration of the difference in results. Eigenvalues computed using equivalent iopt values are mathematically equivalent, but are not guaranteed to be bitwise identical. For example, the results computed using iopt = 0 and iopt = 20 are mathematically equivalent, but are not necessarily bitwise identical.

These algorithms have a tendency to generate underflows that may hurt overall performance. The system default is to mask underflow, which improves the performance of these subroutines.

Real Symmetric Matrix

The eigenvalues and, optionally, the eigenvectors of a real symmetric matrix A are computed as follows:

• For iopt = 0 or 20, the eigenvalues are computed as follows:
  1. Reduce the real symmetric matrix A to a real symmetric tridiagonal matrix using orthogonal similarity transformations.
  2. Compute the eigenvalues of the real symmetric tridiagonal matrix using the implicit QL algorithm.
  3. The eigenvalues are ordered and returned in vector w.
• For iopt = 1 or 21, the eigenvalues and eigenvectors are computed as follows:
  1. Reduce the real symmetric matrix A to a real symmetric tridiagonal matrix using and accumulating orthogonal similarity transformations.
  2. Compute the eigenvalues of the real symmetric tridiagonal matrix and the eigenvectors of the real symmetric matrix using the implicit QL algorithm.
  3. The eigenvalues are ordered and returned in vector w, and the corresponding eigenvectors are returned in matrix Z.

Complex Hermitian Matrix

The eigenvalues and, optionally, the eigenvectors of a complex Hermitian matrix A are computed as follows:

• For iopt = 0 or 20, the eigenvalues are computed as follows:
  1. Reduce the complex Hermitian matrix A to a real symmetric tridiagonal matrix using unitary similarity transformations.
  2. Compute the eigenvalues of the real symmetric tridiagonal matrix using the implicit QL algorithm.
  3. The eigenvalues are ordered and returned in vector w.
• For iopt = 1 or 21, the eigenvalues and eigenvectors are computed as follows:
  1. Reduce the complex Hermitian matrix A to a real symmetric tridiagonal matrix using unitary similarity transformations.
  2. Compute the eigenvalues and eigenvectors of the real symmetric tridiagonal matrix using the implicit QL algorithm.
  3. Back transform the eigenvectors of the real symmetric tridiagonal matrix to those of the original complex Hermitian matrix.
  4. The eigenvalues are ordered and returned in vector w, and the corresponding eigenvectors are returned in matrix Z.

Error Conditions

Resource Errors

Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.

Computational Errors

Eigenvalue (i) failed to converge after (xxx) iterations:

• The eigenvalues (w_j, j = 1, 2, ..., i-1) are correct, but are unordered.
• If iopt = 1 or 21, then z is modified, but no eigenvectors are correct.
• If iopt = 0 or 20 for SSPEV and DSPEV, ap is modified.
• For CHPEV and ZHPEV, ap is modified.
• The return code is set to 1.
• i and xxx can be determined at run time by use of the ESSL error-handling-facilities. To obtain this information, you must use ERRSET to change the number of allowable errors for error code 2101 in the ESSL error option table; otherwise, the default value causes your program to terminate when this error occurs. See What Can You Do about ESSL Computational Errors?.

Input-Argument Errors

1. iopt <> 0, 1, 20, or 21
2. n < 0
3. ldz <= 0 and iopt = 1 or 21
4. n > ldz and iopt = 1 or 21
5. Error 2015 is recoverable or naux<>0, and naux is too small--that is, less than the minimum required value. Return code 2 is returned if error 2015 is recoverable.

Example 1

This example shows how to find the eigenvalues only of a real short-precision symmetric matrix A of order 3, stored in lower-packed storage mode Matrix A is:

                *                  *
                |  1.0  -1.0   0.0 |
                | -1.0   2.0  -1.0 |
                |  0.0  -1.0   1.0 |
                *                  *

where:

• NAUX is equal to N.
• AUX contains N elements.
• LDZ is set to 1 to avoid an error condition.
• DUMMY is used as a placeholder for argument z, which is not used in the computation.
• On output, AP has been overwritten.

Call Statement and Input

           IOPT  AP   W     Z    LDZ  N   AUZ  NAUX
            |    |    |     |     |   |    |    |
CALL SSPEV( 0  , AP , W , DUMMY , 1 , 3 , AUX , 3  )
 
AP       =  (1.0, -1.0, 0.0, 2.0, -1.0, 1.0)

Output

        *          *
        | 0.000000 |
W    =  | 1.000000 |
        | 3.000000 |
        *          *

Example 2

This example shows how to find the eigenvalues and eigenvectors of a real short-precision symmetric matrix A of order 4, stored in upper-packed storage mode. Matrix A is:

                          *                    *
                          | 5.0  4.0  1.0  1.0 |
                          | 4.0  5.0  1.0  1.0 |
                          | 1.0  1.0  4.0  2.0 |
                          | 1.0  1.0  2.0  4.0 |
                          *                    *

where:

• NAUX is equal to 2N.
• AUX contains 2N elements.

Note:

This matrix is used in Example 4.1 in referenced text [63].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   AUZ  NAUX
            |    |    |   |   |   |    |    |
CALL SSPEV( 21 , AP , W , Z , 4 , 4 , AUX , 8  )
 
AP       =  (5.0, 4.0, 5.0, 1.0, 1.0, 4.0, 1.0, 1.0, 2.0, 4.0)

Output

        *          *
        | 1.000000 |
W    =  | 2.000000 |
        | 5.000000 |
        | 9.999999 |
        *          *

        *                                           *
        |  0.707107   0.000000   0.316227  0.632455 |
Z    =  | -0.707107   0.000000   0.316228  0.632455 |
        |  0.000000  -0.707106  -0.632455  0.316227 |
        |  0.000000   0.707107  -0.632455  0.316228 |
        *                                           *

Example 3

This example shows how to find the eigenvalues and eigenvectors of a real short-precision symmetric matrix A, stored in lower-packed storage mode, which has an eigenvalue of multiplicity 2. Matrix A is:

                          *                    *
                          | 6.0  4.0  4.0  1.0 |
                          | 4.0  6.0  1.0  4.0 |
                          | 4.0  1.0  6.0  4.0 |
                          | 1.0  4.0  4.0  6.0 |
                          *                    *

where:

• NAUX is equal to 2N.
• AUX contains 2N elements.

Note:

This matrix is used in Example 4.2 in referenced text [63].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   AUZ  NAUX
            |    |    |   |   |   |    |    |
CALL SSPEV( 1  , AP , W , Z , 7 , 4 , AUX , 8  )
 
AP       =  (6.0, 4.0, 4.0, 1.0, 6.0, 1.0, 4.0, 6.0, 4.0, 6.0)

Output

        *           *
        | -1.000000 |
W    =  |  4.999999 |
        |  5.000000 |
        | 15.000000 |
        *           *

        *                                           *
        | -0.500000   0.000000   0.707107  0.500000 |
        |  0.500000   0.707107   0.000000  0.500000 |
        |  0.500000  -0.707107   0.000000  0.500000 |
Z    =  | -0.500000   0.000000  -0.707107  0.500000 |
        |   .          .          .         .       |
        |   .          .          .         .       |
        |   .          .          .         .       |
        *                                           *

Example 4

This example shows how the results of Example 3 differ if matrix A is a real long-precision symmetric matrix.

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   AUZ  NAUX
            |    |    |   |   |   |    |    |
CALL DSPEV( 1  , AP , W , Z , 7 , 4 , AUX , 8  )

Output

        *           *
        | -1.000000 |
W    =  |  5.000000 |
        |  5.000000 |
        | 15.000000 |
        *           *

        *                                           *
        | -0.500000  -0.216773  -0.673060  0.500000 |
        |  0.500000   0.673060  -0.216773  0.500000 |
        |  0.500000  -0.673060   0.216773  0.500000 |
Z    =  | -0.500000   0.216773   0.673060  0.500000 |
        |   .          .          .         .       |
        |   .          .          .         .       |
        |   .          .          .         .       |
        *                                           *

Example 5

This example shows how to find the eigenvalues and eigenvectors of a complex Hermitian matrix A of order 2, stored in lower-packed storage mode. Matrix A is:

                      *                         *
                      | (1.0, 0.0)  (0.0, -1.0) |
                      | (0.0, 1.0)  (1.0,  0.0) |
                      *                         *

where:

• NAUX is equal to 4N.
• AUX contains 4N elements.
• On output, AP has been overwritten.

Note:

This matrix is used in Example 6.1 in referenced text [63].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   AUZ  NAUX
            |    |    |   |   |   |    |    |
CALL ZHPEV( 1  , AP , W , Z , 2 , 2 , AUX , 8  )
 
AP       =  ((1.0, . ), (0.0, 1.0), (1.0, . ))

Output

        *          *
W    =  | 0.000000 |
        | 2.000000 |
        *          *

        *                                               *
Z    =  |  (0.000000, -0.707107)  (0.000000, -0.707107) |
        | (-0.707107,  0.000000)  (0.707107,  0.000000) |
        *                                               *

Example 6

This example shows how to find the eigenvalues only of a complex Hermitian matrix A of order 4, stored in upper-packed storage mode. Matrix A is:

         *                                                  *
         | (3.0,  0.0)  (1.0, 0.0)  (0.0,  0.0)  (0.0, 2.0) |
         | (1.0,  0.0)  (3.0, 0.0)  (0.0, -2.0)  (0.0, 0.0) |
         | (0.0,  0.0)  (0.0, 2.0)  (1.0,  0.0)  (1.0, 0.0) |
         | (0.0, -2.0)  (0.0, 0.0)  (1.0,  0.0)  (1.0, 0.0) |
         *                                                  *

where:

• NAUX is equal to 3N.
• AUX contains 3N elements.
• LDZ is set to 1 to avoid an error condition.
• DUMMY is used as a placeholder for argument z, which is not used in the computation.
• On output, AP has been overwritten.

Note:

This matrix is used in Example 6.6 in referenced text [63].

Call Statement and Input

           IOPT  AP   W     Z    LDZ  N   AUZ  NAUX
            |    |    |     |     |   |    |    |
CALL ZHPEV( 20 , AP , W , DUMMY , 1 , 4 , AUX , 12 )
 
AP       =  ((3.0, . ), (1.0, 0.0), (3.0, . ), (0.0, 0.0),
             (0.0, -2.0), (1.0, . ), (0.0, 2.0), (0.0, 0.0),
             (1.0, 0.0), (1.0, . ))

Output

        *           *
        | -0.828427 |
W    =  |  0.000000 |
        |  4.000000 |
        |  4.828427 |
        *           *

Example 7

This example shows how to find the eigenvalues and eigenvectors of a complex Hermitian matrix A of order 2, stored in lower-packed storage mode. Matrix A is:

                      *                         *
                      | (1.0, 0.0)  (1.0, -1.0) |
                      | (1.0, 1.0)  (1.0,  0.0) |
                      *                         *

where:

• NAUX is equal to 4N.
• AUX contains 4N elements.
• On output, AP has been overwritten.

Note:

This matrix is used in Example 6.2 in referenced text [63].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   AUZ  NAUX
            |    |    |   |   |   |    |    |
CALL ZHPEV( 1  , AP , W , Z , 2 , 2 , AUX , 8  )
 
AP       =  ((1.0, . ), (1.0, 1.0), (1.0, . ))

Output

        *           *
W    =  | -0.414214 |
        |  2.414214 |
        *           *

        *                                               *
Z    =  |  (0.500000, -0.500000)  (0.500000, -0.500000) |
        | (-0.707107,  0.000000)  (0.707107,  0.000000) |
        *                                               *