eig_sym_band

   more...

Computes all eigenvalues or eigenpairs of a real symmetric matrix A in band storage format. Optionally, interval and extreme eigenvalues or eigenpairs of A can be computed.

Synopsis

#include <imsl.h>

float *imsl_f_eig_sym_band (int n, float a[], int ncoda, …, 0)

The type double function is imsl_d_eig_sym_band.

Required Arguments

int n (Input)
Number of rows and columns in the matrix.

float a[] (Input)
An array of size (ncoda+1) × n containing the  n × n matrix A in band symmetric storage mode with only the diagonal and upper band of A stored.

int ncoda (Input)
The number of upper codiagonals of the matrix.

Return Value

A pointer to the computed eigenvalues of the symmetric band matrix in decreasing order of magnitude. To release this space, use imsl_free. If a FATAL or TERMINAL error occurs, then NULL is returned.

Synopsis with Optional Arguments

#include <imsl.h>

float *imsl_f_eig_sym_band (int n, float a[], int ncoda,

IMSL_RANGE, float elow, float ehigh,

IMSL_EXTREME_VALUES, int small, int n_extreme,

IMSL_RETURN_NUMBER, int *n_eval,

IMSL_VECTORS, float **evec,

IMSL_VECTORS_USER, float evecu[],

IMSL_EVECU_COL_DIM, int evecu_col_dim,

IMSL_RETURN_USER, float evalu[],

0)

Optional Arguments

IMSL_RANGE, float elow, float ehigh (Input)
Return eigenvalues and optionally eigenvectors that lie in the half-open interval (elow, ehigh].
Default: Return all eigenvalues, (elow, ehigh) = (−∞, +∞).

IMSL_EXTREME_VALUES, int small, int n_extreme (Input)
Return extreme eigenvalues and optionally eigenvectors of the matrix. If small = 0, the algebraically largest n_extreme eigenvalues are returned, if small = 1, the algebraically smallest n_extreme eigenvalues are returned.

IMSL_RETURN_NUMBER, int *n_eval (Output)
The number of output eigenvalues in the range (elow, ehigh] or, if optional argument IMSL_EXTREME_VALUES is used, the number of extreme eigenvalues computed.

IMSL_VECTORS, float **evec (Output)
The address of a pointer to an array of size n × n_eval containing the orthonormal eigenvectors of the matrix. On return, the necessary space is allocated by the function. Typically, float *evec is declared, and &evec is used as an argument.

IMSL_VECTORS_USER, float evecu[] (Output)
A user-allocated array of size n × evecu_col_dim containing the orthonormal eigenvectors of the matrix in its first n_eval columns.

IMSL_EVECU_COL_DIM, int evecu_col_dim (Input)
The column dimension of array evecu. If optional argument IMSL_EXTREME_VALUES is used, then evecu_col_dim >= n_extreme is required, otherwise evecu_col_dim >= n.
Default: evecu_col_dim = n_extreme if optional argument IMSL_EXTREME_VALUES is used, evecu_col_dim = n otherwise.

IMSL_RETURN_USER, float evalu[] (Output)
A user-allocated array containing the eigenvalues of matrix A in decreasing order of magnitude in its first n_eval locations. Array evalu must be of size at least n_extreme if optional argument IMSL_EXTREME_VALUES is used, and of size at least n otherwise.

Description

Function imsl_f_eig_sym_band computes by default all eigenvalues and eigenvectors of a real band symmetric matrix A. Alternatively, specific eigenvalues and related eigenvectors of A can be computed: With optional argument IMSL_RANGE, the eigenvalues in a specified interval can be determined, whereas with optional argument IMSL_EXTREME_VALUES, the algebraically largest or smallest (“extreme”) eigenvalues can be computed.

Orthogonal similarity transformations are used to reduce matrix A to an equivalent symmetric tridiagonal matrix T. These transformations are accumulated. The reduction function is based on LAPACK routines ?SBTRD, ?=S,D; see Anderson et al. (1999) and Kaufman (1984).

In the default case, the implicit QR algorithm is used to compute all eigenvalues and eigenvectors of T. By multiplication with the orthogonal transformations of the reduction step the eigenvectors are retransformed into the eigenvectors of A. The QR function is based on LAPACK routines ?STEQR, ?=S,D; see Anderson et al. (1999).

In the case of specific eigenvalues, a bisection algorithm is used to compute the interval or extreme eigenvalues of the tridiagonal matrix T. If required, inverse iteration and orthogonalization are used to compute the related eigenvectors of A. The bisection algorithm is based on LAPACK routines ?STEBZ, ?=S,D, the eigenvector algorithm on LAPACK routines ?STEIN, ?=S,D; see Anderson et al. (1999).

Examples

Example 1

In this example, the eigenvalues of a symmetric banded matrix A of order 5 given by Gregory and Karney (1969, p. 77) are computed. The exact eigenvalues of this matrix are

#include <imsl.h>

int main() {
    int n, ncoda;
    float a[] = { 0.0, 0.0, 1.0, 1.0, 1.0,
                  0.0, 2.0, 2.0, 2.0, 2.0,
                  -1.0, 0.0, 0.0, 0.0, -1.0 };
    float *eval = NULL;

    /*
     *  Matrix A is symmetric and has values
     *      A = ( -1   2   1         )
     *          (  2   0   2   1     )
     *          (  1   2   0   2   1 )
     *          (      1   2   0   2 )
     *          (          1   2  -1 )
     *
     *  The band symmetric representation of A is
     *      A = (  0   0   1   1    1 )
     *          (  0   2   2   2    2 )
     *          ( -1   0   0   0   -1 )
     */
    n = 5;
    ncoda = 2;

    /* Compute eigenvalues */
    eval = imsl_f_eig_sym_band(n, a, ncoda, 0);

    imsl_f_write_matrix("Eigenvalues", 1, n, eval, 0);

    if (eval)
        imsl_free(eval);
}

Output

Eigenvalues
          1            2            3            4            5
      4.464       -3.000       -2.464       -2.000        1.000

Example 2

In this example, the eigenvalues and eigenvectors of a symmetric banded matrix A of order 6 given by Gregory and Karney (1969, p. 75) are computed. The exact eigenvalues of this matrix are

#include <imsl.h>

int main() {
    int n, ncoda;
    float a[] = { 0.0, 0.0, 1.0, 1.0, 1.0, 1.0,
                  0.0, -4.0, -4.0, -4.0, -4.0, -4.0,
                  5.0,  6.0,  6.0,  6.0,  6.0,  5.0 };
    float *eval = NULL, *evec = NULL;

    /*
     *  Matrix A is symmetric and has values
     *      A = (  5  -4   1             )
     *          ( -4   6  -4   1         )
     *          (  1  -4   6  -4   1     )
     *          (      1  -4   6  -4   1 )
     *          (          1  -4   6  -4 )
     *          (              1  -4   5 )
     *
     *  The band symmetric representation of A is
     *      A = ( 0   0   1   1   1   1 )
     *          ( 0  -4  -4  -4  -4  -4 )
     *          ( 5   6   6   6   6   5 )
     */
    n = 6;
    ncoda = 2;

    /* Compute eigenvalues and eigenvectors */
    eval = imsl_f_eig_sym_band(n, a, ncoda,
        IMSL_VECTORS, &evec,
        0);

    imsl_f_write_matrix("Eigenvalues", 1, n, eval, 0);
    imsl_f_write_matrix("Eigenvectors", n, n, evec, 0);

    if (eval)
        imsl_free(eval);
    if (evec)
        imsl_free(evec);
}

Output

                                 Eigenvalues
          1            2            3            4            5            6
      14.45        10.54         5.98         2.42         0.57         0.04
 
                           Eigenvectors
             1            2            3            4            5
1       0.2319      -0.4179      -0.5211       0.5211      -0.4179
2      -0.4179       0.5211       0.2319       0.2319      -0.5211
3       0.5211      -0.2319       0.4179      -0.4179      -0.2319
4      -0.5211      -0.2319      -0.4179      -0.4179       0.2319
5       0.4179       0.5211      -0.2319       0.2319       0.5211
6      -0.2319      -0.4179       0.5211       0.5211       0.4179
 
             6
1       0.2319
2       0.4179
3       0.5211
4       0.5211
5       0.4179
6       0.2319

Warning Errors

Fatal Errors