!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_SYGV / LA_HEGV computes all the eigenvalues, and optionally, the 
! eigenvectors of a real generalized symmetric-definite or complex 
! Hermitian-definite eigenproblem, of the form A*x=(lambda)*B*x, 
! A*Bx=(lambda)*x, or B*A*x=(lambda)*x.
! Here A and B are assumed to be symmetric (Hermitian) and B is also
! positive definite.
!
! =======
!
!    SUBROUTINE LA_SYGV / LA_HEGV( A, B, W, ITYPE, JOBZ, UPLO, INFO )
!       <type>(<wp>), INTENT(INOUT) :: A(:,:), B(:,:)
!       REAL(<wp>), INTENT(OUT) :: W(:)
!       INTEGER, INTENT(IN), OPTIONAL :: ITYPE
!       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 ITYPE is not present then ITYPE = 1 is assumed.
!       
! 2. If JOBZ is not present then JOBZ = 'N' is assumed.
!
! 3. 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 matrix Z
!               of eigenvectors.  The eigenvectors are normalized
!               as follows:
!               if ITYPE = 1 or 2, Z**H*B*Z = I;
!               if ITYPE = 3, Z**H*inv(B)*Z = I.
!            If JOBZ = 'N', then on exit the upper triangle (if UPLO='U')
!               or the lower triangle (if UPLO='L') of A, including the
!               diagonal, is destroyed.
!
! B       (input) either REAL or COMPLEX square array,
!         shape (:,:), size(B,1) == size(A,1).
!         On entry, the symmetric (Hermitian) matrix B. 
!            If UPLO = 'U', the upper triangular part of B contains
!               the upper triangular part of the matrix B.
!            If UPLO = 'L', the lower triangular part of B contains
!               the lower triangular part of the matrix B.
!         On exit, if INFO <= size(A,1), the part of B containing the 
!            matrix is overwritten by the triangular factor U or L from 
!            the Cholesky factorization B = U**H*U or B = L*L**H.
!
! W       (output) REAL array, shape (:), size(W) == size(A,1).
!         If INFO = 0, the eigenvalues in ascending order.
!
! ITYPE   Optional, (input) INTEGER.
!         Specifies the problem type to be solved.
!         If ITYPE is present then:
!            = 1:  A*x = (lambda)*B*x
!            = 2:  A*B*x = (lambda)*x
!            = 3:  B*A*x = (lambda)*x
!         otherwise ITYPE = 1 is assumed.
!
! 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 and B is factored as
!                    U**H*U;
!            = 'L':  Lower triangle of A is stored and B is factored as
!                    L*L**H.
!         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: LA_POTRF or LA_SYEV / LA_HEEV returned an error code:
!               <= size(A,1): if INFO = i, LA_SYEV / LA_HEEV failed to 
!                  converge; i off-diagonal elements of an intermediate
!                  tridiagonal form did not converge to zero;
!               > size(A,1): if INFO = size(A,1) + i <= 2*size(A,1), 
!                  then the leading minor of order i of B is not 
!                  positive definite. The factorization of B could not 
!                  be completed and no eigenvalues or eigenvectors were 
!                  computed.
!         If INFO is not present and an error occurs, then the program
!            is terminated with an error message.
!------------------------------------------------------------------

.