Clarify documentation of singularity/rank-deficiency checks

[TiborGY]

Description

This PR fixes and closes #918, by changing the relevant parts of the docs.

*TRTRS, *TBTRS and *TPTRS

• In *TRTRS, *TBTRS and *TPTRS, replace A check is made to verify that A is nonsingular. with the following:

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.

• In *TRTRS, *TBTRS and *TPTRS, replace > 0: if INFO = i, the i-th diagonal element of A is zero, with > 0: if INFO = i, the i-th diagonal element of A is exactly zero,

Callers of *TRTRS: *GELS, *GELST, *GETSLS, *GGLSE, *GGGLM

• In *GELS, *GELST, *GETSLS replace It is assumed that A has full rank. with the following:

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.

• In *GELS, *GELST, *GETSLS replace > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is zero with > 0: if INFO = i, the i-th diagonal element of the triangular factor of A is exactly zero
• In *GGLSE, add the following:

Callers of this subroutine should note that the singularity/rank-deficiency checks
implemented in this subroutine are rudimentary. The <S,D,C,Z>TRTRS 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.

• In *GGLSE, replace RQ factorization of the pair (B, A) is singular with RQ factorization of the pair (B, A) is exactly singular
• In *GGGLM, add the following:

Callers of this subroutine should note that the singularity/rank-deficiency checks
implemented in this subroutine are rudimentary. The <S,D,C,Z>TRTRS 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.

• In *GGGLM, replace QR factorization of the pair (A, B) is singular with QR factorization of the pair (A, B) is exactly singular

Callers of *TBTRS:

• Apart from the testing subroutines, there appear to be no internal callers of *TBTRS in LAPACK.

Callers of *TPTRS:

• Apart from the testing subroutines, there appear to be no internal callers of *TPTRS in LAPACK.

Checklist

• The documentation has been updated.
• If the PR solves a specific issue, it is set to be closed on merge.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (04b044e) 0.00% compared to head (22e01f8) 0.00%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #924   +/-   ##
=======================================
  Coverage    0.00%    0.00%           
=======================================
  Files        1930     1930           
  Lines      190055   190055           
=======================================
  Misses     190055   190055           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[TiborGY]

Please note that I am still working on this PR, it is not ready for merge yet. Hence the draft status.

[TiborGY]

This is now ready for review and merge.

[TiborGY]

@langou If there are no objections, this is ready for merge when convenient.