FreeBindCraft: BindCraft with Optional PyRosetta Bypass

This repository contains a modified version of Martin Pacesa's BindCraft (v1.52). The primary change is the introduction of an optional PyRosetta bypass mechanism.

For comprehensive details on the original BindCraft pipeline, features, advanced settings, and filter explanations, please refer to the original BindCraft repository: https://github.com/martinpacesa/BindCraft and the original preprint. This fork is hosted at: https://github.com/cytokineking/FreeBindCraft.

Key Modification: PyRosetta Bypass Functionality

The --no-pyrosetta flag, usable during both installation and runtime, enables the following behavior:

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.

Important Note: Rosetta-specific metrics that lack open-source equivalents are not computed; placeholder values are used where needed for compatibility with default filters. Evaluate design quality accordingly.

ipSAE Scoring

FreeBindCraft includes support for ipSAE (interface predicted Structural Alignment Error), a metric for evaluating protein-protein interface quality based on AlphaFold's PAE matrix. This implementation is based on Dunbrack et al. (2025).

What is ipSAE?

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

Ranking by ipSAE: By default, final designs are ranked by i_pTM. You can optionally rank by ipSAE instead:

python bindcraft.py --settings ... --rank-by ipSAE

The interactive CLI (both local and Docker) also prompts for ranking method selection.

Technical Overview & Rationale

For the motivation behind the PyRosetta bypass, implementation details (OpenMM relax, FreeSASA/Biopython SASA, sc-rs shape complementarity), and empirical impact on filter decisions, see the in-depth technical overview:

technical_overview/FreeBindCraft_Technical_Overview.md

Installation

Clone this modified repository:

git clone https://github.com/cytokineking/FreeBindCraft [install_folder]

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'
```

You can also run BindCraft entirely inside a Docker container without a local installation. See the Containerized usage section below for details and an interactive wrapper.

Running BindCraft

Activate the Conda environment:

conda activate BindCraft

Change to your BindCraft installation directory:

# cd /path/to/your/bindcraft/folder/

To use the PyRosetta bypass at runtime, include the --no-pyrosetta flag:

python -u ./bindcraft.py --settings './settings_target/your_target.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json' --no-pyrosetta

To run with PyRosetta enabled (assuming it was installed):

python -u ./bindcraft.py --settings './settings_target/your_target.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json'

Note: Even if you installed BindCraft with PyRosetta, you can still run in bypass mode by adding the --no-pyrosetta flag at runtime.

For details on configuring target settings (--settings), filters (--filters), advanced parameters (--advanced), and other operational aspects of BindCraft, please consult the documentation in the original BindCraft repository.

Interactive CLI

If you run BindCraft without --settings in a terminal (TTY) or pass --interactive, an interactive setup wizard guides you through configuration.

Quickstart (local):

python bindcraft.py               # auto-detects TTY and enters interactive mode
# or
python 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

You can further control runtime behavior with these 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.

Example:

python -u ./bindcraft.py \
  --settings './settings_target/your_target.json' \
  --filters './settings_filters/default_filters.json' \
  --advanced './settings_advanced/default_4stage_multimer.json' \
  --no-animations --no-plots --verbose --rank-by ipSAE

Containerized usage (Docker)

Run FreeBindCraft in a GPU-enabled Docker container (build locally).

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

Build without PyRosetta (default):

docker build -t freebindcraft:gpu .

Build with PyRosetta:

docker build --build-arg WITH_PYROSETTA=true -t freebindcraft:pyrosetta .

Sanity test (OpenMM relax):

mkdir -p ~/bindcraft_out
docker run --gpus all --rm -it \
  --ulimit nofile=65536:65536 \
  -v ~/bindcraft_out:/work/out \
  freebindcraft:gpu \
  python extras/test_openmm_relax.py example/PDL1.pdb /work/out/relax_test

Running BindCraft in Docker (general guidance)

Decide where your inputs and outputs live. Typical layout:

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

Examples:

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

mkdir -p /path/on/host/run_outputs
docker run --gpus all --rm -it \
  --ulimit nofile=65536:65536 \
  -v /path/on/host/run_outputs:/root/software/pdl1 \
  freebindcraft:gpu \
  python bindcraft.py \
    --settings settings_target/PDL1.json \
    --filters settings_filters/default_filt

FreeBindCraft

Install / Use

README