!-----------------------------------------------------------------
!
! Purpose
! =======
!
!  LA_GEEVX computes for an N-by-N real nonsymmetric matrix A, the
!  eigenvalues and, optionally, the left and/or right eigenvectors.
!
!  Optionally also, it computes a balancing transformation to improve
!  the conditioning of the eigenvalues and eigenvectors (ILO, IHI,
!  SCALE, and ABNRM), reciprocal condition numbers for the eigenvalues
!  (RCONDE), and reciprocal condition numbers for the right
!  eigenvectors (RCONDV).
!
!  The right eigenvector v(j) of A satisfies
!                   A * v(j) = lambda(j) * v(j)
!  where lambda(j) is its eigenvalue.
!  The left eigenvector u(j) of A satisfies
!                u(j)**H * A = lambda(j) * u(j)**H
!  where u(j)**H denotes the conjugate transpose of u(j).
!
!  The computed eigenvectors are normalized to have Euclidean norm
!  equal to 1 and largest component real.
!
!  Balancing a matrix means permuting the rows and columns to make it
!  more nearly upper triangular, and applying a diagonal similarity
!  transformation D * A * D**(-1), where D is a diagonal matrix, to
!  make its rows and columns closer in norm and the condition numbers
!  of its eigenvalues and eigenvectors smaller.  The computed
!  reciprocal condition numbers correspond to the balanced matrix.
!  Permuting rows and columns will not change the condition numbers
!  (in exact arithmetic) but diagonal scaling will.  For further
!  explanation of balancing, see section 4.10.2 of the LAPACK
!  Users' Guide.
!
! =======
!
!   SUBROUTINE LA_GEEVX( A, <w>, VL, VR, BALANC, ILO, IHI, &
!                        SCALE, ABNRM, RCONDE, RCONDV, INFO )
!      <type>(<wp>), INTENT(INOUT) :: A(:,:)
!      <type>(<wp>), INTENT(OUT) :: <w'>
!      <type>(<wp>), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:)
!      CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: BALANC
!      INTEGER, INTENT(OUT), OPTIONAL :: ILO, IHI
!      REAL(<wp>), INTENT(OUT), OPTIONAL :: SCALE(:), ABNRM, &
!                                           RCONDE(:), RCONDV(:)
!      INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    where
!       <type> ::= REAL | COMPLEX
!       <wp>   ::= KIND(1.0) | KIND(1.0D0)
!       <w>    ::= WR, WI | W
!       <w'>   ::= WR(:), WI(:) | W(:)
!
! Arguments
! =========
!
! A    (input/output) REAL | COMPLEX array, shape (:,:),
!      SIZE(A,1) == SIZE(A,2) == n.
!      On entry, the n-by-n matrix A.
!      On exit, A has been overwritten.
!
! WR, WI Only real case, (output) REAL arrays, shape (:),
!      SIZE(WR) == SIZE(WI) == n (real and imaginary parts).
! W    Only complex case, (output) COMPLEX array, shape (:),
!      SIZE(W) == n.
!      WR, WI | W contain(s) the computed eigenvalues (WR and
!      WI real and imaginary parts). Complex conjugate pairs
!      of eigenvalues appear consecutively with the eigenvalue
!      having the positive imaginary part first.
!
! VL   Optional (output) REAL | COMPLEX array, shape (:,:),
!      SIZE(VL,1) == SIZE(VL,2) == n.
!      The left eigenvectors u(j) are stored one after another
!      in the columns of VL, in the same order as their
!      eigenvalues. If the j-th eigenvalue is real, then
!      u(j) = VL(:,j), the j-th column of VL.
!      If the j-th and (j+1)-st eigenvalues form a complex
!      conjugate pair, then u(j) = VL(:,j) + i*VL(:,j+1) and
!      u(j+1) = VL(:,j) - i*VL(:,j+1).
!
! VR   Optional (output) REAL | COMPLEX array, shape (:,:),
!      SIZE(VL,1) == SIZE(VL,2) == n.
!      The right eigenvectors v(j) are stored one after another
!      in the columns of VR, in the same order as their eigenvalues.
!      If the j-th eigenvalue is real, then v(j) = VR(:,j),
!      the j-th column of VR.
!      If the j-th and (j+1)-st eigenvalues form a complex
!      conjugate pair, then v(j) = VR(:,j) + i*VR(:,j+1) and
!      v(j+1) = VR(:,j) - i*VR(:,j+1).
!
! BALANC  Optional (input) CHARACTER*1
!      Indicates how the input matrix should be diagonally scaled
!      and/or permuted to improve the conditioning of its
!      eigenvalues.
!      = 'N': Do not diagonally scale or permute;
!      = 'P': Perform permutations to make the matrix more nearly
!             upper triangular. Do not diagonally scale;
!      = 'S': Diagonally scale the matrix, i.e. replace A by
!             D*A*D**(-1), where D is a diagonal matrix chosen
!             to make the rows and columns of A more equal in
!             norm. Do not permute;
!      = 'B': Both diagonally scale and permute A.
!
!      Computed reciprocal condition numbers will be for the matrix
!      after balancing and/or permuting. Permuting does not change
!      condition numbers (in exact arithmetic), but balancing does.
!
! ILO,IHI Optional (output) INTEGER
!      ILO and IHI are integer values determined when A was
!      balanced.  The balanced A(i,j) = 0 if i > j and
!      j = 1,...,ILO-1 or i = IHI+1,...,N.
!
! SCALE  Optional (output) REAL array, shape (:), SIZE(SCALE) == n.
!      Details of the permutations and scaling factors applied
!      when balancing A. If P(j) is the index of the row and column
!      interchanged with row and column j, and D(j) is the scaling
!      factor applied to row and column j, then
!      SCALE(J) = P(J),    for J = 1,...,ILO-1
!               = D(J),    for J = ILO,...,IHI
!               = P(J)     for J = IHI+1,...,N.
!      The order in which the interchanges are made is N to IHI+1,
!      then 1 to ILO-1.
!
! ABNRM  Optional (output) REAL
!      The one-norm of the balanced matrix (the maximum
!      of the sum of absolute values of elements of any column).
!
! RCONDE  Optional (output) REAL array, shape (:), SIZE(RCONDE) == n.
!      RCONDE(j) is the reciprocal condition number of the j-th
!      eigenvalue.
!
! RCONDV  Optional (output) REAL array, shape (:), SIZE(RCONDV) == n.
!      RCONDV(j) is the reciprocal condition number of the j-th
!      right eigenvector.
!
! INFO (output) INTEGER
!      = 0:  successful exit
!      < 0:  if INFO = -i, the i-th argument had an illegal value.
!      > 0:  if INFO = i, the QR algorithm failed to compute all the
!            eigenvalues, and no eigenvectors have been computed;
!            elements and i+1:N of W contain eigenvalues which have
!            converged.
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!-----------------------------------------------------------------------

.