!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_SYEVD / LA_HEEVD computes all eigenvalues and, optionally, 
! eigenvectors of a real symmetric or Hermitian 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_SYEVD / LA_HEEVD( A, W, JOBZ, UPLO, INFO )
!       <type>(<wp>), INTENT(INOUT) :: A(:,:)
!       REAL(<wp>), INTENT(OUT) :: W(:)
!       CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOBZ, UPLO
!       INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    where
!       <type> ::= REAL | COMPLEX
!       <wp>   ::= KIND(1.0) | KIND(1.0D0)
!
! Defaults
! ========
!
! 1. If JOBZ is not present then JOBZ = 'N' is assumed.
! 2. If UPLO is not present then UPLO = 'U' is assumed.
!
! 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.
!            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.
!         If INFO = 0, the 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.
!
! 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, 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.
!
!--------------------------------------------------

.