Skip to content

Improve the documentation - #90

Merged
timholy merged 4 commits into
mainfrom
teh/docs-pages
Oct 21, 2026
Merged

timholy merged 4 commits into
mainfrom
teh/docs-pages

Conversation

@timholy

@timholy timholy commented Oct 21, 2026

Copy link
Copy Markdown
Member

This reorganizes the docs into separate pages, improves the exposition and examples, and polishes a bunch of docstrings.

The manual now has five pages:

- Introduction: the definition of a cover, the role of units, an example
  in which a cover exposes a well-conditioned matrix hidden by scaling
  (with the scale-invariant error bound for `A \ y`), cover-scaled
  regularization to make a symmetric matrix positive definite, and
  guidance on which function to use.
- Cover objectives: penalty functions, the solver table, objective-minimal
  covers, and a new section defining transversals and showing why
  tightness on a maximum-product transversal matters for conditioning.
- Solver invariants: covariance, uniqueness, and consuming one factor.
- Starting points and convergence.
- Reference.

The roundoff worked example is replaced by the conditioning example. The
`cover_transversal` docstring now defines a transversal.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Reorder explanations so that definitions and motivation precede details,
replace ad hoc terms with plain statements, and split long list items.

Correct the preconditioner that a zero `fillbudget` or `flopbudget`
selects (the spanning-forest one, not a diagonal one), document the
`strategies` keyword of `symcover_min` and `cover_min` with its defaults,
state which entry `:leaveout` omits, and use zero tolerance in the
`iscover` example, matching the guarantee stated for `cover`.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
When the Cholesky preconditioner exceeds its fill or flop budget, LSQR
falls back to spanning-forest preconditioning, not diagonal.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.84%. Comparing base (d2a7291) to head (1ec016d).

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #90   +/-   ##
=======================================
  Coverage   98.84%   98.84%           
=======================================
  Files          23       23           
  Lines        6303     6303           
=======================================
  Hits         6230     6230           
  Misses         73       73           

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@timholy
timholy merged commit c88a65a into main Oct 21, 2026
7 checks passed
@timholy
timholy deleted the teh/docs-pages branch October 21, 2026 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant