Note: This model card is for personal use only. Please click the link to find the original author and code repository.

FreeBindCraft: BindCraft with Optional PyRosetta Bypass

Key Modification: PyRosetta Bypass Functionality

• OpenMM Relaxation: Structural relaxation uses an OpenMM-based protocol instead of PyRosetta's FastRelax. This includes structure preparation with PDBFixer, ramped backbone restraints, OBC2 implicit solvation, an additional short-range repulsive term to mitigate clashes, and short MD "shakes" for early stages. Integration with FASPR (Fast, Accurate, and Deterministic Protein Side-chain Packing) for side-chain repacking and further refinement. This function is GPU-accelerated and typically is 2-4x faster than the CPU-based FastRelax, depending on the platform. OpenMM and FASPR are both open-source.
• Shape Complementarity (SC): Replaced with an open-source implementation via sc-rs when available. See sc-rs project: https://github.com/cytokineking/sc-rs. The results of sc-rs are nearly identical to the same calculations performed by PyRosetta.
• SASA Calculations: Surface area and derived metrics are computed using FreeSASA or a Biopython Shrake–Rupley fallback. These values align closely with the PyRosetta-derived values.
• Interface Residues and Alignment: Uses Biopython-based routines for interface residue identification, RMSD, and PDB alignment.

ipSAE Scoring

• ipSAE transforms interface PAE values using a PTM-style scoring function with adaptive normalization
• Higher scores indicate better predicted interface quality (range 0–1)
• Unlike i_pTM which uses a global d0, ipSAE uses per-residue d0 based on the number of interface contacts
• ipSAE is computed for both trajectory statistics and final MPNN design statistics

Technical Overview & Rationale

• technical_overview/FreeBindCraft_Technical_Overview.md

Installation

1. Clone this modified repository:
   git clone https://github.com/cytokineking/FreeBindCraft [install_folder]
2. Navigate into your install folder (cd [install_folder]) and run the installation script. A CUDA-compatible Nvidia graphics card is required.
   Installation script options:
   • --cuda CUDAVERSION: Specify your CUDA version (e.g., '12.4').
   • --pkg_manager MANAGER: Specify 'mamba' or 'conda' (default: 'conda').
   • --no-pyrosetta: Use this flag to install without PyRosetta.
   • --fix-channels: Fix conda channel configuration to resolve dependency conflicts (recommended if experiencing installation issues).
   Example: PyRosetta-Free Installation
   bash install_bindcraft.sh --cuda '12.4' --pkg_manager 'conda' --no-pyrosetta
   Example: Standard Installation (Includes PyRosetta) If you choose to install with PyRosetta, a license is required for commercial use.
   bash install_bindcraft.sh --cuda '12.4' --pkg_manager 'conda'

Running BindCraft

Interactive CLI

• Quickstart (local):
  bash

  1python bindcraft.py # auto-detects TTY and enters interactive mode 2# or 3python bindcraft.py --interactive
• What it asks:
  • Project/binder name, input PDB path (validated must exist), output directory (auto-created)
  • Design type: Miniprotein (≥31 aa) or Peptide (8–30 aa)
    • Peptides: default length 8–25; filters limited to peptide_filters, peptide_relaxed_filters, no_filters; advanced limited to peptide profiles
    • Miniproteins: default length 65–150 (min ≥31); filters limited to default_filters, relaxed_filters, no_filters; advanced excludes peptide profiles
  • Verbose logging, plots, animations, and whether to run with PyRosetta
  • Ranking method for final designs: i_pTM (default) or ipSAE
• Behavior:
  • Generates a target settings JSON inside your chosen output directory and then runs the standard pipeline

Additional New CLI Flags

• --verbose: Enable detailed timing/progress logs for BindCraft internals.
• --debug-pdbs: Write intermediate PDBs from OpenMM relax (.debug_deconcat.pdb, .debug_pdbfixer.pdb, .debug_post_initial_relax.pdb, .debug_post_faspr.pdb)
• --no-plots: Disable saving design trajectory plots (overrides advanced settings).
• --no-animations: Disable saving trajectory animations (overrides advanced settings).
• --rank-by {i_pTM,ipSAE}: Metric to rank final designs by (default: i_pTM). Use ipSAE to rank by interface predicted Structural Alignment Error instead.

Containerized usage (Docker)

Prerequisites (on the host)

• NVIDIA driver installed (check with nvidia-smi).
• Docker CE and NVIDIA Container Toolkit:
  • Linux (Ubuntu):
    1. Install Docker CE and restart the daemon.
    2. sudo apt-get install -y nvidia-container-toolkit
    3. sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker
  • Validate GPU availability inside containers:
    docker run --rm --gpus all nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 nvidia-smi

Build the image from this repository

Running BindCraft in Docker (general guidance)

• Host input PDB: /path/on/host/your_target.pdb
• Host output dir: /path/on/host/run_outputs
• Settings files: either use repo defaults inside the container or mount your own copies from the host

1. Use repository defaults for settings (inside container), but mount outputs to host.

1. Mount a custom target settings JSON from the host (also mount your input PDB):

1. Mount custom filters/advanced settings from the host too:

• Always mount your output directory to the path set as design_path in your target settings (e.g., /root/software/pdl1).
• Always increase file descriptor limits with --ulimit nofile=65536:65536. The image’s entrypoint also attempts to raise the soft limit inside the container.

Interactive wrapper for Docker

• Lists local Docker images and lets you choose one (defaults to freebindcraft:gpu if present, or enter another local image tag such as freebindcraft:pyrosetta)
• Asks for a single GPU index to expose
• Prompts for all inputs identical to the local interactive CLI (design type, validated PDB path, output directory auto-created, chains, hotspots, peptide/miniprotein-specific filters and advanced profiles, verbose/plots/animations, PyRosetta, ranking method)
• Writes a target settings JSON into your chosen output directory
• Launches docker run --rm -it --gpus device=<idx> with host paths mounted to identical locations in the container so your paths work unchanged

Citations & External Tools

• Shape Complementarity (SC): sc-rs — https://github.com/cytokineking/sc-rs
• FreeSASA (SASA): https://github.com/mittinatten/freesasa
• FASPR (Side-chain Packing): https://github.com/tommyhuangthu/FASPR
• Biopython: https://biopython.org
• ipSAE (interface predicted Structural Alignment Error): Dunbrack et al. 2025

Extras: Analysis and Utility Scripts

• extras/analyze_bindcraft_rejections.py: Analyze MPNN rejections across runs and quantify which filters are most responsible; can estimate hypothetical rankings when Rosetta-only filters trigger.
• extras/bindcraft_rejection_analysis_spec.md: Specification describing the rejection analysis outputs and methodology.
• extras/BUGFIX_FILE_DESCRIPTORS.md: Notes on file descriptor fixes in high-throughput runs.
• extras/check_ulimit.sh: Helper script to check system ulimit and suggest adjustments for many-parallel-file workloads.
• extras/compare_interface_metrics_all.py: Compute interface metrics via PyRosetta (if available), FreeSASA, and Biopython across a folder of PDBs; outputs a combined CSV.
• extras/compare_pyrosetta_bypass_scores.py: Side-by-side comparison of PyRosetta vs Biopython-only metrics for a folder of PDBs.
• extras/rescore_accepted_with_rosetta.py: Rescore accepted (Ranked preferred) PDBs from a --no-pyrosetta run using PyRosetta, evaluate whether PyRosetta-driven filters would reject each design, and report failing filters. Supports dynamic filters (default|relaxed|design|custom), parallel workers, and an optional --fast-relax mode to run PyRosetta FastRelax prior to scoring.
• extras/test_openmm_relax.py: Quick test harness for OpenMM and PyRosetta relax routines.

Contributing

Known Issues

• OpenMM GPU backend selection (OpenCL preferred over CUDA): We deliberately prefer OpenCL over CUDA for OpenMM relax because we have not been able to get the CUDA backend reliably working in our environments. OpenCL works, but it is less stable over long runs, so the relax step is executed in a subprocess for isolation and reliability. It also produces JIT log spam; see the next item for a suppression example.
• OpenCL JIT "log spam": You may see repeated lines such as "Failed to read file: /tmp/dep-76532a.d" emitted to stdout/stderr during OpenCL kernel builds.
  • Recommend line buffering to keep logs responsive when filtering
    • Combined output (preferred when piping/teeing):
    bash

    1python -u ./bindcraft.py \ 2 --settings ./settings_target/your_target.json \ 3 --filters ./settings_filters/default_filters.json \ 4 --advanced ./settings_advanced/default_4stage_multimer.json \ 5 --no-pyrosetta \ 6 |& stdbuf -oL -eL grep -v -E 'Failed to read file: .*/dep-[0-9a-fA-F]+\.d([[:space:]]*)?$' \ 7 | stdbuf -oL tee -a ./output/your_target.log
    • Stderr-only (no further pipes):
    bash

    1python -u ./bindcraft.py \ 2 --settings ./settings_target/your_target.json \ 3 --filters ./settings_filters/default_filters.json \ 4 --advanced ./settings_advanced/default_4stage_multimer.json \ 5 --no-pyrosetta \ 6 2> >(stdbuf -oL -eL grep -v -E 'Failed to read file: .*/dep-[0-9a-fA-F]+\.d([[:space:]]*)?$' >&2)
    • Notes:
      • stdbuf forces line buffering for both stdout and stderr, preventing pipeline buffering delays.
      • Use POSIX character class [[:space:]] for portability.
      • If preserving exit code across pipes matters, consider: set -o pipefail.