AlloGen

State-selectivity scoring + guided generation for allosteric binder design.

🧪 One-click demo for biology users: — score CaM binders and run Q_θ-guided PXDesign sampling in 5 minutes. Notebook lives at notebooks/AlloGen_CaM_demo.ipynb.

AlloGen trains a scorer Q_θ(X, Y) ∈ (0,1) that ranks how well a binder Y discriminates a target's holo (active) state X¹ from its apo (inactive) state X⁰. The selectivity score is:

S(Y) = Q_θ(X¹, Y) − Q_θ(X⁰, Y)

Q_θ serves as both a re-ranker (best-of-K) and a gradient signal for guided generation on top of frozen priors (RFdiffusion, PXDesign, Proteina-ComplexA) via Langevin, SMC, TDS, or classifier guidance.

This repository accompanies the paper AlloGen: AlloGen: Conformation-Selective Binder Generation with Differential State Scoring (arXiv 2026).

Installation

conda env create -f environment.yml
conda activate allogen

Or pip-only:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Python 3.10 + PyTorch 2.x are required. A CUDA GPU is recommended for guidance, but CPU works for scoring single designs.

Inference quickstart

# Score the bundled CaM inference sample against the v4-S2 (target-swap) checkpoint
python code/scripts/evaluate.py \
    --target cam \
    --checkpoint checkpoints/Q_theta_phase2.pt \
    --data_dir data/sample/ \
    --outdir /tmp/cam_inference \
    --no_wandb

See inference.md for the scoring API + guidance command lines.

Repo layout

code/
  data/           dataset / graph construction, PDB I/O, target YAMLs
  models/         Q_θ scorer (graph transformer) + differentiable wrapper
  trainers/       two-phase training loop (DockQ regression + selectivity)
  utils/          PDB I/O, backbone frames, SAM optimizer
  scripts/        evaluate, rescore, PXDesign guidance (see scripts/README.md)
checkpoints/      Q_θ paper weights (v4-S2 target-swap split, via Git LFS)
data/sample/      tiny CaM inference sample (test split only)

Checkpoints

Paper weights for the v4-S2 target-swap split are bundled via Git LFS:

git lfs install
git lfs pull

Scoring a single design

import sys; sys.path.insert(0, 'code')
from models.differentiable_features import DifferentiableQTheta

scorer = DifferentiableQTheta(
    checkpoint='checkpoints/Q_theta_phase2.pt',
    device='cuda:0',
)
scorer.load_receptor(
    holo_path='your_holo.pdb', rec_chain='A',
    apo_path='your_apo.pdb',   apo_chain='A',
)
q_holo = scorer.score('design.pdb', binder_chain='B', state='holo')
q_apo  = scorer.score('design.pdb', binder_chain='B', state='apo')
print(f'S = {q_holo - q_apo:.3f}')

Guidance methods

The shipped guidance code wraps PXDesign as the prior and uses Q_θ as the gradient / classifier signal. All four method variants (Langevin, SMC, TDS, classifier guidance) live in code/scripts/pxdesign_guidance/.

See inference.md §3 for command lines.

To deploy Q_θ with RFdiffusion, Proteina-ComplexA, or any other backbone prior, see code/scripts/README.md — Q_θ exposes DifferentiableQTheta for ∇_x S(x), and the PXDesign code is a worked template to mirror.

Citation

@article{cao2026allogen,
  title         = {AlloGen: Conformation-Selective Binder Generation with Differential State Scoring},
  author        = {Cao, Hanqun and Quinn, Zachary and Pal, Aastha and Kimura, Sumi and Zhang, Jingjie and Heng, Pheng Ann and Chatterjee, Pranam},
  year          = {2026},
  eprint        = {2606.05474},
  archivePrefix = {arXiv},
  primaryClass  = {q-bio.BM}
}