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.
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:
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_filters.json \
--advanced settings_advanced/default_4stage_multimer.json \
--no-pyrosetta
- Mount a custom target settings JSON from the host (also mount your input PDB):
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 \
-v /path/on/host/my_settings.json:/app/settings_target/my_settings.json:ro \
-v /path/on/host/your_target.pdb:/app/example/your_target.pdb:ro \
freebindcraft:gpu \
python bindcraft.py \
--settings /app/settings_target/my_settings.json \
--filters settings_filters/default_filters.json \
--advanced settings_advanced/default_4stage_multimer.json \
--no-pyrosetta
- Mount custom filters/advanced settings from the host too:
docker run --gpus all --rm -it \
--ulimit nofile=65536:65536 \
-v /path/on/host/run_outputs:/root/software/pdl1 \
-v /path/on/host/my_settings.json:/app/settings_target/my_settings.json:ro \
-v /path/on/host/my_filters.json:/app/settings_filters/my_filters.json:ro \
-v /path/on/host/my_advanced.json:/app/settings_advanced/my_advanced.json:ro \
-v /path/on/host/your_target.pdb:/app/example/your_target.pdb:ro \
freebindcraft:gpu \
python bindcraft.py \
--settings /app/settings_target/my_settings.json \
--filters /app/settings_filters/my_filters.json \
--advanced /app/settings_advanced/my_advanced.json \
--no-pyrosetta
Notes:
- 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
After you build an image locally, you can use the interactive Docker wrapper:
python docker_cli.py
This wizard:
- 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
On completion or Ctrl+C, the container exits and is auto-removed; outputs persist on the host via the mounted output directory.
Extras: Analysis and Utility Scripts
This repository includes additional scripts and documents in extras/ to assist with analysis and testing:
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.
See extras/README.md for detailed usage examples and options.
Contributing
Pull requests are welcome.
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):
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 \
|& stdbuf -oL -eL grep -v -E 'Failed to read file: .*/dep-[0-9a-fA-F]+\.d([[:space:]]*)?$' \
| stdbuf -oL tee -a ./output/your_target.log
- Stderr-only (no further pipes):
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 \
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.
评论