!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_GELS solves overdetermined or underdetermined real linear systems
! involving an m-by-n matrix A, or its transpose, using a QR or LQ
! factorization of A.  It is assumed that A has full rank.
! The following options are provided:
! 1. If TRANS = 'N' and m >= n:  find the least squares solution of
!    an overdetermined system, i.e., solve the least squares problem
!                 minimize || B - A*X ||.
! 2. If TRANS = 'N' and m < n:  find the minimum norm solution of
!    an underdetermined system A * X = B.
! 3. If TRANS = 'T' and m >= n:  find the minimum norm solution of
!    an undetermined system A**T * X = B.
! 4. If TRANS = 'T' and m < n:  find the least squares solution of
!    an overdetermined system, i.e., solve the least squares problem
!                 minimize || B - A**T * X ||.
! 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.
!
! Arguments
! =========
!
!  SUBROUTINE LA_GELS( A, B, TRANS, INFO )
!    <type>(<wp>), INTENT( INOUT ) :: A( :, : ), <rhs>
!    CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: TRANS
!    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,
!        if m >= n, A is overwritten by details of its QR
!                   factorization as returned by DGEQRF;
!        if m <  n, A is overwritten by details of its LQ
!                   factorization as returned by _GELQF.
!      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 matrix B of right hand side vectors, stored
!      columnwise; B is m-by-nrhs if TRANS = 'N', or n-by-nrhs
!      if TRANS = 'T'.
!      On exit, B is overwritten by the solution vectors, stored
!      columnwise:
!      if TRANS = 'N' and m >= n, rows 1 to n of B contain the least
!      squares solution vectors; the residual sum of squares for the
!      solution in each column is given by the sum of squares of
!      elements n+1 to m in that column;
!      if TRANS = 'N' and m < n, rows 1 to n of B contain the
!      minimum norm solution vectors;
!      if TRANS = 'T' and m >= n, rows 1 to m of B contain the
!      minimum norm solution vectors;
!      if TRANS = 'T' and m < n, rows 1 to m of B contain the
!      least squares solution vectors; the residual sum of squares
!      for the solution in each column is given by the sum of
!      squares of elements m+1 to n 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 (:)
!
! TRANS Optional (input) CHARACTER*1
!      Specifies the form of the system of equations:
!      = 'N':  the linear system involves A;
!      = 'T':  the linear system involves A**T;
!      = 'C':  the linear system involves A**H.
!      If TRANS is not present TRANS = 'N' is assumed.
!      INFO = -3 if TRANS /= 'N' nor 'T' nor 'C'
!
! INFO Optional (output) INTEGER
!      = 0:  successful exit
!      < 0:  if INFO = -i, the i-th argument had an illegal value
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!--------------------------------------

.