HybriDock-Pep

HybriDock-Pep is a brand new protein-peptide docking and scoring pipeline, with many features like selectivity and high accuracy. Given a receptor PDB and a peptide sequence, it folds and docks the peptide through a modified diffusion generative built for effeciency and accuracy. Then it runs a physics-based ML scorer working geometry features outputting kcal/mol with accuracy in the range of ABFE. From the either the CLI or the terminal UI, it runs efficiently on consumer hardware, and tested against >1,000 real complexes. Get started and run it yourself.

Creator: Choppa Purandhar Ram, 15 Years Old

Table of contents

1. What this does
2. The pipeline
3. Get started
4. Usage & subcommands
5. Advanced / manual install
6. Repository structure
7. Testing
8. Why us?
9. Roadmap
10. Project status · Citations · License

---

What this does

The software takes a protein structure (in the form of a PDB file) and a peptide sequence, to hand back ranked 3D poses of the peptide folded, along with a calibrated binding score(ΔG, in kcal/mol). Furthermore, it also returns a selectivity score when given 2 proteins as receptors as it then identifies if the peptide prefers a protein more than the other, and by how much in terms of a relative kcal/mol to the proteins.

Built for iGEM: Taking into account the hardware constraints of iGEM teams, it works in a way where it delivers hundreds of peptide poses on even laptops like a MacBook in under 30 minutes.

It does not need a GPU. Measured end-to-end with the GPU made invisible: 100 poses in 7 min 40 s, 10 poses in 68 s, on an 8-core Apple M3 — ΔG −9.4 kcal/mol, the same answer the GPU path gives. That works out to ~24 s of setup plus ~4.4 s per pose, so a few hundred poses still lands inside half an hour with no accelerator at all. Full method, caveats, and the command to re-run it: Hardware floor. No GPU and no install at all? Run it on a free Colab T4.

The pipeline

The software is split into 2 main parts: an AI diffusion generative model making 3D poses, docked and folded, and a physics and geometry-based model that scores the poses and outputs a ΔG in kcal/mol. Happening in two Conda environments, the code is split and built for simple, fast pipelines.

The main scorer ΔG Stage 3.6 of the software scores the peptide's affinity to the protein with a self-made geometry-feature model and an ML model. While we could've used already existing scoring functions, we identified the lack of development in the area of peptides and therefore made, what we claim, to be the best non-FEP/LIE scoring model for peptides, even achieving kcal/mol scores at an MAE of ~1.6 kcal/mol where ABFE reports an average error of ~1-2.5 kcal/mol.

Furthermore, it can also run crystal protein-peptide docking, with values attuned to them. crystal-score runs the sibling crystal-tuned model directly on it.

--refine-topk K is a Stage 3.5 addition that runs energy-minimization in GBn2 implcit solvent and outputs a larger, more relative kcal/mol score, usually ~-60 kcal/mol with large deviations. It acts to relax the peptide onto the protein better in order to find better fits the AI model might have missed. We use our own scoring model instead of this, and more details can be found in Usage.

Being a scientific model, it has claims and data associated with the pipeline software. However, there are 3 main claims that we make: (1) it's the best non-FEP/LIE peptide affinity scorer we can find a fair baseline for; (2) It is the most effecient (accuracy/time) model publicly available, with MAE in range of cross-target ABFE; and (3) it ships a structure-based selectivity ΔΔG a sequence-only ML scorer structurally can't provide. Full evidence: The claims.

---

Get started

Prefer a video? Setup and first run — full walkthrough covers everything in this section on a clean machine.

0. No GPU? Run it in the browser on Google Colab

notebooks/HybriDock_Pep_Colab.ipynb runs the whole pipeline — sampling and scoring — on a free Colab T4 GPU. Nothing to install locally; open the badge, set Runtime ▸ Change runtime type ▸ T4 GPU, and run the cells top to bottom. It clones the repo, builds both environments via scripts/colab_setup.sh, validates the install with crystal-score, then gives you form fields for the peptide, receptor (bundled example, RCSB PDB ID, or your own upload), pocket, and sample count. Results come back as a ranked table, a 3D view of the best pose, and a downloadable zip.

Tight on runtime disk? bash scripts/colab_setup.sh --lite trims ~260 MB — the blind-mode checkpoint, the AD4/obabel extras, and the Boost C++ headers once Vina has compiled. It cannot touch the two things that actually dominate the install, PyTorch and the 2.4 GB ESM-2 weights, because docking needs both.

Budget 15–25 minutes for the environment build, once per Colab session, then ~3–10 minutes for a --n-samples 100 dock of a 12-mer. Mounting Google Drive in the notebook's second cell caches the ~2.5 GB ESM-2 weights and the model checkpoints between sessions.

The setup script picks the CUDA build to match whichever GPU Colab hands you — a T4 is compute capability 7.5 and needs a different PyTorch wheel than the cu128 build install.sh uses locally — and verifies it with a real kernel launch and a PyG import rather than trusting the version string. Prefer a local install if you have your own GPU: it is faster and nothing is reclaimed out from under you.

Rather use a shell than a notebook? You never have to touch the notebook's forms. Open a Colab terminal (the button at the bottom of the left sidebar on Colab Pro; on the free tier, run !pip install -q colab-xterm, %load_ext colabxterm, %xterm in a cell) and:

git clone --recursive https://github.com/Tasty-Ramen2010/hybridock-pep.git
cd hybridock-pep
bash scripts/colab_setup.sh

That puts hybridock-pep and hybridock-tui on PATH and wires ~/.bashrc, so every command in this README works verbatim from then on — including hybridock-tui, the guided UI, which a notebook cell cannot host but a terminal can:

hybridock-tui                    # or drive the CLI directly:
hybridock-pep dock --peptide ETFSDLWKLLPE --receptor data/pdbs/1YCR_mdm2.pdb \
    --site 25.20 -25.61 -7.97 --box 30 --n-samples 100 --output-dir runs/my_run

1. Install

macOS, Linux, or WSL2:

git clone --recurse-submodules https://github.com/Tasty-Ramen2010/hybridock-pep.git
cd hybridock-pep
./install.sh

Windows: double-click install.bat (or run it from PowerShell/CMD) once as it sets up WSL2 for the user, then runs install.sh inside it. After that, you can open the WSL2/Ubuntu terminal (type wsl in any Windows terminal). All work is done inside WSL2, not cmd or PowerShell

install.sh does everything: installs conda if you don't have it, creates both conda environments with the right PyTorch build for your GPU, downloads and checksum-verifies the RAPiDock models' weights (~110 MB, from Zenodo), checks the receptor-prep tooling, runs a smoke test, and finishes by opening the guided terminal UI.

1. It takes around ~15-30 minutes most of it is conda quietly solving dependencies plus a PyTorch download. If it looks frozen on a line like Solving environment: \, DO NOT Ctrl+C it.
2. It's safe to re-run any time, and is reccomended to do after git pull.
3. In every new terminal after that, run conda activate score-env before using the CLI or UI.

flag	effect
--no-ui	don't auto-launch the UI at the end — useful for scripted or headless installs
--force	recreate the conda environments from scratch
--skip-rapidock	scoring environment only, skips the GPU sampling environment
--lite	skip rapidock_global.pt (54 MB) — the checkpoint only dock --blind reads. Ordinary site-directed docking is unaffected; PyTorch and the ESM-2 weights are needed either way

Already installed and want the latest? From inside the hybridock-pep folder:

git pull
git submodule update --init --recursive
./install.sh

git pull gets the new code, git submodule update catches up the bundled RAPiDock submodule if it moved too, and re-running install.sh just makes sure new dependencies are installed.

Uninstalling ./uninstall.sh removes the two conda environments and the downloaded model weights (asks for confirmation first); ./uninstall.sh --all also deletes this entire folder. conda/Miniforge installation is left unbothered; refer to ./uninstall.sh --help.

2. Check it worked

hybridock-pep crystal-score \
    --receptor data/pdbs/1YCR_mdm2.pdb \
    --peptide-pdb data/pdbs/1YCR_peptide.pdb \
    --peptide ETFSDLWKLLPE

Expect Crystal ΔG = -9.28 kcal/mol. Anything from −8 to −11 means a healthy install and everything is built properly. The experimental affinity for the (MDM2/p52, PDB 1YCR) complex is known to be -8.5. The machine just rescores an already exisinting pose, and is the fastest way to know scoring is working as intended. The command make verify can be run to check all of the functions offered by the software.

3. Run something real

Command to run pipeline:

hybridock-pep dock \
    --peptide ETFSDLWKLLPE --receptor data/pdbs/1YCR_mdm2.pdb \
    --site 25.20 -25.61 -7.97 --box 30 --n-samples 20 \
    --output-dir runs/demo

About ~15 minutes on an Apple M3. This is the one part of a run that needs the GPU sampling environment (already installed above, unless you passed --skip-rapidock). Results land in runs/demo/best_pose.pdb and runs/demo/ranked_poses.csv.

--site is the centre of the binding pocket, in ångströms, and must match the receptor you passed — getting it wrong is the most common mistake (the run finishes but searched empty space). See hybridock-pep guide dock, or help topic 8 in the UI.

To enter the terminal UI:

./launch_ui.sh

walks you through the same fields with a live progress bar. Its --demo mode simulates a full run in a few seconds with no GPU at all, and familiarizes the user with the rest of the UI.

./launch_ui.sh --demo

Below are screenshots of the software in action, including ASCII art, a finished demo, and the help screen.

key	action
↑ / ↓	move between form fields (Tab / Shift-Tab also work)
Ctrl-C	STOP — abort a running job and everything it spawned
Ctrl-G	help — 10 topics, including selectivity, crystal scoring, AI vs physics scoring
Ctrl-T	Demo run (no GPU)
Ctrl-R	Full run
Ctrl-Y	Crystal Score — score an existing bound pose, no sampling (see below)
Ctrl-B	browse for a file (or just drag a .pdb onto any path field)
Ctrl-Q	quit — Ctrl-C only stops the current run

The Scoring mode field picks between the UI's two capabilities: ai (default — Full ▶ / Half / Quick / Selectivity ⚖ / Demo ▷ all run RAPiDock sampling + the AI affinity model; the Vina/AD4 physics backends run automatically underneath and are never a field you fill in) and crystal (score an existing bound pose directly with the crystal-tuned model — no sampling, seconds instead of minutes; fill in Peptide pose PDB and press Crystal Score ⚗ / Ctrl-Y). Same underlying commands as dock and crystal-score below — the UI just fills them in for you.

The ASCII gallery isn't just for the demo — the plain CLI shows the same rotating gallery during a real Stage 1 wait. There's a small easter egg in the terminal UI too, if you go looking (Ctrl-A). Set HYBRIDOCK_NO_ART=1 to turn all of it off.

4. Built-in help, right in the terminal

No UI needed — worked examples with real measured numbers:

hybridock-pep guide dock      # one worked example + measured timing
hybridock-pep guide prep      # receptor prep, why the backend doesn't change your ΔG
hybridock-pep guide tuning    # environment switches, Apple Silicon notes
hybridock-pep guide all

5. Run the test suite

pytest                  # fast suite — 730 passed, 72 skipped, ~20-40s
pytest -m slow          # + real Vina/OpenMM/terminal integration tests, ~55 min
pytest -k mmgbsa        # just one area

Skips aren't failures — they're the slow tier plus tests for optional tools you may not have installed.

Environment switches

variable	effect
HYBRIDOCK_RAPIDOCK_BATCH=N	poses per diffusion step (default derived from RAM)
HYBRIDOCK_MMGBSA_FAST=1	5.4× faster MM-GBSA; shifts ΔG by up to ~4.5 kcal/mol
METAL_E3NN_DISABLE=1	disable the optional metal-e3nn kernel (A/B testing)
HYBRIDOCK_NO_ART=1	turn off the ASCII art gallery during long waits

---

Usage — the seven subcommands

HybriDock-Pep is one CLI with seven subcommands: dock, selectivity, reproducibility, crystal-score, prep, calibrate, benchmark. Run hybridock-pep <command> --help for the full flag list.

dock — end-to-end docking + scoring

hybridock-pep dock \
    --peptide ETFSDLWKLLPE \
    --receptor receptors/mdm2.pdb \
    --site 25.20 -25.61 -7.97 \   # binding-site center (x y z, Å)
    --box 30 \                    # search box edge (Å)
    --n-samples 100 \             # RAPiDock passes (default 100)
    --refine-topk 10 \            # MM-GBSA on the top-10 cluster reps
    --output-dir runs/mdm2_p53

The default ΔG (delta_g) is the AI-pose affinity model — Vina is clash-relief only, AD4 is off.

Flag	What it does
--scoring vina,ad4	force-field backends to run (default vina = clash relief; add ad4 for research telemetry). Neither is the headline ΔG.
--refine-topk K	physics absolute-ΔG refinement — MM-GBSA (AMBER ff14SB + GBn2) on the top-K cluster reps. Note: MM-GBSA gives a physically-grounded single-snapshot energy but ranks worse than the learned scorer on our data (r≈0.25 vs 0.32); use it for an absolute-energy sanity check on final candidates, not for ranking.
--ultra [K]	ultra ranking mode — compute rank_score as the mean of K feature-jittered evaluations (randomized smoothing, default K=32). Tightens within-target ranking ~+2 pts pairwise at ~K× scoring cost; does not improve absolute ΔG.
--ensemble	also emit the optional geometry+Vina ensemble ΔG column (research/telemetry; not the default scorer)
--free-entropy	add the free-state conformational-entropy feature (helps long/floppy peptides)
--input-poses DIR	skip Stage 1 and score pre-generated poses (e.g. sampled on a remote CUDA box)
--seed N	deterministic run (modulo CUDA nondeterminism; logged to run_metadata.json)
--mmgbsa-ie / --mmgbsa-3traj / --mmgbsa-dielectric EPS	interaction-entropy term · three-trajectory MM-GBSA · custom solute dielectric
--mmgbsa-cpu-only / --no-minimize	force MM-GBSA onto CPU · skip the OpenMM pre-minimization

Blind docking — no known pocket

Give --blind with no --site and HybriDock-Pep finds its own candidate binding sites instead of requiring you to name one:

hybridock-pep dock \
    --peptide ETFSDLWKLLPE \
    --receptor receptors/mdm2.pdb \
    --blind \
    --n-pocket-search 300 \   # exploratory poses across the whole receptor (default 300)
    --n-pockets 3 \           # candidate binding sites to refine (default 3)
    --n-per-pocket 150 \      # poses generated at each candidate site (default 150)
    --output-dir runs/blind_run

Three stages, all automatic: (1) an exploratory pass at --n-pocket-search poses across the whole receptor using rapidock_global.pt (the checkpoint trained for whole-receptor, no-pocket-hint sampling); (2) those poses' Cα centroids are grouped spatially into --n-pockets candidate sites, ranked by how many poses landed there; (3) each candidate site gets its own focused --n-per-pocket-pose refinement pass, with the receptor cropped to a neighborhood of that site and the checkpoint chosen by peptide length (see below). The refined poses (not the exploratory ones) flow into scoring exactly as a single-site run would; pocket_assignment.csv in the output directory records which candidate site each pose came from.

--blind with --site still works as before (a hint that only disables the off-pocket pose filter, not the pocket-search pipeline) — pocket search only triggers when --site is omitted entirely.

Long-peptide checkpoint routing

RAPiDock's placement accuracy degrades with peptide length — the standard checkpoint (rapidock_local.pt) does fine on ≤12-mers but its long/very_long (13+ residue) placement error grows well past what any downstream correction can fix. A specialized checkpoint (longer_local.pt, unfreezes the receptor-interaction layers and retrains on a length-stratified oversampled set — see docs/architecture.md "Long-peptide checkpoint") targets exactly that population. Every dock run (blind or sited) routes automatically:

hybridock-pep dock ... --long-checkpoint-threshold 13   # default; peptides ≥ this route to longer_local.pt

If longer_local.pt isn't present in your model directory, routing silently falls back to rapidock_local.pt with a logged warning — nothing breaks on a fresh install that only has the two checkpoints the base RAPiDock-Reloaded release ships.

selectivity — does my peptide prefer target A over off-target B?

hybridock-pep selectivity \
    --peptide LISAAALAAIFAAALAC \
    --target-receptor data/pdbs/1T2D_receptor.pdb \
    --target-site 24.84 22.73 41.69 --target-box 30 \
    --offtarget-receptor data/pdbs/hldh.pdb \
    --offtarget-site 63.30 -30.43 -29.90 --offtarget-box 30 \
    --output-dir runs/selectivity_check

Returns ΔΔG = ΔG_target − ΔG_offtarget with a 95 % bootstrap CI over the top-K cluster centroids. Negative ΔΔG with a CI that doesn't cross zero ⇒ statistically selective. This sidesteps the absolute-Kd ceiling because the same systematic bias applies to both receptors and cancels in the difference.

reproducibility — multi-seed pose agreement

hybridock-pep reproducibility \
    --peptide ETFSDLWKLLPE --receptor receptors/mdm2.pdb \
    --site 25.20 -25.61 -7.97 --box 30 \
    --seeds 1 2 3 --n-samples 100 --output-dir runs/repro

Runs the pipeline once per seed and reports the Cα-centroid agreement across runs — the honest stochastic stability of the sampler on your target.

crystal-score — score an existing crystal pose

HybriDock-Pep ships two scoring functions of the same design, separately tuned: the AI-pose model (the default inside dock, calibrated on RAPiDock/AI poses) and the crystal model (calibrated on crystal/native poses). When you already have a crystal-quality bound pose and just want its ΔG — no docking — call the crystal scorer directly:

hybridock-pep crystal-score \
    --receptor receptors/mdm2.pdb \
    --peptide-pdb poses/native_peptide.pdb \
    --peptide ETFSDLWKLLPE
# → Crystal ΔG = -9.28 kcal/mol  (geometry + interaction map, crystal-tuned model)

No RAPiDock, no Vina, no MM-GBSA — it runs the geometry + interaction-map crystal model (affinity_crystal_ifp.joblib (packaged), override with --artifact) on the pose you give it.

prep — pre-build a receptor PDBQT

hybridock-pep prep --receptor receptors/mdm2.pdb --output-dir prepped/

Wraps receptor preparation (meeko mk_prepare_receptor.py, or ADFRsuite prepare_receptor when present) so you can cache the receptor once and reuse it across many dock runs.

calibrate — fit the ΔG correction to your own data

hybridock-pep calibrate \
    --training-csv data/training_complexes.csv \
    --scores-json data/training_scores.json \
    --output data/calibration.json

Pass the result to dock --calibration data/calibration.json. Shipped calibrations live in data/ with full LOO-CV provenance; see docs/calibration_notes.md.

benchmark — score a CSV of complexes against baselines

hybridock-pep benchmark \
    --test-csv data/test_complexes.csv \
    --baselines vina,adcp \
    --report benchmark_report.md

ARM Linux (DGX Spark, Grace, Graviton, Ampere)

Verified end-to-end on a DGX Spark (GB10, linux-aarch64): 693 tests pass and dock completes. Two platform limits, both handled automatically:

• No autogrid build on conda-forge for linux-aarch64, so --scoring ad4 is unavailable. AD4 is off by default and the reported ΔG comes from the affinity model, so nothing else changes. The installer says so instead of failing.
• No openbabel build for Python 3.11 either, so neither babel nor obabel exists. Ligand prep falls back to meeko's Polymer route. It works, but converts fewer poses than babel (7/20 on a 1YCR --n-samples 20 run) because meeko rejects poses it cannot template-pad — raise --n-samples to compensate.

If your GPU is newer than the PyTorch wheel that gets installed (the GB10 is sm_121; the cu128 wheel targets sm_90/100/120), Stage 1 detects it and disables TorchScript GPU fusion, which is the only part that needs runtime NVRTC codegen. Without that, every fused kernel dies with nvrtc: error: invalid value for --gpu-architecture and sampling silently produces zero poses.

Cross-platform & accelerator tuning (CUDA · ROCm · oneAPI · Metal · CPU)

Backend selection and per-device tuning are automatic — no flags. Each compute path is routed to the fastest silicon available and tuned for it, centralized in hybridock_pep/hardware.py (OpenMM) and sampling/run_rapidock.py::_optimize_backends (torch):

Stage (engine)	NVIDIA (CUDA)	AMD (ROCm)	Intel (oneAPI)	Apple (Metal)	CPU
Stage 1 — RAPiDock (torch)	TF32 fast path (matmul_precision('high'), allow_tf32)	ROCm via the CUDA API, same TF32 path	XPU + intel-extension-for-pytorch (ipex)	MPS + op-fallback, + metal-e3nn if installed	physical-core threads
Stage 1.5 / 3.5 — OpenMM	CUDA, mixed precision	HIP, mixed precision	OpenCL	OpenCL	thread-pinned CPU
Stage 2 — Vina / AD4	CPU (cpu=physical cores)	CPU	CPU	CPU	CPU

OpenMM platform priority is CUDA → HIP → OpenCL → CPU (HIP beats OpenCL on AMD; OpenCL covers Intel and Apple GPUs, which have no native OpenMM backend); mixed precision gives near-double accuracy at near-single speed. Vina/AD4, the geometry model, and the calibrated ΔG are pure-CPU and identical on every platform — only Stage 1 sampling and the OpenMM relaxations change speed with hardware. No local NVIDIA GPU? Sample Stage 1 elsewhere (or on CPU) and run scoring locally with dock --input-poses poses_dir/. The Apple path is not theoretical: a full 100-pose MDM2/p53 run finishes in <15 min on a fanless MacBook Air M3 (16 GB, MPS) — see Speed in RESULTS.md. On Apple Silicon, run_rapidock.py also auto-patches in metal-e3nn — a standalone, from-scratch fused-Metal-kernel replacement for e3nn's tensor products — if it's installed; it's optional (pip install git+https://github.com/Tasty-Ramen2010/metal-e3nn.git), not bundled, and never required — its own benchmarks report 3.1–6.7× faster tensor products on Apple GPUs, falling straight back to stock e3nn if it's absent or METAL_E3NN_DISABLE=1 is set.

Outputs

Every run writes to --output-dir: ranked_poses.csv (per-pose scores + calibrated ΔG), best_pose.pdb, cluster_summary.csv, convergence.png, dendrogram.png, and run_metadata.json (git SHA, seeds, software versions, input hashes — everything needed to reproduce the run).

ranked_poses.csv includes a rank_score column — the composition-IFP ranking model (E309). To screen a peptide panel, dock each candidate against the same receptor and compare their best-pose rank_score (lower = predicted stronger); it ranks within-target candidates better than the absolute ΔG (70.5% vs 64.5% pooled-pairwise) because it is size-normalized. It is not an absolute ΔG (use delta_g) and not a within-run pose ranker (that ordering is the CSV row order).

rank_score is target-dependent — reliable on shape/hydrophobic grooves (SH3 ρ=+0.91, MDM2 +0.67), weak where affinity is single-residue side-chain chemistry (PDZ +0.26, BH3 −0.63). It self-reports confidence: interaction_map.ranking_confidence(best_pose_rank_scores) returns high (reliable — 100% correct direction in validation) when the panel's scores spread out, low (verify in wet lab) when they cluster. Full validation write-up archived on Zenodo: 10.5281/zenodo.21764713.

best_pose.pdb is the exact geometry the headline ΔG was computed on, with standard residue names — so you can re-score it directly: hybridock-pep crystal-score --receptor R.pdb --peptide-pdb <out>/best_pose.pdb --peptide SEQ. (A best_pose_vina_relaxed.pdb with the Vina clash-relieved geometry is also written for visualization; it is ligand-format and not meant for re-scoring.)

---

Advanced / manual install

Almost everyone should use ./install.sh in Get started — it auto-detects your OS/GPU, creates both environments, downloads the model weights, and runs the smoke test, and it's safe to re-run any time. This is the manual equivalent, for full control over each step:

# 1. Scoring + analysis environment (the package itself)
conda env create -f envs/score-env.yml
conda activate score-env
pip install -e .

# 2. GPU sampling environment (Stage 1) — pick your platform
conda env create -f envs/rapidock-env.yml            # Linux/WSL2 + CUDA
# conda env create -f envs/rapidock-env-macos.yml    # Apple Silicon (MPS)

Nothing else to download. ADFRsuite is not required: receptor PDBQT comes from meeko, declared in envs/score-env.yml, with no license click-through. AD4 grid maps come from conda-forge autogrid, which scripts/setup_environment.py installs as a best-effort extra — conda-forge has no linux-aarch64 build of it, so on ARM Linux --scoring ad4 is simply unavailable and the installer says so. Nothing else changes: AD4 is off by default and the reported ΔG comes from the affinity model. The RAPiDock model weights (~55 MB) are fetched automatically from a public Zenodo record and checksum-verified. PULCHRA is optional and only affects a backbone-rebuild path.

Verify the install with bash scripts/smoke_test.sh, or just run ./launch_ui.sh for a guided walkthrough. Full walkthrough with every platform edge case: INSTALL.md.

---

Repository structure

hybridock-pep/
├── README.md · RESULTS.md · MODEL_CARD.md   # start here — quickstart, benchmarks, shipped models
├── SM_TableS1.xls · SM_TableS2.xls           # supplementary data tables
├── INSTALL.md                     # environment setup + optional license-restricted extras (PULCHRA)
├── Makefile                       # make setup / verify / demo / reproduce / test
├── LICENSE                        # MIT
├── pyproject.toml                 # score-env package definition
├── docs/                          # architecture notes, dev timeline, diagnostics, images/
├── notebooks/                     # HybriDock_Pep_Colab.ipynb — full pipeline on a free Colab T4
├── envs/
│   ├── score-env.yml
│   ├── rapidock-env.yml           # Linux/WSL2 + CUDA
│   └── rapidock-env-macos.yml     # Apple Silicon (MPS)
├── src/hybridock_pep/
│   ├── cli.py                     # argparse entry point (6 subcommands + crystal-score)
│   ├── driver.py                  # orchestrates Stage 1 + Stage 2 across both envs
│   ├── hardware.py                # per-accelerator backend selection (CUDA/ROCm/oneAPI/MPS/CPU)
│   ├── models.py                  # validated run configs (pydantic)
│   ├── prep/                      # receptor + ligand PDBQT preparation
│   ├── sampling/                  # RAPiDock subprocess wrapper, pose I/O
│   ├── scoring/                   # Vina, AD4, MM-GBSA, entropy, geometry/affinity models
│   ├── analysis/                  # RMSD clustering, ensemble statistics, plotting
│   ├── output/                    # progress bars, ASCII art, CSV + metadata writers
│   ├── ui/                        # terminal UI (prompt_toolkit) + built-in guide text
│   └── selectivity.py             # ΔΔG selectivity primitive
├── third_party/RAPiDock/          # RAPiDock-Reloaded submodule
├── experiments/                   # the E0–E37x research ledger — every script cited in RESULTS.md
├── scripts/                       # calibration, smoke test, colab_setup.sh, other operational tooling
├── tests/                         # pytest suite (fast + `-m slow` integration tests)
└── data/                          # calibration files, benchmark sets, shipped fixture PDBs

---

Testing

pip install -e ".[dev]"          # pytest + dev tools (the runtime install omits them)
pytest                           # fast suite — 730 passed, 72 skipped, ~20-40s
pytest -m slow                   # + integration tests (real Vina/OpenMM/pty, ~55 min)
pytest --cov=hybridock_pep       # coverage

WSL2 / CUDA: the MM-GBSA test runs real OpenMM. Export the WSL CUDA path so it finds the GPU: export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH. OMP_NUM_THREADS=1 keeps the sklearn-heavy scoring tests fast.

Full disclosure on the count: the pass/skip split depends on which optional tools you have. With a standard score-env (meeko, autogrid4, openbabel, ADFRsuite) the fast suite is 730 passed, 72 skipped, 1 expected-fail. The skips are the slow-marked tier plus tests needing tools you may not have installed — they are skips, not failures. pytest -m slow runs the real-Vina, real-OpenMM and real-terminal tests, and takes roughly 55 minutes.

---

Evaluation methodology

Benchmarks follow standard leakage-control practice: leave-cluster-out CV on every headline number, the standard 30% sequence-identity clustering cutoff reported alongside our 60% number, and the full accuracy-vs-identity-threshold trend rather than a single split. Full methodology, numbers, and reproduction commands: RESULTS.md.

The claims — measured in kcal/mol, leakage-free

New here? Read these three, in this order:

METHODS.md	What it does and how it was validated — the whole method in a few minutes. Start here.
RESULTS.md	Every leakage-free number, and the command that reproduces each one.
MODEL_CARD.md	Which of the 10 data/*.joblib actually ship, and the honest limits.

① The best available, fastest, reference-free non-FEP/LIE protein–peptide ΔG scorer — with FEP-competitive absolute error. On absolute cross-target peptide affinity it reaches MAE ≈ 1.3–1.6 kcal/mol under a rigorous 60%-sequence-identity clustered split (the honest, leakage-free regime) — squarely inside the ABFE (absolute FEP) accuracy band of ~1.2–2.5 kcal/mol, i.e. FEP-competitive on absolute-ΔG error, at ~1000× lower cost and with no reference peptide required.

② It beats a faithful clone of PPI-Affinity — the previous best published ML peptide scorer — on the identical leakage-free split, on every metric, with the margin widening once leakage is removed:

  matched n=865 PDBbind peptide-Kd · 60%-id clustered CV (leakage-free)
  ───────────────────────────────────────────────────────────────────
  model                       MAE↓    RMSE↓   Pearson r↑
  HybriDock-Pep (ours)        1.35    1.69    0.352      ◀ WIN on all three
  PPI-clone (ProtDCal+SVR)    1.46    1.84    0.210
  ───────────────────────────────────────────────────────────────────

Every number is measured, links to the script that reproduces it, and uses MAE/RMSE in kcal/mol as the primary metric (r is secondary — it is fragile to the test set and capped near the field ceiling for everyone, FEP included). We report the full accuracy-vs-identity-cutoff trend with a placement-aware identity metric, including the standard 30% cutoff (MAE 1.39 / r 0.32).

Created by Choppa Purandhar Ram (age 15) — Head of Dry Lab, Denmark High School iGEM 2026.

Full evidence for both claims — the five-test breakdown, the FEP-competitive analysis, why absolute cross-target affinity is hard for everyone, a fresh out-of-training check, the raw datasets, and a command-to-number reproduction table — lives in RESULTS.md. Everything there is measured, every claim links to the script that reproduces it, and every negative result is kept on the record in the development timeline archived on Zenodo: 10.5281/zenodo.21764713. The full research ledger (E0–E37x, every refuted idea) lives in experiments/ and docs/. In-depth data, training sets, and everything too large for git: docs/DATA_ARCHIVE.md — MD trajectory cache on Zenodo 10.5281/zenodo.21680573.

HybriDock-Pep vs FEP — when to use which

Complementary tools, not rivals — a cheap triage layer and a precision layer. FEP is the gold standard where it applies; we cover the regime it can't afford to.

Reach for FEP when…	Reach for HybriDock-Pep when…
ranking close variants of a known binder on one target (RBFE lead-op) — r ≈ 0.8–0.9, sub-kcal, its home turf	screening dozens of diverse candidates fast — minutes each on one GPU (FEP can't screen; it re-derives per system)
you can spend GPU-days + expert setup for a trusted number	you need absolute cross-target ΔG with no reference — both land ~1.3–2.5 kcal/mol, we're ~1000× cheaper
lead optimization / final go-no-go affinity	you need selectivity ΔΔG or to score AI-generated poses — FEP doesn't do these cheaply

Have 2–3 measured Kd on-target? Anchor first (within-receptor r → 0.61–0.71) — better than either cold-absolute option.

---

Roadmap / to-do

Done ✓

• Two-stage pipeline (RAPiDock-Reloaded sampling → physics/geometry rescoring), MIT, cross-platform
• Calibrated ΔG in kcal/mol; leakage-free benchmark (60%-id clustered CV)
• Beat PPI-Affinity clone on the identical honest split (MAE 1.35 vs 1.46; r 0.352 vs 0.210)
• Selectivity ΔΔG primitive (target vs off-target) with bootstrap CI
• Rigorous characterisation of the absolute-cross-target wall (why it's hard for FEP too)
• --ultra verification tier scoped (MM-GBSA + charged/entropy physics; honest limits documented)
• Guided terminal UI with live progress bars and a no-GPU demo mode

In progress / next

• Trajectory cache (e363) — simulate once, re-derive any physics term offline (near done)
• Per-residue ΔΔG design map (which residues drive PfLDH-vs-hLDH selectivity) — the winnable, relative regime
• Data expansion + representation (the field's proven lever for absolute cross-target: more/synthetic data + PLM embeddings)
• Uncertainty/confidence flag surfaced per prediction (know when to trust an absolute ΔG)
• iGEM wiki write-up: lead with kcal/mol MAE + selectivity + honest negative on absolute cross-target

Explicitly out of scope (proven dead-ends, kept on the record)

• Breaking absolute cross-target r past the field ceiling with more physics — fundamental wall (see docs)
• Raw electrostatic/entropy terms as absolute-ΔG features — charge-count/near-cancellation artifacts

---

Citations

• RAPiDock — Zhao et al., Nat. Mach. Intell. 7:1308 (2025).
• AutoDock Vina — Eberhardt et al., J. Chem. Inf. Model. 61:3891 (2021).
• OpenMM — Eastman et al., PLOS Comp. Biol. 13:e1005659 (2017).
• PPI-Affinity — Romero-Molina et al., J. Proteome Res. 21:1829 (2022); web server unmaintained since 2022.
• Boltz-2 affinity fine-tune — "On fine-tuning Boltz-2 for protein–protein affinity prediction," arXiv:2512.06592 (2025).
• Boltz-2 reliability audit — "On the Reliability of AI Methods in Drug Discovery: Evaluation of Boltz-2," arXiv:2603.05532 (2026).
• Peptide-docking review — Martins, Santos & Sousa, J. Comput. Chem. 47:5, doi:10.1002/jcc.70328 (2026).
• Baselines compared on the T100 set — DFIRE (Zhou & Zhou, Protein Sci. 11:2714, 2002); Kdeep (Jiménez et al., J. Chem. Inf. Model. 58:287, 2018); RF-Score (Ballester & Mitchell, Bioinformatics 26:1169, 2010); PRODIGY (Xue et al., Bioinformatics 32:3676, 2016).
• HybriDock-Pep — this repository, 2026.

License

MIT. Third-party dependencies retain their own licenses — see INSTALL.md for ADFRsuite, AutoDock4, and PULCHRA caveats (none redistributed here).