Repository navigation
Description
Summary
Target v0.5.3. Make the scientific provenance and enclosure arguments discoverable from the public interval API and its shared rounding helpers in src/interval.rs and src/rounding.rs.
Current State
REFERENCES.md owns the bibliography, and docs/mathematical_basis.md explains scalar outward rounding, division/reciprocals, determinant enclosures, and interval linear solves. Much of the source attribution currently lives in private module/helper documentation. Most public scalar interval methods and determinant methods lack direct reference/proof links; IntervalMatrix::solve links its enclosure proof but cites reference [20] as plain text.
The v0.5.2 measurement policy fingerprints the complete bytes of src/**/*.rs, including comments. These rustdoc edits are deliberately deferred until v0.5.3 so they do not invalidate the collected v0.5.2 source identity. Standalone Markdown improvements are separate because those files are outside the source and harness inventories.
Related: #307 (implemented interval division/solve APIs) and #327 (runnable examples). These are related work, not blocking dependencies. No upstream research-repo-tools change is needed.
Proposed Changes
- Add concise, clickable reference and mathematical-basis links to
IntervalandIntervalMatrixdocumentation and the relevant public methods:try_from_subtraction,try_add,try_mul,try_square,try_div,try_recip,det,det_sign, andsolve. Keep the bibliography and detailed derivations in their existing owning documents. - Improve nearby attribution in
src/rounding.rs: magnitude-ordered FastTwoSum and its assumptions ([17]); TwoProductFMA in the safe residual range ([18]); binary64 decomposition ([9]); and the local exact integer comparison for products and quotients. Link the residual-underflow threshold and quotient-comparison arguments. Do not imply that TwoProductFMA supplies an error-free division residual. - Distinguish standard foundations from crate-specific implementation arguments: interval inclusion arithmetic ([14], [20]), the Leibniz identity ([12]), the subset-DP organization, and the fixed-pivot interval solve proof.
- Use published-destination links and stable citation/section anchors that work in ordinary public rustdoc, including docs.rs. Preserve the existing public contracts, typed failures, and feature boundaries.
Benefits
Users can reach the scientific justification directly from the API they are using, without searching private modules or guessing which bibliography entry supports a guarantee.
Implementation Notes and Acceptance
- The listed public methods/types and relevant private helpers have appropriate nearby attribution or a precise link to the owning explanation.
- Preserve finite endpoints, zero-free divisor requirements, gradual-underflow handling, determinant zero versus inconclusive evidence, and the solve guarantee for every independently admitted system. Do not claim IEEE 1788 conformance or tight solution bounds.
- Keep changes confined to documentation unless a separately reviewed correctness issue requires implementation work. Preserve stable reference numbers and existing links.
- Run
just doc-checkfor default/exact documentation and inspect rendered links/anchors; run the required Markdown/spelling and formatting checks. Run default/exact doctests if executable examples change. No benchmark campaign is needed merely to validate documentation. - Land this work before the v0.5.3 measurement identity is captured. Preserve v0.5.2 reports and evidence under their original identities; do not relax fingerprint checks or relabel old measurements.
- Astra checkpoint: not required for attribution and navigation over settled contracts. Request Astra if the work exposes a new or disputed numerical guarantee, proof gap, or proposed mathematical-contract change.
No commits, pushes, tags, release commands, or long measurements are authorized by this planning issue alone.
Activity
chore(release): prepare v0.5.2