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

SGEEV, DGEEV, CGEEV, and ZGEEV--Eigenvalues and, Optionally, All or Selected Eigenvectors of a General Matrix

SGEEV and DGEEV compute the eigenvalues and, optionally, all or selected eigenvectors of real general matrix A. CGEEV and ZGEEV compute the eigenvalues and, optionally, all or selected eigenvectors of complex general matrix A. Eigenvalues are returned in complex vector w, and eigenvectors are returned in complex matrix Z:

Az = wz

Table 123. Data Types

Syntax

On Entry

iopt

indicates the type of computation to be performed, where:

If iopt = 0, eigenvalues only are computed.

If iopt = 1, eigenvalues and eigenvectors are computed.

If iopt = 2, eigenvalues and eigenvectors corresponding to selected eigenvalues are computed.

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

a

is the real or complex general matrix A of order n, whose eigenvalues and, optionally, eigenvectors are computed. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 123. On output, A is overwritten; that is, the original input is not preserved.

lda

is the leading dimension of the array specified for a. Specified as: a fullword integer; lda > 0 and lda >= n.

w

See On Return.

z

See On Return.

ldz

has the following meaning, where:

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

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

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

If iopt = 0, ldz > 0.

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

select

has the following meaning, where:

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

If iopt = 2, it is the logical vector select of length n whose true elements indicate those eigenvalues whose corresponding eigenvectors are to be computed.

Specified as: a one-dimensional array of (at least) length n, containing logical data items. Element values can be true (.TRUE.) or false (.FALSE.).

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 123. 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, SGEEV, DGEEV, CGEEV, and ZGEEV 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 SGEEV and DGEEV:

If iopt = 0, naux >= n.

If iopt = 1, naux >= 2n.

If iopt = 2,

naux >= n²+4n.

For CGEEV and ZGEEV:

If iopt = 0, naux >= 2n.

If iopt = 1, naux >= 3n.

If iopt = 2, naux >= 2n²+5n.

On Return

w

is the vector w of length n, containing the eigenvalues of A. The eigenvalues are unordered. For SGEEV and DGEEV, complex conjugate pairs appear consecutively with the eigenvalue having the positive imaginary part first.

Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 123.

z

has the following meaning, where:

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

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

If iopt = 2, it is the n by m matrix Z, containing the m eigenvectors of matrix A, which correspond to the m selected eigenvalues in w_i,

where m is the number of true elements in the logical vector select. The eigenvector in column i of matrix Z corresponds to the i-th selected eigenvalue. Any eigenvector that does not converge is set to 0.

Returned as: a two-dimensional array, containing numbers of the data type indicated in Table 123, where:

If iopt = 1, the array must be ldz by (at least) n.

If iopt = 2, the array must be ldz by (at least) m.

Notes

1. When you specify iopt = 0, you must also specify:
   • A positive value for ldz
   • A dummy argument for z (see Example 1)
   • A dummy argument for select.
2. When you specify iopt = 1, you must also specify a dummy argument for select.
3. The following items must have no common elements: matrix A, matrix Z, vector w, vector select, and the data area specified for aux; otherwise, results are unpredictable. See Concepts.
4. 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 eigenvectors and eigenvalues for either a real general matrix or a complex general matrix. For more information on these methods, see references [39], [43], [45], [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 the examples for an illustration of the difference in the results.

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 General Matrix

The eigenvalues and, optionally, all or selected eigenvectors of a real general matrix A are computed as follows.

• For iopt = 0, the eigenvalues are computed as follows:
  1. Balance the real general matrix A.
  2. Reduce the balanced matrix to a real upper Hessenberg matrix using orthogonal similarity transformations.
  3. Compute the eigenvalues of the real upper Hessenberg matrix using the QR algorithm.
  4. The eigenvalues are returned in vector w.
• For iopt = 1, the eigenvalues and eigenvectors are computed as follows:
  1. Balance the real general matrix A.
  2. Reduce the balanced matrix to a real upper Hessenberg matrix using orthogonal similarity transformations.
  3. Accumulate the orthogonal similarity transformations used in the reduction of the real balanced matrix to upper Hessenberg form.
  4. Compute the eigenvalues of the real upper Hessenberg matrix and the eigenvectors of the corresponding real balanced matrix using the QR algorithm.
  5. Back transform the eigenvectors of the balanced matrix to the eigenvectors of the original matrix.
  6. The eigenvalues are returned in vector w, and the eigenvectors are returned in matrix Z.
• For iopt = 2, the eigenvalues and selected eigenvectors are computed as follows:
  1. Balance the real general matrix A.
  2. Reduce the balanced matrix to a real upper Hessenberg matrix using orthogonal similarity transformations.
  3. Compute the eigenvalues of the real upper Hessenberg matrix using the QR algorithm.
  4. Compute the eigenvectors of the real upper Hessenberg matrix corresponding to selected eigenvalues, indicated in the logical vector select, using inverse iteration.
  5. Back transform the eigenvectors of the real upper Hessenberg matrix to the eigenvectors of the balanced matrix.
  6. Back transform the eigenvectors of the balanced matrix to the eigenvectors of the original matrix.
  7. The eigenvalues are returned in vector w, and the eigenvectors are returned in matrix Z.

Complex General Matrix

The eigenvalues and, optionally, all or selected eigenvectors of a complex general matrix A are computed as follows.

• For iopt = 0, the eigenvalues are computed as follows:
  1. Balance the complex general matrix A.
  2. Reduce the complex balanced matrix to a complex upper Hessenberg matrix using unitary similarity transformations.
  3. Compute the eigenvalues of the complex upper Hessenberg matrix using a QR algorithm with implicit shift.
  4. The eigenvalues are returned in vector w.
• For iopt = 1, the eigenvalues and eigenvectors are computed as follows:
  1. Balance the complex general matrix A.
  2. Reduce the complex balanced matrix to a complex upper Hessenberg matrix using unitary similarity transformations.
  3. Accumulate the unitary similarity transformations used in the reduction of the complex balanced matrix to complex upper Hessenberg form.
  4. Compute the eigenvalues of the complex upper Hessenberg matrix and the eigenvectors of the complex balanced matrix using a QR algorithm with implicit shift.
  5. Back transform the eigenvectors of the complex balanced matrix to the eigenvectors of the original matrix.
  6. The eigenvalues are returned in vector w, and the eigenvectors are returned in matrix Z.
• For iopt = 2, the eigenvalues and selected eigenvectors are computed as follows:
  1. Balance the complex general matrix A.
  2. Reduce the complex balanced matrix to a complex upper Hessenberg matrix using unitary similarity transformations.
  3. Compute the eigenvalues of the complex upper Hessenberg matrix using a QR algorithm with implicit shift.
  4. Compute the eigenvectors of the complex upper Hessenberg matrix corresponding to selected eigenvalues, indicated in the logical vector select, using inverse iteration.
  5. Back transform the eigenvectors of the complex upper Hessenberg matrix to the eigenvectors of the complex balanced matrix.
  6. Back transform the eigenvectors of the complex balanced matrix to the eigenvectors of the original matrix.
  7. The eigenvalues are returned in vector w, and the eigenvectors are returned in matrix Z.

Error Conditions

Resource Errors

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

Computational Errors

1. Eigenvalue (i) failed to converge after (xxx) iterations.
   • The eigenvalues (w_j, j = n, n-1, ..., i+1) are correct.
   • If iopt = 1, then z is modified, but no eigenvectors are correct.
   • a 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?.
2. Eigenvector (yyy) failed to converge after (zzz) iterations. (The computational error message may occur multiple times with processing continuing after each error, because the number of allowable errors for error code 2102 is set to be unlimited in the ESSL error option table.)
   • All eigenvalues are correct.
   • The eigenvector that failed to converge is set to 0.
   • Any selected eigenvectors for which this message has not been issued are correct.
   • a is modified.
   • The return code is set to 2.
   • yyy and zzz for the last eigenvector that failed to converge 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 2199 in the ESSL error option table. See What Can You Do about ESSL Computational Errors?.

Input-Argument Errors

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

Example 1

This example shows how to find the eigenvalues only of a real short-precision general matrix A of order 4, where:

• NAUX is equal to N.
• AUX contains N elements.
• LDZ is set to avoid an error condition.
• DUMMY1 and DUMMY2 are used as placeholders for arguments z and select, which are not used in the computation.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W     Z     LDZ  SELECT   N   AUX  NAUX
            |    |   |   |     |      |     |      |    |    |
CALL SGEEV( 0  , A , 4 , W , DUMMY1 , 1 , DUMMY2 , 4 , AUX , 4  )
 
        *                     *
        | -2.0  2.0  2.0  2.0 |
A    =  | -3.0  3.0  2.0  2.0 |
        | -2.0  0.0  4.0  2.0 |
        | -1.0  0.0  0.0  5.0 |
        *                     *

Output

        *                       *
        | (0.999999,  0.000000) |
W    =  | (2.000001,  0.000000) |
        | (2.999996,  0.000000) |
        | (3.999999,  0.000000) |
        *                       *

Example 2

This example shows how to find the eigenvalues and eigenvectors of a real short-precision general matrix A of order 3, where:

• NAUX is equal to 2N.
• AUX contains 2N elements.
• DUMMY is used as a placeholder for argument select, which is not used in the computation.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT  N   AUX  NAUX
            |    |   |   |   |   |     |     |    |    |
CALL SGEEV( 1  , A , 3 , W , Z , 3 , DUMMY , 3 , AUX , 6  )
 
        *                     *
        |  33.0   16.0   72.0 |
A    =  | -24.0  -10.0  -57.0 |
        |  -8.0   -4.0  -17.0 |
        *                     *

Output

        *                      *
        | (3.000022, 0.000000) |
W    =  | (1.000019, 0.000000) |
        | (1.999961, 0.000000) |
        *                      *
 
        *                                                                         *
        |  (2.498781, 0.000000)   (76.837608,  0.000000)   (79.999451,  0.000000) |
Z    =  | (-1.874081, 0.000000)  (-61.470169,  0.000000)  (-64.999649,  0.000000) |
        | (-0.624695, 0.000000)  (-20.489990,  0.000000)  (-19.999886,  0.000000) |
        *                                                                         *

Example 3

This example shows how to find the eigenvalues and eigenvectors of a real short-precision general matrix A of order 3, where:

• NAUX is equal to 2N.
• AUX contains 2N elements.
• DUMMY is used as a placeholder for argument select, which is not used in the computation.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT  N   AUX  NAUX
            |    |   |   |   |   |     |     |    |    |
CALL SGEEV( 1  , A , 3 , W , Z , 3 , DUMMY , 3 , AUX , 6  )
 
        *                  *
        |  8.0  -1.0  -5.0 |
A    =  | -4.0   4.0  -2.0 |
        | 18.0  -5.0  -7.0 |
        *                  *

Output

        *                       *
        | (1.999999,  3.999998) |
W    =  | (1.999999, -3.999998) |
        | (0.999997,  0.000000) |
        *                       *
 
        *                                                                     *
        |  (0.044710, 0.410578)   (0.044710, -0.410578)  (1.732048, 0.000000) |
Z    =  | (-0.365868, 0.455287)  (-0.365868, -0.455287)  (3.464096, 0.000000) |
        |  (0.455287, 0.365868)   (0.455287, -0.365868)  (1.732049, 0.000000) |
        *                                                                     *

Example 4

This example shows how to find the eigenvalues and selected eigenvectors of a real short-precision general matrix A of order 4, where:

• NAUX is equal to N²+4N.
• AUX contains NAUX elements.
• The first, third, and fourth eigenvectors are selected and appear in the first, second, and third columns of matrix Z, respectively.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT   N   AUX  NAUX
            |    |   |   |   |   |     |      |    |    |
CALL SGEEV( 2  , A , 4 , W , Z , 4 , SELECT , 4 , AUX , 32 )

        *                     *
        | -2.0  2.0  2.0  2.0 |
A    =  | -3.0  3.0  2.0  2.0 |
        | -2.0  0.0  4.0  2.0 |
        | -1.0  0.0  0.0  5.0 |
        *                     *

           *         *
           | .TRUE.  |
SELECT =   | .FALSE. |
           | .TRUE.  |
           | .TRUE.  |
           *         *

Output

        *                       *
        | (0.999999,  0.000000) |
W    =  | (2.000001,  0.000000) |
        | (2.999996,  0.000000) |
        | (3.999999,  0.000000) |
        *                       *

        *                                                                    *
        | (1.000000, 0.000000)  (-0.674014, 0.000000)  (-0.474306, 0.000000) |
Z    =  | (0.750000, 0.000000)  (-0.674014, 0.000000)  (-0.474306, 0.000000) |
        | (0.500000, 0.000000)  (-0.674013, 0.000000)  (-0.474306, 0.000000) |
        | (0.250000, 0.000000)  (-0.337006, 0.000000)  (-0.474305, 0.000000) |
        *                                                                    *

Example 5

This example shows how to find the eigenvalues and selected eigenvectors of a real short-precision general matrix A of order 3, where:

• NAUX is equal to N²+4N.
• AUX contains NAUX elements.
• The first and second eigenvectors are selected and appear in the first and second columns of matrix Z, respectively.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT   N   AUX  NAUX
            |    |   |   |   |   |     |      |    |    |
CALL SGEEV( 2  , A , 3 , W , Z , 3 , SELECT , 3 , AUX , 21 )

        *                  *
        |  8.0  -1.0  -5.0 |
A    =  | -4.0   4.0  -2.0 |
        | 18.0  -5.0  -7.0 |
        *                  *

          *         *
          | .TRUE.  |
SELECT =  | .TRUE.  |
          | .FALSE. |
          *         *

Output

        *                       *
        | (1.999999,  3.999998) |
W    =  | (1.999999, -3.999998) |
        | (0.999997,  0.000000) |
        *                       *

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

Example 6

This example shows how the results of Example 5 would differ if matrix A was a real long-precision general matrix. On output, A has been overwritten.

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT   N   AUX  NAUX
            |    |   |   |   |   |     |      |    |    |
CALL DGEEV( 2  , A , 3 , W , Z , 3 , SELECT , 3 , AUX , 21 )

Output

        *                       *
        | (2.000000,  4.000000) |
W    =  | (2.000000, -4.000000) |
        | (1.000000,  0.000000) |
        *                       *

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

Example 7

This example shows how to find the eigenvalues only of a complex long-precision general matrix A of order 3, where:

• NAUX is equal to 2N.
• AUX contains 2N elements.
• LDZ is set to avoid an error condition.
• DUMMY1 and DUMMY2 are used as placeholders for arguments z and select, which are not used in the computation.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W     Z     LDZ  SELECT   N   AUX  NAUX
            |    |   |   |     |      |     |      |    |    |
CALL ZGEEV( 0  , A , 3 , W , DUMMY1 , 1 , DUMMY2 , 3 , AUX , 6  )
 
        *                                          *
        |  (1.0,  2.0)   (3.0,  4.0)  (21.0, 22.0) |
A    =  | (43.0, 44.0)  (13.0, 14.0)  (15.0, 16.0) |
        |  (5.0,  6.0)   (7.0,  8.0)  (25.0, 26.0) |
        *                                          *

Output

        *                        *
        | (39.776655, 42.995668) |
W    =  | (-7.477530,  6.880321) |
        |  (6.700876, -7.875989) |
        *                        *

Example 8

This example shows how to find the eigenvalues and eigenvectors of a complex long-precision general matrix A of order 4, where:

• NAUX is equal to 3N.
• AUX contains 3N elements.
• DUMMY is used as a placeholder for argument select, which is not used in the computation.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT  N   AUX  NAUX
            |    |   |   |   |   |     |     |    |    |
CALL ZGEEV( 1  , A , 4 , W , Z , 4 , DUMMY , 4 , AUX , 12 )
 
        *                                                     *
        | (5.0, 9.0)  (5.0,  5.0)  (-6.0, -6.0)  (-7.0, -7.0) |
A    =  | (3.0, 3.0)  (6.0, 10.0)  (-5.0, -5.0)  (-6.0, -6.0) |
        | (2.0, 2.0)  (3.0,  3.0)  (-1.0,  3.0)  (-5.0, -5.0) |
        | (1.0, 1.0)  (2.0,  2.0)  (-3.0, -3.0)   (0.0,  4.0) |
        *                                                     *

Output

        *                      *
        | (4.000000, 8.000000) |
W    =  | (2.000000, 6.000000) |
        | (3.000000, 7.000000) |
        | (1.000000, 5.000000) |
        *                      *

        *                                                                                          *
        | (0.625817, 0.229776)  (0.333009, -0.729358)  (-1.535458, 1.519551)  (0.000000, 3.464102) |
Z    =  | (0.625817, 0.229776)  (0.666017, -1.458715)  (-1.535458, 1.519551)  (0.000000, 1.732051) |
        | (0.625817, 0.229776)  (0.333009, -0.729358)  ( 0.000000, 0.000000)  (0.000000, 1.732051) |
        | (0.000000, 0.000000)  (0.333009, -0.729358)  (-1.535458, 1.519551)  (0.000000, 1.732051) |
        *                                                                                          *

Example 9

This example shows how to find the eigenvalues and selected eigenvectors of a complex long-precision general matrix A of order 4, where:

• NAUX is equal to 2N²+5N.
• AUX contains NAUX elements.
• The first, third, and fourth eigenvectors are selected and appear in the first, second, and third columns of matrix Z, respectively.
• On output, A has been overwritten.

Note:

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

Call Statement and Input

           IOPT  A  LDA  W   Z  LDZ  SELECT   N   AUX  NAUX
            |    |   |   |   |   |     |      |    |    |
CALL ZGEEV( 2  , A , 4 , W , Z , 4 , SELECT , 4 , AUX , 52 )

        *                                                     *
        | (5.0, 9.0)  (5.0,  5.0)  (-6.0, -6.0)  (-7.0, -7.0) |
A    =  | (3.0, 3.0)  (6.0, 10.0)  (-5.0, -5.0)  (-6.0, -6.0) |
        | (2.0, 2.0)  (3.0,  3.0)  (-1.0,  3.0)  (-5.0, -5.0) |
        | (1.0, 1.0)  (2.0,  2.0)  (-3.0, -3.0)   (0.0,  4.0) |
        *                                                     *

          *         *
          | .TRUE.  |
SELECT =  | .FALSE. |
          | .TRUE.  |
          | .TRUE.  |
          *         *

Output

        *                      *
        | (4.000000, 8.000000) |
W    =  | (2.000000, 6.000000) |
        | (3.000000, 7.000000) |
        | (1.000000, 5.000000) |
        *                      *

        *                                                                      *
        | (-0.748331, 0.000000)  (-0.935414, 0.000000)  (-1.247219, 0.000000) |
Z    =  | (-0.748331, 0.000000)  (-0.935414, 0.000000)  (-0.623610, 0.000000) |
        | (-0.748331, 0.000000)   (0.000000, 0.000000)  (-0.623610, 0.000000) |
        |  (0.000000, 0.000000)  (-0.935414, 0.000000)  (-0.623610, 0.000000) |
        *                                                                      *