Skip to content

roadmap.md

Latest commit

 

History

History
122 lines (100 loc) · 6.08 KB

roadmap.md

File metadata and controls

122 lines (100 loc) · 6.08 KB

Roadmap

This roadmap records likely directions for the la-stack crate. It is not a stability promise; release scope depends on mathematical correctness, API maturity, downstream need, and validation quality. Concrete implementation work is tracked as GitHub issues; keep this document focused on release direction, ordering, and non-goals.

Pre-1.0 releases may still revise public APIs when that makes the crate more correct or easier to use safely. The v0.4.x line should stay on stable Rust and focus on documentation, downstream ergonomics, API-contract cleanup, validation, invariant audits, and benchmark coverage. The v0.5.0 line is reserved for work that depends on stabilized generic_const_exprs or equivalent const-generic expressiveness.

Scalar Scope

la-stack intentionally supports f64 for floating-point APIs and exact rationals behind the optional "exact" feature. This is not a temporary implementation detail: the crate targets small, fixed-size, robustness-sensitive numerical and computational geometry workloads where f64 plus exact arithmetic is the right tradeoff.

Other scalar families are non-goals. Users who need lower-precision f32 / f16 support, throughput-oriented reduced precision, accelerator-heavy computation, large dynamic matrices, sparse matrices, or broad decomposition coverage should use larger linear-algebra ecosystems such as nalgebra or faer.

Current Release Sequence

v0.4.2 Stable Rust Cleanup

The v0.4.2 milestone collects the work that can be done on today's stable Rust while keeping the crate useful to downstream geometry crates. The GitHub native Blocking / Is blocked by graph mirrors this order:

Completed foundation work:

  • #100 clarified f64 as the intended floating-point type in README and other documentation.
  • #109 added fallible runtime matrix dispatch and contextual index errors.
  • #83 changed Matrix::set to return Option<()> instead of bool.
  • #94 made tolerance parsing explicit and consistent across the crate.
  • #82 unified det() error behavior across all dimensions as far as stable Rust allows.
  • #120 completed the parse-don't-validate NonZero* audit.
  • #111, #112, #113, and #117 cleaned up Markdown/YAML tooling, CI speed, and shared Rust workflow/security checks.

Current API-invariant cleanup:

  • #126 is resolved as an internal parse-don't-validate design rather than a public proof-bearing API. Matrix<D> and Vector<D> remain the raw boundary types so callers can pass deserialized, fixture, or otherwise unchecked f64 storage and receive structured diagnostics. Crate-private FiniteMatrix<D> and FiniteVector<D> are validated domain types that carry the finite-entry proof behind the scenes for LU, LDLT, determinant, error-bound, and exact-arithmetic paths.
  • The public prelude stays focused on downstream composition: raw boundary types, factorization handles, tolerances, crate errors, dispatch helpers, and documented constants. Proof-bearing wrappers remain crate-private, and exact-arithmetic integer/rational re-exports remain gated behind the "exact" feature.
  • The public LDLT API remains Matrix::ldlt. Symmetry proof storage is kept internal, SymmetricMatrix is not exported, asymmetric inputs return LaError::Asymmetric, and negative LDLT pivots return LaError::NotPositiveSemidefinite rather than being folded into LaError::Singular.
  • The determinant error-bound constants ERR_COEFF_2, ERR_COEFF_3, and ERR_COEFF_4 are documented as dimension-specific roundoff multipliers over the absolute Leibniz sum, not caller-tuned tolerances.

Remaining release blockers:

  • #125 - Add a Semgrep guardrail against unwrap / expect in examples, benches, and doctests.
  • #98 - Add random-input percentile benchmarks to the exact arithmetic suite.

The broad shape is now: document scalar scope, add downstream dispatch ergonomics, clean up small API contracts, tighten validation, encode reusable invariants behind the public raw-boundary API, lock examples and benchmarks into proper error handling, then finish with broader benchmark work.

v0.5.0 Generic Const Expressions

v0.5.0 is reserved for the post-stabilization const-generic API revision. The current anchor issue is #123, which tracks refactoring determinant APIs around stable generic_const_exprs.

That work should revisit determinant APIs after the language can express more dimension-dependent support at the type level. In particular, it should look for ways to reduce runtime D branching, make closed-form determinant support more explicit, and unify direct, LU-backed, error-bound, and exact determinant paths where doing so improves correctness and maintainability.

Longer-Term Directions

  • Keep the crate focused on fixed small dimensions and stack allocation.
  • Preserve const fn surfaces where they make mathematical evaluation compile-time checkable.
  • Grow exact-arithmetic support only where it strengthens robustness-sensitive workflows without making the default build dependency-heavy.
  • Use benchmarks to validate performance claims against nalgebra and faer within the crate's intended dimensional scope.

Non-Goals

  • Dynamic or large matrix dimensions.
  • Sparse matrices, parallel solvers, GPU acceleration, or out-of-core storage.
  • Alternate floating-point scalar families such as f32 or f16.
  • Replacing full-featured linear-algebra libraries.