Skip to content

feat: Construct Gram matrices from fixed vectors #219

Description

@acgetchell

Summary

Add fixed-size Gram-matrix construction from finite stack-backed vectors, so
callers can form G[i,j] = v_i . v_j through one checked and benchmarked linear
algebra kernel.

This is additive stable-Rust work. It does not require a general rectangular
matrix type: an input such as [Vector<N>; M] can produce Matrix<M> with two
independent const parameters on stable Rust.

Downstream motivation: delaunay

Delaunay independently assembles Gram matrices for full-dimensional simplex
volume and codimension-one facet measure, then delegates the symmetric positive-
definite determinant to la-stack::Ldlt. The dot-product loops, finite-result
checks, and matrix writes are generic linear algebra. Centralizing them in
la-stack would leave Delaunay responsible only for geometric edge formation,
factorial normalization, degeneracy interpretation, and public geometry errors.

This also makes the simplex volume/quality part of Delaunay #513 easier to
benchmark at the correct boundary: Gram construction and LDLT remain separately
auditable in la-stack, while end-to-end geometric measures remain in
Delaunay.

Requested contract

One possible surface is:

pub fn gram_matrix<const M: usize, const N: usize>(
    vectors: &[Vector<N>; M],
) -> Result<Matrix<M>, LaError>;

An associated constructor or a runtime-dispatch companion is also acceptable.
The operation should:

  • accept only finite proof-bearing Vector inputs;
  • produce an exactly symmetric Matrix<M> by construction;
  • compute each independent dot product once and mirror it;
  • preserve typed non-finite computation context if a dot product overflows;
  • remain allocation-free and available without the exact feature;
  • support the downstream envelope through at least M,N <= 8;
  • compose directly with Matrix::ldlt without weakening LDLT's preconditions.

Acceptance criteria

  • Known-answer and property tests cover orthogonal, linearly dependent,
    rectangular (M != N), zero-dimensional, and mixed-scale vector sets.
  • Symmetry is exact bit-for-bit, not reconstructed independently in both
    triangles.
  • Results agree with an independent matrix-product oracle on representable
    inputs, and overflow has typed diagnostics.
  • Focused benchmarks cover the dimensions used by downstream simplex/facet
    measures and compare with hand-written dot loops or appropriate peer APIs.
  • Documentation explains that Gram construction does not itself prove positive
    definiteness or affine independence; those remain factorization/caller
    decisions.

Downstream cleanup enabled

After release, Delaunay can replace both local Gram assembly loops with this
kernel, retain its geometric edge-vector construction and measure semantics,
and use #513 to benchmark the end-to-end simplex volume, facet measure, and
quality APIs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    apienhancementNew feature or requestperformancePerformance related issuesrustPull requests that update rust code

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions