Dense Symmetric Eigenvalue Solver

S3L_sym_eigen

Description

S3L_sym_eigen finds selected eigenvalues and, optionally, eigenvectors of Hermitian matrices. The eigenvalues and eigenvectors can be selected by specifying a range of values or a range of indices for the desired eigenvalues/vectors.

Syntax

The C and Fortran syntax for S3L_sym_eigen are shown below.

C/C++ Syntax

Example 8-65

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_sym_eigen(A, axis1, axis2, E, V, J, job, range, limits, tolerances)
    S3L_array_t       A
    int               axis1
    int               axis2
    S3L_array_t       E
    S3L_array_t       V
    S3L_array_t       J
    int               job
    int               range
    void              *limits
    void              *tolerances

F77/F90 Syntax

Example 8-66

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_sym_eigen(A, axis1, axis2, E, V, J, job, range, limits, tolerances,
ier)
    integer*8         A
    integer*4         axis1
    integer*4         axis2
    integer*8         E
    integer*8         V
    integer*8         J
    integer*4         job
    integer*4         range
    <type_lim>        limits(2)
    <type_tol>        tolerances(2)
    integer*4         ier

where <type_lim> is either integer*4 or real*4 and <type_tol> is either real*4 or real*8.

Input

• A - S3L array handle describing a real or complex parallel array. On entry, A contains one or more two-dimensional Hermitian matrices, b, each of which is assumed to be dense and square. The axes of b are identified by the arguments axis1 and axis2.

• axis1 - Integer variable denoting the axis of A that contains the rows of each Hermitian matrix, b.

• axis2 - Integer variable denoting the axis of A that contains the columns of each Hermitian matrix, b. axis2 must be greater than axis1.

• job - Integer variable indicating whether or not eigenvectors are to be computed. A value of 0 indicates that only eigenvalues are desired. Otherwise, both eigenvalues and eigenvectors are calculated.

• range - Integer variable indicating the range of eigenvalues to be computed, as follows:

  • 0 - Return all eigenvalues.

  • 1 - Compute all eigenvalues within the specified interval.

  • 2 - Return a range of eigenvalue indices (when eigenvalues are sorted in ascending order).

• limits - Defines the eigenvalue interval when the value of range is 1 or 2. Specifically, when range equals:

  • 0 - limits is not used.

  • 1 - limits must be a scalar real vector of length 2. Its values bracket the interval in which eigenvalues are requested--that is, all eigenvalues in the interval [limits(1), limits(2)] will be found.

  • 2 - limits must be a scalar integer vector of length 2. For eigenvalues sorted in ascending order, eigenvalues corresponding to limits(1) through limits(2) will be found.

• tolerances - Real vector of length 2. Its precision must match that of A. That is, if A is of type S3L_float or S3L_complex, tolerances must be single-precision. If A is of type S3L_double or S3L_double_complex, tolerances must be double-precision.

tolerances(1) gives the absolute error tolerance for the eigenvalues. If tolerances(1) is less than or equal to zero, the value eps * norm(b) will be used in its place, where eps is the machine tolerance and norm(b) is the 1-norm of the tridiagonal matrix obtained by reducing b to tridiagonal form.

tolerances(2) controls the reorthogonalization of eigenvectors. Eigenvectors corresponding to eigenvalues that are within tolerances(2) * norm(b) of each other will be reorthogonalized. If tolerances(1) is less than or equal to zero, the value 1.0e-03 will be used in its place.

Output

This function uses the following arguments for output:

• A - Upon exit, the contents of A are destroyed.

• E - S3L array handle describing a real parallel array with rank(E) = rank(A) -1. axis1 of E must have the same extent as axis1 of A. The remaining axes are instance axes matching those of A in order of declaration and extents. Thus, each vector f within E corresponds to a matrix b within A.

• On return, each f contains the eigenvalues of the corresponding matrix b.

• V - S3L array handle describing a parallel array with the same rank, extents, and data type as A. For each instance matrix b within A, there is a corresponding two-dimensional array, w, within V. axis1 denotes the axis of V that contains the rows of w; axis2 denotes the axis of V that contains the columns of w.

On return, each column of w will contain an eigenvector of w.

• J - S3L array handle describing an integer parallel array with rank(J) = rank(A) - 1. axis1 of J should have an extent of 2. The remaining axes are instance axes matching those of A in order of declaration and extents. Thus, J will contain vectors of length 2 corresponding to the matrices b embedded within A.

On return, the first element of each vector will contain the number of eigenvalues found. The second element of each vector will contain the number of eigenvectors found.

• ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_sym_eigen returns S3L_SUCCESS.

S3L_sym_eigen performs generic checking of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code.

• S3L_ERR_ARG_AXISNUM - Invalid value of axis1 or axis2.

• S3L_ERR_MATCH_RANK - Ranks of the parallel arrays do not match.

• S3L_ERR_ARRNOTSQ - The two-dimensional arrays in A are not square.

• S3L_ERR_MATCH_EXTENTS - The extents of the parallel arrays do not match.

• S3L_ERR_MATCH_DTYPE - The arguments are not all of the same data type and precision.

• S3L_ERR_ARG_RANGE_INV - Invalid value used for range or limits.

• S3L_ERR_ARG_NULL - Value of range is 1 or 2 but limits is a NULL pointer (C/C++) or 0 (F77/F90).

Examples

../examples/s3l/eigen/eigen.c
../examples/s3l/eigen-f/engen.f