Merge pull request #143 from acgetchell/feat/138-release-performance-comparison

feat(bench): add release performance comparison workflow

Author: acgetchell

CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for helping improve `la-stack`. This crate is intentionally small and
+invariant-heavy, so changes should preserve mathematical correctness, API
+clarity, and the fixed-dimension stack-allocation model.
+
+## Workflow
+
+```bash
+cargo install just
+just setup        # install/verify dev tools + sync Python deps
+just check        # lint/validate (non-mutating)
+just fix          # apply auto-fixes (mutating)
+just ci           # lint + tests + examples + bench compile
+```
+
+The repository uses Rust-native tooling for documentation and config checks:
+`rumdl` for Markdown, `dprint` with `pretty_yaml` for YAML, `taplo` for TOML,
+and `typos` for spelling. GitHub Actions references are SHA-pinned, restricted
+to an explicit allowlist, and kept with readable version comments for review.
+
+CI runs `just ci` on Ubuntu, macOS, and Windows to keep platform coverage
+aligned with the local comprehensive validation path.
+
+For coverage commands and report locations, see [`docs/COVERAGE.md`](docs/COVERAGE.md).
+For benchmark methodology, see [`docs/BENCHMARKING.md`](docs/BENCHMARKING.md).
+For the full set of developer commands, run `just --list`.
+
+## AI-Assisted Development
+
+This repository contains an [`AGENTS.md`](AGENTS.md) file, which defines the
+canonical rules and invariants for AI coding assistants and autonomous agents
+working on this codebase.
+
+AI tools, including ChatGPT, Claude, CodeRabbit, Codex, KiloCode, and WARP, are
+expected to read and follow `AGENTS.md` when proposing or applying changes.
+
+Portions of this library were developed with the assistance of these tools:
+
+- [ChatGPT](https://openai.com/chatgpt)
+- [Claude](https://www.anthropic.com/claude)
+- [CodeRabbit](https://coderabbit.ai/)
+- [Codex](https://openai.com/codex/)
+- [KiloCode](https://kilocode.ai/)
+- [WARP](https://www.warp.dev)
+
+All code was written and/or reviewed and validated by the author.
+
+For full tool citation metadata, see the
+[AI-Assisted Development Tools](REFERENCES.md#ai-assisted-development-tools)
+section of [`REFERENCES.md`](REFERENCES.md).

README.md

@@ -49,6 +49,16 @@ See [CHANGELOG.md](CHANGELOG.md) for release history and
 - Large matrices/dimensions with parallelism: use [`faer`](https://crates.io/crates/faer) if you need this
 - Alternate floating-point scalar families: `la-stack` supports `f64` and optional exact arithmetic, not `f32` / `f16` APIs
 
+## ✅ Use this crate when
+
+- Your matrices and vectors have small, fixed dimensions known at compile time
+- Stack allocation and `Copy` value semantics fit your data flow
+- You want explicit LU / LDLT / determinant APIs rather than a broad algebra toolkit
+- You need exact determinants, exact determinant signs, or exact linear solves
+  for fixed-size systems
+- Robust predicates matter for geometry-style workloads near degeneracy
+- You prefer a default build with no runtime dependencies
+
 ## 🔢 Scalar types
 
 The scalar model is intentionally limited to `f64` for floating-point work and
@@ -71,6 +81,12 @@ Add this to your `Cargo.toml`:
 la-stack = "0.4.2"
 ```
 
+### Feature flags
+
+- `default`: no runtime dependencies
+- `exact`: `BigRational` exact determinant and solve APIs
+- `bench`: Criterion, nalgebra, and faer for internal benchmarks
+
 Solve a 5×5 system via LU:
 
 ```rust
@@ -335,7 +351,14 @@ not store NaN or infinity.
 
 Raw data: [docs/assets/bench/vs_linalg_lu_solve_median.csv](docs/assets/bench/vs_linalg_lu_solve_median.csv)
 
-Summary (median time; lower is better). The “la-stack vs nalgebra/faer” columns show the % time reduction relative to each baseline (positive = la-stack faster):
+Representative benchmark: `lu_solve` factors the matrix and solves one
+right-hand side. Median time is lower-is-better, and the “la-stack vs
+nalgebra/faer” columns show the % time reduction relative to each baseline
+(positive = la-stack faster). This is not an aggregate score across all
+operations.
+
+For the full per-kernel comparison methodology, input construction, and
+release-comparison workflow details, see [docs/BENCHMARKING.md](docs/BENCHMARKING.md).
 
 <!-- BENCH_TABLE:lu_solve:median:new:BEGIN -->
 
@@ -397,37 +420,22 @@ CI runs `just ci` on Ubuntu, macOS, and Windows to keep platform coverage
 aligned with the local comprehensive validation path.
 
 For coverage commands and report locations, see [`docs/COVERAGE.md`](docs/COVERAGE.md).
-For the full set of developer commands, see `just --list` and `AGENTS.md`.
+For the full contributor workflow, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## 📝 Citation
 
 If you use this library in academic work, please cite it using [CITATION.cff](CITATION.cff) (or GitHub's
-"Cite this repository" feature). A Zenodo DOI will be added for tagged releases.
+"Cite this repository" feature). Tagged releases are archived on Zenodo.
 
 ## 📚 References
 
 For canonical references to the algorithms used by this crate, see [REFERENCES.md](REFERENCES.md).
 
 ## 🤖 AI Agents
 
-This repository contains an `AGENTS.md` file, which defines the canonical rules and invariants
-for all AI coding assistants and autonomous agents working on this codebase.
-
-AI tools (including `ChatGPT`, `Claude`, `CodeRabbit`, `KiloCode`, and `WARP`) are expected to read
-and follow `AGENTS.md` when proposing or applying changes.
-
-Portions of this library were developed with the assistance of these AI tools:
-
-- [ChatGPT](https://openai.com/chatgpt)
-- [Claude](https://www.anthropic.com/claude)
-- [CodeRabbit](https://coderabbit.ai/)
-- [KiloCode](https://kilocode.ai/)
-- [WARP](https://www.warp.dev)
-
-> All code was written and/or reviewed and validated by the author.
-
-For full tool citation metadata, see the [AI-Assisted Development Tools](REFERENCES.md#ai-assisted-development-tools)
-section of `REFERENCES.md`.
+AI coding assistants should read [AGENTS.md](AGENTS.md) before proposing or
+applying changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository's
+AI-assisted development note.
 
 ## 📄 License
 

benches/common/vs_linalg.rs

@@ -0,0 +1,122 @@
+//! Shared helpers for the `vs_linalg` benchmark and its smoke tests.
+
+use faer::linalg::solvers::{Ldlt as FaerLdlt, PartialPivLu};
+use faer::perm::PermRef;
+use nalgebra::SMatrix;
+
+/// Return `det(P)` for faer's permutation representation.
+///
+/// Sign(det(P)) is +1 for even permutations and -1 for odd. Parity is computed
+/// from the number of cycles: `sign = (-1)^(n - cycles)`.
+pub fn faer_perm_sign(p: PermRef<'_, usize>) -> f64 {
+    let (forward, _inverse) = p.arrays();
+    let n = forward.len();
+
+    let mut seen = vec![false; n];
+    let mut cycles = 0usize;
+
+    for start in 0..n {
+        if seen[start] {
+            continue;
+        }
+        cycles += 1;
+
+        let mut i = start;
+        while !seen[i] {
+            seen[i] = true;
+            i = forward[i];
+        }
+    }
+
+    if (n - cycles).is_multiple_of(2) {
+        1.0
+    } else {
+        -1.0
+    }
+}
+
+/// Compute a determinant from a faer partial-pivot LU factorization.
+pub fn faer_det_from_partial_piv_lu(lu: &PartialPivLu<f64>) -> f64 {
+    // For PA = LU with unit-lower L, det(A) = det(P) * det(U).
+    let u = lu.U();
+    let mut det = 1.0;
+    for i in 0..u.nrows() {
+        det *= u[(i, i)];
+    }
+    det * faer_perm_sign(lu.P())
+}
+
+/// Compute a determinant from a faer LDLT factorization.
+pub fn faer_det_from_ldlt(ldlt: &FaerLdlt<f64>) -> f64 {
+    let d = ldlt.D().column_vector();
+    let mut det = 1.0;
+    for i in 0..d.nrows() {
+        det *= d[i];
+    }
+    det
+}
+
+/// Return a deterministic, strictly diagonally-dominant benchmark matrix entry.
+#[inline]
+#[allow(clippy::cast_precision_loss)] // D, r, c are small integers, precision loss is not an issue.
+pub fn matrix_entry<const D: usize>(r: usize, c: usize) -> f64 {
+    if r == c {
+        // Strict diagonal dominance for stability.
+        (r as f64).mul_add(1.0e-3, (D as f64) + 1.0)
+    } else {
+        // Small, varying off-diagonals.
+        0.1 / ((r + c + 1) as f64)
+    }
+}
+
+/// Build the shared matrix rows used by all crates for a dimension.
+#[inline]
+pub fn make_matrix_rows<const D: usize>() -> [[f64; D]; D] {
+    let mut rows = [[0.0; D]; D];
+
+    for (r, row) in rows.iter_mut().enumerate() {
+        for (c, entry) in row.iter_mut().enumerate() {
+            *entry = matrix_entry::<D>(r, c);
+        }
+    }
+
+    rows
+}
+
+/// Return a deterministic benchmark vector entry.
+#[inline]
+#[allow(clippy::cast_precision_loss)] // i is a small integer, precision loss is not an issue.
+pub fn vector_entry(i: usize, offset: f64) -> f64 {
+    (i as f64) + 1.0 + offset
+}
+
+/// Build the shared vector input used by all crates for a dimension.
+#[inline]
+pub fn make_vector_array<const D: usize>(offset: f64) -> [f64; D] {
+    let mut data = [0.0; D];
+
+    for (i, entry) in data.iter_mut().enumerate() {
+        *entry = vector_entry(i, offset);
+    }
+
+    data
+}
+
+/// Compute nalgebra's matrix infinity norm using la-stack's row-sum convention.
+#[inline]
+pub fn nalgebra_inf_norm<const D: usize>(m: &SMatrix<f64, D, D>) -> f64 {
+    // Infinity norm = max absolute row sum.
+    let mut max_row_sum = 0.0;
+
+    for r in 0..D {
+        let mut row_sum = 0.0;
+        for c in 0..D {
+            row_sum += m[(r, c)].abs();
+        }
+        if row_sum > max_row_sum {
+            max_row_sum = row_sum;
+        }
+    }
+
+    max_row_sum
+}