| # `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). |
|
|
