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.
-
template<typename T>
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>
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>
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>
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.
-
template<typename T>