Guide and Reference

Performance and Accuracy Considerations

The accuracy of the resulting eigenvalues and eigenvectors varies between the short- and long-precision versions of each subroutine. The degree of difference depends on the size and conditioning of the matrix computation. Some of the subroutines have examples illustrating this difference.
The short precision subroutines provide increased accuracy by accumulating intermediate results in long precision. Occasionally, for performance reasons, these intermediate results are stored.
If you want to compute 10% or fewer eigenvalues only, or you want to compute 30% or fewer eigenvalues and eigenvectors, you get better performance if you use _SPSV and _HPSV instead of _SPEV and _HPEV, respectively. For all other uses, you should use _SPEV and _HPEV.
There are some ESSL-specific rules that apply to the results of computations on the workstation processors using the ANSI/IEEE standards. For details, see "What Data Type Standards Are Used by ESSL, and What Exceptions Should You Know About?".

Eigensystem Analysis Subroutines

This section contains the eigensystem analysis subroutine

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 118. Data Types

A w, Z aux Subroutine
Short-precision real Short-precision complex Short-precision real SGEEV
Long-precision real Long-precision complex Long-precision real DGEEV
Short-precision complex Short-precision complex Short-precision real CGEEV
Long-precision complex Long-precision complex Long-precision real ZGEEV

A	w, Z	`aux`	Subroutine
Short-precision real	Short-precision complex	Short-precision real	SGEEV
Long-precision real	Long-precision complex	Long-precision real	DGEEV
Short-precision complex	Short-precision complex	Short-precision real	CGEEV
Long-precision complex	Long-precision complex	Long-precision real	ZGEEV

Syntax

Fortran	CALL SGEEV \| DGEEV \| CGEEV \| ZGEEV (`iopt`, `a`, `lda`, `w`, `z`, `ldz`, `select`, `n`, `aux`, `naux`)
C and C++	sgeev \| dgeev \| cgeev \| zgeev (`iopt`, `a`, `lda`, `w`, `z`, `ldz`, `select`, `n`, `aux`, `naux`);
PL/I	CALL SGEEV \| DGEEV \| CGEEV \| ZGEEV (`iopt`, `a`, `lda`, `w`, `z`, `ldz`, `select`, `n`, `aux`, `naux`);

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 118. 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 118. 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 118.

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 118, 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

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.
When you specify iopt = 1, you must also specify a dummy argument for select.
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".
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], [60], [81], [91], and [93]. 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

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?".
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

iopt <> 0, 1, or 2
n < 0
lda <= 0
n > lda
ldz <= 0 and iopt <> 0
n > ldz and iopt <> 0
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 [60].

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 [60].

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 [60].

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 [60].

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 [60].

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 [60].

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 [60].

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 [60].

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) |
        *                                                                     *

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 119. Data Types

A, z w, aux Subroutine
Short-precision real Short-precision real SSPEV
Long-precision real Long-precision real DSPEV
Short-precision complex Short-precision real CHPEV
Long-precision complex Long-precision real ZHPEV

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

Fortran	CALL SSPEV \| DSPEV \| CHPEV \| ZHPEV (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `aux`, `naux`)
C and C++	sspev \| dspev \| chpev \| zhpev (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `aux`, `naux`);
PL/I	CALL SSPEV \| DSPEV \| CHPEV \| ZHPEV (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `aux`, `naux`);

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 119. 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 119. 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 119.

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 119.

Notes

When you specify iopt = 0 or 20, you must specify:
- A positive value for ldz
- A dummy argument for z (see "Example 1")
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".
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.
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".
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], [60], [81], [91], and [93]. 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

iopt <> 0, 1, 20, or 21
n < 0
ldz <= 0 and iopt = 1 or 21
n > ldz and iopt = 1 or 21
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 [60].

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 [60].

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 [60].

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 [60].

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 [60].

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) |
        *                                               *

SSPSV, DSPSV, CHPSV, and ZHPSV--Extreme Eigenvalues and, Optionally, the Eigenvectors of a Real Symmetric Matrix or a Complex Hermitian Matrix

SSPSV and DSPSV compute the extreme eigenvalues and, optionally, the eigenvectors of real symmetric matrix A, stored in lower- or upper-packed storage mode. CHPSV and ZHPSV compute the extreme eigenvalues and, optionally, the eigenvectors of complex Hermitian matrix A, stored in lower- or upper-packed storage mode. The extreme eigenvalues are returned in vector w, and the corresponding eigenvectors are returned in matrix Z:

Az = wz

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

Table 120. Data Types

A, z w, aux Subroutine
Short-precision real Short-precision real SSPSV
Long-precision real Long-precision real DSPSV
Short-precision complex Short-precision real CHPSV
Long-precision complex Long-precision real ZHPSV

Note: If you want to compute 10% or fewer eigenvalues only, or you want to compute 30% or fewer eigenvalues and eigenvectors, you get better performance if you use _SPSV and _HPSV instead of _SPEV and _HPEV, respectively. For all other uses, you should use _SPEV and _HPEV.

Syntax

Fortran	CALL SSPSV \| DSPSV \| CHPSV \| ZHPSV (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `m`, `aux`, `naux`)
C and C++	sspsv \| dspsv \| chpsv \| zhpsv (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `m`, `aux`, `naux`);
PL/I	CALL SSPSV \| DSPSV \| CHPSV \| ZHPSV (`iopt`, `ap`, `w`, `z`, `ldz`, `n`, `m`, `aux`, `naux`);

On Entry

iopt

indicates the type of computation to be performed, where:

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

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

If iopt = 10 or 30, the m largest eigenvalues only are computed.

If iopt = 11 or 31, the m largest eigenvalues and the eigenvectors are computed.

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

ap

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

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

If iopt = 20, 21, 30, or 31, 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 120. On output, 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, 10, 20, or 30, it is not used in the computation.

If iopt = 1, 11, 21, or 31, 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, 10, 20, or 30, ldz > 0.

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

n

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

m

is the number of eigenvalues and, optionally, eigenvectors to be computed. Specified as: a fullword integer; 0 <= m <= n.

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 120. 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, SSPSV, DSPSV, CHPSV, and ZHPSV 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 SSPSV and DSPSV:

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

If iopt = 1, 11, 21, or 31, naux >= 9n.

For CHPSV and ZHPSV:

If iopt = 0, 10, 20, or 30, naux >= 5n.

If iopt = 1, 11, 21, or 31, naux >= 11n.

On Return

w

is the vector w of length n, containing in the first m positions of either the m smallest eigenvalues of A in ascending order or the m largest eigenvalues of A in descending order.

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

z

has the following meaning, where:

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

If iopt = 1, 11, 21, or 31, it is the n by m matrix Z, containing m 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) m array, containing numbers of the data type indicated in Table 120.

Notes

When you specify iopt = 0, 10, 20, or 30, you must specify:
- A positive value for ldz
- A dummy argument for z (see "Example 4")
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".
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.
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".
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 methods used to compute the extreme eigenvalues and, optionally, the eigenvectors for either a real symmetric matrix or a complex Hermitian matrix are described in the steps below. For more information on these methods, see references [39], [43], [60], [81], [91], and [93]. If n or m is 0, no computation is performed. The results of the computations using short- and long-precision data can vary in accuracy. 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.

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

For iopt = 0, 10, 20, or 30, the eigenvalues are computed as follows:
1. Reduce the real symmetric matrix A (for SSPSV and DSPSV) or complex Hermitian matrix A (for CHPSV and ZHPSV) to a real symmetric tridiagonal matrix using orthogonal similarity transformations (for SSPSV and DSPSV) or unitary similarity transforms (for CHPSV and ZHPSV).
2. Compute the m smallest eigenvalues or m largest eigenvalues of the real symmetric tridiagonal matrix using a rational variant of the QR method with Newton corrections.
3. The eigenvalues are returned in vector w in the first m positions, where the m smallest are placed in ascending order, or the m largest are placed in descending order.
For iopt = 1, 11, 21, or 31, the eigenvalues and eigenvectors are computed as follows:
1. Reduce the real symmetric matrix A (for SSPSV and DSPSV) or complex Hermitian matrix A (for CHPSV and ZHPSV) to a real symmetric tridiagonal matrix using orthogonal similarity transformations (for SSPSV and DSPSV) or unitary similarity transforms (for CHPSV and ZHPSV).
2. Compute the m smallest eigenvalues or m largest eigenvalues of the real symmetric tridiagonal matrix using a rational variant of the QR method with Newton corrections.
3. Compute the corresponding eigenvectors of the real symmetric tridiagonal matrix using inverse iteration.
4. Back transform the eigenvectors of the real symmetric tridiagonal matrix to those of the original matrix.
5. The eigenvalues are returned in vector w in the first m positions, where the m smallest are placed in ascending order, or the m largest are placed in descending order. 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 computational error message may occur multiple times with processing continuing after each error, because the number of allowable errors for error code 2114 is set to be unlimited in the ESSL error option table.)
- The eigenvalue, w_i, is the best estimate obtained. Any eigenvalues for which this message has not been issued are correct.
- 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 2199 in the ESSL error option table. See "What Can You Do about ESSL Computational Errors?".
Eigenvector (i) failed to converge after (xxx) 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 zero; however, any selected eigenvectors for which this message is not issued are correct.
- ap is modified.
- The return code is set to 2.
- 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 2199 in the ESSL error option table. See "What Can You Do about ESSL Computational Errors?".

Input-Argument Errors

iopt <> 0, 1, 10, 11, 20, 21, 30, or 31
n < 0
m < 0
m > n
ldz <= 0 and iopt = 1, 11, 21, or 31
n > ldz and iopt = 1, 11, 21, or 31
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 two smallest eigenvalues and corresponding eigenvectors of a real long-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 9N.
AUX contains 9N elements.
On output, AP has been overwritten.

Note: This matrix is used in Example 4.1 in referenced text [60].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   M   AUX  NAUX
            |    |    |   |   |   |   |    |    |
CALL DSPSV( 21 , AP , W , Z , 4 , 4 , 2 , AUX , 36 )
 
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 |
        |  .       |
        |  .       |
        *          *

        *                      *
        | -0.707107   0.000000 |
Z    =  |  0.707107   0.000000 |
        |  0.000000  -0.707107 |
        |  0.000000   0.707107 |
        *                      *

Example 2

This example shows how to find the three largest eigenvalues and corresponding eigenvectors of a real long-precision symmetric matrix A of order 4, stored in lower-packed storage mode, having an eigenvalue of multiplicity two. 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 9N.
AUX contains 9N elements.
On output, AP has been overwritten.

Note: This matrix is used in Example 4.2 in referenced text [60].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   M   AUX  NAUX
            |    |    |   |   |   |   |    |    |
CALL DSPSV( 11 , AP , W , Z , 8 , 4 , 3 , AUX , 36 )
 
AP       =  (6.0, 4.0, 4.0, 1.0, 6.0, 1.0, 4.0, 6.0, 4.0, 6.0)

Output

        *           *
        | 15.000000 |
W    =  |  5.000000 |
        |  5.000000 |
        |   .       |
        *           *

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

Example 3

This example shows how to find the largest eigenvalue and the corresponding eigenvector 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 11N.
AUX contains 11N elements.
On output, AP has been overwritten.

Note: This matrix is used in Example 6.1 in referenced text [60].

Call Statement and Input

           IOPT  AP   W   Z  LDZ  N   M   AUX  NAUX
            |    |    |   |   |   |   |    |    |
CALL ZHPSV( 11 , AP , W , Z , 2 , 2 , 1 , AUX , 22 )
 
AP       =  ((1.0, . ), (0.0, 1.0), (1.0, . ))

Output

        *          *
W    =  | 2.000000 |
        |  .       |
        *          *

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

Example 4

This example shows how to find the two smallest 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 5N.
AUX contains 5N 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 [60].

Call Statement and Input

           IOPT  AP   W     Z    LDZ  N   M   AUX  NAUX
            |    |    |     |     |   |   |    |    |
CALL ZHPSV( 20 , AP , W , DUMMY , 1 , 4 , 2 , AUX , 20 )
 
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 |
        |   .       |
        |   .       |
        *           *

SGEGV and DGEGV--Eigenvalues and, Optionally, the Eigenvectors of a Generalized Real Eigensystem, Az=wBz, where A and B Are Real General Matrices

These subroutines compute the eigenvalues and, optionally, the eigenvectors of a generalized real eigensystem, where A and B are real general matrices. Eigenvalues w are based on the two parts returned in vectors alpha and beta, such that w_i = alpha_i/beta_i for beta_i <> 0, and w_i = infinity for beta_i = 0. Eigenvectors are returned in matrix Z:

Az = wBz

Table 121. Data Types

A, B, beta, aux alpha, Z Subroutine
Short-precision real Short-precision complex SGEGV
Long-precision real Long-precision complex DGEGV

Syntax

Fortran	CALL SGEGV \| DGEGV (`iopt`, `a`, `lda`, `b`, `ldb`, `alpha`, `beta`, `z`, `ldz`, `n`, `aux`, `naux`)
C and C++	sgegv \| dgegv (`iopt`, `a`, `lda`, `b`, `ldb`, `alpha`, `beta`, `z`, `ldz`, `n`, `aux`, `naux`);
PL/I	CALL SGEGV \| DGEGV (`iopt`, `a`, `lda`, `b`, `ldb`, `alpha`, `beta`, `z`, `ldz`, `n`, `aux`, `naux`);

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.

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

a

is the real general matrix A of order n. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 121. 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.

b

is the real general matrix B of order n. Specified as: an ldb by (at least) n array, containing numbers of the data type indicated in Table 121. On output, B is overwritten; that is, the original input is not preserved.

ldb

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

alpha

See 'On Return'.

beta

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, 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, ldz > 0.

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

n

is the order of matrices A and B. 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 121. 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, SGEGV and DGEGV dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, naux >= 3n.

On Return

alpha

is the vector alpha of length n, containing the numerators of the eigenvalues of the generalized real eigensystem Az = wBz. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 121.

beta

is the vector beta of length n, containing the denominators of the eigenvalues of the generalized real eigensystem Az = wBz. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 121.

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 the generalized real eigensystem, Az = wBz. The eigenvector in column i of matrix Z corresponds to the eigenvalue w_i, computed using the alpha_i and beta_i values. Each eigenvector is normalized so that the modulus of its largest element is 1.

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

Notes

When you specify iopt = 0, you must specify:
- A positive value for ldz
- A dummy argument for z (see "Example 1")
Matrices A, B, and Z, vectors alpha and beta, and the work area specified for aux must have no common elements; otherwise, results are unpredictable. See "Concepts".
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 following steps describe the methods used to compute the eigenvalues and, optionally, the eigenvectors of a generalized real eigensystem, Az = wBz, where A and B are real general matrices. The methods are based upon Moler and Stewart's QZ algorithm. You must calculate the resulting eigenvalues w based on the two parts returned in vectors alpha and beta. Each eigenvalue is calculated as follows: w_i = alpha_i/beta_i for beta_i <> 0 and w_i = infinity for beta_i = 0. Eigenvalues are unordered, except that complex conjugate pairs appear consecutively with the eigenvalue having the positive imaginary part first.

For iopt = 0, the eigenvalues are computed as follows:
1. Simultaneously reduce A to upper Hessenberg form and B to upper triangular form using orthogonal transformations.
2. Reduce A from upper Hessenberg form to quasi-upper triangular form while maintaining the upper triangular form of B using orthogonal transformations.
3. Compute the eigenvalues of the generalized real eigensystem with A in quasi-upper triangular form and B in upper triangular form using orthogonal transformations.
4. The numerators and denominators of the eigenvalues are returned in vectors alpha and beta, respectively.
For iopt = 1, the eigenvalues and eigenvectors are computed as follows:
1. Simultaneously reduce A to upper Hessenberg form and B to upper triangular form using and accumulating orthogonal transformations.
2. Reduce A from upper Hessenberg form to quasi-upper triangular form while maintaining the upper triangular form of B using and accumulating orthogonal transformations.
3. Compute the eigenvalues of the generalized real eigensystem with A in quasi-upper triangular form and B in upper triangular form using and accumulating orthogonal transformations.
4. Compute the eigenvectors of the generalized real eigensystem with A in quasi-upper triangular form and B in upper triangular form using back substitution.
5. The numerators and denominators of the eigenvalues are returned in vectors alpha and beta, respectively, and the eigenvectors are returned in matrix Z.

For more information on these methods, see references [39], [43], [55], [77], [60], [59], [81], [91], and [93]. If n is 0, no computation is performed. The results of the computations using short- and long-precision data can vary in accuracy.

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.

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 = i+1, i+2, ..., n) are correct.
If iopt = 1, then Z is modified, but no eigenvectors are correct.
A and B have been 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

iopt <> 0 or 1
n < 0
lda <= 0
n > lda
ldb <= 0
n > ldb
ldz <= 0 and iopt = 1
n > ldz and iopt = 1
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 generalized eigensystem problem, AZ = wBZ, 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, matrices A and B are overwritten.

Note: These matrices are from page 257 in referenced text [59].

Call Statement and Input

           IOPT  A  LDA  B  LDB  ALPHA   BETA     Z    LDZ  N   AUX  NAUX
            |    |   |   |   |     |      |       |     |   |    |    |
CALL DGEGV( 0  , A , 3 , B , 3 , ALPHA , BETA , DUMMY , 1 , 3 , AUX , 9  )

        *                 *
        | 10.0  1.0   2.0 |
A    =  |  1.0  3.0  -1.0 |
        |  1.0  1.0   2.0 |
        *                 *

        *               *
        | 1.0  2.0  3.0 |
B    =  | 4.0  5.0  6.0 |
        | 7.0  8.0  9.0 |
        *               *

Output

         *                       *
         |  (4.778424, 0.000000) |
ALPHA =  | (-4.760580, 0.000000) |
         |  (2.769466, 0.000000) |
         *                       *

         *           *
         |  0.000000 |
BETA  =  |  0.934851 |
         | 15.446215 |
         *           *

Example 2

This example shows how to find the eigenvalues and eigenvectors of a real generalized eigensystem problem, AZ = wBZ, where:

NAUX is equal to 3N.
AUX contains 3N elements.
On output, matrices A and B are overwritten.

Note: These matrices are from page 263 in referenced text [59].

Call Statement and Input

           IOPT  A  LDA  B  LDB  ALPHA   BETA   Z  LDZ  N   AUX  NAUX
            |    |   |   |   |     |      |     |   |   |    |    |
CALL DGEGV( 1  , A , 5 , B , 5 , ALPHA , BETA , Z , 5 , 5 , AUX , 15 )

        *                          *
        | 2.0  3.0  4.0  5.0   6.0 |
        | 4.0  4.0  5.0  6.0   7.0 |
A    =  | 0.0  3.0  6.0  7.0   8.0 |
        | 0.0  0.0  2.0  8.0   9.0 |
        | 0.0  0.0  0.0  1.0  10.0 |
        *                          *

        *                             *
        | 1.0  -1.0  -1.0  -1.0  -1.0 |
        | 0.0   1.0  -1.0  -1.0  -1.0 |
B    =  | 0.0   0.0   1.0  -1.0  -1.0 |
        | 0.0   0.0   0.0   1.0  -1.0 |
        | 0.0   0.0   0.0   0.0   1.0 |
        *                             *

Output

         *                       *
         |  (7.950050, 0.000000) |
         | (-0.277338, 0.000000) |
ALPHA =  |  (2.149669, 0.000000) |
         |  (6.720718, 0.000000) |
         | (10.987556, 0.000000) |
         *                       *

         *          *
         | 0.374183 |
         | 1.480299 |
BETA  =  | 1.636872 |
         | 1.213574 |
         | 0.908837 |
         *          *

        *
        | (1.000000, 0.000000)  (-0.483408, 0.000000)   (0.540696, 0.000000)
        | (0.565497, 0.000000)   (1.000000, 0.000000)   (0.684441, 0.000000)
Z    =  | (0.180429, 0.000000)  (-0.661372, 0.000000)  (-1.000000, 0.000000)
        | (0.034182, 0.000000)   (0.180646, 0.000000)   (0.363671, 0.000000)
        | (0.003039, 0.000000)  (-0.017732, 0.000000)  (-0.041865, 0.000000)
        *
                                                                      *
                          (1.000000, 0.000000)  (-1.000000, 0.000000) |
                          (0.722065, 0.000000)  (-0.610415, 0.000000) |
                         (-0.089003, 0.000000)  (-0.116987, 0.000000) |
                         (-0.223599, 0.000000)   (0.038979, 0.000000) |
                          (0.050111, 0.000000)   (0.018653, 0.000000) |
                                                                      *

SSYGV and DSYGV--Eigenvalues and, Optionally, the Eigenvectors of a Generalized Real Symmetric Eigensystem, Az=wBz, where A Is Real Symmetric and B Is Real Symmetric Positive Definite

These subroutines compute the eigenvalues and, optionally, the eigenvectors of a generalized real symmetric eigensystem, where A is a real symmetric matrix, and B is a real positive definite symmetric matrix. Both A and B are stored in lower storage mode in two-dimensional arrays. Eigenvalues are returned in vector w, and eigenvectors are returned in matrix Z:

Az = wBz

where A = A^T, B = B^T, and x^TBx > 0.

Table 122. Data Types

A, B, w, Z, aux Subroutine
Short-precision real SSYGV
Long-precision real DSYGV

Syntax

Fortran	CALL SSYGV \| DSYGV (`iopt`, `a`, `lda`, `b`, `ldb`, `w`, `z`, `ldz`, `n`, `aux`, `naux`)
C and C++	ssygv \| dsygv (`iopt`, `a`, `lda`, `b`, `ldb`, `w`, `z`, `ldz`, `n`, `aux`, `naux`);
PL/I	CALL SSYGV \| DSYGV (`iopt`, `a`, `lda`, `b`, `ldb`, `w`, `z`, `ldz`, `n`, `aux`, `naux`);

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.

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

a

is the real symmetric matrix A of order n. It is stored in lower storage mode. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 122. On output, the data in the lower triangle of 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.

b

is the real positive definite symmetric matrix B of order n. It is stored in lower storage mode. Specified as: an ldb by (at least) n array, containing numbers of the data type indicated in Table 122. On output, the data in the lower triangle of B is overwritten; that is, the original input is not preserved.

ldb

is the leading dimension of the array specified for b. Specified as: a fullword integer; ldb > 0 and ldb >= 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, 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, ldz > 0.

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

n

is the order of matrices A and B. 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 122. 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, SSYGV and DSYGV 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:

If iopt = 0, naux >= n.

If iopt = 1, naux >= 2n.

On Return

w

is the vector w of length n, containing the eigenvalues of the generalized real symmetric eigensystem Az = wBz in ascending order. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 122.

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 the generalized real symmetric eigensystem, Az = wBz. The eigenvectors are normalized so that Z^TBZ = I. 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 122.

Notes

When you specify iopt = 0, you must specify:
- A positive value for ldz
- A dummy argument for z (see "Example 1")
Matrices A and Z may coincide. Matrices A and B, vector w, and the data area specified for aux must have no common elements; otherwise, results are unpredictable. Matrices Z and B, vector w, and the data area specified for aux must also have no common elements; otherwise, results are unpredictable. See "Concepts".
For a description of how real symmetric matrices are stored in lower storage mode, see "Lower Storage Mode".
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 following steps describe the methods used to compute the eigenvalues and, optionally, the eigenvectors of a generalized real symmetric eigensystem, Az = wBz, where A is a real symmetric matrix, and B is a real positive definite symmetric matrix. Both A and B are stored in lower storage mode in two-dimensional arrays.

Compute the Cholesky Decomposition of B:

B = LL^T

For a description of methods used in this computation, see SPPF, DPPF, SPOF, DPOF, CPOF, and ZPOF--Positive Definite Real Symmetric or Complex Hermitian Matrix Factorization.
Compute C:

C = L^-1AL^-T

In this computation, C overwrites A.
Solve the real symmetric eigensystems analysis problem, computing the eigenvalues w and, optionally, the eigenvectors Y:

CY = wY

where:

Y = L^TZ

For a description of the methods used for this computation, see "Real Symmetric Matrix". In this computation, Y overwrites Z.
If eigenvectors are requested (with iopt = 1), transform the eigenvectors Y into the eigenvectors Z of the original system, Az = wBz, by solving L^TZ = Y for Z:

Z = L^-TY

For more information on these methods, see references [39], [43], [55], [60], [59], [81], [91], and [93]. If n is 0, no computation is performed. The results of the computations using short- and long-precision data can vary in accuracy.

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.

Error Conditions

Resource Errors

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

Computational Errors

The B matrix is not positive definite. The leading minor of order i has a nonpositive determinant.
- B is modified, but no eigenvalues or eigenvectors are correct.
- The return code is set to 1.
- i 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 2115 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?".
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, then z is modified, but no eigenvectors are correct.
- A and B have been modified.
- The return code is set to 2.
- 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

iopt <> 0 or 1
n < 0
lda <= 0
n > lda
ldb <= 0
n > ldb
ldz <= 0 and iopt = 1
n > ldz and iopt = 1
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 symmetric generalized eigensystem problem, AZ = wBZ, 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, the lower triangle of A and B is overwritten.

Note: These matrices are used in Example 8.6.2 in referenced text [59].

Call Statement and Input

           IOPT  A  LDA  B  LDB  W     Z    LDZ  N   AUX  NAUX
            |    |   |   |   |   |     |     |   |    |    |
CALL DSYGV( 0  , A , 2 , B , 2 , W , DUMMY , 1 , 2 , AUX , 2  )

        *              *
A    =  | 229.0     .  |
        | 163.0  116.0 |
        *              *

        *            *
B    =  | 81.0    .  |
        | 59.0  43.0 |
        *            *

Output

        *           *
W    =  | -0.500000 |
        |  5.000000 |
        *           *

Example 2

This example shows how to find the eigenvalues and eigenvectors of a real symmetric generalized eigensystem problem, AZ = wBZ, where:

NAUX is equal to 2N.
AUX contains 2N elements.
On output, the lower triangle of A and B is overwritten.

Note: These matrices are from page 67 in referenced text [55].

Call Statement and Input

           IOPT  A  LDA  B  LDB  W   Z  LDZ  N   AUX  NAUX
            |    |   |   |   |   |   |   |   |    |    |
CALL DSYGV( 1  , A , 3 , B , 3 , W , Z , 3 , N , AUX , 6  )

        *                 *
        | -1.0    .    .  |
A    =  |  1.0   1.0   .  |
        | -1.0  -1.0  1.0 |
        *                 *

        *               *
        | 2.0   .    .  |
B    =  | 1.0  2.0   .  |
        | 0.0  1.0  2.0 |
        *               *

Output

        *           *
        | -1.500000 |
W    =  |  0.000000 |
        |  2.000000 |
        *           *

        *                                 *
        |  0.866025   0.000000   0.000000 |
Z    =  | -0.577350  -0.408248  -0.707107 |
        |  0.288675  -0.408248   0.707107 |
        *                                 *

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

A, z	w, `aux`	Subroutine
Short-precision real	Short-precision real	SSPEV
Long-precision real	Long-precision real	DSPEV
Short-precision complex	Short-precision real	CHPEV
Long-precision complex	Long-precision real	ZHPEV

A, B, beta, `aux`	alpha, Z	Subroutine
Short-precision real	Short-precision complex	SGEGV
Long-precision real	Long-precision complex	DGEGV

A, B, w, Z, `aux`	Subroutine
Short-precision real	SSYGV
Long-precision real	DSYGV