minAlphaFold2: a readable PyTorch re-implementation of AlphaFold2

The bottleneck this project names

The Why this exists section is the most interesting part of the README, because it argues that the problem is not computational but editorial. AlphaFold2 is described as one of the most consequential deep learning systems ever shipped, but reading it usually means bouncing between a 62 page supplement, a JAX codebase tuned for Google scale inference, and a production grade PyTorch port, OpenFold, that adds its own scaffolding on top. The lack of clear pedagogical resources is said to be a bottleneck in AI crossed with biology, causing AI talent to allocate into more legible fields such as language models or image generation, and that in turn limiting research progress, company formation and downstream medical innovation. The project trades production readiness for a single property: you can sit down and read AlphaFold2 cover to cover in an afternoon. The MIT licence, the primary language Python, the default branch main, a last push on 2026-10-05 and no GitHub releases describe a research project rather than a shipped product.

The rule that shapes the code: one file per numbered algorithm

The structure is the method. The README says the model architecture is around 3,000 lines of pure PyTorch and about 9,000 across the whole package including losses, data pipeline and training loop, and that every module maps one to one to a numbered algorithm in the 62 page supplement, which is included in the repository as af2_paper.pdf. The mapping section is called the authoritative index. Every file is named after the supplement section it implements, and every unusual design choice cites a paper line. The implementation is pure PyTorch, built from nn.Linear, nn.LayerNorm, torch.einsum and standard activations, with no einops, no custom CUDA kernels and no external machine learning libraries. The inspiration is named too, Andrej Karpathy's minGPT, which is the same pedagogical contract applied to a language model. The result is a codebase where a reader with the supplement open can navigate by algorithm number rather than by guessing which file implements what.

The quickstart, and the CPU sanity check

The Quickstart is three commands, and the third one is a test of the plumbing rather than a training run.

git clone https://github.com/ChrisHayduk/minAlphaFold2
cd minAlphaFold2
pip install -e '.[dev]'          # core: torch, numpy; + pytest

# 5-minute sanity check: overfit a single PDB on CPU.
python scripts/overfit_single_pdb.py \
  --pdb artifacts/overfit_single_pdb/1a0m_A/ground_truth_1a0m_A.pdb \
  --steps 1000

The README says the artifacts, namely the predicted PDB, the ground truth PDB, a PyMOL view script and per step losses, land in artifacts/overfit_single_pdb/<chain_id>/, and that this confirms the forward pass, the losses and the optimiser plumbing all work end to end without any of the MSA or template machinery. That last clause is the important one, because it isolates what you can check in five minutes on a laptop from what you cannot. The pyproject.toml shows why the environment is small: only two runtime dependencies, torch at 2.3 or newer and numpy at 1.24 or newer, with the comment that this matches the pure PyTorch and standard library philosophy, and everything else, meaning structure relaxation, cloud GPUs and tests, is optional.

The three rung training ladder

The training ladder is the clearest teaching device in the repository, because it gives you three strictly increasing scopes. Rung 1 is the single protein overfit, which asks whether the model works at all, and the README says it takes about a minute on CPU or about 20 seconds on a laptop GPU, converging to sub angstrom C alpha RMSD. Rung 2 is small scale training on a handful of chains, where you preprocess two or three OpenProteinSet chains locally and run a few epochs to exercise the whole pipeline, including block deletion, MSA clustering, template processing, crops, losses and checkpoints. The README frames rung 2 as the rung for iterating on architecture or loss changes, which is the actual research use case.

python scripts/train_af2.py \
  --stage initial \
  --model-config tiny \
  --training-protocol alphafold2 \
  --checkpoint-dir checkpoints/smoke \
  --processed-features-dir data/processed_features \
  --processed-labels-dir data/processed_labels \
  --batch-size 1 --grad-accum-steps 1 \
  --epochs 2

Rung 3 is the full reproduction following the protocol in supplementary table 4, with two stages, about ten million training samples in stage 1 and about 1.5 million in stage 2, and the README notes the stage 1 cost as roughly seven days on TPUv3. The gradient accumulation detail is worth pausing on, because it is where the single GPU claim comes from. The README says grad_accum_steps closes the gap to the 128 core TPU configuration, that larger values accumulate clipped micro batch gradients weighted by actual sample count, that a partial window at the end of an epoch is also updated but with a smaller effective batch, and that at paper scale the default batch size times grad accum steps matches the protocol's 128 way effective batch. Gradient checkpointing, cited to supplement section 1.11.8, is what fits the 48 block Evoformer at full chain crop sizes.

The paper spec recipe, and where it lives

The training recipe is claimed to come straight from the paper, and the README is specific about what that means. Two stage training, initial then fine tune, with gradient accumulation, a samples based warmup then decay learning rate schedule, parameter EMA, gradient clipping, and a section 1.9.11 violation loss that turns on at the fine tune boundary, all driven from a single configuration file, configs/training_alphafold2.toml, with the model architecture in a second file, configs/alphafold2.toml. Both are described as commented line by line with supplement citations, and the README says the hyperparameters of crop sizes, learning rate, warmup samples and violation loss weight come straight from the training config while the architecture comes from the model config. The violation loss is the detail that shows the fidelity intent, since it is a term that exists to penalise a specific geometric violation and switching it on only at the fine tune boundary is not a detail you would invent.

Cloud GPUs through Modal, and the held out experiment path

For people who do not have TPU access, the project offers a cloud path through Modal. The README says one command launches the full two stage training on H200 or A100 hardware, with runs that auto resume from a shared checkpoint volume, and the sample commands show the pattern: install the modal extra, run modal setup, put the processed features and labels onto a volume as a one time upload of roughly 100 GB, then run one script per stage, with the checkpoint volume named minalphafold-checkpoints and the data volume minalphafold-data. The final checkpoints are pulled back with a volume get. The same section covers held out experiments, where you supply exact role manifests and set the validation fraction to zero so nothing is split at random, and the manifest format is given as a chains array with a chain id and a full group id, with the instruction to include the authoritative group ID on every entry in both files so that group separation can be checked, and cluster id also supported.

The optional dependencies, and what the project is not

The pyproject.toml is where the project's boundaries are stated most economically, and the extras are small and explained. The relax extra pulls in openmm and pdbfixer for Amber style structure relaxation, following supplement section 1.8.6, with a comment that it drags in C++ extensions unrelated to the model itself, so it should be installed only if you actually want to clean up predicted bond lengths and clashes. The modal extra pulls in modal itself, and the dev extra pulls in pytest, with an all extra that combines them. The README is equally direct about what this is not. It is not an inference harness around DeepMind's weights, it is not a speed benchmark, and it is not an AF2 multimer or AF3 implementation. What it is, in the README's words, is a compact, trainable, single file per algorithm reference that you can fork, tweak and run end to end on a single GPU. The trade is stated plainly in the Why this exists section, and it is the right trade for the stated audience, which is a reader trying to learn the algorithm rather than a team trying to ship a predictor.

Editorial conclusion

Adopt minAlphaFold2 if your goal is to understand how AlphaFold2 works, or to prototype architecture and loss changes for protein structure prediction, because the one to one mapping between files and the supplement's numbered algorithms is the whole point of the project. Do not adopt it to predict structures in production, since the README states plainly that it is not an inference harness around DeepMind's weights and not a speed benchmark. Before you start, read the supplement alongside the code, budget for the data pipeline rather than the model, and confirm the single GPU training path is what you need rather than a TPU scale reproduction.

Frequently asked questions

Official sources

1. ChrisHayduk/minAlphaFold2 on GitHub
2. Issues
3. License: MIT
4. README