Added: Benchmarks and plotting for performance analysis

Adds a comprehensive benchmark suite comparing `la-stack` against
`nalgebra` for various linear algebra operations across different
dimensions. Includes tooling to automatically generate plots and
update the README with benchmark results. This facilitates ongoing
performance monitoring and optimization.

Author: acgetchell

.codacy.yml

@@ -3,6 +3,7 @@
 #
 # This repository is primarily Rust.
 # Note: clippy and rustfmt are not supported by Codacy and are handled by GitHub Actions CI.
+# cspell:ignore pyproject
 
 engines:
   # === DOCUMENTATION / SCRIPTS ===
@@ -22,6 +23,29 @@ engines:
       severity: warning
       include_code: true
 
+  # === PYTHON / SECURITY ===
+  # Ruff for Python linting and formatting (reads from pyproject.toml)
+  ruff:
+    enabled: true
+    include_paths:
+      - "scripts/**/*.py"
+      - "**/*.py"
+    config:
+      file: "pyproject.toml"
+
+  # Bandit for Python security analysis
+  bandit:
+    enabled: true
+    include_paths:
+      - "scripts/**/*.py"
+      - "**/*.py"
+    config:
+      severity: high
+      confidence: high
+      skips: ["B101", "B102", "B103", "B108", "B110", "B404", "B603", "B607"]
+      exclude_info: true
+      exclude_dirs: ["tests"]
+
   # === RUST / SECURITY ===
   lizard:
     enabled: true
@@ -30,8 +54,9 @@ engines:
       - "tests/**/*.rs"
       - "examples/**/*.rs"
       - "benches/**/*.rs"
+      - "scripts/**/*.py"
     config:
-      languages: ["rust"]
+      languages: ["rust", "python"]
       threshold:
         cyclomatic_complexity: 15
         token_count: 300
@@ -46,6 +71,7 @@ engines:
       - "tests/**/*.rs"
       - "examples/**/*.rs"
       - "benches/**/*.rs"
+      - "scripts/**/*.py"
 
   trivy:
     enabled: true
@@ -75,14 +101,26 @@ exclude_paths:
   - ".git/**"
   - ".cspellcache"
   - ".DS_Store"
+  # Python artifacts
+  - "__pycache__/**"
+  - "*.pyc"
+  - ".pytest_cache/**"
+  - ".ruff_cache/**"
+  - ".mypy_cache/**"
+  - "venv/**"
+  - ".venv/**"
+  - "uv.lock"
 
 # Focus analysis on source, docs, and CI configuration
 include_paths:
   - "src/**"
   - "benches/**"
   - "examples/**"
   - "tests/**"
+  - "scripts/**"
+  - "*.py"
   - "Cargo.toml"
+  - "pyproject.toml"
   - "rust-toolchain.toml"
   - "rustfmt.toml"
   - "justfile"
@@ -100,6 +138,9 @@ languages:
   rust:
     extensions:
       - ".rs"
+  python:
+    extensions:
+      - ".py"
   markdown:
     extensions:
       - ".md"

.github/workflows/ci.yml

@@ -55,6 +55,12 @@ jobs:
         with:
           tool: just
 
+      - name: Install uv (for Python scripts and pytest)
+        if: matrix.os != 'windows-latest'
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a  # v7.1.5
+        with:
+          version: "latest"
+
       - name: Install Node.js (for markdownlint and cspell)
         if: matrix.os != 'windows-latest'
         uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0

.github/workflows/codacy.yml

@@ -61,6 +61,19 @@ jobs:
           mkdir -p "$CODACY_WORKDIR"
           rsync -a --delete --exclude '.git' ./ "$CODACY_WORKDIR/"
 
+      - name: Verify Codacy config includes Python security tooling
+        run: |
+          set -euo pipefail
+          config="$CODACY_WORKDIR/.codacy.yml"
+          if [ ! -f "$config" ]; then
+            echo "::error::.codacy.yml not found in workspace copy ($config)"
+            exit 1
+          fi
+          if ! grep -qE '^  bandit:' "$config"; then
+            echo "::error::Bandit engine not configured in .codacy.yml; Python security scanning will be skipped."
+            exit 1
+          fi
+
       # Execute Codacy Analysis CLI and generate a SARIF output with
       # the security issues identified during the analysis
       - name: Run Codacy Analysis CLI

.gitignore

@@ -4,3 +4,13 @@
 /build*
 /cobertura.xml
 .DS_Store
+
+# Python / uv
+__pycache__/
+**/__pycache__/
+*.egg-info/
+.venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+uv.lock

.python-version

@@ -0,0 +1 @@
+3.11

Cargo.toml

@@ -6,6 +6,7 @@ rust-version = "1.92"
 license = "BSD-3-Clause"
 description = "Small, stack-allocated linear algebra for fixed dimensions"
 readme = "README.md"
+documentation = "https://docs.rs/la-stack"
 repository = "https://github.com/acgetchell/la-stack"
 categories = ["mathematics", "science"]
 keywords = ["linear-algebra", "geometry", "const-generics"]

README.md

@@ -32,6 +32,11 @@ while keeping the API intentionally small and explicit.
 - ✅ `unsafe` forbidden
 - ✅ No runtime dependencies (dev-dependencies are for contributors only)
 
+## 🚫 Anti-goals
+
+- Comprehensive: use [`nalgebra`](https://crates.io/crates/nalgebra) if you need a full-featured library
+- Bare-metal performance: see [`blas-src`](https://crates.io/crates/blas-src), [`lapack-src`](https://crates.io/crates/lapack-src), [`openblas-src`](https://crates.io/crates/openblas-src)
+
 ## 🔢 Scalar types
 
 Today, the core types are implemented for `f64`. The intent is to support `f32` and `f64`
@@ -107,6 +112,27 @@ just commit-check # lint + all tests + examples
 
 For the full set of developer commands, see `just --list` and `WARP.md`.
 
+## 📊 Benchmarks (vs nalgebra)
+
+![LU solve (factor + solve): median time vs dimension](docs/assets/bench/vs_nalgebra_lu_solve_median.svg)
+
+Raw data: [docs/assets/bench/vs_nalgebra_lu_solve_median.csv](docs/assets/bench/vs_nalgebra_lu_solve_median.csv)
+
+Summary (median time; lower is better). “la-stack vs nalgebra” is the % time reduction relative to nalgebra (positive = la-stack faster):
+
+<!-- BENCH_TABLE:lu_solve:median:new:BEGIN -->
+| D | la-stack median (ns) | nalgebra median (ns) | la-stack vs nalgebra |
+|---:|--------------------:|--------------------:|---------------------:|
+| 2 | 2.125 | 19.172 | +88.9% |
+| 3 | 13.562 | 24.082 | +43.7% |
+| 4 | 28.365 | 55.434 | +48.8% |
+| 5 | 48.567 | 76.793 | +36.8% |
+| 8 | 141.935 | 182.628 | +22.3% |
+| 16 | 642.935 | 605.115 | -6.3% |
+| 32 | 2,761.816 | 2,505.691 | -10.2% |
+| 64 | 17,009.208 | 14,696.410 | -15.7% |
+<!-- BENCH_TABLE:lu_solve:median:new:END -->
+
 ## 📄 License
 
 BSD 3-Clause License. See [LICENSE](./LICENSE).