!-----------------------------------------------------------------
!
! Purpose
! =======
!
!  LA_SBEVX / LA_HBEVX computes selected eigenvalues and, optionally,
!  eigenvectors of a 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( AB, W, UPLO, Z, VL, VU, IL, IU, &
!                         M, IFAIL, Q, ABSTOL, 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 | COMPLEX
!       <wp>   ::= KIND(1.0) | KIND(1.0D0)
!
! Arguments
! =========
!
! AB   (input/output) REAL /  COMPLEX rectangular array, shape (:,:).
!      On entry, the upper or lower triangle of the Symetric /Hermitian
!      band matrix A, stored in the first kd+1 rows of the array.  The
!      j-th column of A is stored in the j-th column of the array AB
!      as follows:
!      if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
!      if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).
!      On exit, AB is overwritten by values generated during the
!      reduction to tridiagonal form.
!      Where kd = SIZE(AB,1)-1 and n = SIZE(AB,2).
!
! W    (output) REAL array, shape (:), SIZE(W) == n.
!      The first M elements contain the selected eigenvalues in
!      ascending order.
!
! UPLO Optional (input) CHARACTER*1
!         If UPLO is present then:
!            = 'U':  Upper triangle of A is stored;
!            = 'L':  Lower triangle of A is stored.
!         otherwise UPLO = 'U' is assumed.
!
! Z    Optional (output) REAL / COMPLEX array, shape (:,:),
!      SIZE(Z,1) == SIZE(Z,2) == n.
!      If INFO = 0, 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 holding the eigenvector
!      associated with 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.
!
! VL   Optional (input) REAL
! VU   Optional (input) REAL
!      The lower and upper bounds of the interval to be searched
!      for eigenvalues. VL < VU.
!      If VL is not present VL = -HUGE(<wp>) is assumed.
!      If VU is not present VU =  HUGE(<wp>) is assumed.
!
! IL   Optional (input) INTEGER
! IU   Optional (input) INTEGER
!      The indices (in ascending order) of the smallest and largest
!      eigenvalues to be returned. 1 <= IL <= IU <= n, if n > 0;
!      If IL is not present IL = 1 is assumed.
!      If IU is not present IU = n is assumed.
!
! M    Optional (output) INTEGER
!      The total number of eigenvalues found.  0 <= M <= n.
!
! IFAIL (output) INTEGER array, shape(:,:), 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.
!
! Q    Optional (output) REAL / COMPLEX array, shape(:,:),
!      SIZE(Q,1) == SIZE(Q,2) == n.
!      The n-by-n unitary matrix used in the reduction to tridiagonal
!      form.
!
! 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 + EPS *   max( |a|,|b| ) ,
!
!      where EPS is the machine precision. If ABSTOL is less than
!      or equal to zero, then  EPS*|T| will be used in its place,
!      where |T| is the 1-norm of the tridiagonal matrix obtained
!      by reducing AB to tridiagonal form.
!
!      Eigenvalues will be computed most accurately when ABSTOL is
!      set to twice the underflow threshold 2*_LAMCH('S'), not zero.
!      If this routine returns with INFO>0, indicating that some
!      eigenvectors did not converge, try setting ABSTOL to
!      2*_LAMCH('S').
!      If ABSTOL is not present then ABSTOL = 2*_LAMCH('S') is assumed.
!      _LAMCH ::= SLAMCH | DLAMCH.
!
!      See "Computing Small Singular Values of Bidiagonal Matrices
!      with Guaranteed High Relative Accuracy," by Demmel and
!      Kahan, LAPACK Working Note #3.
!
! INFO Optional (output) INTEGER
!       = 0:  successful exit.
!       < 0:  if INFO = -i, the i-th argument had an illegal value.
!       > 0:  if INFO = i, the algorithm failed to converge; i
!             off-diagonal elements of an intermediate tridiagonal
!             form did not converge to zero.
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!
!  Further Details
!  ===============
!
!  The band storage scheme is illustrated by the following example, when
!  N = 6, KD = 2, and UPLO = 'U':
!
!  On entry:                       On exit:
!
!      *    *   a13  a24  a35  a46      *    *   u13  u24  u35  u46
!      *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
!     a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66
!
!  Similarly, if UPLO = 'L' the format of A is as follows:
!
!  On entry:                       On exit:
!
!     a11  a22  a33  a44  a55  a66     l11  l22  l33  l44  l55  l66
!     a21  a32  a43  a54  a65   *      l21  l32  l43  l54  l65   *
!     a31  a42  a53  a64   *    *      l31  l42  l53  l64   *    *
!
!  Array elements marked * are not used by the routine.
!-------------------------------------

.