Skip to content

Add runnable examples for column selection, interval solves, and exact rational dots #327

Closed

Description

@acgetchell

Summary

Target v0.5.3. Make the v0.5.2 public additions easy to learn through runnable examples: add focused column-selection and interval-solve programs, extend the existing rational-input example with exact dot products, and retain the existing polynomial example.

Current State

  • examples/polynomial_determinant.rs already demonstrates exact cancellation, borrowed leading coefficients, and typed work-budget exhaustion.
  • examples/rational_input_5x5.rs demonstrates an exact rational solve whose binary64 reconstruction becomes singular, but does not use RationalVector::dot or rational_dot.
  • Column selection and interval division/solve have tested rustdoc examples, but no standalone runnable programs under examples/.
  • The release measurement declaration captures examples/**/*.rs in the harness identity. These executable changes are deliberately deferred until v0.5.3 to preserve the collected v0.5.2 evidence. Do not edit captured examples, relabel evidence, or restart that release's measurements as part of this follow-up.

Related API work: #305 (rational dots), #306 (column selection), #307 (interval division/solve), and #308 (polynomial determinants). Those APIs are already implemented; they are references, not new blockers. Related benchmark workstream: #326.

Proposed Changes

  1. Add a column-selection example, such as examples/column_basis.rs, using a small rectangular matrix, an explicit validated absolute tolerance, and independently known selected columns. Show checking the returned rank before using a square selected minor, and explain that the result is provisional numerical rank even at zero tolerance. Demonstrate a partial selection without turning it into an exact singularity claim. Link to the existing exact-certification guide where appropriate.
  2. Add an interval-solve example, such as examples/interval_solve.rs, covering zero-free division/reciprocal, a small system with analytically known solution enclosure, and explicit handling of IntervalSolveInconclusive / IntervalRangeExhausted as fallback requirements. Distinguish zero-containing divisor rejection from an inconclusive solve; neither proves singularity. Keep the successful enclosure contract for every independently admitted system clear.
  3. Extend examples/rational_input_5x5.rs with an exact objective/dot product evaluated on its existing exact solution. Exercise both the prepared RationalVector::dot and borrowed-slice rational_dot entry points, check an independently calculated exact rational result, and avoid intermediate f64 conversion. Demonstrate the checked slice contract without adding a redundant standalone dot-product program.
  4. Retain examples/polynomial_determinant.rs as the canonical runnable polynomial workflow. Add or improve discovery links if needed; do not duplicate its cancellation/budget example.
  5. Update README Examples/API links and the code-organization map. Let the existing Cargo-metadata discovery in just examples run the new binaries; add manifest/feature-policy entries only where actually required. Keep default-feature examples independent of exact.

Benefits

New users can run coherent public workflows from the repository without searching tests or assembling fragments, while the README stays concise and links to authoritative contracts.

Implementation Notes and Acceptance

  • Each example uses public APIs, propagates ordinary errors with Result, and contains meaningful assertions against independently known values or exact typed error fields. Do not weaken supported-success cases to make an example pass.
  • Preserve feature, numerical and resource boundaries: provisional basis versus exact certification; interval enclosure versus approximate solve; exact dot arithmetic; and explicit polynomial work limits without claiming a byte/time bound.
  • just examples discovers and executes all new/extended programs under their correct feature configuration. No benchmark acquisition is required for example validation.
  • Run focused Rust formatting/lint checks for the examples, just markdown-fix, just markdown-ci, just doc-check, and the required default/exact doctest checks. Keep generic runner tests upstream; assertions belong in the executable examples.
  • Update docs/code_organization.md and README navigation together. Preserve the current release's generated reports and source/harness identity; new measurement identity belongs to the later release plan.
  • Astra checkpoint: not required for routine examples of these settled APIs. Request Astra only if implementation exposes a new mathematical claim, certification gap, or proposed public-contract change.

This is consumer-owned documentation/example work with no new upstream research-repo-tools capability or dependency required. Do not change package versions, commit, push, or run long measurements without separate authorization.

Activity

  1. added this to the v0.5.3 milestone on Oct 29, 2026
  2. added
    documentationImprovements or additions to documentation
    rustPull requests that update rust code
    testingIssues that come up in testing
    on Oct 29, 2026
  3. added a commit that references this issue on Nov 9, 2026
    647184f
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 codetestingIssues that come up in testing

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions