@@ -0,0 +1,77 @@
+# Fast Statistical Models for Python
+
+This repository contains the PyCon US 2026 deck and reproducibility artifacts for **Breaking the Speed Limit: Python 3.14, Numba, and Codex in Statistical Computing**.
+
+Core thesis:
+
+- simulation is how statisticians write tests;
+- speed only counts after the statistic is preserved;
+- Python remains the scientific interface;
+- Numba, JAX, Python 3.14, threads, processes, and A100 solve different bottlenecks.
+
+## View the slides
+
+Use the project conda environment by default:
+
+```bash
+conda activate py312
+python -m http.server 8000
+```
+
+Open:
+
+```text
+http://localhost:8000/slides/index.html
+```
+
+PDF/print mode:
+
+```text
+http://localhost:8000/slides/index.html?print-pdf
+```
+
+The canonical deck is [`slides/index.html`](slides/index.html). Current structure is 32 slides total: 27 main-path slides and 5 backup slides.
+
+## Results layout
+
+- MacBook/local trust tier: [`experiments/results/macbook_air_long/latest/`](experiments/results/macbook_air_long/latest/)
+- Linux server CPU scale tier: [`experiments/results/linux_server_cpu/long_safe_20260503_190133/`](experiments/results/linux_server_cpu/long_safe_20260503_190133/)
+- Historical A100 long-safe tier: [`experiments/results/linux_server_a100/long_safe_20260503_190133/`](experiments/results/linux_server_a100/long_safe_20260503_190133/)
+- A100 permutation follow-up notes and figures: [`experiments/results/linux_server_a100/permutation_followup/`](experiments/results/linux_server_a100/permutation_followup/)
+- A100 permutation break-even notes: [`experiments/results/linux_server_a100/permutation_break_even/`](experiments/results/linux_server_a100/permutation_break_even/)
+- Slide-ready figures: [`experiments/results/presentation_figures/`](experiments/results/presentation_figures/)
+
+## Current result status
+
+- MacBook k-means and permutation correctness/calibration results are the trust tier used in the main talk.
+- Linux server CPU and k-means A100 results are scale evidence used in the main talk.
+- The old A100 permutation matched slice is historical negative evidence: `n=5,000`, `p=50,000`, `batch_R=512`, before streamed reduction and the broader shape sweep.
+- The current A100 permutation break-even narrative uses `a100_streamed_reduction`, larger `batch_R`, and a measured shape sweep. Speedup is scoped to the matched CPU matrix baseline divided by A100 streamed full end-to-end. Compile is excluded, transfer is included, and kernel-only rows are not used for CPU/A100 decisions.
+- A100 permutation correctness wording is intentionally scoped: historical rows marked `check` are not exact `pass` rows; new accepted GPU rows should be emitted as `pass_gpu_tolerance`.
+
+## Regenerate figures
+
+MacBook figures:
+
+```bash
+python -m experiments.visualization.plot_macbook_air_evidence \
+  --results-dir experiments/results/macbook_air_long/latest
+```
+
+Server CPU and k-means/A100 presentation figures:
+
+```bash
+python -m experiments.visualization.plot_server_talk_evidence
+```
+
+A100 permutation break-even figures, when the experiment CSVs are available:
+
+```bash
+python -m experiments.server.a100_permutation_break_even plot \
+  --out-dir experiments/results/linux_server_a100/permutation_break_even \
+  --presentation-dir experiments/results/presentation_figures
+```
+
+## Deck QA
+
+Latest screenshot and render QA artifacts are written under [`slides/qa/latest/`](slides/qa/latest/). The QA pass checks browser mode, print/PDF mode, video poster fallbacks, broken media URLs, clipping, overlap, console errors, and A100 pending/experimental wording.
@@ -30,14 +30,25 @@ plot_and_summarize(
 
 The root-level quick-run server outputs were removed after validation. Only the timestamped long-safe directories are curated for GitHub.
 
+## A100 Permutation Follow-up
+
+The long-safe A100 permutation chart is historical matched-slice evidence: `n=5,000`, `p=50,000`, `batch_R=512`, before streamed reduction and before the broader break-even sweep. It remains useful because it shows that a GPU logo does not guarantee a win.
+
+The current permutation GPU narrative uses:
+
+- [`linux_server_a100/permutation_followup/`](linux_server_a100/permutation_followup/) for streamed-reduction pipeline/decomposition notes and figures.
+- [`linux_server_a100/permutation_break_even/`](linux_server_a100/permutation_break_even/) for the CPU/A100 break-even summary.
+
+Speedup in the break-even map is scoped to the matched CPU matrix baseline divided by A100 streamed full end-to-end. Compile is excluded, transfer is included, and kernel-only rows are not used for CPU/A100 speedup decisions.
+
 ## Presentation Figures
 
 Slides and the poster should use the normalized 16:9 summaries in
 [`presentation_figures/`](presentation_figures/) when citing server/A100
 results. These figures are regenerated by:
 
 ```bash
-/Users/lucajiang/anaconda3/envs/py312/bin/python -m experiments.visualization.plot_server_talk_evidence
+python -m experiments.visualization.plot_server_talk_evidence
 ```
 
 The MacBook correctness and local evidence tier lives in
 
@@ -114,7 +114,7 @@ Inputs and transformation:
 
 Conclusion supported by this figure:
 
-For the matched `R=1,000` and `R=10,000` points, CPU is faster than A100 in this implementation. This is an important negative result: the current JAX GPU permutation path has enough overhead that it does not beat the CPU baseline on the matched slice, even though it validates the matrix reformulation.
+For the old matched `R=1,000` and `R=10,000` points at `n=5,000`, `p=50,000`, and `batch_R=512`, CPU is faster than A100 in this implementation. This is historical pre-break-even evidence: it predates the streamed-reduction follow-up, larger `batch_R` sweep, and broader shape sweep. It should not be read as the final A100 permutation conclusion.
 
 ### `figures/permutation_matrix_reformulation.png`
 
 
@@ -6,7 +6,7 @@ Generated: 2026-05-05
 - Compile time: excluded from warm end-to-end comparisons; compile is recorded separately in the decomposition CSV.
 - Transfer: included for A100 end-to-end and streamed-reduction rows.
 - Stage sums: named decomposition stages do not exhaust `total_end_to_end_time_s`; the figure adds an explicit `other overhead` segment so stacked bars reconcile to the recorded total.
-- CPU comparison: full end-to-end CPU matrix baseline, not per-batch and not kernel-only.
+- CPU comparison: matched full end-to-end CPU matrix baseline, not per-batch, not kernel-only, and not an exhaustive best-of-all-CPU search.
 - Kernel-only rows: labeled separately as `kernel-only hypothesis, not end-to-end permutation test` and excluded from speedup decisions.
-- Correctness: new rows are marked `check`; no speedup plot uses failed rows.
+- Correctness: historical rows are marked `check`; future accepted GPU-tolerance rows should be marked `pass_gpu_tolerance`; no speedup plot uses failed rows.
 - Visual check: updated decision and decomposition slides were exported to PDF and screenshotted at 1280x720.
@@ -3,7 +3,8 @@
 Generated/updated: 2026-05-05T21:23:58+0800
 
 ## CPU baseline
-- Best trusted CPU implementation used here: `numpy_matrix_same_stream` batched matrix path.
+- Matched CPU matrix baseline used here: `numpy_matrix_same_stream` batched matrix path.
+- Scope: this is not an exhaustive best-of-all-CPU search; speedup means matched CPU matrix baseline divided by A100 streamed full end-to-end.
 - CPU rows recorded: 27.
 
 ## Break-even
@@ -29,6 +30,9 @@ Generated/updated: 2026-05-05T21:23:58+0800
 ## Correctness
 - Correctness check rows: 97.
   - check: 97
+- Historical `check` rows mean accepted bounded CPU/JAX comparisons under the then-current status vocabulary; they are not exact `pass` rows.
+- New accepted GPU rows should be emitted as `pass_gpu_tolerance`.
+- The result CSVs with `max_abs_p_diff` and `max_abs_stat_diff` are generated on the experiment server but are not committed in this repository snapshot.
 
 ## OOM / memory-risk / timeout
 - `batch_R_sweep.csv`: 0 timeout/skipped/memory-risk/fail rows.
 
@@ -17,16 +17,17 @@ This suite preserves the feature-wise two-group mean-difference statistic and us
   - check: 2
 
 ## Correctness
-- Rows passing or checking the small matched CPU/JAX subset: 74.
-- Exact `pass` rows: 0; `check` rows: 74. The A100 float32 subset is kept as `check` because tiny statistic differences can flip about one permutation count in p-values.
+- Accepted small matched CPU/JAX subset rows: 74.
+- Exact `pass` rows: 0; historical `check` rows: 74. These are accepted bounded checks under the then-current status vocabulary, not exact pass rows.
+- New accepted A100 float32 rows should be emitted as `pass_gpu_tolerance`; tiny statistic differences can flip about one permutation count in p-values.
 - `max_abs_p_diff` and `max_abs_stat_diff` are from a bounded small matched subset for each benchmark row; large rows are timed without changing the statistic or permutation stream.
 
 ## End-to-end vs kernel-only
 - End-to-end rows include W construction, host-to-device transfer, `W @ X`, p-value reduction, and collection of reduced results.
 - Kernel-only rows are labeled `kernel-only hypothesis, not end-to-end permutation test`; they time only device-resident `W_batch @ X_device`.
 
 ## Bottleneck summary
-- Dominant measured A100 end-to-end stage: `permutation_generation_time_s`.
+- Largest recorded named A100 end-to-end stage in this run: `permutation_generation_time_s`.
 - A100 becomes faster at n=5000, p=50000, R=10000, batch_R=4096.
 
 ## Unavailable / OOM / timeout rows
 
@@ -18,11 +18,11 @@ Older quick-validation outputs, the incomplete long run, and the pre-x64 full ru
 ## Reproduce current curated figures
 
 ```bash
-/Users/lucajiang/anaconda3/envs/py312/bin/python -m experiments.run_macbook_evidence_extra \
+python -m experiments.run_macbook_evidence_extra \
   --output-dir experiments/results/macbook_air_long/latest \
   --checkpoint-every 20 --max-iter 15
 
-/Users/lucajiang/anaconda3/envs/py312/bin/python -m experiments.visualization.plot_macbook_air_evidence \
+python -m experiments.visualization.plot_macbook_air_evidence \
   --results-dir experiments/results/macbook_air_long/latest
 ```
 
 
@@ -52,11 +52,11 @@ Figure metadata:
 Use the project default local environment:
 
 ```bash
-/Users/lucajiang/anaconda3/envs/py312/bin/python -m experiments.run_macbook_evidence_extra \
+python -m experiments.run_macbook_evidence_extra \
   --output-dir experiments/results/macbook_air_long/latest \
   --checkpoint-every 20 --max-iter 15
 
-/Users/lucajiang/anaconda3/envs/py312/bin/python -m experiments.visualization.plot_macbook_air_evidence \
+python -m experiments.visualization.plot_macbook_air_evidence \
   --results-dir experiments/results/macbook_air_long/latest
 ```