# Neural-network single-bit-flip experiment

This experiment loads a pinned pretrained CIFAR-10 ResNet-20, extracts the
64 values entering its final classifier, and exhaustively flips every stored
bit in every final-layer weight under float32, float16, and int8 storage. The
float16 and int8 comparisons keep the backbone in float32 so the scope stays
small enough to explain and reproduce.

It is the reproducible artifact for [**I Flipped One Bit in a Neural Network
Until It Developed a Favorite Animal**](https://blog.jasonsuhari.com/i-flipped-one-bit-in-a-neural-network).

## Reproduce

    python -m venv .venv
    .\.venv\Scripts\python.exe -m pip install -r requirements.txt
    .\.venv\Scripts\python.exe run_experiment.py
    .\.venv\Scripts\python.exe verify_results.py

On macOS or Linux, use `.venv/bin/python`.

The first run downloads the byte-identical 163 MB CIFAR-10 Python archive from
PaddlePaddle's public dataset mirror because the University of Toronto host can
stall on long transfers; the runner checks the archive against the MD5 published
on the official CIFAR page before extraction. It also downloads a 1.09 MB
checkpoint. PyTorch Hub loads model code from commit
`786c16252c0fc58ee9adac063f8337cc4a7a497a`; the runner refuses to continue
unless the checkpoint's complete SHA-256 is
`4118986f0df73003d572b0e397f0ac7b3f60af1f31aff3d2da164536e36f6ec8`.

## Selection rule

The calibration set contains the first 100 test images from each CIFAR-10
class. Among finite bit flips whose target row is one of bird, cat, deer, dog,
frog, or horse, the runner chooses the candidate with the largest target-class
prediction share; ties prefer lower accuracy, then the smaller flat weight
index and bit index. The selected candidate is evaluated once on all 10,000
test images.

## Outputs

- `results.json`: method, hashes, scope, controls, winning mutations, metrics,
  precision boundary, and environment.
- `candidate-search.csv`: all 35,840 candidates, including non-finite float
  results that were excluded from selection.
- `animal-target-summary.csv`: maximum calibration share and perfect-candidate
  counts for each animal class and storage format.
- `prediction-distributions.csv`: exact before-and-after class counts.
- `per-class-accuracy.csv`: exact scenario-by-class accuracy.
- `winner-predictions.csv`: all 10,000 labels, original predictions, winning
  feature activations, target logits, and mutated predictions.
- `prediction-collapse-evidence.png`: first-party chart rendered from the CSV.
- `manifest.json`: hashes and sizes for every output.

`verify_results.py` checks the committed outputs and single-bit invariant
without redownloading the dataset. Rerun `run_experiment.py` to reproduce the
model evaluation and candidate search.

## Claim boundary

This measures one pinned checkpoint, one test set, and one exhaustively
searched 10 x 64 final layer. It does not prove that every neural network has a
single-bit failure, and it does not model radiation, DRAM fault rates, ECC,
actual accelerator memory paths, or a full float16/int8 deployment.