ProteinDJ v3.0.0

ProteinDJ v3.0.0

Major Update: PyRosectomy for commercial use, OpenMM Relaxation, and BoltzGen

Authors: @JoshuaMHardy @tlitfin @dladd

This release brings together a rewrite of dl_binder_design, analysis, and switches BindCraft to FreeBindCraft to remove the PyRosetta dependency. We have also integrated BoltzGen for fold design. Note that v3 is not backwards compatible and requires a fresh installation, as containers and models have been updated.

---

Highlights

• New step-by-step tutorial for binder design on the insulin receptor
• Replaced BindCraft with FreeBindCraft, removing the PyRosetta dependency from the binder hallucination stage.
• Rewrote dl_binder_design to drop PyRosetta in favour of OpenMM-based relaxation (GPU-accelerated, 4-5x faster than FastRelax).
• Rewrote analyse_best_designs.py (the final Analysis stage) to drop PyRosetta entirely, replacing it with PDBFixer/OpenMM relaxation, arpeggia (shape complementarity, H-bonds, SAP), and PRODIGY (binding free energy)
• Added BoltzGen as a third Fold Design engine alongside RFdiffusion and BindCraft, with new boltzgen_denovo (de novo monomer/binder generation) and boltzgen_motifscaff (existing monomer/binder sequence/structure redesign, including insertions and deletions) pipeline modes.
• Added a new option for prediction (af2_boltz) which runs AlphaFold2 first, followed by Boltz-2 on the surviving designs.
• Boltz-2 target prediction now supports targets with multiple/broken chains.
• Added an optional target-free "unbound" binder prediction with Boltz-2 (boltz_predict_unbound_binder, off by default)
• Collapsed the 8 monomer/binder RFdiffusion design_mode options into 4 (rfd_denovo, rfd_foldcond, rfd_motifscaff, rfd_partialdiff); monomer vs. binder behaviour is now auto-detected at runtime
• Removed the rfd_contigs/rfd_inpaint_seq manual contig-specification parameters entirely. RFdiffusion contigs are now always auto-generated from parameters — trim/edit your target PDB directly (e.g. in ChimeraX/PyMOL) instead of writing contig strings by hand.

FreeBindCraft / BindCraft

• Raised verbosity of the OpenMM relaxation step to report per-iteration energies.
• Relaxation across the 3 stages now always resumes from the best geometry seen so far, so the tight-tolerance stage 3 (0.1 kJ/mol/nm) refines the best structure rather than a potentially degraded one from stage 2.
• Forced temp file writes to the working directory.
• Container now explicitly installs CUDA 12 Python modules; pinned cuda-nvcc/cuda-version to 12.* to stop conda-forge from pulling CUDA 13.1+.

ProteinMPNN + FastRelax/OpenMMRelax

• dl_interface_design_multi.py now uses OpenMM relaxation instead of FastRelax (ProteinMPNN-OpenMMRelax) based on the algorithm used in FreeBindCraft, with increased logging of energies and acceptance/rejection decisions.
• Merged the af2 and dl_binder_design containers into one (dl_binder_design), since both now require GPU — the standalone af2.def and container are removed.
• ProteinMPNN weights removed from the container; now mounted at runtime via a new mpnn_models parameter, same as AF2 weights (with a matching model download step).

ProteinMPNN+OpenMMRelax benchmarking

We applied our new OpenMMRelax approach to binder design using the same benchmarking approach and five targets as in our paper, and calculated in silico success rates for AF2 prediction. Although there is some stochastic variation per target due to the random seeds, the average success rate across all targets was similar between FastRelax and OpenMMRelax, with the GPU-accelerated OpenMMRelax running 4-5x faster than CPU-bound FastRelax.

Sequence Design Method	HA	IL7Rα	IR	PD-L1	TrkA	Average
v2 ProteinMPNN(Soluble)	5.0%	5.8%	27.6%	33.9%	8.5%	16.2%
v3 ProteinMPNN(Soluble)	6.4%	9.8%	23.1%	33.9%	8.6%	16.4%
v2 ProteinMPNN(Soluble) + FastRelax	6.1%	9.1%	29.6%	52.3%	18.1%	23.0%
v3 ProteinMPNN(Soluble) + OpenMMRelax	4.9%	15.1%	30.1%	52.1%	13.5%	23.1%

Analysis & Filtering

• analyse_best_designs.py rewritten to remove PyRosetta:
  • Each predicted structure is now energy-minimized once (PDBFixer + OpenMM), preserving per-atom B-factors, and every metric is calculated from that single relaxed structure.
  • Interface shape complementarity (Lawrence & Colman algorithm), hydrogen bonds, buried unsatisfied hydrogen bonds (angle-dependent), and SAP score are now calculated with arpeggia instead of the sc binary/PyRosetta.
  • Binding free energy (pr_intface_deltaG) is now predicted with PRODIGY's IC-NIS model (kcal/mol) instead of Rosetta's InterfaceAnalyzerMover (Rosetta Energy Units).
  • Removed the defunct pr_intface_packstat / pr_TEM metrics and associated filters (pr_min_intface_packstat / pr_max_tem) metrics, which had no open-source equivalent.
  • Designs where the binder and target chains have no interface contact at all (e.g. a failed prediction) no longer crash the Analysis stage -- BSA, shape complementarity, deltaG, H-bonds, and unsatisfied H-bonds are reported as zero instead of raising an error.
  • Fixed handling of mkdssp >=4.0's PDB/mmCIF auto-detection for headerless AF2/Boltz output PDBs.
• Fold-based filtering (FilterFold) now uses BioPython (+DSSP) to calculate radius of gyration and the number of secondary structures, with the same mkdssp >=4.0 header fix applied.
• Sequence-property filtering (extinction coefficient, isoelectric point) split out of filter_analysis.py into a new dedicated scripts/filter_seq.py, exposed via a renamed FilterSeq process (replaces FilterMPNN).
• prep_fampnn_designs.py rewritten to use PDBFixer + FASPR (pyfaspr) instead of PyRosetta for backbone/side-chain restoration, preserving per-residue B-factor/occupancy metadata.
• New mpnn_time metric added alongside existing mpnn_score / fampnn_avg_psce.

Structure Prediction

• af2_initial_guess predict.py now uses BioPython for I/O, PDBfixer/Pyfaspr to add side-chains, instead of PyRosetta
• prep_boltz_yaml.py now detects chain breaks (C→N distance > 3 Å) and splits a target into multiple chains (B, C, D, …) before prediction.
• align_boltz.py updated to align/compute RMSD against all non-binder target chains, rather than assuming a single chain B.
• New metrics: boltz_ptm_binder (binder-only pTM) and boltz_ptm_target (mean pTM across all target chains). boltz_iptm is redefined as the mean binder→target interface pTM across all target chains.
• New pred_method option: af2_boltz, which cascades the two existing structure prediction methods -- AlphaFold2 Initial-Guess runs first as a fast pre-filter, survivors are filtered with any af2_* thresholds, and only the surviving designs are then re-predicted and filtered with Boltz-2 (boltz_* thresholds). This gives Boltz-2-quality metrics on the final design set while avoiding the cost of running Boltz-2 on every candidate.
  • When af2_boltz is used, both af2_* and boltz_* metric columns are populated for designs that make it through both stages.
  • Ranking (--rank_designs) defaults to the Boltz-2 metrics (boltz_ptm / boltz_ipSAE_min) when pred_method is af2_boltz, since Boltz-2 is the final/most-refined stage.
• Added persistent cache for AlphaFold2 to reduce compilation overhead of jax models by caching compiled kernels on disk, which persists across multiple runs (af2_jax_compilation_cache_dir). Each cache file is valid for a single design+target length and a single GPU model e.g. A30 only.
• Added ipTM metric for AlphaFold2 with filter (af2_min_iptm). Renamed metric field names for Boltz-2 from *_interface to *_iptm, *_iplddt, and *_ipde for consistency.
• Added an optional target-free "unbound" binder prediction with Boltz-2 (boltz_predict_unbound_binder, off by default), which predicts the binder chain alone as a monomer to check whether it folds consistently in the absence of the target. Binder design modes only; runs alongside the existing (bound) Boltz-2 prediction and adds new metrics: boltz_unbound_rmsd, boltz_unbound_conf_score, boltz_unbound_ptm, boltz_unbound_plddt, boltz_unbound_pde metrics with matching filters (boltz_max_unbound_rmsd, boltz_min_unbound_conf_score, boltz_min_unbound_ptm, boltz_min_unbound_plddt, boltz_max_unbound_pde).

Fold Conditioning

• Replaced PyRosetta DSSP with BioPython DSSP (mkdssp) for secondary structure assignment in create_scaffolds.py
• Removed incomplete P-SEA fallback (get_sse)
• Changed GenerateRFDFoldCond process label from pyrosetta_tools to python_tools (which already includes biopython and dssp)

RFdiffusion

• Collapsed monomer_denovo/binder_denovo into rfd_denovo, monomer_foldcond/binder_foldcond into rfd_foldcond, monomer_motifscaff/binder_motifscaff into rfd_motifscaff, and monomer_partialdiff/binder_partialdiff into rfd_partialdiff. Each mode now auto-detects monomer vs. binder design from whether input_pdb (and, for rfd_motifscaff/rfd_partialdiff, chain count/contigs) indicates a target is present, via a single is_binder_mode flag computed once and threaded through the workflow. Existing pipeline configs using the old 8 mode names will need to be updated to the new 4 mode names
• bindsweeper updated to match: binder_schema.json mode keys and mode-prefix checks renamed from binder_* to rfd_*.
• hotspot_residues now supports comma-separated residue ranges (e.g. A115-120) and whole-chain tokens (e.g. B) in addition to single residues, expanded internally into individual residues for RFdiffusion's ppi.hotspot_res — previously only single residues were supported, unlike BindCraft/BoltzGen.
• Removed the rfd_contigs/rfd_inpaint_seq manual contig-specification parameters entirely. RFdiffusion contigs are now always auto-generated from input_pdb/design_length/motifscaff_spec/rfd_partialdiff_spec, the same way BindCraft/BoltzGen work — trim/edit your target PDB directly (e.g. in ChimeraX/PyMOL) instead of writing contig strings by hand.
• rfd_motifscaff binder design now defaults to the complex_base RFdiffusion checkpoint automatically (unless motifscaff_inpaint_seq/flexible_residues is set, or rfd_ckpt_override is set explicitly). This mode never sets hotspot residues, so RFdiffusion's own checkpoint auto-selection would otherwise silently fall back to the monomer-only base checkpoint even when a target chain is present.
• renamed rfd_length to rfd_motifscaff_length, rfd_scaffold_dir to rfd_foldcond_scaffold_dir, rfd_mask_loops to rfd_foldcond_mask_loops to better indicate their mode relevance

BoltzGen

• Added BoltzGen as a third Fold Design engine alongside RFdiffusion and BindCraft, via two new pipeline modes:
  • boltzgen_denovo — diffuse a new binder (chain A) of a given length against a fixed target (from input_pdb), with optional hotspot/anti-hotspot residues and/or target structural flexibility.
  • boltzgen_motifscaff — rework an existing chain A binder against the remaining fixed chain(s) of input_pdb, with independent control over architecture changes (insertions/deletions), sequence redesign of kept residues, and structural flexibility.
• BoltzGen model weights are downloaded/mounted the same way as AF2/ProteinMPNN (new bg_models parameter); only the 3 artifacts needed for the design step are fetched (~4.0 GB total), using the hf CLI instead of wget/curl for fast Xet-backed downloads.
• RunBG avoids unnecessary Hugging Face Hub network calls at runtime once models are cached.
• Added docs/integrating_fold_design_tools.md, a developer guide for integrating new Fold Design tools into ProteinDJ, generalised from lessons learned during the BoltzGen integration.
• Unified the residue-spec grammar used by hotspot_residues (RFdiffusion, BindCraft, BoltzGen) and BoltzGen's bg_not_binding_residues: comma-separated tokens, each a chain-qualified residue (A56), chain-qualified range (A115-120), or bare chain ID meaning the whole chain (B)
• Unified motif scaffolding mode/parameters with RFdiffusion: shares motifscaff_spec/motifscaff_inpaint_seq/flexible_residues params also used by rfd_motifscaff

Bug Fixes

• Using --rank_designs together with --run_fold_only now raises a clear error at startup (no prediction metrics are generated to rank on) instead of silently proceeding.
• Fixed a -resume caching bug where changing any single parameter (even one unrelated to fold design or filtering) could force RunRFD and several filtering steps (FilterFold, FilterSeq, FilterAF2, FilterBoltz, FilterAnalysis) to needlessly re-execute from scratch. These processes previously passed the entire Nextflow params object into a helper function inside their script blocks, which caused Nextflow to hash the whole params object rather than just the specific values each process actually uses. The relevant values are now computed once in the workflow body and explicitly passed to each process, so unrelated parameter changes no longer invalidate their caches.
• Fixed the uncropped_target_pdb parameter's JSON Schema pattern, which incorrectly required the value to be exactly the literal string .pdb (missing a wildcard prefix) instead of any path ending in .pdb.
• Fixed handling of design length when a single integer is provided rather than a range
• Count of final designs is now calculated after ranking is complete

Documentation

• Installation docs updated: Nextflow ≥24.04 requirement clarified, plus guidance to set NXF_SYNTAX_PARSER=v1 for Nextflow v26+.
• Added ProteinMPNN model weight download instructions (~0.2 GB: vanilla, soluble, and HyperMPNN weights).
• metrics.md, parameters.md, README.md, and all Nextflow JSON schemas updated for new/renamed metrics and parameters, removing stale "PyRosetta"/"Rosetta Energy Units" references from the Analysis stage description in favour of the new arpeggia/PRODIGY/OpenMM toolchain.
• docs/modes.md restructured around the new 4 RFdiffusion modes, each documenting both monomer and binder usage; README.md, parameters.md, testing.md, installation.md, and bindsweeper.md updated to the new rfd_* mode names.
• Added Arpeggia, OpenMM/PDBFixer, and PRODIGY to the software list and citations in README.md.

Infrastructure & Config

• Rebuilt python_tools, bindcraft, and dl_binder_design container definitions (now install uv, pyfaspr, pdbfixer, etc.); af2.def removed.
• New mpnn_models parameter (path to ProteinMPNN checkpoints) added to nextflow.config, including a cluster-profile default path.
• apptainer.pullTimeout increased to 20 minutes in the cluster profile.
• .gitignore updated to exclude work/, *.sif, and lib/**/__pycache__/.
• Improved compatibility with Amazon S3 storage systems.
• Refactored fold-design mode dispatch in main.nf into a DesignEngine strategy pattern (lib/DesignEngine.groovy, BindCraftEngine, BoltzGenEngine, RFDEngine), consolidating each engine's validation, startup logging, and input-file collection and removing ~300 lines of duplicated per-mode logic.
• Added pytest and nf-test suite for input validation and file checks, as well as process/module level tests.
• bindsweeper's binder_schema.json (used to validate sweep configs) is now mechanically generated from the pipeline's per-mode Nextflow schemas via a new scripts/generate_bindsweeper_schema.py, instead of being hand-maintained. Every parameter valid for a given mode is now available to sweep, rather than a previously hand-curated subset.
• Per-mode generated Nextflow schemas (schemas/nextflow_schema_<mode>.json) no longer include empty parameter groups

---