!-----------------------------------------------------------------
!
! Purpose
! =======
!
!  LA_SBEVD / LA_HBEVD computes all the eigenvalues and, optionally,
!  eigenvectors of a complex Hermitian band matrix A. If eigenvectors
!  are desired, it uses a divide and conquer algorithm.
!  The divide and conquer algorithm makes very mild assumptions about
!  floating point arithmetic. It will work on machines with a guard
!  digit in add/subtract, or on those binary machines without guard
!  digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or
!  Cray-2. It could conceivably fail on hexadecimal or decimal machines
!  without guard digits, but we know of none
!
! =========
!
!    SUBROUTINE LA_SBEVD / LA_HBEVD( AB, W, UPLO, Z, INFO )
!        <type>(<wp>), INTENT(INOUT) :: AB(:,:)
!        REAL(<wp>), INTENT(OUT) :: W(:)
!        CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO
!        <type>(<wp>), INTENT(OUT), OPTIONAL :: Z(:,:)
!        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.  If UPLO = 'U' or it is not
!      present, the first superdiagonal and the diagonal of the
!      tridiagonal matrix T are returned in rows kd and kd+1 of AB,
!      and if UPLO = 'L', the diagonal and first subdiagonal of T are
!      returned in the first two rows of AB.
!      Where kd = SIZE(AB,1)-1 and n = SIZE(AB,2).
!
! W    (output) REAL array, shape (:), SIZE(W) == n.
!      If INFO = 0, the 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, Z contains the orthonormal eigenvectors of the
!      matrix A, with the i-th column of Z holding the eigenvector
!      associated with W(i).
!
! 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.
!-------------------------------------

.