Skip to content

Link interval and rounding rustdoc to scientific references and enclosure proofs #328

Closed

Description

@acgetchell

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

  1. Add concise, clickable reference and mathematical-basis links to Interval and IntervalMatrix documentation and the relevant public methods: try_from_subtraction, try_add, try_mul, try_square, try_div, try_recip, det, det_sign, and solve. Keep the bibliography and detailed derivations in their existing owning documents.
  2. 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.
  3. 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.
  4. 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-check for 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationrustPull requests that update rust code

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions