
 
  Purpose
  =======
  
       LA_GESVD and LA_GESDD compute the singular values and, 
 optionally, the left and/or right singular vectors from the singular
 value decomposition  (SVD) of a real or complex m by n matrix A. The
 SVD of A is written
                    A = U * SIGMA * V^H
 where SIGMA is an  m by n matrix which is zero except for its 
 min(m, n) diagonal elements, U is an m by m orthogonal (unitary) 
 matrix, and V is an n by n orthogonal (unitary) matrix. The diagonal
 elements of SIGMA , i.e., the values 
 
      sigma(i)= SIGMA(i,i), i = 1, 2,..., min(m, n)
 are the singular values of A; they are real and non-negative, and are
 returned in descending order. The first min(m, n) columns of U and V 
 are the left and right singular vectors of A, respectively.
 LA_GESDD solves the same problem as LA_GESVD but uses a divide and 
 conquer method if singular vectors are desired. For large matrices it
 is usually much faster than LA_GESVD when singular vectors are 
 desired, but uses more workspace.
 
 Note: The routine returns V^H , not V .
 
 ========
 
    SUBROUTINE LA_GESVD / LA_GESDD( A, S, U=u, VT=vt, &
              WW=ww, JOB=job, INFO=info )  
      <type>(<wp>), INTENT(INOUT) :: A(:,:)
      REAL(<wp>), INTENT(OUT) :: S(:)
      <type>(<wp>), INTENT(OUT), OPTIONAL :: U(:,:), VT(:,:)
      REAL(<wp>), INTENT(OUT), OPTIONAL :: WW(:)
      CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOB
      INTEGER, INTENT(OUT), OPTIONAL :: INFO
      where
      <type> ::= REAL | COMPLEX
      <wp>   ::= KIND(1.0) | KIND(1.0D0)
  
 Arguments
 =========
 
 A      (input/output) REAL or COMPLEX array, shape (:, :) with 
        size(A, 1) = m and size(A, 2) = n.
        On entry, the matrix A.
        On exit, if JOB = 'U' and U is not present, then A is 
        overwritten with the first min(m, n) columns of U (the left
        singular vectors, stored columnwise).
        If JOB = 'V' and VT is not present, then A is overwritten with
        the first min(m, n) rows of V^H (the right singular vectors, 
        stored rowwise).
        In all cases the original contents of A are destroyed.
 S      (output) REAL array, shape (:) with size(S) = min(m, n).
        The singular values of A, sorted so that S(i) >= S(i+1).
 U      Optional (output) REAL or COMPLEX array, shape (:, :) with 
        size(U, 1) = m  and size(U, 2) = m or min(m, n).
        If size(U, 2) = m, U contains the m by m matrix U .
        If size(U; 2) = min(m, n), U contains the first min(m, n) 
        columns of U (the left singular vectors, stored columnwise).
 VT     Optional (output) REAL or COMPLEX array, shape (:, :) with 
        size(VT, 1) = n or min(m, n) and size(VT, 2) = n.
        If size(VT, 1) = n , VT contains the n by n matrix V^H .
        If size(VT, 1) = min(m, n), VT contains the first min(m, n)
        rows of V^H (the right singular vectors, stored rowwise).
 WW     Optional (output) REAL array, shape (:) with size(WW) = 
        min(m, n) - 1
        If INFO > 0, WW contains the unconverged superdiagonal elements
        of an upper bidiagonal matrix B whose diagonal is in SIGMA (not
        necessarily sorted). B has the same singular values as A.
        Note: WW is a dummy argument for LA_GESDD.
 JOB    Optional (input) CHARACTER(LEN=1).
        = 'N': neither columns of U nor rows of V^H are returned in 
          array A.
        = 'U': if U is not present, the first min(m, n) columns of U 
          (the left singular vectors) are returned in array A;
        = 'V': if VT is not present, the first min(m, n) rows of V^H 
          (the right singular vectors) are returned in array A;
        Default value: 'N'.
 INFO   Optional (output) INTEGER.
        = 0: successful exit.
        < 0: if INFO = -i, the i-th argument had an illegal value.
        > 0: The algorithm did not converge.
        If INFO is not present and an error occurs, then the program is
        terminated with an error message.

