Skip to content

damborik22/BindMaster

BranchesTags

Repository files navigation

CI License: MIT Python 3.10+ Platform

BindMaster

A unified toolkit for GPU-accelerated protein binder design — installer, configurator, and evaluator in one repository.

Components

Component What it does Runs in
bindmaster install Installs BindCraft, BoltzGen, and/or Mosaic bash
bindmaster configure Interactive wizard: target → configs → run scripts system Python
bindmaster evaluate Parse outputs, rank designs, optionally re-fold with Boltz2 Mosaic uv venv

Installed tools

Tool What it does Environment
BindCraft Protein binder design via AlphaFold2 conda env BindCraft (Python 3.10)
BoltzGen Structure generation with Boltz-1 conda env BoltzGen (Python 3.12)
Mosaic JAX/Boltz2-based binder hallucination uv venv (Mosaic/.venv)

Each tool runs in its own isolated environment. Environments must not be mixed.

Architecture

flowchart LR
    Input["Target structure\n(.pdb / .mmcif)"]
    Config["Configurator\nwizard → run scripts"]
    Mosaic["Mosaic\n(JAX + Boltz-2)"]
    BG["BoltzGen\n(Boltz-1)"]
    BC["BindCraft\n(AF2 + MPNN)"]
    PX["PXDesign\n(Protenix)"]
    Boltz2["Boltz-2\nrefolding"]
    AF2["AF2\nrefolding"]
    Report["Report generator\nranked HTML + CSV"]

    Input --> Config
    Config --> Mosaic & BG & BC & PX
    Mosaic & BG & BC & PX -->|sequences| Boltz2
    Boltz2 --> AF2
    AF2 --> Report
Loading

Repository structure

BindMaster/
├── bindmaster.py               ← unified CLI entry point (system Python)
├── install/
│   ├── install.sh              ← x86_64 installer (master branch)
│   └── install_aarch.sh        ← aarch64 / DGX Spark installer
├── configurator/
│   └── configurator.py         ← interactive setup wizard
├── evaluator/
│   └── evaluator.py            ← output parser + Boltz2 re-fold (Mosaic venv)
├── Evaluator/                  ← bundled evaluator code
├── bindmaster_examples/        ← Mosaic hallucination template (copied on install)
├── tools/
│   └── aarch64/                ← pre-built ARM64 binaries (dssp, DAlphaBall)
├── BindCraft/                  ← installed tool (gitignored)
├── BoltzGen/                   ← installed tool (gitignored)
├── Mosaic/                     ← installed tool (gitignored)
└── runs/                       ← generated run folders (gitignored)

Quick start

# 1. Clone (x86_64)
git clone https://github.com/damborik22/BindMaster.git ~/BindMaster
cd ~/BindMaster

# 2. Install tools
bindmaster install             # interactive menu
bindmaster install --tool all  # install everything

# 3. Configure a run
bindmaster configure

# 4. Run (scripts generated by configure)
bash runs/<name>/run_all.sh

# 5. Evaluate results
bindmaster evaluate runs/<name>

bindmaster CLI reference

bindmaster install   [--tool bindcraft|boltzgen|mosaic|all] [--cuda VERSION] [--skip-examples]
bindmaster configure [options passed through to configurator.py]
bindmaster evaluate  <run-dir> [--metric METRIC] [--top N] [--refold N] [--target PDB]
bindmaster evaluate  --sequences FILE  [--target PDB] [--refold N]
bindmaster --help

bindmaster install

Options:

Flag Description
--tool all|bindcraft|boltzgen|mosaic Which tool(s) to install. Omit for interactive menu.
--cuda VERSION CUDA version for conda package resolution (default: 12.4)
--skip-examples Do not prompt to run bundled examples after install
--standalone Force local Miniforge3 install (no system conda needed)
--system-conda Use existing system conda instead of local install

bindmaster configure

Interactive wizard that:

  1. Asks for a target name, PDB file, chain(s), and hotspot residues
  2. Sets global binder length and design count, with per-tool overrides
  3. Lets you enable/disable each tool (Mosaic → BoltzGen → BindCraft)
  4. Writes all config files and shell scripts into runs/<name>/
  5. Optionally runs the full pipeline immediately
bindmaster configure
bindmaster-config          # legacy shortcut (same thing)

What gets generated

runs/<name>/
├── target/<name>.pdb
├── mosaic/
│   └── hallucinate.py          ← non-interactive, all params injected
├── boltzgen/
│   ├── config.yaml
│   └── outputs/
├── bindcraft/
│   ├── target_settings.json
│   ├── filters.json
│   ├── advanced.json
│   └── outputs/
├── run_mosaic.sh
├── run_boltzgen.sh
├── run_bindcraft.sh
└── run_all.sh                  ← runs all enabled tools in sequence

bindmaster evaluate

Parses design outputs from any combination of Mosaic, BoltzGen, and BindCraft, cross-ranks all designs by a configurable metric, and writes a summary.

Runs inside the Mosaic uv venv (the only environment that has JAX + Boltz2). Mosaic must be installed before running evaluate.

Run-directory mode

bindmaster evaluate runs/PDL1_test
bindmaster evaluate runs/PDL1_test --metric bt_ipsae --top 20
bindmaster evaluate runs/PDL1_test --refold 5 --target runs/PDL1_test/target/PDL1.pdb

Output written to runs/<name>/evaluation/:

  • summary.csv — all designs merged and ranked
  • report.txt — top-N with key metrics
  • refolded/ — Boltz2 PDB structures (if --refold N used)

Sequence-only mode

Re-fold a list of bare sequences from any source without a run directory:

# From a file (one sequence per line, # comments OK)
bindmaster evaluate --sequences my_seqs.txt --refold 3 --target target.pdb

# From stdin
echo "MAEVKLSYVL..." | bindmaster evaluate --sequences - --refold 1

Ranking metrics

Metric Direction Notes
iptm higher → better Interface pTM (default)
bt_ipsae higher → better Binder→target iPSAE
tb_ipsae higher → better Target→binder iPSAE
ipsae_min higher → better min(bt, tb) iPSAE
ranking_loss lower → better Mosaic design-stage ranking loss
plddt_binder_mean higher → better Mean binder pLDDT
pae_bt_mean lower → better Mean binder→target PAE

Installer details

Requirements

  • Linux with an NVIDIA GPU (CUDA driver ≥ 12.1)
  • git and curl available in PATH
  • ~60 GB free disk space
  • Conda/Miniforge is not required — the installer downloads Miniforge3 automatically if needed

What happens during install

Each tool goes through:

  1. Clone — repo cloned into BindMaster/<Tool>/
  2. Environment — conda env or uv venv created with packages (spinner + full log)
  3. Smoke test — minimal import or --help call
  4. Example (optional, skippable) — bundled example run
  5. Shortcut — launcher written to BindMaster/bin/

Non-interactive options

bash install/install.sh --tool bindcraft
bash install/install.sh --tool boltzgen
bash install/install.sh --tool mosaic
bash install/install.sh --tool all
bash install/install.sh --skip-examples
bash install/install.sh --cuda 12.1

Server / HPC installation (no admin required)

BindMaster works fully standalone — no system conda, no admin, no writes outside the project directory:

git clone https://github.com/damborik22/BindMaster.git
cd BindMaster
python3 bindmaster.py install --tool all --yes

# Add to PATH:
export PATH="$(pwd)/bin:$PATH"
echo 'export PATH="/path/to/BindMaster/bin:$PATH"' >> ~/.bashrc

The installer auto-detects if system conda is unavailable or read-only and downloads Miniforge3 into BindMaster/conda/. All environments and shortcuts stay inside the project directory. To remove everything: rm -rf BindMaster/.

Platform / branch

Branch Platform Installer
master x86_64 Linux + NVIDIA GPU install/install.sh
aarch64 NVIDIA DGX Spark / Grace-Hopper install/install.sh (aarch64 version) 
# x86_64
git clone https://github.com/damborik22/BindMaster.git

# aarch64 / DGX Spark
git clone -b aarch64 https://github.com/damborik22/BindMaster.git

Both branches: bindmaster install or bash install/install.sh.

aarch64 notes

  • BindCraft: ARM64 binaries (DAlphaBall.gcc, dssp) bundled in tools/aarch64/ — copied automatically.
  • BoltzGen: pip install torch==2.5.1 (aarch64 PyPI wheels include CUDA).
  • Mosaic: esmj excluded on aarch64 (no wheel available).

Shortcuts

After installation, launchers are available in BindMaster/bin/:

bindmaster         # unified CLI (install / configure / evaluate)
bindcraft          # activates BindCraft conda env, cd to BindCraft dir
boltzgen           # activates BoltzGen conda env, cd to BoltzGen dir
mosaic             # activates Mosaic uv venv, cd to Mosaic dir
bindmaster-config  # runs configurator directly (legacy)

Reinstalling a tool

bindmaster install --tool bindcraft

Answer Y when prompted to remove the existing directory and conda environment.

Monitoring installs

tail -f ~/BindMaster/install.log         # x86_64
tail -f ~/BindMaster/install_aarch.log   # aarch64

Troubleshooting

BindCraft smoke test fails Check BindCraft/params/ contains .npz weight files. If the AF2 download was interrupted, reinstall.

BoltzGen model download fails BoltzGen downloads Boltz-1 weights (~6 GB) on first use. Re-run — it resumes automatically.

uv not found after Mosaic install

source ~/.bashrc

bindmaster evaluate — Mosaic must be installed

bindmaster install --tool mosaic

A tool failed, others succeeded

bindmaster install --tool <toolname>

Checking what's installed

conda env list                    # shows BindCraft and BoltzGen envs
ls BindMaster/bin/                # shows shortcuts
ls BindMaster/conda/envs/         # shows local envs (standalone mode)

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages