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

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

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

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

Notes

1. When you specify iopt = 0, you must specify:
   • A positive value for ldz
   • A dummy argument for z (see Example 1)
2. 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.
3. For a description of how real symmetric matrices are stored in lower storage mode, see Lower Storage Mode.
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 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.

1. Compute the Cholesky Decomposition of B:

   B = LL^T

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

2. Compute C:

   C = L^-1AL^-T

   In this computation, C overwrites A.

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

4. 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], [58], [63], [62], [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.

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

1. 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?.
2. 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

1. iopt <> 0 or 1
2. n < 0
3. lda <= 0
4. n > lda
5. ldb <= 0
6. n > ldb
7. ldz <= 0 and iopt = 1
8. n > ldz and iopt = 1
9. 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 [62].

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

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