code/scripts/README.md

code/scripts/ — entry points

This public release ships only the inference and sampling code for Q_θ.

File / dir	Purpose
evaluate.py	Score binders in a pre-built *.pkl test set with a Q_θ checkpoint; reports Spearman ρ, AUC, selectivity gap.
rescore.py	Re-score raw PDB designs (binder + holo + apo) with Q_θ.
pxdesign_guidance/	PXDesign-prior guidance with Q_θ (Langevin / SMC / TDS / classifier).

Training, baseline scoring (ProteinMPNN / ESM-IF / Rosetta / DFIRE / energy panel), guidance for RFdiffusion / Proteina-ComplexA, and paper-figure aggregation are not shipped; the inference path above is the only supported surface for the public release.

---

Deploying Q_θ with other base models

Q_θ provides two interfaces:

1. Re-ranker (best-of-K). Given K candidate binders from any prior, score each with S(Y) = Q_θ(X¹, Y) − Q_θ(X⁰, Y) and pick the top. No gradient signal needed; the prior is unmodified.
2. Gradient signal for guidance. Compute ∇_Y S(Y) via DifferentiableQTheta (in code/models/differentiable_features.py) and inject into the prior's sampler (Langevin step, SMC weight, TDS twist, classifier guidance score).

The pxdesign_guidance/ subdir is a worked example of interface (2) wrapping PXDesign. To plug Q_θ into another prior, mirror that pattern:

RFdiffusion

1. Clone RFdiffusion: https://github.com/RosettaCommons/RFdiffusion.
2. Follow its install + checkpoint download.
3. In RFdiffusion's diffusion loop, after each denoising step, materialize the predicted backbone, build the holo/apo graph inputs expected by DifferentiableQTheta, and either:
   • Apply a Langevin nudge: x ← x + η · ∇_x S(x).
   • Add a classifier-guidance term to the denoiser's xt-1 mean: μ' = μ + s · σ² · ∇_x log p(y|x), where log p(y|x) ≈ S(x) (Q_θ is treated as the log-likelihood of "is good binder").
4. Reference template: pxdesign_guidance/guided_pxdesign.py.

Proteina-ComplexA

1. Clone Proteina: https://github.com/proteinabio/proteina-complexa (or the released artifact).
2. Use its ComplexA mode that emits binder coords conditioned on a receptor.
3. Same plug pattern as RFdiffusion — wrap the sampler with DifferentiableQTheta for guidance, or run unguided and re-rank with evaluate.py / rescore.py.

Any backbone prior

The only contract Q_θ enforces:

• Receptor input is a PDB with holo and apo coordinates.
• Binder input is a PDB (or coords) with chain id distinct from receptor's.
• For guidance, expose differentiable Cα + backbone coordinates so ∇_x S(x) flows.

See code/models/differentiable_features.py:DifferentiableQTheta for the exact interface (load_receptor(holo_path, apo_path, …), score(design_path, binder_chain, state), .differentiable_score(coords, …)).

---

Why other guidance scripts aren't shipped

The RFdiffusion / Proteina guidance variants in our internal tree depend on those projects' un-released CIF formats and patched samplers; we don't want to ship modified third-party code. The PXDesign variants we do ship use only PXDesign's public API and are self-contained.

For citation / reproduction context, see the paper §4 (guidance methods).