
 
 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 )
            <type>(<wp>), INTENT(INOUT) :: AB(:,:)
            REAL(<wp>), INTENT(OUT) :: W(:)
            CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO
            <type>(<wp>), INTENT(OUT), OPTIONAL :: Z(:,:)
            REAL(<wp>), INTENT(IN), OPTIONAL :: VL, VU
            INTEGER, INTENT(IN), OPTIONAL :: IL, IU
            INTEGER, INTENT(OUT), OPTIONAL :: M
            INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:)
            <type>(<wp>), INTENT(OUT), OPTIONAL :: Q(:,:)
            REAL(<wp>), INTENT(IN), OPTIONAL :: ABSTOL
            INTEGER, INTENT(OUT), OPTIONAL :: INFO
         where
            <type> ::= REAL j COMPLEX
            <wp> ::= 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(<wp>) and VU = HUGE(<wp>), where 
        <wp> ::= 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_<wp>) * max(|a|, |b|),
        where <wp> is the working precision. If ABSTOL<=0, then 
        EPSILON(1.0_<wp>)* ||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_<wp>, 'Save minimum'), not zero.
        Default value: 0.0_<wp>.
        Note: If this routine returns with INFO > 0, then some 
        eigenvectors did not converge. Try setting ABSTOL to 
        2 * LA_LAMCH(1.0_<wp>, '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.

