Repository navigation
Examples
A tour of examples/ and research/, roughly smallest to largest. All of these run from the repo root after building (python build.py Release OpenBLAS --fast).
The smallest possible end-to-end example: SimplePCN learning XOR with a 2-8-1 network, no dataset loading. Good first script to read if you want to see configure()/train_step()/predict() with nothing else around them.
python examples/xor.pySequentialPCN on scikit-learn's 8x8 Digits dataset (1,797 images). Small and fast, good for iterating on the API without MNIST's download or training time.
The script behind the README's headline benchmark: SimplePCN, 784-512-512-10, sigmoid, AdamW with decay. Downloads canonical MNIST (idx-ubyte format, matching ngc-learn's preprocessing exactly) into ./data on first run.
python examples/mnist.py <seed> <epochs> <steps>
# e.g. python examples/mnist.py 7 100 20All three arguments are optional, defaulting to seed=7, epochs=15, steps=30.
The DKPPCN counterpart: same MNIST data, direct feedback alignment instead of classic settling, far fewer inference steps.
python examples/mnist_dkppcn.py <seed> <epochs> <inference_steps> <device>
# e.g. python examples/mnist_dkppcn.py 7 50 2 cpudevice accepts cpu, cuda, or gpu (defaults to cpu); see CUDA Backend for what's actually implemented there.
A tuned, "final validation" configuration layering several techniques together: forward-projection state initialization, uniform weight init matching ngc-learn's convention, AdamW, and mu_cache_threshold for settling speedups. Worth reading as a worked example of how these knobs compose, with the script's own comments explaining why each one is needed together rather than independently.
Hyperparameter search over SimplePCN's MNIST configuration using Optuna. Requires the dev dependency group (uv sync --group dev).
Runs SimplePCN, GaussSeidelPCN, ConvolutionalPCN, and SimpleConvolutionalPCN against each other for a quick relative-speed comparison, rather than one network in isolation.
Not predictive coding at all: plain PyTorch backprop baselines, built to match a PC script's architecture and training setup exactly (test_ffnn.py mirrors DKPPCN's shape, test_ffnn_deep.py mirrors mnist.py's SimplePCN config) so the two can be compared on equal footing. This is the same role the README's "PyTorch backprop (control)" column plays in the main benchmark table.
ImageNet-scale training, using the convolutional PC networks. imagenet.py holds the data pipeline (JPEG decode, CHW conversion, on-disk .npz cache so repeat runs skip re-decoding). imagenet_pc_vgg7_ce.py is the actual training script: a VGG-7 architecture matching PCX's own recipe, with cross-entropy energy on the terminal layer.
python research/imagenet_pc_vgg7_ce.py <epochs> <batch_size> <lr> <ir> <checkpoint_prefix> <T>All arguments are optional; T (settling steps) is overridable specifically to support sweeping it, per the main repo's roadmap item on whether a smaller T reaches comparable accuracy for less compute. Supports checkpoint/resume via ModelIO, so re-running the same command picks back up from <checkpoint_prefix>.safetensors.
Independent PyTorch replicas of PCX's own VGG-7 backprop baseline on the same data pipeline and hardware, with no Deepity involved. These exist to get a trustworthy reference number on this exact setup, rather than trusting a number copied from a paper that may have preprocessed data differently. imagenet_pytorch_baseline.py reproduced the paper's own target almost exactly (46.24% vs. the paper's 46.08%±0.15%) on its first confirmed run.
The remaining scripts (diagnose_pc_layer_stats.py, sweep_pc_ir.py, sweep_pc_optimizer_freeze.py, imagenet_bp_control_vgg7_ce.py) are working investigation scripts tied to specific debugging sessions on the ImageNet training instability mentioned above, not general-purpose usage examples. Their own docstrings explain the specific hypothesis each one is testing, if you're digging into that particular issue.