
 
 Purpose
 =======
 
        LA_GEEVX computes for a real or complex square matrix A, the 
 eigenvalues and, optionally, the left and/or right eigenvectors. 
 Optionally, it also balances A and computes reciprocal condition
 numbers for the  eigenvalues and right eigenvectors.
 A right eigenvector v(j) of A satisfies
                   A * v(j) = lambda(j) * v(j)
 where lambda(j) is its eigenvalue. A left eigenvector u(j) of A 
 satisffies
                   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 involves permuting its rows and columns to make 
 it more nearly upper triangular and then scaling rows and columns by
 a diagonal similarity transformation to reduce the condition numbers 
 of the eigenvalues and eigenvectors.
        Computed reciprocal condition numbers pertain to the matrix 
 after balancing. Permuting does not change condition numbers (in 
 exact arithmetic), but scaling does.

 =========
 
    SUBROUTINE LA_GEEVX( A, <w>, VL=vl, VR=vr, BALANC=balanc, ILO=ilo, &
                     IHI=ihi, SCALE=scale, ABNRM=abnrm, RCONDE=rconde, &
                     RCONDV=rcondv, INFO=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 or COMPLEX square array, shape (:,:).
          On entry, the matrix A.
          On exit, the contents of A are destroyed.
 <w>      (output) REAL or COMPLEX array, shape (:) with size(w) = 
          size(A,1).
          The computed eigenvalues.
          <w(:)> ::= WR(:), WI(:) | W(:),
          where
          WR(:), WI(:) are of REAL type (for the real and imaginary
          parts) and W(:) is of COMPLEX type.
          Note: If A is real, then a complex-conjugate pair appear 
          consecutively, with the eigenvalue having the positive 
          imaginary part appearing first.
 VL       Optional (output) REAL or COMPLEX square array, shape (:,:)
          with size(VL,1) = size(A,1).
          The left eigenvectors u(j) are stored in the columns of VL in
          the order of their eigenvalues. Each eigenvector is scaled so
          that the Euclidean norm is 1 and the largest component is real.
          Note: If A is real then complex eigenvectors, like their 
          eigenvalues, occur in complex conjugate pairs. The real and 
          imaginary parts of the first eigenvector of the pair are
          stored in VL(:,j) and VL(:,j+1). Thus a complex conjugate pair
          is given by 
            u(j) = VL(:,j) + i*VL(:,j+1), u(j+1) = VL(:,j) - i*VL(:,j+1)
 VR       Optional (output) REAL or COMPLEX square array, shape (:,:) 
          with size(VR,1) = size(A,1).
          The right eigenvectors v(j) are stored in the columns of VR in
          the order of their eigenvalues.
          Each eigenvector is scaled so that the Euclidean norm is 1 and 
          the largest component is real.
          Note: If A is real then complex eigenvectors, like their 
          eigenvalues, occur in complex conjugate pairs. The real and 
          imaginary parts of the first eigenvector of the pair are stored
          in VR(:,j) and VR(:,j+1). Thus a complex conjugate pair is 
          given by 
 	     v(j) = VR(:,j) + i*VR(:,j+1), v(j+1) = VR(:,j) - i*VR(:,j+1)
 BALANC   Optional (input) CHARACTER(LEN=1).
          Indicates whether the input matrix should be permuted and/or 
          diagonally scaled.
             = 'N': Do not permute or scale;
             = 'P': Permute but do not scale;
             = 'S': Scale but do not permute;
             = 'B': Both permute and scale.
           Default value: 'N'.
 ILO,IHI  Optional (output) INTEGER.
          ILO and IHI are determined when A is balanced. The balanced
          A(i,j) = 0 if i > j and j = 1, ..., ILO-1 or 
          i = IHI+1, ... , size(A,1).
 SCALE    Optional (output) REAL array, shape (:) with size(SCALE) = 
          size(A,1).
          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
          P(j) = SCALE(j), j = 1, ..., ILO-1 and j =IHI+1, ...,  n
          D(j) = SCALE(j), j = ILO, ... , IHI.
 ABNRM    Optional (output) REAL.
          The l1 norm of the balanced matrix (the maximum of the sum 
          of absolute values of elements of any column).
 RCONDE   Optional (output) REAL array, shape (:) with size(RCONDE) =
          size(A,1). RCONDE(j) is the reciprocal condition number of 
          the j-th eigenvalue.
 RCONDV   Optional (output) REAL array, shape (:), size(RCONDV) = 
          size(A,1). RCONDV(j) is the reciprocal condition number of 
          the j-th right eigenvector.
 INFO     Optional (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 or condition numbers were
          computed; elements 1:ILO-1 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.

