eig_herm_band (complex)

   more...

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

Synopsis

#include <imsl.h>

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

The type d_complex function is imsl_z_eig_herm_band.

Required Arguments

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

f_complex a[] (Input)
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 Hermitian 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_c_eig_herm_band (int n, f_complex 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, f_complex **evec,

IMSL_VECTORS_USER, f_complex 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, f_complex **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, f_complex *evec is declared, and &evec is used as an argument.

IMSL_VECTORS_USER, f_complex 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_c_eig_herm_band computes by default all eigenvalues and eigenvectors of a complex Hermitian band 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 ?HBTRD, ?=C,Z; 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, ?=C,Z; 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, ?=C,Z; see Anderson et al. (1999).

Examples

Example 1

In this example, the eigenvalues of a Hermitian banded matrix A of order 5 are computed.

#include <imsl.h>

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

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

    /* Compute eigenvalues */
    eval = imsl_c_eig_herm_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
      10.26        -8.34         6.97        -5.11         1.20

Example 2

A Toeplitz matrix is a square matrix whose entries are constant along each diagonal. In this example, the eigenvalues and eigenvectors of a Hermitian Toeplitz band matrix of order 6 are computed.

#include <imsl.h>

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

    /*
     *  Matrix A is Hermitian and band Toeplitz:
     *      A = (   5    -4+i   1+2i                      )
     *          ( -4-i     5   -4+i    1+2i               )
     *          (  1-2i  -4-i    5    -4+i    1+2i        )
     *          (        1-2i  -4-i     5    -4+i    1+2i )
     *          (               1-2i  -4-i     5    -4+i  )
     *          (                      1-2i  -4-i     5   )
     *
     *  The band symmetric representation of A is
     *      A = ( 0    0    1+2i   1+2i   1+2i   1+2i )
     *          ( 0  -4+i  -4+i   -4+i   -4+i   -4+i  )
     *          ( 5    5     5      5      5      5   )
     */
    n = 6;
    ncoda = 2;

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

    imsl_f_write_matrix("Eigenvalues", 1, n, eval, 0);
    imsl_c_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.07         9.62         5.74         4.37        -4.16         0.35
 
                     Eigenvectors
                           1                          2
1  (     0.2443,     0.1189)  (    -0.4705,     0.0231)
2  (    -0.3986,    -0.1173)  (     0.4891,     0.0000)
3  (     0.5035,     0.0000)  (    -0.1968,     0.0113)
4  (    -0.4872,     0.1272)  (    -0.1383,     0.1405)
5  (     0.3561,    -0.2142)  (     0.3226,    -0.3676)
6  (    -0.2064,     0.1767)  (    -0.3277,     0.3384)
 
                           3                          4
1  (    -0.4378,    -0.0754)  (    -0.2249,    -0.4001)
2  (     0.1271,     0.2753)  (    -0.2448,    -0.1604)
3  (     0.4590,     0.0000)  (    -0.2583,     0.3702)
4  (    -0.3468,    -0.3007)  (    -0.1961,     0.4066)
5  (    -0.2764,     0.1247)  (     0.2598,     0.1347)
6  (     0.3802,     0.2298)  (     0.4589,     0.0000)
 
                           5                          6
1  (    -0.1444,    -0.2300)  (     0.4272,    -0.2001)
2  (     0.0346,    -0.4138)  (     0.4879,     0.0000)
3  (     0.3758,    -0.3355)  (     0.1700,     0.1022)
4  (     0.5038,     0.0000)  (     0.0308,    -0.1960)
5  (     0.3014,     0.2857)  (     0.3133,    -0.3741)
6  (     0.0454,     0.2677)  (     0.4277,    -0.1991)

Warning Errors

Fatal Errors