diff --git a/SRC/cgels.f b/SRC/cgels.f index 740bac890..4dda66f91 100644 --- a/SRC/cgels.f +++ b/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 diff --git a/SRC/cgelst.f b/SRC/cgelst.f index 0178c53dc..fe0ea3be8 100644 --- a/SRC/cgelst.f +++ b/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 diff --git a/SRC/cgetsls.f b/SRC/cgetsls.f index 606e81437..87bf2dd71 100644 --- a/SRC/cgetsls.f +++ b/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 diff --git a/SRC/cggglm.f b/SRC/cggglm.f index 60828cf68..1e666a366 100644 --- a/SRC/cggglm.f +++ b/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 diff --git a/SRC/cgglse.f b/SRC/cgglse.f index 6fbd71d1b..836d3496f 100644 --- a/SRC/cgglse.f +++ b/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. diff --git a/SRC/ctbtrs.f b/SRC/ctbtrs.f index e5da1aeae..cb62eb339 100644 --- a/SRC/ctbtrs.f +++ b/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 diff --git a/SRC/ctptrs.f b/SRC/ctptrs.f index 456e1b782..368f58ec9 100644 --- a/SRC/ctptrs.f +++ b/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 diff --git a/SRC/ctrtrs.f b/SRC/ctrtrs.f index e17785402..18b493c83 100644 --- a/SRC/ctrtrs.f +++ b/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 diff --git a/SRC/dgels.f b/SRC/dgels.f index 90b2c91aa..2376330a1 100644 --- a/SRC/dgels.f +++ b/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 diff --git a/SRC/dgelst.f b/SRC/dgelst.f index aadb5af57..24129517e 100644 --- a/SRC/dgelst.f +++ b/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 diff --git a/SRC/dgetsls.f b/SRC/dgetsls.f index 73b505ff7..9db9b491c 100644 --- a/SRC/dgetsls.f +++ b/SRC/dgetsls.f @@ -22,8 +22,17 @@ *> *> DGETSLS 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. +*> 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 diff --git a/SRC/dggglm.f b/SRC/dggglm.f index 56a168415..1fe366e73 100644 --- a/SRC/dggglm.f +++ b/SRC/dggglm.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 DTRTRS 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 diff --git a/SRC/dgglse.f b/SRC/dgglse.f index 45e89eebe..181a42373 100644 --- a/SRC/dgglse.f +++ b/SRC/dgglse.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 DTRTRS 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. diff --git a/SRC/dtbtrs.f b/SRC/dtbtrs.f index 166cd0dc3..93e7c5552 100644 --- a/SRC/dtbtrs.f +++ b/SRC/dtbtrs.f @@ -39,8 +39,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/dtptrs.f b/SRC/dtptrs.f index 3b3a8906b..1fb5eebaa 100644 --- a/SRC/dtptrs.f +++ b/SRC/dtptrs.f @@ -38,9 +38,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/dtrtrs.f b/SRC/dtrtrs.f index 184b213e6..2c23850d9 100644 --- a/SRC/dtrtrs.f +++ b/SRC/dtrtrs.f @@ -39,8 +39,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/sgels.f b/SRC/sgels.f index 9a311a825..1630ec239 100644 --- a/SRC/sgels.f +++ b/SRC/sgels.f @@ -37,7 +37,17 @@ *> *> SGELS 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 diff --git a/SRC/sgelst.f b/SRC/sgelst.f index 3c6ccf16f..613a2b0d0 100644 --- a/SRC/sgelst.f +++ b/SRC/sgelst.f @@ -38,7 +38,16 @@ *> SGELST 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 diff --git a/SRC/sgetsls.f b/SRC/sgetsls.f index ce4e02d4f..2946d732e 100644 --- a/SRC/sgetsls.f +++ b/SRC/sgetsls.f @@ -22,8 +22,17 @@ *> *> SGETSLS 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. +*> 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 diff --git a/SRC/sggglm.f b/SRC/sggglm.f index 52c59b8bf..d7b3cb5d7 100644 --- a/SRC/sggglm.f +++ b/SRC/sggglm.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 STRTRS 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 diff --git a/SRC/sgglse.f b/SRC/sgglse.f index 527e7b371..96cb5876e 100644 --- a/SRC/sgglse.f +++ b/SRC/sgglse.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 STRTRS 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. diff --git a/SRC/stbtrs.f b/SRC/stbtrs.f index 103e1d28c..2c59b3616 100644 --- a/SRC/stbtrs.f +++ b/SRC/stbtrs.f @@ -39,8 +39,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/stptrs.f b/SRC/stptrs.f index 556f03c64..71a4e1229 100644 --- a/SRC/stptrs.f +++ b/SRC/stptrs.f @@ -38,9 +38,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/strtrs.f b/SRC/strtrs.f index 6cba2e842..609344c61 100644 --- a/SRC/strtrs.f +++ b/SRC/strtrs.f @@ -39,8 +39,14 @@ *> *> A * X = B or A**T * 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 diff --git a/SRC/zgels.f b/SRC/zgels.f index 2b8913c19..b373d9a22 100644 --- a/SRC/zgels.f +++ b/SRC/zgels.f @@ -37,7 +37,17 @@ *> *> ZGELS 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 diff --git a/SRC/zgelst.f b/SRC/zgelst.f index 09f7ccd7b..9c1767f84 100644 --- a/SRC/zgelst.f +++ b/SRC/zgelst.f @@ -38,7 +38,16 @@ *> ZGELST 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 diff --git a/SRC/zgetsls.f b/SRC/zgetsls.f index 26311c611..20b2278cc 100644 --- a/SRC/zgetsls.f +++ b/SRC/zgetsls.f @@ -22,8 +22,17 @@ *> *> ZGETSLS 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 diff --git a/SRC/zggglm.f b/SRC/zggglm.f index 6a7c3da5f..830193664 100644 --- a/SRC/zggglm.f +++ b/SRC/zggglm.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 ZTRTRS 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 diff --git a/SRC/zgglse.f b/SRC/zgglse.f index abefbae1e..30e7783cc 100644 --- a/SRC/zgglse.f +++ b/SRC/zgglse.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 ZTRTRS 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. diff --git a/SRC/ztbtrs.f b/SRC/ztbtrs.f index d21efe61d..66aface3e 100644 --- a/SRC/ztbtrs.f +++ b/SRC/ztbtrs.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 diff --git a/SRC/ztptrs.f b/SRC/ztptrs.f index cfddc3251..fcc4b0355 100644 --- a/SRC/ztptrs.f +++ b/SRC/ztptrs.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 diff --git a/SRC/ztrtrs.f b/SRC/ztrtrs.f index 728e0a403..c4735f126 100644 --- a/SRC/ztrtrs.f +++ b/SRC/ztrtrs.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