la-stack 0.4.0

Fast, stack-allocated linear algebra for fixed dimensions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# Benchmarking

This guide covers how to run, compare, and track performance for la-stack.

## Benchmark suites

la-stack has two Criterion benchmark suites:

- **`vs_linalg`** (`benches/vs_linalg.rs`) — compares la-stack against
  nalgebra and faer across D=2–64 for LU, solve, det, dot, norm, etc.
  Use this to answer "why choose la-stack over other crates?"

- **`exact`** (`benches/exact.rs`) — measures exact-arithmetic methods
  (`det_exact`, `solve_exact`, `det_sign_exact`, etc.) alongside f64
  baselines (`det`, `det_direct`) across D=2–5. Use this to understand
  the cost of exact arithmetic and track optimization progress.

## Quick reference

```bash
# Run vs_linalg benchmarks
just bench-vs-linalg

# Run exact-arithmetic benchmarks
just bench-exact

# Save an exact baseline (e.g., before optimising)
just bench-save-baseline v0.4.0

# Compare current code against a saved baseline
just bench-compare v0.4.0

# Generate a snapshot without comparison
just bench-compare
```

## Comparing performance across releases

Criterion baselines are saved into `target/criterion/` and persist across
`git checkout` but **not** across `cargo clean`.

### Workflow

```bash
# 1. Check out the old release and save its baseline
git checkout v0.2.0
just bench-save-baseline v0.2.0

# 2. Switch to current code and run benchmarks
git checkout main   # or your feature branch
just bench-exact    # populates target/criterion/*/new/

# 3. Generate a comparison table in docs/PERFORMANCE.md
just bench-compare v0.2.0
```

You can save multiple baselines and compare against any of them.

### Output

`just bench-compare` writes `docs/PERFORMANCE.md` (gitignored — it contains
machine-specific timings). The file includes per-dimension tables showing
median times, percent change, and speedup for each benchmark.

## vs\_linalg plotting

The `criterion_dim_plot.py` script generates CSV/SVG plots and updates the
README benchmark table from vs\_linalg results:

```bash
# Run benchmarks + update README table and SVG plot
just bench-vs-linalg
just plot-vs-linalg-readme
```

See `scripts/criterion_dim_plot.py --help` for options.

## Release workflow

At release time, save a baseline so future work can compare against it:

```bash
just bench-save-baseline $TAG
```

See `docs/RELEASING.md` step 5 for where this fits in the release process.