Purpose
=======
LA_SBEVX / LA_HBEVX compute selected eigenvalues and, optionally,
the corresponding eigenvectors of a real symmetric/complex Hermitian
band matrix A. Eigenvalues and eigenvectors can be selected by
specifying either a range of values or a range of indices for the
desired eigenvalues.
=========
SUBROUTINE LA_SBEVX / LA_HBEVX( AB, W, UPLO=uplo, Z=z, &
VL=vl, VU=vu, IL=il, IU=iu, M=m, IFAIL=ifail, &
Q=q, ABSTOL=abstol, INFO=info )
(), INTENT(INOUT) :: AB(:,:)
REAL(), INTENT(OUT) :: W(:)
CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO
(), INTENT(OUT), OPTIONAL :: Z(:,:)
REAL(), INTENT(IN), OPTIONAL :: VL, VU
INTEGER, INTENT(IN), OPTIONAL :: IL, IU
INTEGER, INTENT(OUT), OPTIONAL :: M
INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:)
(), INTENT(OUT), OPTIONAL :: Q(:,:)
REAL(), INTENT(IN), OPTIONAL :: ABSTOL
INTEGER, INTENT(OUT), OPTIONAL :: INFO
where
::= REAL j COMPLEX
::= KIND(1.0) j KIND(1.0D0)
Arguments
=========
AB (input/output) REAL or COMPLEX array, shape (:,:) with
size(AB,1) = kd + 1 and size(AB,2) = n, where kd is the number
of subdiagonals or superdiagonals in the band and n is the order
of A.
On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L')
triangle of matrix A in band storage. The kd + 1 diagonals of A
are stored in the rows of AB so that the j-th column of A is
stored in the j-th column of AB as follows:
if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j
1<=j<=n
if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd)
1<=j<=n.
On exit, AB is overwritten by values generated during the
reduction of A to a tridiagonal matrix T . If UPLO = 'U' the
first superdiagonal and the diagonal of T are returned in rows
kd and kd + 1 of AB. If UPLO = 'L', the diagonal and first
subdiagonal of T are returned in the first two rows of AB.
W (output) REAL array, shape (:) with size(W) = n.
The first M elements contain the selected eigenvalues in
ascending order.
UPLO Optional (input) CHARACTER(LEN=1).
= 'U' : Upper triangle of A is stored;
= 'L' : Lower triangle of A is stored.
Default value: 'U'.
Z Optional (output) REAL or COMPLEX array, shape (:,:) with
size(Z,1) = n and size(Z,2) = M.
The first M columns of Z contain the orthonormal eigenvectors of
the matrix A corresponding to the selected eigenvalues, with the
i-th column of Z containing the eigenvector associated with the
eigenvalue in W(i). If an eigenvector fails to converge, then
that column of Z contains the latest approximation to the
eigenvector, and the index of the eigenvector is returned in
IFAIL.
Note: The user must ensure that at least M columns are supplied
in the array Z. When the exact value of M is not known in
advance, an upper bound must be used. In all cases M<=n.
VL,VU Optional (input) REAL.
The lower and upper bounds of the interval to be searched for
eigenvalues. VL < VU.
Default values: VL = -HUGE() and VU = HUGE(), where
::= KIND(1.0) | KIND(1.0D0).
Note: Neither VL nor VU may be present if IL and/or IU is
present.
IL,IU Optional (input) INTEGER.
The indices of the smallest and largest eigenvalues to be
returned. The IL-th through IU-th eigenvalues will be found.
1<=IL<=IU<=size(A,1).
Default values: IL = 1 and IU = size(A,1).
Note: Neither IL nor IU may be present if VL and/or VU is
present.
Note: All eigenvalues are calculated if none of the arguments
VL, VU, IL and IU are present.
M Optional (output) INTEGER.
The total number of eigenvalues found. 0<=M<=size(A,1).
Note: If IL and IU are present then M = IU - IL + 1.
IFAIL Optional (output) INTEGER array, shape (:) with size(IFAIL) = n.
If INFO = 0, the first M elements of IFAIL are zero.
If INFO > 0, then IFAIL contains the indices of the eigenvectors
that failed to converge.
Note: If Z is present then IFAIL should also be present.
Q Optional (output) REAL or COMPLEX square array, shape(:,:) with
size(Q,1) = n.
The n by n unitary matrix used in the reduction to tridiagonal
form. This is computed only if Z is present.
ABSTOL Optional (input) REAL.
The absolute error tolerance for the eigenvalues. An approximate
eigenvalue is accepted as converged when it is determined to lie
in an interval [a,b] of width less than or equal to
ABSTOL + EPSILON(1.0_) * max(|a|, |b|),
where is the working precision. If ABSTOL<=0, then
EPSILON(1.0_)* ||T||1 will be used in its place, where
||T||1 is the l1 norm of the tridiagonal matrix obtained by
reducing A to tridiagonal form. Eigenvalues will be computed most
accurately when ABSTOL is set to twice the underflow threshold
2 * LA_LAMCH(1.0_, 'Save minimum'), not zero.
Default value: 0.0_.
Note: If this routine returns with INFO > 0, then some
eigenvectors did not converge. Try setting ABSTOL to
2 * LA_LAMCH(1.0_, 'Save minimum').
INFO Optional (output) INTEGER
= 0: successful exit.
< 0: if INFO = -i, the i-th argument had an illegal value.
> 0: if INFO = i, then i eigenvectors failed to converge. Their
indices are stored in array IFAIL.
If INFO is not present and an error occurs, then the program is
terminated with an error message.