Skip to content

code_organization.md

Latest commit

 

History

History
272 lines (239 loc) · 17.1 KB

code_organization.md

File metadata and controls

272 lines (239 loc) · 17.1 KB
Raw

Code Organization

Module, feature, and file-placement guidance for the published Rust library and its unpublished comparison-benchmark package. Read AGENTS.md for agent rules and use the contributor workflow for setup and validation commands.

Contents

Library modules

src/lib.rs wires private implementation modules and public re-exports. It also owns the documentation-only guide module, the private README doctest mirrors, and the public prelude. There is no src/main.rs.

Module Owns
src/angle.rs VectorAngle slice extension trait, direction scaling, and the shared unsigned-angle kernel
src/error.rs LaError and typed singularity, non-finite, positive-semidefinite, tolerance, factorization, arithmetic-operation, and exact-conversion categories
src/exact.rs Exact determinants and solves, determinant-sign filtering, and exact-to-f64 conversion
src/gram.rs Fixed-size Gram construction from vector dot products
src/interval.rs Interval scalars, matrices, and determinant-sign certification
src/ldlt.rs Unpivoted Ldlt<D> factorization for exactly symmetric positive-definite matrices, solves, and determinants
src/lu.rs Partially pivoted Lu<D> factorization, solves, and determinants
src/matrix.rs Matrix<D>, finite storage, accessors, matrix operations, norms, and direct determinant APIs
src/norm.rs Exact range-boundary fallback for the approximate Euclidean norm
src/rational.rs RationalMatrix<D> and RationalVector<D>, canonical rational inputs, and denominator clearing for exact arithmetic
src/rounding.rs Shared binary64 rounding primitives for certified arithmetic
src/scaled_product.rs Allocation-free scaled products for floating-point factor diagonals
src/tolerance.rs Validated singular-tolerance policy
src/vector.rs Vector<D>, finite storage, reductions, norms, and certified scalar results

Keep shared arithmetic invariants in the lowest owning module and expose public items through src/lib.rs. Mathematical derivations and algorithm references belong in Mathematical basis and REFERENCES.md.

Feature boundaries

The Cargo manifest owns feature and dependency declarations.

  • exact gates src/exact.rs, src/rational.rs, their additional tests, exact guides, and exact-arithmetic examples. It enables det_exact(), strict det_exact_f64(), rounded det_exact_rounded_f64(), det_sign_exact(), solve_exact(), strict solve_exact_f64(), and rounded solve_exact_rounded_f64() for finite binary64 inputs, plus the rational-input types.
  • det_sign_exact() is infallible for finite-by-construction Matrix values. Exact-value, conversion, and solve APIs retain their genuine scale, representation, and singularity failures.
  • ExactF64Conversion converts an already-computed determinant or solution under the strict or rounded contract without rerunning exact elimination. Feature-gated re-exports include DeterminantSign, ExactF64Conversion, RationalMatrix, RationalVector, BigInt, BigRational, FromPrimitive, ToPrimitive, and Signed.
  • Typed error categories, including UnrepresentableReason, remain available without exact; matching errors must not require optional arithmetic dependencies.
  • The scaled BigInt determinant core uses direct expansions for D≤4 and fraction-free Bareiss elimination for D≥5. Exact signs add a floating-point filter for D≤4. Exact solves use fraction-free forward elimination with first-non-zero pivoting and integer back-substitution over a common denominator, reducing each final component into BigRational. Rational inputs use direct substitution for triangular systems (including row permutations), and otherwise clear denominators before reusing the integer backend.
  • bench is a cfg-only gate for benchmark targets. Benchmark libraries remain dev-dependencies. Nalgebra and faer belong only to the unpublished la-stack-comparison package under benches/comparison, so exact benchmark builds do not compile either peer library.

Tests and examples

  • Rust unit tests live in inline #[cfg(test)] modules in src/*.rs.
  • tests/proptest_*.rs covers angles, matrix, vector, factorization, exact, rational, interval, and Gram properties. Exact and rational suites require exact.
  • Other tests/*.rs suites cover regressions, API contracts, allocation behavior, conversion boundaries, and benchmark inputs. Shared property-test configuration lives in tests/common/.
  • tests/vector_angles.rs owns independent analytical angle regressions, typed operand/shape errors, and allocation evidence. tests/angle_bench_inputs.rs runs the independent fixture gates shared with the angle benchmark.
  • tests/rational_structured_solve.rs checks triangular solves against the captured Gaussian reference, exact residuals, and typed singularity metadata through D=8, including arbitrary row permutations and wide rational inputs.
  • benches/comparison/tests/vs_linalg_inputs.rs checks the shared comparison fixtures. just test-bench-inputs and the full CI test pass include both workspace packages.
  • tests/semgrep/ contains deliberate static-analysis fixtures, not ordinary runnable API examples.
  • Python tests live under scripts/tests/ and run with pytest through just test-python or the aggregate validation workflows.
  • examples/ contains complete runnable workflows. README mirrors and public guide doctests live in src/lib.rs.
  • examples/vector_angles.rs demonstrates fixed-vector and borrowed-slice angles, independent magnitude scaling, and subnormal separations.

Use Testing guidance for dimension coverage and test design, and Documentation guidance for executable-example ownership.

Benchmarks and support tooling

benches/ contains Criterion suites for angles, exact arithmetic, Gram construction, intervals, linear forms, structured rational solves, and nalgebra/faer comparisons. Helpers under benches/common/ own fixture and oracle validation. Exact benchmark helpers accept only ValidatedExactInput, after independent validation outside timing. Adversarial groups include near-singular, large-entry, and Hilbert inputs. benches/common/angle.rs owns the independently checked angle fixtures and the stable comparison kernel; benches/angle.rs separates prepared vectors, borrowed slices, and construction costs. benches/common/rational_solve.rs owns the structured rational fixtures and captured Delaunay Gaussian control. benches/rational_solve.rs separates construction, prepared solves, and full runtime-dispatch adapter costs; tests/exact_bench_config.rs includes its independent fixture gates.

The root package is the default workspace member. benches/comparison/Cargo.toml owns the vs_linalg target at benches/vs_linalg.rs and its input test. Select it with just bench-vs-linalg or Cargo's -p la-stack-comparison. Both packages inherit the root workspace lints and share the lockfile and target directory.

The Benchmarking guide owns benchmark commands, methodology, baselines, output locations, and report promotion. The Scripts guide owns the Python script inventory and entry points for comparisons and plotting. The pinned published research-repo-tools dependency owns changelog generation, normalization, minor-series archiving, note lookup, and tag preparation through its CLI. Consumer identity and dependency-body policy stay in [tool.research-repo-tools.changelog] in pyproject.toml, with formatting in changelog-rumdl.toml; no common template is copied locally. focused integration checks live in scripts/tests/test_changelog_integration.py. The same dependency owns CodeRabbit review orchestration through thin Just wrappers. scripts/tests/test_review_integration.py owns consumer wiring checks with local stubs; the contributor review workflow owns prerequisites and invocation policy. The justfile owns executable development workflows.

osv-scanner.toml owns temporary advisory-specific dependency exceptions, and .gitleaks.toml owns narrow secret-scan false-positive exceptions. Their rationale and review policy belong in Security Checks.

The shared package also owns managed tool installation, verification, and update implementation. .python-version, rust-toolchain.toml, and pyproject.toml own consumer declarations; scripts/tests/test_toolchain_integration.py checks the exact published pin, registry lock, installed version and distribution hashes, alongside actual recipe sequencing and native managed execution. The .github/actions/setup-tools/action.yml composite synchronizes the locked PyPI package and exports verified paths for CI. Release callers disable its caches.

Release metadata, version checks, Markdown line checks, and Semgrep fixture validation also belong to the shared CLI. Consumer policy stays in pyproject.toml; scripts/tests/test_maintenance_integration.py verifies the actual release selectors and preservation of scientific evidence. scripts/tests/test_cargo_update_integration.py exercises native dependency upgrades and coupled exclusions against a disposable local registry.

The shared package also owns process discovery, captured/live execution, exact byte transport, CPU metadata, diagnostics, and zizmor authentication. Consumers call its public process API directly. Shared Criterion estimates replace local timing wrappers. Tests use shared Just inspection and retain scientific selection and consumer policy checks.

Performance consumers use shared Criterion parsing and estimate/comparison validation, digest verification, archive extraction, byte-preserving document sections, and multi-file transactions. Shared rendering produces complete-run reports, coordinate SVG, timing CSV and document tables. Historical artifact bytes and fingerprint framing remain frozen and readable directly. Published v0.2.0 owns common-harness orchestration, completeness, worktrees, complete run retention, validated latest selection, and transactional report publication. Its RunTableStyle API owns compact README table formatting; the consumer selects dimension headings, intervals below timings, a common confidence legend and ratio-only speedups without rewriting Markdown cells or prose. Generic parsing, staging, and rollback tests belong upstream; local tests verify the scientific and retained-artifact integration boundaries.

Hosted Dependabot approvals use the pinned shared GitHub workflow; the rollout guide owns settings and deployment verification.

tooling/criterion-inventory.toml declares native full-suite list commands and minimum scientific report/plot coverage. tooling/criterion-saved.toml declares complete saved-sample requirements. Shared discovery and saved-sample APIs own inventory parsing and exact raw-file verification. The release workflow packages only datasets that pass that gate; its regression and archive tests live in scripts/tests/test_release_baseline.py.

tooling/performance.just declares native Cargo commands, features, and input gates for both local measurements and release inventories. tooling/performance.toml uses the shared measurement schema for source/harness inputs, probes, timeouts, and compatibility fields. tooling/performance-policy.toml owns the scientific metric catalog, exact groups, peer mappings and historical API availability. scripts/performance_runs.py binds those declarations to scientific coverage, release compatibility and named reference-phase assertions. scripts/archive_performance.py composes shared APIs for tracked-only measurements, metadata-free historical raw archives and la-stack README publication. tooling/performance-plot.toml declares dimensions, units, series and axes. tooling/performance-report.toml owns the canonical report path, title, and shared history path. The obsolete CSV conversion declaration and pre-Just Python phase replay are removed. The old comparison renderer, CSV/provenance writer, summary reader, plotter, release-inventory wrapper and Python packaging are removed. Only the two consumer adapters remain; scripts/tests/test_performance_workflow.py verifies installed-package integration and offline replay. Shared renderers preserve the figure’s scientific coordinates, units and originating series. The adoption record owns retained-helper dispositions, Python 3.15 review and native validation gates.

tooling/semgrep/ owns a locked Python 3.14 environment for Semgrep 1.180.0 while its wheels exclude Python 3.15. Local scans, shared fixture validation and hosted SARIF use it; ordinary support scripts use Python 3.15. The root .semgrepignore keeps ordinary Rust and Python tests in those scans while excluding deliberate tests/semgrep/ fixtures, which just semgrep-test validates separately. Git-ignored dependencies, environments, caches, and build outputs remain outside production scans.

.github/actions/prepare-release-benchmarks/action.yml groups tool installation, input validation, and inventory under the release workflow's shared setup timeout.

.github/workflows/publish-crates.yml owns the reviewed-release event, native Cargo dry-run, deployment approval and OIDC upload. The publishing declaration in pyproject.toml selects la-stack, native checks and the Criterion asset; shared release gates own generic identity, ancestry and registry checks. scripts/tests/test_release_publishing.py owns installed-package consumer checks and upload-barrier tests. The release guide owns account setup, manual publication, registry verification and recovery.

Documentation owners

Use Documentation guidance for README, references, mathematical background, rustdoc, and generated-file ownership. Focused operational rules live in docs/dev/; human setup and validation guidance lives in CONTRIBUTING.md. Release procedures belong in Releasing.

Managing changes owns Git and GitHub procedures. Measuring coverage owns local and CI coverage execution. The generated performance report records measured results; Benchmarking owns the commands that produce and compare them. Local benchmark summaries owns complete versioned local datasets. Completed optimization studies belong under archived performance studies. The Rust 1.99 study owns the compiler migration baseline and its retained measurements; it is separate from generated release-to-release reports. The interval and certified-reduction study owns the #247/#248 same-toolchain comparisons and downstream adoption evidence. The vector-angle study owns the #249 formulation decision, comparative timings, and retained source provenance. The sparse vector-angle study owns the #287 shared-zero optimization, dense controls, and retained evidence. The triangular rational solve study owns the #246 Rust 1.99 baseline, adapter/kernel comparisons, and retained evidence. The exact determinant row scaling study owns the row-local scaling comparison, exponent-spread diagnostics, and workload tradeoffs. The exact solve normalization study owns the shared-denominator back-substitution comparison and diagonal controls. The algebraic floating-point study owns the #250 numerical/performance experiment and its raw evidence.

The validation index maps arithmetic contracts to independent tests and owns dated validation decisions and their limitations. The algebraic floating-point decision records rejection and the maintainer's closure of unperformed prototype work. Mathematical guarantees remain in mathematical_basis.md; performance archives retain measurement data and experimental sources.

When adding, removing, renaming, or moving files, update the applicable ownership rows here. Prefer links to the detailed owner over copying its procedure into this map or AGENTS.md.