Skip to content

Clarify documentation of singularity/rank-deficiency checks#924

Merged
langou merged 8 commits intoReference-LAPACK:masterfrom
TiborGY:master
Jul 25, 2024
Merged

Clarify documentation of singularity/rank-deficiency checks#924
langou merged 8 commits intoReference-LAPACK:masterfrom
TiborGY:master

Conversation

@TiborGY
Copy link
Copy Markdown

@TiborGY TiborGY commented Nov 1, 2023 •
edited
Loading

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
Copy link
Copy Markdown

codecov bot commented Nov 2, 2023 •
edited
Loading

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.

langou
langou previously approved these changes Nov 2, 2023
View reviewed changes
@TiborGY
Copy link
Copy Markdown
Author

TiborGY commented Nov 2, 2023

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

langou
langou previously approved these changes Nov 13, 2023
View reviewed changes
@TiborGY TiborGY marked this pull request as ready for review November 26, 2023 17:59
@TiborGY
Copy link
Copy Markdown
Author

TiborGY commented Nov 26, 2023

This is now ready for review and merge.

@TiborGY
Copy link
Copy Markdown
Author

TiborGY commented Feb 11, 2024

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

@langou langou merged commit 3c351aa into Reference-LAPACK:master Jul 25, 2024
@chenrui333 chenrui333 mentioned this pull request Jan 9, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@langou langou langou approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Documentation for *TRTRS should note it only detects exact singularity

2 participants

@TiborGY @langou