Streamline reproduction tablesHEADmain

1 files changed, 55 insertions, 86 deletions

diff --git a/README.md b/README.md
index 0f3153e..fb4c83b 100644
--- a/README.md
+++ b/README.md
@@ -1,100 +1,69 @@
-# Anonymous KAFT MVP reproduction
+# KAFT minimal reproduction
 
-This repository is a minimal, self-contained reproduction of two core
-observations for deep message-passing GNNs:
+Run from the repository root. The experiment downloads Cora automatically and
+uses CPU by default.
 
-1. a plain deep GCN can lose usable backward transport even when a
-   standardized hidden-state probe remains informative; and
-2. Kronecker-Aligned Feedback Training (KAFT) improves training while leaving
-   the forward GCN unchanged.
+## Entry points
 
-The package intentionally contains only the code needed for this MVP. It does
-not include manuscript files, review material, cached datasets, private paths,
-or repository history.
+| Path | Command | Purpose |
+|---|---|---|
+| Notebook | `python -m pip install -r requirements.txt`<br>`jupyter nbconvert --to notebook --execute reproduce_mvp.ipynb --inplace --ExecutePreprocessor.timeout=1200` | One-click end-to-end reproduction with assertions and displayed tables |
+| CLI | `python -m pip install -e .`<br>`python run_mvp.py` | Equivalent non-interactive run |
 
-## One-click notebook
+## Protocol
 
-Open `reproduce_mvp.ipynb` and choose **Run All**. The first cell installs the
-local package, the experiment downloads Cora automatically, and the remaining
-cells train BP and KAFT, run the gradient diagnostic, display the result
-tables, and save machine-readable artifacts.
+| Field | Value |
+|---|---|
+| Dataset / split | Cora / public Planetoid split |
+| Forward model | Identical bias-free GCN for BP and KAFT |
+| Accuracy run | 6 layers, width 64, seeds 0--2, 200 epochs |
+| Diagnostic run | 10-layer BP, seeds 0--2, 100 epochs |
+| Optimizer | Adam, learning rate 0.01, weight decay \(5\times10^{-4}\) |
+| KAFT graph feedback | Fixed linear diffusion, \(\alpha=0.5\), 10 steps; hop cap \(K=3\) |
+| KAFT feature feedback | 64 Gaussian probes; alignment every 10 steps |
+| Selection | Test accuracy at the validation peak; test labels are not used for selection |
 
-The same notebook can be executed non-interactively:
-
-```bash
-python -m pip install -r requirements.txt
-jupyter nbconvert \
-  --to notebook \
-  --execute reproduce_mvp.ipynb \
-  --inplace \
-  --ExecutePreprocessor.timeout=1200
-```
-
-## Command-line reproduction
-
-```bash
-python -m pip install -e .
-python run_mvp.py
-```
-
-The default CPU protocol uses:
-
-- Cora with the public Planetoid split;
-- an identical six-layer, width-64, bias-free GCN forward model for BP and
-  KAFT;
-- seeds 0, 1, and 2;
-- Adam, learning rate 0.01, weight decay \(5\times10^{-4}\), 200 epochs;
-- KAFT diffusion \(\alpha=0.5\), 10 fixed linear propagation steps;
-- hop cap \(K=3\), 64 Gaussian probes, and alignment every 10 steps;
-- a separate ten-layer, 100-epoch BP diagnostic.
-
-KAFT changes only the hidden-layer backward rule. Its graph-side feedback is
-\(P_\ell(\hat A)D(\hat A)\), and its feature-side matrix is aligned to the
-chain-normalized suffix-weight probe target. The output layer uses the true
-cross-entropy error.
-
-## Outputs
-
-Running either entry point writes:
-
-```text
-artifacts/
-├── mvp_results.json
-├── mvp_summary.csv
-└── training_curves.png
-```
-
-The JSON file contains the full configuration, every seed-level result,
-training histories, and the ten-layer gradient diagnostic. Test accuracy is
-reported at the validation peak; the test labels are never used for
-selection.
-
-## Expected behavior
-
-Exact numbers can vary slightly with library versions and hardware. The
-checked-in executed notebook and artifacts record the environment used for
-the release. The intended qualitative checks are:
-
-- KAFT exceeds BP test accuracy in the six-layer comparison;
-- the ten-layer BP diagnostic reaches exact-zero weight gradients;
-- the output-adjacent preactivation error remains finite; and
-- the standardized penultimate hidden-state probe remains above chance.
-
-The checked end-to-end CPU run produced:
+## Checked reference output
 
 | Method | Test accuracy at validation peak |
 |---|---:|
 | BP | \(68.87\pm1.20\%\) |
 | KAFT | **\(78.53\pm1.33\%\)** |
 
-For the separate ten-layer BP diagnostic, all ten weight gradients were
-exactly zero in 3/3 seeds. The output-adjacent error remained between
-\(1.26\times10^{-4}\) and \(1.60\times10^{-4}\), while the standardized
-penultimate probe obtained 51.4--57.8% accuracy (seven classes).
+| Ten-layer BP diagnostic | Checked result |
+|---|---:|
+| Seeds with all weight gradients exactly zero | 3/3 |
+| Output-adjacent error | \(1.26\times10^{-4}\)--\(1.60\times10^{-4}\) |
+| Standardized penultimate probe accuracy | 51.4--57.8% |
+| Seven-class chance accuracy | 14.3% |
+
+## Verification contract
 
-## Scope
+| Assertion in `reproduce_mvp.ipynb` | Expected |
+|---|---:|
+| KAFT mean test accuracy exceeds BP | `True` |
+| All ten-layer BP weight gradients are exactly zero | `True` |
+| Output-adjacent error is finite and nonzero | `True` |
+| Standardized hidden probe is above chance | `True` |
+
+## Outputs
 
-This is a compact verification path, not the complete experimental suite.
-It covers the diagnostic and the central BP-versus-KAFT mechanism on one
-standard benchmark. The full evaluation uses additional datasets, backbones,
-depths, normalizers, and ablations.
+| File | Contents |
+|---|---|
+| `artifacts/mvp_results.json` | Configuration, environment, seed-level results, histories, diagnostics |
+| `artifacts/mvp_summary.csv` | BP/KAFT mean, standard deviation, and seed count |
+| `artifacts/training_curves.png` | Median training loss and test-accuracy curves |
+
+## Repository contents
+
+| Path | Role |
+|---|---|
+| `reproduce_mvp.ipynb` | Executed one-click reproduction |
+| `run_mvp.py` | Command-line entry point |
+| `kaft_mvp/data.py` | Dataset download and normalized sparse adjacency |
+| `kaft_mvp/trainers.py` | Matched BP and KAFT trainers |
+| `kaft_mvp/experiment.py` | Protocol, aggregation, and artifact generation |
+| `THIRD_PARTY.md` | Dependency and license summary |
+
+This MVP covers the central diagnostic and matched BP-versus-KAFT mechanism on
+one benchmark; it is not the complete experimental suite.