diff --git a/benches/LADDER.md b/benches/LADDER.md new file mode 100644 index 00000000..36701a09 --- /dev/null +++ b/benches/LADDER.md @@ -0,0 +1,231 @@ +# Comprehensive Benchmarking + +This benchmark separates kernel, shared-memory, process, network, and scaling effects. Define: + +- `N`: nodes +- `C`: usable cores per node +- `R`: MPI ranks per node +- `P`: in-process partitions per rank +- `P_total = N × R × P`: total partitions + +Choose `R` for the platform, normally one rank per NUMA domain, then set `P = C / R`. Keep `R` +and `P` fixed wherever the ladder requires a direct comparison. + +> **Example platform.** All flags, term counts, timings, and memory figures below were measured on +> code based on `main` commit `97f95f762dfc7174243ccd59dd4ecbbb9775b610`, on Deucalion x86 +> nodes with `C=128`, using `R=8` and `P=16` for MPI runs. They are calibration and job-sizing +> examples, not portable targets but memory should be relatively similar. + +## Ladder + +| rung | shape | purpose | +| --- | --- | --- | +| L1 | `N=1, R=1, P=1` | isolate single-thread kernel performance | +| L2a | `N=1, R=1, P=C` | measure full-node shared-memory performance | +| L2b | `N=1, R=R_platform, P=C/R` | isolate process and MPI overhead without a network hop | +| L3 | `N>1`, same `R` and `P` as L2b | isolate the network | +| L4 | vary `N`, hold `R` and `P` fixed | measure strong and weak scaling | + +L2a, L2b, and L3 use the same model flags. Only the execution shape changes. Term counts are +topology-independent, so a mismatch means the problem definition changed. + +## Running a row + +```bash +uv sync --all-groups --all-extras # once +just bench L1-hubbard --hubbard-cutoff=10 --hubbard-lower-atol=4.2e-05 \ + -k "test_model_propagate and hubbard" +``` + +Name `LABEL` by rung, row, and arm, for example `L1-hubbard-branch`. A run writes +`results/time-