
 
 Purpose
 ======= 

       LA_GELSS and LA_GELSD compute the minimum-norm least squares 
 solution to one or more real or complex linear systems A*x = b using
 the singular value decomposition of A. Matrix A is rectangular and may
 be rank-deficient. The vectors b and corresponding solution vectors x
 are the columns of matrices denoted B and X , respectively.
       The effective rank of A is determined by treating as zero those 
 singular values which are less than RCOND times the largest singular 
 value. In addition to X , the routines also return the right singular
 vectors and, optionally, the rank and singular values of A.
       LA_GELSD combines the singular value decomposition with a divide
 and conquer technique. For large matrices it is often much faster than 
 LA_GELSS but uses more workspace.
 
 ==========
 
        SUBROUTINE LA_GELSS / LA_GELSD( A, B, RANK=rank, S=s, &
                                          RCOND=rcond, INFO=info )
             <type>(<wp>), INTENT( INOUT ) :: A(:,:), <rhs>
             INTEGER, INTENT(OUT), OPTIONAL :: RANK
             REAL(<wp>), INTENT(OUT), OPTIONAL :: S(:)
             REAL(<wp>), INTENT(IN), OPTIONAL :: RCOND
             INTEGER, INTENT(OUT), OPTIONAL :: INFO
        where
             <type> ::= REAL | COMPLEX
             <wp>   ::= KIND(1.0) | KIND(1.0D0)
             <rhs>  ::= B(:,:) | B(:)
 
 Arguments
 =========
 
 A       (input/output) REAL or COMPLEX array, shape (:,:).
         On entry, the matrix A.
         On exit, the first min(size(A,1), size(A,2)) rows of A are 
         overwritten with its right singular vectors, stored rowwise.
 B       (input/output) REAL or COMPLEX array, shape (:,:) with 
         size(B,1) = max(size(A,1), size(A,2)) or shape (:) with 
         size(B) = max(size(A,1), size(A,2)).
         On entry, the matrix B.
         On exit, the solution matrix X .
         If size(A,1) >= size(A,2) and RANK = size(A,2), the residual 
         sum-of-squares for the solution in a column of B is given by 
         the sum of squares of elements in rows size(A,2)+1:size(A,1)
         of that column.
 RANK    Optional (output) INTEGER.
         The effective rank of A, i.e., the number of singular values 
         of A which are greater than the product RCOND*sigma1 , where
  	 sigma1 is the greatest singular value.
 S       Optional (output) REAL array, shape (:) with size(S) = 
         min(size(A,1), size(A,2)).
         The singular values of A in decreasing order.
         The condition number of A in the 2-norm is
 	 K2(A)= sigma1/sigma(min(size(A,1),size(A,2)) .
 RCOND   Optional (input) REAL.
         RCOND is used to determine the effective rank of A.
         Singular values sigma(i)<=RCOND*sigma1  are treated as zero.
         Default value: 10*max(size(A,1), size(A,2))*EPSILON(1.0_<wp>),
         where <wp> is the working precision.
 INFO    Optional (output) INTEGER.
         = 0: successful exit.
         < 0: if INFO = -i, the i-th argument had an illegal value.
         > 0: the algorithm for computing the SVD failed to converge; 
 	 if INFO = i,i off-diagonal elements of an intermediate 
 	 bidiagonal form did not converge to zero.
         If INFO is not present and an error occurs, then the program 
         is terminated with an error message.

