Repository navigation
Description
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.rsalready demonstrates exact cancellation, borrowed leading coefficients, and typed work-budget exhaustion.examples/rational_input_5x5.rsdemonstrates an exact rational solve whose binary64 reconstruction becomes singular, but does not useRationalVector::dotorrational_dot.- Column selection and interval division/solve have tested rustdoc examples, but no standalone runnable programs under
examples/. - The release measurement declaration captures
examples/**/*.rsin 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
- 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. - 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 ofIntervalSolveInconclusive/IntervalRangeExhaustedas 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. - Extend
examples/rational_input_5x5.rswith an exact objective/dot product evaluated on its existing exact solution. Exercise both the preparedRationalVector::dotand borrowed-slicerational_dotentry points, check an independently calculated exact rational result, and avoid intermediatef64conversion. Demonstrate the checked slice contract without adding a redundant standalone dot-product program. - Retain
examples/polynomial_determinant.rsas the canonical runnable polynomial workflow. Add or improve discovery links if needed; do not duplicate its cancellation/budget example. - Update README Examples/API links and the code-organization map. Let the existing Cargo-metadata discovery in
just examplesrun the new binaries; add manifest/feature-policy entries only where actually required. Keep default-feature examples independent ofexact.
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 examplesdiscovers 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.mdand 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
docs: add runnable examples and link interval proofs