!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_GELSS computes the minimum norm solution to a real linear least
! squares problem:
! Minimize 2-norm(| b - A*x |).
! using the singular value decomposition (SVD) of A. A is an m-by-n
! matrix which may be rank-deficient.
! Several right hand side vectors b and solution vectors x can be
! handled in a single call; they are stored as the columns of the
! m-by-nrhs right hand side matrix B and the n-by-nrhs solution matrix
! X.
! The effective rank of A is determined by treating as zero those
! singular values which are less than RCOND times the largest singular
! value.
!
! Arguments
! =========
!
!  SUBROUTINE LA_GELSS( A, B, RANK, S, RCOND, INFO )
!    <type>(<wp>), INTENT( INOUT ) :: A( :, : ), <rhs>
!    INTEGER, INTENT(IN), OPTIONAL :: RANK
!    REAL(<wp>), INTENT(OUT), OPTIONAL :: S(:)
!    REAL(<wp>), INTENT(IN), OPTIONAL :: RCOND
!    INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    <type> ::= REAL | COMPLEX
!    <wp>   ::= KIND(1.0) | KIND(1.0D0)
!    <rhs>  ::= B(:,:) | B(:)
!
! =====================
!
! A    (input/output) either REAL or COMPLEX array, shape (:,:),
!      SIZE(A,1) == m, SIZE(A,2) == n.
!      On entry, the m-by-n matrix A.
!      On exit, the first min(m,n) rows of A are overwritten with
!      its right singular vectors, stored rowwise.
!      INFO = -1 if SIZE(A,1) < 0 or SIZE(A,2) < 0
!
! B    (input/output) either REAL or COMPLEX array, shape either
!      (:,:) or (:), size(B,1) or size(B) == size(A,1). SIZE(B,2) == nrhs.
!      On entry, the m-by-nrhs right hand side matrix B.
!      On exit, B is overwritten by the n-by-nrhs solution
!      matrix X.  If m >= n and RANK = n, the residual
!      sum-of-squares for the solution in the i-th column is given
!      by the sum of squares of elements n+1:m in that column.
!      INFO = -2 if SIZE(B,1) /= max(SIZE(A,1), SIZE(A,2)) or SIZE(B,2) < 0
!                    and if shape of B is (:,:) or
!                if SIZE(B) /= max(SIZE(A,1), SIZE(A,2)) or SIZE(B,2) < 0
!                   and if shape of B is (:)
!
! RANK Optional (output) INTEGER
!      The effective rank of A, i.e., the number of singular values
!      which are greater than RCOND*S(1).
!
! S    Optional (output) REAL array, shape (:), SIZE(S) == min(m,n)
!      The singular values of A in decreasing order.
!      The condition number of A in the 2-norm = S(1)/S(min(m,n)).
!      INFO = -4 if SIZE(S) /= min(SIZE(A,1),SIZE(A,2))
!
! RCOND Optional (input) REAL
!      RCOND is used to determine the effective rank of A.
!      Singular values S(i) <= RCOND*S(1) are treated as zero.
!      If RCOND < 0, machine precision is used instead.
!
! 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.
!--------------------------------------

.