!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_SYEVX / LA_HEEVX computes selected eigenvalues and, optionally, 
! eigenvectors of a real symmetric or Hermitian 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_SYEVX / LA_HEEVX( A, W, UPLO, VL, VU, IL, IU, 
!                                    M, IFAIL, ABSTOL, INFO )
!       <typw>(<wp>), INTENT(INOUT) :: A(:,:)
!       REAL(<wp>), INTENT(OUT) :: W(:)
!       CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO
!       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
!    where
!       <type> ::= REAL | COMPLEX
!       <wp>   ::= KIND(1.0) | KIND(1.0D0)
!
! Defaults
! ========
!
! 1. If IFAIL is present then JOBZ = 'V' otherwise JOBZ = 'N'
!       is assumed.
!       
! 3. If UPLO is not present then UPLO = 'U' is assumed.
!
! 4. If IL or IU are not present and VL or VU are not present then 
!       all eigenvalues are computed ( M = size(A,1) ).
!
! 5. If IL is present and IU is not present then IU = size(A,1) is assumed.
!    If IL is not present and IU is present then IL = 1 is assumed.
!
! 6. If VL is present and VU is not present then VU = +infinity is assumed.
!    If VL is not present and VU is present then VL = -infinity is assumed.
!
! 7. If ABSTOL is not present then ABSTOL = 2*SLAMCH('S') is assumed.
!       In this case the eigenvalues are computed most accurately.
!
! Argument dependency
! ======== ==========
!
! 1. If either IL or IU are present then neither VL nor VU are present.
!    If either VL or VU are present then neither IL nor IU are present.
!
! 2. If JOBZ = 'N' then IFAIL must not be present.
!
! Arguments
! =========
!
! A    (input/output) either REAL or COMPLEX square array, 
!      shape (:,:), size(A,1) == size(A,2) >= 0.
!      On entry, the symmetric (Hermitian) matrix A.  
!         If UPLO = 'U', the upper triangular part of A contains
!            the upper triangular part of the matrix A.  
!         If UPLO = 'L', the lower triangular part of A contains
!            the lower triangular part of the matrix A.
!      On exit: 
!         If JOBZ = 'V', then if INFO = 0, A contains the
!            orthonormal eigenvectors of the matrix A corresponding
!            to the selected eigenvalues, with the i-th column of
!            A holding the eigenvector associated with W(i).
!            If an eigenvector fails to converge, then that column 
!            of A contains the latest approximation to the eigenvector, 
!            and the index of the eigenvector is returned in IFAIL.
!         If JOBZ = 'N', then on exit the lower triangle (if UPLO='L')
!            or the upper triangle (if UPLO='U') of A, including the
!            diagonal, is destroyed.
!
! W    (output) REAL array,  shape (:), size(W) == size(A,1) >= 0.
!      On normal exit, the first M elements contain the selected
!      eigenvalues in ascending order.
!
! JOBZ Optional, (input) CHARACTER*1
!      If JOBZ is present then:
!         = 'N':  Compute eigenvalues only;
!         = 'V':  Compute eigenvalues and eigenvectors.
!      otherwise JOBZ = 'N' is assumed.
!
! 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.
!
! VL   Optional, (input) REAL.
! VU   Optional, (input) REAL.
!      If VL and VU are present ( VL < VU ) then
!         the lower and upper bounds of the interval to be searched
!         for eigenvalues. All eigenvalues in the half-open interval 
!         (VL,VU] will be found.
!      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.
!      If IL and IU are present ( 1 <= IL <= IU <= size(A,1) ) then
!         the indices (in ascending order) of the smallest and
!         largest eigenvalues to be returned. The IL-th through 
!         IU-th eigenvalues will be found.
!      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 <= size(A,1) ).
!      If IL and IU are present then M = IU-IL+1.
!
! IFAIL Optional, (output) INTEGER array, shape (:), 
!      size(IFAIL) == size(A,1) >= 0.
!      If IFAIL is present then JOBZ = 'V' is assumed and
!         eigenvectors are computed.
!         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  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 A 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'). _ ::= S | D.
!
!      See "Computing Small Singular Values of Bidiagonal Matrices
!      with Guaranteed High Relative Accuracy," by Demmel and
!      Kahan, LAPACK Working Note #3.
!
!      If ABSTOL is not present then ABSTOL = 2*SLAMCH('S') is assumed.
!
! INFO Optional, (output) INTEGER
!      If INFO is present:
!         = 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.
!
!---------------------------------

.