Standard Least Square APIs#

GELS#

group gels

Functions

template<typename T>
void gels(char *trans, integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, T *work, integer *lwork, integer *info)#

GELS solves overdetermined or underdetermined systems for GE matrices.

Purpose:

   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 underdetermined 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.

Parameters:
  • TRANS – [in]

    TRANS is CHARACTER*1

    = ‘N’: the linear system involves A;

    = ‘T’: the linear system involves A**T.

  • M – [in]

    M is INTEGER

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

  • N – [in]

    N is INTEGER

    The number of columns of the matrix A. N >= 0.

  • NRHS – [in]

    NRHS is INTEGER

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

  • A – [inout]

    A is REAL array, dimension (LDA,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 SGEQRF;

    if M < N, A is overwritten by details of its LQ factorization as returned by SGELQF.

  • LDA – [in]

    LDA is INTEGER

    Computes row and column scaling to reduce condition number of matrix

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

  • B – [inout]

    B is REAL 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 = ‘T’.

    On exit, if INFO = 0, 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.

  • LDB – [in]

    LDB is INTEGER

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

  • WORK – [out]

    WORK is REAL array, dimension (MAX(1,LWORK))

    On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

  • LWORK – [in]

    LWORK is INTEGER

    The dimension of the array WORK. LWORK >= fla_max( 1, MN + fla_max( MN, NRHS ) ).

    For optimal performance, LWORK >= fla_max( 1, MN + fla_max( MN, NRHS )*NB ). where MN = min(M,N) and NB is the optimum block size.

    If LWORK = -1, then a workspace query is assumed; 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 – [out]

    INFO is INTEGER

    = 0: successful exit

    < 0: if INFO = -i, the i-th argument had an illegal value

    > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.

GELSS#

group gelss

Functions

template<typename T>
void gelss(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, T *s, T *rcond, integer *rank, T *work, integer *lwork, integer *info)#

The minimum-norm solution to a real linear least squares problem.

Purpose:

       Computation of 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.

Parameters:
  • m – [in]

    m is integer*

    The number of rows of the matrix a. m >= 0.

  • n – [in]

    n is integer*

    The number of columns of the matrix a. n >= 0.

  • nrhs – [in]

    nrhs is integer*

    The number of right hand sides, i.e., the number of columns of the matrices b and X. nrhs >= 0.

  • a – [inout]

    a is float/double array, dimension (lda,n)

    On entry, the m-by-n matrix.

    On exit, the first min(m,n) rows of A are overwritten with its right singular vectors, stored rowwise.

  • lda – [in]

    lda is integer*

    The leading dimension of the matrix a, lda >= fla_max(1,m)

  • b – [inout]

    b is float/double array, dimension (ldb,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.

  • ldb – [in]

    ldb is integer*

    The leading dimension of the matrix b, ldb >= fla_max(1,max(m,n)).

  • s – [out]

    s is float/double array, dimension (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)).

  • rcond – [in]

    rcond is float/double*

    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.

  • rank – [out]

    rank is integer*

    The effective rank of a, i.e., the number of singular values which are greater than rcond*S(1).

  • WORK – [out]

    WORK is COMPLEX array, dimension (MAX(1,LWORK))

    On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

  • LWORK – [in]

    LWORK is INTEGER

    The dimension of the array WORK. LWORK >= 1, and also:

    LWORK >= 2*min(M,N) + fla_max(M,N,NRHS)

    For good performance, LWORK should generally be larger.

    If LWORK = -1, then a workspace query is assumed; 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.

  • RWORK – [out] RWORK is REAL array, dimension (5*min(M,N))

  • INFO – [out]

    INFO is 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.

template<typename T, typename Ta>
void gelss(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, Ta *s, Ta *rcond, integer *rank, T *work, integer *lwork, Ta *rwork, integer *info)#

GELSD#

group gelsd

Functions

template<typename T>
void gelsd(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, T *s, T *rcond, integer *rank, T *work, integer *lwork, integer *iwork, integer *info)#

The minimum-norm solution to a real linear least squares problem.

Purpose:

       Computation of 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 problem is solved in three steps:
       (1) Reduce the coefficient matrix a to bidiagonal form with Householder transformations,
       reducing the original problem into a "bidiagonal least squares problem" (BLS)
       (2) Solve the BLS using a divide and conquer approach.
       (3) Apply back all the Householder transformations to solve the original least squares
       problem.

       The effective rank of A is determined by treating as zero those singular values which are
       less than rcond times the largest singular value.

       The divide and conquer algorithm makes very mild assumptions about floating point
       arithmetic. It will work on machines with a guard digit in add/subtract, or on those
       binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP,
       Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without
       guard digits, but we know of none.

Parameters:
  • m – [in]

    m is integer*

    The number of rows of the matrix a. m >= 0.

  • n – [in]

    n is integer*

    The number of columns of the matrix a. n >= 0.

  • nrhs – [in]

    nrhs is integer*

    The number of right hand sides, i.e., the number of columns of the matrices b and X. nrhs >= 0.

  • a – [inout]

    a is float/double array, dimension (lda,n)

    On entry, the m-by-n matrix.

    On exit, A has been destroyed.

  • lda – [in]

    lda is integer*

    The leading dimension of the matrix a, lda >= fla_max(1,m)

  • b – [inout]

    b is float/double array, dimension (ldb,nrhs)

    On entry, the m-by-n matrix.

    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.

  • ldb – [in]

    ldb is integer*

    The leading dimension of the matrix b, ldb >= fla_max(1,max(m,n)).

  • s – [out]

    s is float/double array, dimension (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)).

  • rcond – [in]

    rcond is float/double*

    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.

  • rank – [out]

    rank is integer*

    The effective rank of a, i.e., the number of singular values which are greater than rcond*S(1).

  • WORK – [out]

    WORK is COMPLEX array, dimension (MAX(1,LWORK))

    On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

  • LWORK – [in]

    LWORK is INTEGER

    The dimension of the array WORK. LWORK must be at least 1.

    The exact minimum amount of workspace needed depends on M, N and NRHS. As long as LWORK is at least

    2 * N + N * NRHS

    if M is greater than or equal to N or

    2 * M + M * NRHS

    if M is less than N, the code will execute correctly.

    For good performance, LWORK should generally be larger.

    If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the array WORK and the minimum sizes of the arrays RWORK and IWORK, and returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK is issued by XERBLA.

  • RWORK – [out]

    RWORK is REAL array, dimension (MAX(1,LRWORK))

    LRWORK >=

    10*N + 2*N*SMLSIZ + 8*N*NLVL + 3*SMLSIZ*NRHS +

    MAX( (SMLSIZ+1)**2, N*(1+NRHS) + 2*NRHS )

    if M is greater than or equal to N or

    10*M + 2*M*SMLSIZ + 8*M*NLVL + 3*SMLSIZ*NRHS +

    MAX( (SMLSIZ+1)**2, N*(1+NRHS) + 2*NRHS )

    if M is less than N, the code will execute correctly.

    SMLSIZ is returned by ILAENV and is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about 25), and NLVL = MAX( 0, INT( LOG_2( MIN( M,N )/(SMLSIZ+1) ) ) + 1 )

    On exit, if INFO = 0, RWORK(1) returns the minimum LRWORK.

  • IWORK – [out]

    IWORK is INTEGER array, dimension (MAX(1,LIWORK))

    LIWORK >= fla_max(1, 3*MINMN*NLVL + 11*MINMN), where MINMN = MIN( M,N ).

    On exit, if INFO = 0, IWORK(1) returns the minimum LIWORK.

  • INFO – [out]

    INFO is 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.

template<typename T, typename Ta>
void gelsd(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, Ta *s, Ta *rcond, integer *rank, T *work, integer *lwork, Ta *rwork, integer *iwork, integer *info)#

GELSY#

group gelsy

Functions

template<typename T>
void gelsy(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, integer *jpvt, T rcond, integer *rank, T *work, integer *lwork, integer *info)#

GELSY solves overdetermined or underdetermined systems for GE matrices.

Purpose:

   GELSY computes the minimum-norm solution to a real linear least
   squares problem:
      minimize || A * X - B ||
   using a complete orthogonal factorization 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 routine first computes a QR factorization with column pivoting:
      A * P = Q * [ R11 R12 ]
                  [  0  R22 ]
   with R11 defined as the largest leading submatrix whose estimated
   condition number is less than 1/RCOND.  The order of R11, RANK,
   is the effective rank of A.

   Then, R22 is considered to be negligible, and R12 is annihilated
   by orthogonal transformations from the right, arriving at the
   complete orthogonal factorization:
     A * P = Q * [ T11 0 ] * Z
                 [  0  0 ]
   The minimum-norm solution is then
     X = P * Z**T [ inv(T11)*Q1**T*B ]
                  [        0         ]
   where Q1 consists of the first RANK columns of Q.

   This routine is basically identical to the original xGELSX except
   three differences:
    o The call to the subroutine xGEQPF has been substituted by the
      the call to the subroutine xGEQP3. This subroutine is a Blas-3
      version of the QR factorization with column pivoting.
    o Matrix B (the right hand side) is updated with Blas-3.
    o The permutation of matrix B (the right hand side) is faster and
      more simple.

Parameters:
  • M – [in]

    M is INTEGER

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

  • N – [in]

    N is INTEGER

    The number of columns of the matrix A. N >= 0.

  • NRHS – [in]

    NRHS is INTEGER

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

  • A – [inout]

    A is REAL array, dimension (LDA,N)

    On entry, the M-by-N matrix A.

    On exit, A has been overwritten by details of its complete orthogonal factorization.

  • LDA – [in]

    LDA is INTEGER

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

  • B – [inout]

    B is REAL array, dimension (LDB,NRHS)

    On entry, the M-by-NRHS right hand side matrix B.

    On exit, the N-by-NRHS solution matrix X.

  • LDB – [in]

    LDB is INTEGER

    Computes row and column scaling to reduce condition number of matrix B

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

  • JPVT – [inout]

    JPVT is INTEGER array, dimension (N)

    On entry, if JPVT(i) .ne. 0, the i-th column of A is permuted to the front of AP, otherwise column i is a free column.

    On exit, if JPVT(i) = k, then the i-th column of AP was the k-th column of A.

  • RCOND – [in]

    RCOND is REAL

    RCOND is used to determine the effective rank of A, which is defined as the order of the largest leading triangular submatrix R11 in the QR factorization with pivoting of A, whose estimated condition number < 1/RCOND.

  • RANK – [out]

    RANK is INTEGER

    The effective rank of A, i.e., the order of the submatrix R11. This is the same as the order of the submatrix T11 in the complete orthogonal factorization of A.

  • WORK – [out]

    WORK is REAL array, dimension (MAX(1,LWORK))

    On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

  • LWORK – [in]

    LWORK is INTEGER

    The dimension of the array WORK. The unblocked strategy requires that: LWORK >= MAX( MN+3*N+1, 2*MN+NRHS ), where MN = min( M, N ).

    The block algorithm requires that: LWORK >= MAX( MN+2*N+NB*(N+1), 2*MN+NB*NRHS ), where NB is an upper bound on the blocksize returned by ILAENV for the routines SGEQP3, STZRZF, STZRQF, SORMQR, and SORMRZ.

    If LWORK = -1, then a workspace query is assumed; 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 – [out]

    INFO is INTEGER

    = 0: successful exit

    < 0: If INFO = -i, the i-th argument had an illegal value.

template<typename T, typename Ta>
void gelsy(integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, integer *jpvt, Ta rcond, integer *rank, T *work, integer *lwork, Ta *rwork, integer *info)#

GETSLS#

group getsls

Functions

template<typename T>
void getsls(char *trans, integer *m, integer *n, integer *nrhs, T *a, integer *lda, T *b, integer *ldb, T *work, integer *lwork, integer *info)#

GETSLS solves overdetermined or underdetermined real linear systems.

Purpose:

  GETSLS solves overdetermined or underdetermined real linear systems
  involving an M-by-N matrix A, using a tall skinny QR or short wide 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.

Parameters:
  • TRANS – [in]

    TRANS is CHARACTER*1

    = ‘N’: the linear system involves A;

    = ‘T’: the linear system involves A**T.

  • M – [in]

    M is INTEGER

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

  • N – [in]

    N is INTEGER

    The number of columns of the matrix A. N >= 0.

  • NRHS – [in]

    NRHS is INTEGER

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

  • A – [inout]

    A is REAL array, dimension (LDA,N)

    On entry, the M-by-N matrix A.

    On exit, A is overwritten by details of its QR or LQ factorization as returned by SGEQR or SGELQ.

  • LDA – [in]

    LDA is INTEGER

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

  • B – [inout]

    B is REAL 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 = ‘T’.

    On exit, if INFO = 0, 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.

    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.

  • LDB – [in]

    LDB is INTEGER

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

  • WORK – [out]

    (workspace) COMPLEX array, dimension (MAX(1,LWORK))

    On exit, if INFO = 0, WORK(1) contains optimal (or either minimal or optimal, if query was assumed) LWORK. See LWORK for details.

  • LWORK – [in]

    LWORK is INTEGER

    The dimension of the array WORK.

    If LWORK = -1 or -2, then a workspace query is assumed.

    If LWORK = -1, the routine calculates optimal size of WORK for the optimal performance and returns this value in WORK(1).

    If LWORK = -2, the routine calculates minimal size of WORK and returns this value in WORK(1).

  • INFO – [out]

    INFO is INTEGER

    = 0: successful exit

    < 0: if INFO = -i, the i-th argument had an illegal value

    > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.