Skip to content

docs: record algebraic floating-point rejection - #281

Merged
acgetchell merged 1 commit into
mainfrom
doc/250-algebraic-float-decision
Oct 15, 2026
Merged

acgetchell merged 1 commit into
mainfrom
doc/250-algebraic-float-decision

Conversation

@acgetchell

@acgetchell acgetchell commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

The #250 evaluation found that an algebraic Matrix::norm_inf reduction could return f64::MAX where strict accumulation must report LaError::NonFinite. This PR records the decision to reject algebraic floating-point operations and retain the existing arithmetic model.

  • Preserve the study, raw evidence archive, measurements, source provenance, and reproduction instructions under docs/archive/performance/studies/.
  • Add docs/validation/ records connecting strict f64, certified bounds, intervals, exact arithmetic, and conversion contracts to their evidence.
  • Update the mathematical basis, navigation, and roadmap, including the README release-link inventory required by CI.

The prototype improved local D=4/5 timings by about 22–25% and D=8 by 39–40%, while D=2/3 regressed. Those measurements describe a rejected prototype, not a correctness-preserving optimization. No library behavior changes. Native Linux/Windows prototype execution was not performed; the records distinguish cross-compilation from native validation and document the maintainer's decision to end that work.

Validation: full just ci passed, including 141 Python tests, 1,002 Rust tests, default/exact doctests, static checks, benchmark compilation, and examples. The archived report also passed explicit Markdown/spelling checks, and all 40 retained Criterion measurements were checked for 100 valid samples. The local full CI run needed to run outside the sandbox because the TOML formatter's macOS system-configuration access crashed inside it.

Closes #250, already closed with the recorded negative decision.

Summary by CodeRabbit

  • Documentation
    • Added a validation guide describing arithmetic guarantees, limitations, and related tests.
    • Documented the decision to retain strict floating-point arithmetic after an evaluation found that reassociation could hide required overflow errors, despite some benchmark improvements.
    • Updated the roadmap and documentation index to link the study and validation records.
  • Chores
    • Updated the README release-check threshold.

- Retain strict arithmetic after the norm reduction prototype hid required overflow errors despite local timing gains.
- Preserve the numerical counterexample, measurements, provenance, and reproducible experimental evidence.
- Map floating-point, certified, interval, and exact arithmetic contracts to validation evidence and record closure of the remaining prototype work.
- Update documentation navigation, release planning, and the reviewed README link inventory.

Closes #250
@acgetchell
acgetchell enabled auto-merge (squash) October 15, 2026 17:34
@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: acgetchell/la-stack/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Team
  • Run ID: fefbd7ed-f05a-4ae4-83e5-4d8e12cc3fc4
📥 Commits

Reviewing files that changed from the base of the PR and between d1f85bb and 2f6c7ad.

⛔ Files ignored due to path filters: 2
  • docs/archive/performance/studies/algebraic-float/evidence.tar.gz is excluded by !**/*.gz
  • docs/archive/performance/studies/algebraic-float/measurements.csv is excluded by !**/*.csv
📒 Files selected for processing: 10
  • README.md
  • docs/archive/performance/studies/README.md
  • docs/archive/performance/studies/algebraic-float.md
  • docs/archive/performance/studies/algebraic-float/provenance.json
  • docs/code_organization.md
  • docs/mathematical_basis.md
  • docs/roadmap.md
  • docs/validation/README.md
  • docs/validation/algebraic-floating-point.md
  • pyproject.toml

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

📝 Walkthrough

The change documents the evaluation of algebraic floating-point operations for Matrix::norm_inf. It records an overflow misclassification in the prototype, retains strict arithmetic, and updates the validation records, arithmetic documentation, roadmap, and documentation links.

Changes: Algebraic Floating-Point Decision

Layer / File(s) Summary
Archived study and evidence
docs/archive/performance/studies/algebraic-float.md, docs/archive/performance/studies/algebraic-float/provenance.json, docs/archive/performance/studies/README.md
The study records the candidate reduction, numerical findings, performance measurements, provenance, and validation scope. It documents the retain-strict decision and links the study from the archive index.
Validation decision and arithmetic contracts
docs/validation/algebraic-floating-point.md, docs/validation/README.md, docs/mathematical_basis.md
The validation record documents the overflow counterexample, test results, and unperformed native Linux and Windows runs. The validation index and mathematical basis describe the arithmetic contracts and link the related records.
Roadmap and documentation references
docs/roadmap.md, docs/code_organization.md, README.md, pyproject.toml
The roadmap records the completed decision and removes the planned v0.5.1 adoption follow-up. Documentation links identify the related records, and the README release rule’s expected match count changes from 31 to 32.

Priority: ⬇️ Low

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

Change: Other

Merge Risk: ⚪ Minimal · up to 2f6c7

This documentation-only change records the arithmetic decision and adds navigation; no actionable merge risk remains.

Pre-merge checks: Passed 4
Passed 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 primary change: documenting the rejection of algebraic floating-point operations and retaining strict arithmetic.
Linked Issues check Passed Issue #250 is closed and provides historical context only. No active directly linked target remains, so this pull request has no active linked-issue coding requirements. The documented retain-strict d…
Out of Scope Changes check Passed The changed files remain within the documented scope of recording the #250 evaluation. The study archive, validation records, mathematical basis, navigation, roadmap, and README release-link rule supp…
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@codecov

codecov Bot commented Oct 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.14%. Comparing base (6592723) to head (2f6c7ad).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #281   +/-   ##
=======================================
  Coverage   98.14%   98.14%           
=======================================
  Files          14       14           
  Lines        7160     7160           
=======================================
  Hits         7027     7027           
  Misses        133      133           
Flag Coverage Δ
unittests 98.14% <ø> (ø)

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.

@acgetchell
acgetchell merged commit a275ddf into main Oct 15, 2026
19 checks passed
@acgetchell
acgetchell deleted the doc/250-algebraic-float-decision branch October 15, 2026 18:03
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.

perf: evaluate algebraic floating point for selected f64 functions

1 participant