Merge pull request #924 from TiborGY/master

Clarify documentation of singularity/rank-deficiency checks

Author: langou

SRC/cgels.f

@@ -37,7 +37,17 @@
 *>
 *> CGELS solves overdetermined or underdetermined complex linear systems
 *> involving an M-by-N matrix A, or its conjugate-transpose, using a QR
-*> or LQ factorization of A.  It is assumed that A has full rank.
+*> or LQ factorization of A.
+*>
+*> It is assumed that A has full rank, and only a rudimentary protection
+*> against rank-deficient matrices is provided. This subroutine only detects
+*> exact rank-deficiency, where a diagonal element of the triangular factor
+*> of A is exactly zero.
+*>
+*> It is conceivable for one (or more) of the diagonal elements of the triangular
+*> factor of A to be subnormally tiny numbers without this subroutine signalling
+*> an error. The solutions computed for such almost-rank-deficient matrices may
+*> be less accurate due to a loss of numerical precision.
 *>
 *> The following options are provided:
 *>
@@ -161,7 +171,7 @@
 *>          = 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
+*>                triangular factor of A is exactly zero, so that A does not have
 *>                full rank; the least squares solution could not be
 *>                computed.
 *> \endverbatim

SRC/cgelst.f

@@ -38,7 +38,16 @@
 *> CGELST solves overdetermined or underdetermined real linear systems
 *> involving an M-by-N matrix A, or its conjugate-transpose, using a QR
 *> or LQ factorization of A with compact WY representation of Q.
-*> It is assumed that A has full rank.
+*>
+*> It is assumed that A has full rank, and only a rudimentary protection
+*> against rank-deficient matrices is provided. This subroutine only detects
+*> exact rank-deficiency, where a diagonal element of the triangular factor
+*> of A is exactly zero.
+*>
+*> It is conceivable for one (or more) of the diagonal elements of the triangular
+*> factor of A to be subnormally tiny numbers without this subroutine signalling
+*> an error. The solutions computed for such almost-rank-deficient matrices may
+*> be less accurate due to a loss of numerical precision.
 *>
 *> The following options are provided:
 *>
@@ -163,7 +172,7 @@
 *>          = 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
+*>                triangular factor of A is exactly zero, so that A does not have
 *>                full rank; the least squares solution could not be
 *>                computed.
 *> \endverbatim

SRC/cgetsls.f

@@ -22,8 +22,17 @@
 *>
 *> CGETSLS solves overdetermined or underdetermined complex 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.
+*> factorization of A.
 *>
+*> It is assumed that A has full rank, and only a rudimentary protection
+*> against rank-deficient matrices is provided. This subroutine only detects
+*> exact rank-deficiency, where a diagonal element of the triangular factor
+*> of A is exactly zero.
+*>
+*> It is conceivable for one (or more) of the diagonal elements of the triangular
+*> factor of A to be subnormally tiny numbers without this subroutine signalling
+*> an error. The solutions computed for such almost-rank-deficient matrices may
+*> be less accurate due to a loss of numerical precision.
 *>
 *>
 *> The following options are provided:
@@ -141,7 +150,7 @@
 *>          = 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
+*>                triangular factor of A is exactly zero, so that A does not have
 *>                full rank; the least squares solution could not be
 *>                computed.
 *> \endverbatim

SRC/cggglm.f

@@ -61,6 +61,16 @@
 *>                  x
 *>
 *> where inv(B) denotes the inverse of B.
+*>
+*> Callers of this subroutine should note that the singularity/rank-deficiency checks
+*> implemented in this subroutine are rudimentary. The CTRTRS subroutine called by this
+*> subroutine only signals a failure due to singularity if the problem is exactly singular.
+*>
+*> It is conceivable for one (or more) of the factors involved in the generalized QR
+*> factorization of the pair (A, B) to be subnormally close to singularity without this
+*> subroutine signalling an error. The solutions computed for such almost-rank-deficient
+*> problems may be less accurate due to a loss of numerical precision.
+*> 
 *> \endverbatim
 *
 *  Arguments:
@@ -159,12 +169,12 @@
 *>          = 0:  successful exit.
 *>          < 0:  if INFO = -i, the i-th argument had an illegal value.
 *>          = 1:  the upper triangular factor R associated with A in the
-*>                generalized QR factorization of the pair (A, B) is
+*>                generalized QR factorization of the pair (A, B) is exactly
 *>                singular, so that rank(A) < M; the least squares
 *>                solution could not be computed.
 *>          = 2:  the bottom (N-M) by (N-M) part of the upper trapezoidal
 *>                factor T associated with B in the generalized QR
-*>                factorization of the pair (A, B) is singular, so that
+*>                factorization of the pair (A, B) is exactly singular, so that
 *>                rank( A B ) < N; the least squares solution could not
 *>                be computed.
 *> \endverbatim

SRC/cgglse.f

@@ -52,6 +52,16 @@
 *> matrices (B, A) given by
 *>
 *>    B = (0 R)*Q,   A = Z*T*Q.
+*>
+*> Callers of this subroutine should note that the singularity/rank-deficiency checks
+*> implemented in this subroutine are rudimentary. The CTRTRS subroutine called by this
+*> subroutine only signals a failure due to singularity if the problem is exactly singular.
+*>
+*> It is conceivable for one (or more) of the factors involved in the generalized RQ
+*> factorization of the pair (B, A) to be subnormally close to singularity without this
+*> subroutine signalling an error. The solutions computed for such almost-rank-deficient
+*> problems may be less accurate due to a loss of numerical precision.
+*> 
 *> \endverbatim
 *
 *  Arguments:
@@ -153,12 +163,12 @@
 *>          = 0:  successful exit.
 *>          < 0:  if INFO = -i, the i-th argument had an illegal value.
 *>          = 1:  the upper triangular factor R associated with B in the
-*>                generalized RQ factorization of the pair (B, A) is
+*>                generalized RQ factorization of the pair (B, A) is exactly
 *>                singular, so that rank(B) < P; the least squares
 *>                solution could not be computed.
 *>          = 2:  the (N-P) by (N-P) part of the upper trapezoidal factor
 *>                T associated with A in the generalized RQ factorization
-*>                of the pair (B, A) is singular, so that
+*>                of the pair (B, A) is exactly singular, so that
 *>                rank( (A) ) < N; the least squares solution could not
 *>                    ( (B) )
 *>                be computed.

SRC/ctbtrs.f

@@ -39,8 +39,14 @@
 *>
 *>    A * X = B,  A**T * X = B,  or  A**H * X = B,
 *>
-*> where A is a triangular band matrix of order N, and B is an
-*> N-by-NRHS matrix.  A check is made to verify that A is nonsingular.
+*> where A is a triangular band matrix of order N, and B is an N-by-NRHS matrix.
+*>
+*> This subroutine verifies that A is nonsingular, but callers should note that only exact
+*> singularity is detected. It is conceivable for one or more diagonal elements of A to be
+*> subnormally tiny numbers without this subroutine signalling an error.
+*>
+*> If a possible loss of numerical precision due to near-singular matrices is a concern, the
+*> caller should verify that A is nonsingular within some tolerance before calling this subroutine.
 *> \endverbatim
 *
 *  Arguments:
@@ -125,7 +131,7 @@
 *>          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 A is zero,
+*>          > 0:  if INFO = i, the i-th diagonal element of A is exactly zero,
 *>                indicating that the matrix is singular and the
 *>                solutions X have not been computed.
 *> \endverbatim

SRC/ctptrs.f

@@ -38,9 +38,14 @@
 *>
 *>    A * X = B,  A**T * X = B,  or  A**H * X = B,
 *>
-*> where A is a triangular matrix of order N stored in packed format,
-*> and B is an N-by-NRHS matrix.  A check is made to verify that A is
-*> nonsingular.
+*> where A is a triangular matrix of order N stored in packed format, and B is an N-by-NRHS matrix.
+*>
+*> This subroutine verifies that A is nonsingular, but callers should note that only exact
+*> singularity is detected. It is conceivable for one or more diagonal elements of A to be
+*> subnormally tiny numbers without this subroutine signalling an error.
+*>
+*> If a possible loss of numerical precision due to near-singular matrices is a concern, the
+*> caller should verify that A is nonsingular within some tolerance before calling this subroutine.
 *> \endverbatim
 *
 *  Arguments:
@@ -110,7 +115,7 @@
 *>          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 A is zero,
+*>          > 0:  if INFO = i, the i-th diagonal element of A is exactly zero,
 *>                indicating that the matrix is singular and the
 *>                solutions X have not been computed.
 *> \endverbatim

SRC/ctrtrs.f

@@ -39,8 +39,14 @@
 *>
 *>    A * X = B,  A**T * X = B,  or  A**H * X = B,
 *>
-*> where A is a triangular matrix of order N, and B is an N-by-NRHS
-*> matrix.  A check is made to verify that A is nonsingular.
+*> where A is a triangular matrix of order N, and B is an N-by-NRHS matrix.
+*>
+*> This subroutine verifies that A is nonsingular, but callers should note that only exact
+*> singularity is detected. It is conceivable for one or more diagonal elements of A to be
+*> subnormally tiny numbers without this subroutine signalling an error.
+*>
+*> If a possible loss of numerical precision due to near-singular matrices is a concern, the
+*> caller should verify that A is nonsingular within some tolerance before calling this subroutine.
 *> \endverbatim
 *
 *  Arguments:
@@ -119,7 +125,7 @@
 *>          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 A is zero,
+*>          > 0:  if INFO = i, the i-th diagonal element of A is exactly zero,
 *>               indicating that the matrix is singular and the solutions
 *>               X have not been computed.
 *> \endverbatim

SRC/dgels.f

@@ -37,7 +37,17 @@
 *>
 *> DGELS 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.
+*> factorization of A.
+*>
+*> It is assumed that A has full rank, and only a rudimentary protection
+*> against rank-deficient matrices is provided. This subroutine only detects
+*> exact rank-deficiency, where a diagonal element of the triangular factor
+*> of A is exactly zero.
+*>
+*> It is conceivable for one (or more) of the diagonal elements of the triangular
+*> factor of A to be subnormally tiny numbers without this subroutine signalling
+*> an error. The solutions computed for such almost-rank-deficient matrices may
+*> be less accurate due to a loss of numerical precision.
 *>
 *> The following options are provided:
 *>
@@ -162,7 +172,7 @@
 *>          = 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
+*>                triangular factor of A is exactly zero, so that A does not have
 *>                full rank; the least squares solution could not be
 *>                computed.
 *> \endverbatim

SRC/dgelst.f

@@ -38,7 +38,16 @@
 *> DGELST 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 with compact WY representation of Q.
-*> It is assumed that A has full rank.
+*>
+*> It is assumed that A has full rank, and only a rudimentary protection
+*> against rank-deficient matrices is provided. This subroutine only detects
+*> exact rank-deficiency, where a diagonal element of the triangular factor
+*> of A is exactly zero.
+*>
+*> It is conceivable for one (or more) of the diagonal elements of the triangular
+*> factor of A to be subnormally tiny numbers without this subroutine signalling
+*> an error. The solutions computed for such almost-rank-deficient matrices may
+*> be less accurate due to a loss of numerical precision.
 *>
 *> The following options are provided:
 *>
@@ -163,7 +172,7 @@
 *>          = 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
+*>                triangular factor of A is exactly zero, so that A does not have
 *>                full rank; the least squares solution could not be
 *>                computed.
 *> \endverbatim