docs: freeze native baseline reproductions

1 files changed, 147 insertions, 0 deletions

diff --git a/BASELINES.md b/BASELINES.md
new file mode 100644
index 0000000..34e9f58
--- /dev/null
+++ b/BASELINES.md
@@ -0,0 +1,147 @@
+# Native-baseline reproduction ledger
+
+This ledger separates three comparison types:
+
+1. matched architectures/budgets inside this repository;
+2. native author protocols reproduced without tracked source edits;
+3. published author numbers used for context while reproduction is pending.
+
+Native protocols are not equal-compute comparisons. Their value is to prevent
+weak in-house reimplementations from defining the state of the art.
+
+## In-repository baselines
+
+The audited implementations and completed results are in `RESULTS.md`:
+
+- BP, FA, and DFA share the SDIL forward architecture and data order;
+- direct node perturbation uses a causal target on every hidden update and no
+  learned vectorizer;
+- the no-traffic, `P=0` SDIL backbone is learned direct feedback by node
+  perturbation in the sense of Lansdell, Prakash, and Kording (2020);
+- PEPITA and Forward-Forward use paper/reference-code schedules;
+- canonical EP uses persistent free particles and the published shallow/deep
+  relaxation schedules.
+
+The main ledger reports accuracy, wall time, scalar loss observations,
+forward-equivalent examples, peak memory, and any test-selection differences.
+
+## BurstCCN native CIFAR-10
+
+- Paper/model: Greedy et al., *Cell-type-specific cortical feedback coordinates
+  hierarchical credit assignment* (2026),
+  <https://www.biorxiv.org/content/10.64898/2026.06.16.732595v1>.
+- Author repository: <https://github.com/neuralml/BurstCCN-journal>.
+- Frozen revision: `9170e110b4d18729dc5bc5d517fc52eefcd04d69`.
+- External checkout: `/scratch/yurenh2/sdil-reference/BurstCCN-journal` on
+  `timan107`.
+- Environment: `/scratch/yurenh2/venvs/burstccn`.
+- Dataset root: `/home/yurenh2/sdrn/data`.
+
+The repository's top-level `cifar10_burstccn_fa` default currently resolves to
+sigmoid/MSE with fixed random feedback. That configuration stayed at chance in
+an initial compatibility run and does not match the paper's strongest CIFAR
+method. The paper Methods and repository plotting labels specify ReLU with
+divisive RMS normalization, softmax output, and plastic W/Y/Q pathways. The
+paper-faithful Hydra resolution used here is:
+
+```text
+--config-name=cifar10_burstccn_kp
+dataset.root=/home/yurenh2/sdrn/data
+model.hidden_activation_function=relu_rms
+model.output_activation_function=softmax
+model.W.optimiser.lr=0.002
+model.Y.mode=sym_W
+model.Q.mode=sym_Y
+```
+
+The inherited configuration supplies three convolutional layers plus a
+1500-unit fully connected layer, batch size 32, 400 epochs, label smoothing
+0.05, SGD momentum 0.9, weight decay `1e-4`, two warmup epochs and cosine
+decay. Y and Q use learning rate `0.001`. The paper reports
+`17.03 ± 0.21%` top-1 error (`82.97 ± 0.21%` accuracy) for symmetric-plastic
+BurstCCN.
+
+Reproduction command (seed 0):
+
+```bash
+WANDB_MODE=offline WANDB_SILENT=true \
+WANDB_NAME=burstccn-cifar10-symplastic-paper-seed0 \
+WANDB_DIR=/scratch/yurenh2/burstccn-wandb CUDA_VISIBLE_DEVICES=5 \
+/scratch/yurenh2/venvs/burstccn/bin/python train.py \
+  --config-name=cifar10_burstccn_kp \
+  dataset.root=/home/yurenh2/sdrn/data training.seed=0 \
+  model.hidden_activation_function=relu_rms \
+  model.output_activation_function=softmax \
+  model.W.optimiser.lr=0.002 model.Y.mode=sym_W model.Q.mode=sym_Y \
+  hydra.run.dir=/scratch/yurenh2/burstccn-native/cifar10_symplastic_paper_seed0
+```
+
+The native trainer evaluates test every epoch and records both latest and best
+test error. It has a validation loader but model saving is disabled in this
+configuration. We will report final test accuracy as the primary reproduction,
+native best-test accuracy separately, and explicitly label the latter as
+test-selected. No run will be removed for a poor endpoint.
+
+## Dual Propagation native CIFAR-10
+
+- Paper/model: Høier and Zach, *Two Tales of Single-Phase Contrastive Hebbian
+  Learning* (ICML 2024), <https://arxiv.org/abs/2402.08573>.
+- Author repository: <https://github.com/Rasmuskh/dualprop_icml_2024>.
+- Frozen revision: `7b2595b34421e1483a721dbfdeff8cdabda3a1ff`.
+- External checkout: `/scratch/yurenh2/sdil-reference/dualprop_icml_2024` on
+  `timan107`.
+- Environment: `/scratch/yurenh2/venvs/dualprop` with JAX/JAXlib 0.4.14 and
+  CUDA 11.8/cuDNN 8.6 runtime wheels.
+
+The official CIFAR archive already present in `/home` used Python batches,
+whereas TensorFlow Datasets requested the official binary layout. It was
+losslessly converted into
+`/scratch/yurenh2/cifar10-binary-converted-v1.tar.gz`; TFDS then generated the
+author-code records under `data/cifar10/3.0.2`. The verified splits contain
+50,000 train and 10,000 test examples. No image or label values were changed.
+
+The paper's strongest stable CIFAR-10 row is DP-transpose with `alpha=0`,
+`beta=0.1`, reporting `92.41 ± 0.07%`; the paper BP reference is
+`92.36 ± 0.16%`. The exact author script uses VGG16, 130 epochs, batch size
+100, 16 requested `fwK` nudged passes (17 forward-only layer passes including
+the initial pass), 90/10 train/validation selection, peak learning rate 0.025,
+10 warmup epochs, decay at epoch 120, momentum 0.9, and weight decay `5e-4`.
+It saves the best-validation checkpoint and evaluates test once after training.
+
+The complete seed-1988 reproduction uses the official command with only the
+experiment name added:
+
+```bash
+CUDA_VISIBLE_DEVICES=7 XLA_PYTHON_CLIENT_PREALLOCATE=false \
+TF_FORCE_GPU_ALLOW_GROWTH=true \
+/scratch/yurenh2/venvs/dualprop/bin/python train.py \
+  --model VGG16 --dataset cifar10 --num-epochs 130 --batch-size 100 \
+  --alpha 0.0 --beta 0.1 --loss sce --inference-sequence fwK \
+  --inference-passes-nudged 16 --learning-rate 0.025 \
+  --learning-rate-final 0.000002 --warmup-learning-rate 0.001 \
+  --learning-algorithm dualprop-lagr-ff --activation relu \
+  --decay-epochs 120 --warmup-epochs 10 --momentum 0.9 \
+  --weight-decay 5e-4 --dtype float32 --param-dtype float32 \
+  --percent-train 90 --percent-val 10 --seeds 1988 \
+  --experiment-name sdil-dp-full-a0-b0p1-seed1988-v1
+```
+
+The actual command also prepends the environment's NVIDIA wheel `lib`
+directories to `LD_LIBRARY_PATH`; this changes runtime linkage, not author
+source. A one-epoch full-VGG smoke completed without OOM/NaN in 203.4 training
+seconds, reaching 20.48% validation and 20.04% test accuracy. The 130-epoch
+seed is therefore scheduled as a long native reproduction rather than treated
+as a cheap matched baseline.
+
+## Reporting rules for external runs
+
+- Record repository URL/revision, tracked-source cleanliness, full resolved
+  configuration, environment package freeze, dataset identity, GPU, wall time,
+  and output hashes.
+- Preserve failed compatibility runs, but do not mix them into a paper-method
+  aggregate when their resolved protocol differs from the paper.
+- Report native final, validation-selected, and test-selected metrics under
+  separate labels.
+- One reproduced seed is evidence of executable fidelity, not a replacement for
+  a published multi-seed uncertainty interval. Expand seeds only when GPU time
+  permits and never select the reproduced seed by its accuracy.