!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_SPEVX / LA_HPEVX computes selected eigenvalues and, optionally,
! eigenvectors of a real symmetric / hermitian matrix A in packed
! storage.
! Eigenvalues/vectors can be selected by specifying either a range
! of values or a range of indices for the desired eigenvalues.
!
! Arguments
! =========
!
! SUBROUTINE LA_SPEVX / LA_HPEVX( AP, W, UPLO, Z, VL, VU, &
!                       IL, IU, M, IFAIL, ABSTOL, INFO )
!    <type>(<wp>), INTENT(INOUT) :: AP(:)
!    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(:)
!    REAL(<wp>), INTENT(IN), OPTIONAL :: ABSTOL
!    INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    <type> ::= REAL | COMPLEX
!    <wp>   ::= KIND(1.0) | KIND(1.0D0)
!
! =====================
!
! AP   (input/output) REAL / COMPLEX array, shape (:),
!      SIZE(AP) == (n*(n+1)/2).
!      On entry, the upper or lower triangle of the symmetric
!      / hermitian matrix A, packed columnwise in a linear array.
!      The j-th column of A is stored in the array AP as follows:
!      if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
!      if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
!      On exit, AP is overwritten by values generated during the
!      reduction to tridiagonal form.  If UPLO = 'U', the diagonal
!      and first superdiagonal of the tridiagonal matrix T overwrite
!      the corresponding elements of A, and if UPLO = 'L', the
!      diagonal and first subdiagonal of T overwrite the
!      corresponding elements of A.
!      INFO = -1 if SIZE(AP) < 0 or SIZE(AP) /= n*(n+1)/2.
!
! W    (output) either REAL array, shape (:),
!      SIZE(W) == n, where = n*(n+1)/2 ==  SIZE(AP).
!      If INFO = 0, the eigenvalues in ascending order.
!      INFO = -2 if SIZE(W) /= n.
!
! UPLO Optional (input) CHARACTER*1
!      = 'U':  Upper triangle of A is stored;
!      = 'L':  Lower triangle of A is stored.
!      If UPLO is not present UPLO = 'U' is assumed.
!      INFO -3 if UPLO /= 'U' nor 'L'.
!
! Z    Optional (output) REAL / COMPLEX rectangular array, shape
!      (:,:), size(Z,1) == n and 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, dimension (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.
!
! ABSTOL  (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 AP 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 (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.
!
!---------------------------------

.