CGELS  -  solve  overdetermined or underdetermined complex
       linear systems involving an M-by-N matrix A, or its conju­
       gate-transpose, using a QR or LQ factorization of A


SYNOPSIS

       SUBROUTINE CGELS( TRANS, M, N, NRHS, A, LDA, B, LDB, WORK,
                         LWORK, INFO )

           CHARACTER     TRANS

           INTEGER       INFO, LDA, LDB, LWORK, M, N, NRHS

           COMPLEX       A( LDA, * ), B( LDB, * ), WORK( * )


PURPOSE

       CGELS solves  overdetermined  or  underdetermined  complex
       linear systems involving an M-by-N matrix A, or its conju­
       gate-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  solu­
       tion of
          an underdetermined system A * X = B.

       3. If TRANS = 'C' and m >= n:  find the minimum norm solu­
       tion of
          an undetermined system A**H * X = B.

       4. If TRANS = 'C' and m < n:  find the least squares solu­
       tion of
          an overdetermined system, i.e., solve the least squares
       problem
                       minimize || B - A**H * 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

       TRANS   (input) CHARACTER
               = 'N': the linear system involves A;
               = 'C': the linear system involves A**H.

               The number of rows of the matrix A.  M >= 0.

       N       (input) INTEGER
               The number of columns of the matrix A.  N >= 0.

       NRHS    (input) INTEGER
               The  number  of right hand sides, i.e., the number
               of columns of the matrices B and X. NRHS >= 0.

       A       (input/output) COMPLEX array, dimension (LDA,N)
               On entry, the M-by-N matrix A.  if M >=  N,  A  is
               overwritten  by details of its QR factorization as
               returned by CGEQRF; if M <  N, A is overwritten by
               details  of  its  LQ  factorization as returned by
               CGELQF.

       LDA     (input) INTEGER
               The leading dimension of  the  array  A.   LDA  >=
               max(1,M).

       B       (input/output) COMPLEX array, dimension (LDB,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 = 'C'.  On exit, B is  over­
               written  by  the  solution vectors, stored column­
               wise: 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 = 'C' and m >= n, rows 1 to M of
               B  contain  the  minimum norm solution vectors; if
               TRANS = 'C' 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.

       LDB     (input) INTEGER
               The leading dimension  of  the  array  B.  LDB  >=
               MAX(1,M,N).

       WORK    (workspace/output) COMPLEX array, dimension
               (LWORK)
               On exit, if INFO = 0, WORK(1) returns the  optimal
               LWORK.

       LWORK   (input) INTEGER
               The dimension of the array WORK.  LWORK >= max( 1,
               MN + max( MN, NRHS ) ).  For optimal  performance,
               LWORK >= max( 1, MN + max( MN, NRHS )*NB ).  where
               MN = min(M,N) and NB is the optimum block size.

               the  routine  only  calculates the optimal size of
               the WORK array, returns this value  as  the  first
               entry  of  the  WORK  array,  and no error message
               related to LWORK is issued by XERBLA.

       INFO    (output) INTEGER
               = 0:  successful exit
               < 0:  if INFO = -i, the i-th argument had an ille­
               gal value


Man(1) output converted with man2html