docs(science): add mathematical basis and clarify numerical guarantees

[acgetchell]

• define the binary64, factorization, determinant-filter, exact-arithmetic, tolerance, and error contracts
• align README, API documentation, examples, and LDLT diagnostics with guarantees over stored values
• audit academic references and extend Criterion coverage for determinant error-bound paths

Closes#159
Closes#164

Summary by CodeRabbit

• Documentation

  • Added a new “Mathematical basis” page covering numerical guarantees, exact arithmetic semantics, and API usage boundaries.
  • Expanded/rewrote README and reference materials, including improved wording for determinant error bounds, LDLT behavior, LU limitations, and exactness guarantees.
  • Refined citations and example guidance; updated contribution references and badges.

• Bug Fixes

  • Updated user-facing error messages for LDLT non–positive-semi-definite cases to better reflect computed numerical conditions.

• Tests

  • Strengthened exact determinant benchmark baselines and comparison logic, including certified error-bound coverage.
  • Improved benchmark comparison tooling tests and validation of LU determinant verification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 22fd1535-d662-4b72-a4d8-df3921d7c995

📥 Commits

Reviewing files that changed from the base of the PR and between 31b7b1e and e257343.

📒 Files selected for processing (5)

• AGENTS.md
• CITATION.cff
• docs/mathematical_basis.md
• scripts/tests/test_bench_compare.py
• src/ldlt.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/mathematical_basis.md
• src/ldlt.rs

---

📝 Walkthrough

Walkthrough

The PR adds a mathematical-basis document, revises numerical and LDLT documentation, relocates internal symmetry plumbing, expands certified determinant benchmarks, and updates compatibility-aware benchmark comparison behavior.

Changes

Numerical contracts and validation

Layer / File(s)	Summary
Mathematical basis and API documentation README.md, docs/mathematical_basis.md, REFERENCES.md, src/exact.rs, examples/*, CONTRIBUTING.md, AGENTS.md, CITATION.cff, justfile, typos.toml	Documents stored-binary64 semantics, factorization scope, exact arithmetic, determinant filtering, API boundaries, references, examples, and repository tooling metadata.
LDLT contracts and internal symmetry plumbing src/error.rs, src/ldlt.rs, src/lib.rs, src/matrix.rs, src/lu.rs	Clarifies LDLT rejection diagnostics and determinant contracts, relocates the crate-private SymmetricMatrix, and updates factorization documentation.
Certified determinant benchmark coverage benches/*, tests/exact_bench_config.rs, tests/vs_linalg_inputs.rs, docs/BENCHMARKING.md	Adds certified-bound and paired determinant baselines, validates bounds against exact oracles, and documents supported benchmark variants and compatibility differences.
Compatibility-aware benchmark comparison scripts/bench_compare.py, scripts/tests/test_bench_compare.py	Adds exact determinant filter rows, models unavailable v0.4.3 baselines through comparison policy, and tests coverage and provenance behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• acgetchell/la-stack#45: Adds related determinant error-bound benchmark validation.
• acgetchell/la-stack#143: Updates the same benchmark comparison workflow.
• acgetchell/la-stack#182: Strengthens validation of determinant error bounds.

Suggested labels:documentation, performance, testing

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The justfile rumdl version bump and typos.toml edit are unrelated to the requested docs and badge work.	Drop the tooling/version and typo-dictionary changes unless they are required for the docs/badge work.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding a mathematical basis and clarifying numerical guarantees.
Linked Issues check	✅ Passed	The README badge updates and new mathematical-basis docs align with issues #159 and #164.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/159-mathematical-basis

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.87%. Comparing base (b1e431a) to head (e257343).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@ Coverage Diff @@## main #187 +/- ##
=======================================
Coverage 97.87% 97.87% =======================================
Files 8 8 Lines 4944 4947 +3 =======================================
+ Hits 4839 4842 +3 
Misses 105 105 

Flag	Coverage Δ
unittests	97.87% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/mathematical_basis.md`:
- Line 201: Update the determinant/sign test table row containing
det_direct_with_errbound so the absolute-value notation around estimate does not
create Markdown table separators; escape the pipe characters or replace the
notation with equivalent wording. Then run just markdown-check and just
markdown-fix.
In `@scripts/bench_compare.py`:
- Around line 800-816: Add a focused test covering the baseline_unavailable and
missing_current branch in the comparison flow, asserting that it emits a
CoverageGap with suite="exact", the expected group and bench identifiers,
missing_current=True, and missing_baseline=False. Reuse the existing test
fixtures and setup for policy-driven baseline-unavailable scenarios.
In `@src/ldlt.rs`:
- Around line 27-37: Update the public LDLT documentation near
`factor_symmetric` and `Matrix::ldlt` to distinguish zero-pivot errors: an
uncoupled zero pivot returns `LaError::Singular`, while a zero pivot with
non-zero remaining coupling returns `LaError::NotPositiveSemidefinite`; retain
the existing tolerance-small positive pivot behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fd400d48-79b9-483b-941c-c2758d07ab1f

📥 Commits

Reviewing files that changed from the base of the PR and between b1e431a and 31b7b1e.

📒 Files selected for processing (23)

• CONTRIBUTING.md
• README.md
• REFERENCES.md
• benches/common/exact.rs
• benches/exact.rs
• benches/vs_linalg.rs
• docs/BENCHMARKING.md
• docs/mathematical_basis.md
• examples/exact_det_3x3.rs
• examples/exact_sign_3x3.rs
• examples/exact_solve_3x3.rs
• justfile
• scripts/bench_compare.py
• scripts/tests/test_bench_compare.py
• src/error.rs
• src/exact.rs
• src/ldlt.rs
• src/lib.rs
• src/lu.rs
• src/matrix.rs
• tests/exact_bench_config.rs
• tests/vs_linalg_inputs.rs
• typos.toml

💤 Files with no reviewable changes (1)

• src/lib.rs