BoltzMaker

BoltzMaker: Boltz2 campaign-scale structure and affinity prediction, binding analysis, and run control, orchestrated end to end from a single spec file.

Read the BoltzMaker Blog page for more info

Read an example 5HT2 GPCR receptor campaign analysis

A single script that manages a Boltz-2 batch campaign end to end: parse a boltz_input.md spec, generate the per-target Boltz YAML files, preflight the environment and inputs, run boltz predict with a live progress bar (with resume support), and analyze the results into a CSV, an XLSX workbook, and an HTML dashboard — optionally enriched with real protein-ligand interaction analysis via cif2plip. The non-GPU stages — the new wizard, generate, preflight, and full analyze (including PLIP interaction detection and compare-sse) — are also available with no local install at boltzmaker.mdeller.com; only the GPU run step still needs your own hardware (see Web deployment below).

Why it matters: hand-running a Boltz-2 campaign means writing dozens of near-identical YAML files by hand, remembering the right CLI flags for the hardware you’re on, and manually digging through prediction JSONs afterwards, all repetitive, error-prone steps that don’t need a human. BoltzMaker turns a single annotated spec into the full pipeline: generated inputs, environment/input validation (including ligand-chemistry sanity checks — undefined stereocentres, ambiguous protonation states, stray salts — so bad input chemistry is caught before hours of compute, not silently mispredicted), a monitored run with Mac-safe memory defaults, and a ready-to-read report. It is useful for: structural biologists and drug-discovery scientists running Boltz-2 structure/affinity panels (single targets, covalent-linkage studies, or multi-chain SAR/selectivity campaigns) who want a repeatable, resumable, well-documented pipeline instead of a pile of hand-edited scripts.

Don’t want to hand-write the spec at all? BoltzMaker.py new interviews you in plain English — proteins, partners, ligands, and the constraint sentences — and writes a valid boltz_input.md for you. If you’ve already got a reference co-crystal or homology structure for a protein, it can even suggest pocket-contact residues automatically, remapped onto your target’s own numbering via sequence alignment, instead of you reading them off a structure viewer by hand.

BoltzMaker grew out of five smaller, single-purpose tools written earlier: generate_yaml for building the input YAMLs, simple-zsh-script-to-run-boltz2 for driving the actual boltz predict runs, analyze-boltz2-results for the post-run analysis, cif2plip for protein-ligand interaction profiling, and smiles2grid for rendering a ligand set into a boxed grid of 2D structures. BoltzMaker consolidates all five into one spec-driven pipeline sharing a single campaign format, so the same input file drives every stage instead of juggling separate scripts and re-typing target names between them.

And yes, the name is a nod to Boltmaker, Timothy Taylor’s Champion Beer of Britain and one of the author’s favourites.

See CHANGELOG.md for what’s changed recently, and PROJECT_PLAN.md for the roadmap behind the To-Do list below.

📥 Installation

Two ways to install, depending on whether the computer running BoltzMaker has internet access. Most people want Path 1. (Looking for more detail/troubleshooting on either path? See One-time setup and docs/tier_b_offline_install.md further down.)

Path 1: This computer has internet access

1. Open the Terminal app (Applications -> Utilities -> Terminal, or search for “Terminal” with Spotlight), then make a folder for BoltzMaker and go into it:

mkdir -p ~/Desktop/BoltzMaker
cd ~/Desktop/BoltzMaker

2. Download BoltzMaker into that folder:

git clone https://github.com/bellcheddar/BoltzMaker.git .

(the trailing . tells it to put the files directly into the folder you just made, rather than inside another new folder). If this is the first time you’ve used git, macOS may pop up a dialog asking to install “Command Line Tools” — click Install and wait for it to finish, then run the command again.

3. Run the installer:

./install.sh

Wait for it to finish. It downloads a few GB of software the first time, so it can take a while depending on your connection.

4. Check it worked:

pixi run preflight examples/t4_lysozyme/boltz_input.md

If you see a table of green PASS results, you’re ready to go — see Commands below for what to run next.

Path 2: This computer has no internet access

Use this for a lab machine, server, or any computer that’s offline or behind a firewall. You’ll need a second computer that does have internet access to prepare a single installer file first.

1. On the computer with internet access, follow Path 1 above, then build the offline installer file:

pixi global install pixi-pack
pixi-pack --platform osx-arm64 --ignore-pypi-non-wheel --create-executable -o boltzmaker-installer.sh

(use --platform linux-64 instead of osx-arm64 if the offline computer runs Linux)

2. Copy boltzmaker-installer.sh, together with the whole BoltzMaker folder, onto the offline computer (USB drive, internal network transfer, etc.).

3. On the offline computer, in a terminal, go to where you copied those files and run:

./boltzmaker-installer.sh -o ./boltzmaker-env
source ./boltzmaker-env/activate.sh
export KMP_DUPLICATE_LIB_OK=TRUE

4. Check it worked:

python3 BoltzMaker.py preflight examples/t4_lysozyme/boltz_input.md

Full details, including a couple of one-time extra steps this path needs, are in docs/tier_b_offline_install.md.

🧩 Architecture

+----------------+     +----------+     +-----------+     +-----+     +---------+
| boltz_input.md | --> | generate | --> | preflight | --> | run | --> | analyze |
+----------------+     +----------+     +-----------+     +-----+     +---------+

Each stage reads only the manifest + files the previous stage wrote, so any stage can be re-run on its own (generate, preflight, run, or analyze individually) without repeating the others: all simply chains all four.

🔧 One-time setup

python3 BoltzMaker.py setup

Creates a dedicated .venv (Python 3.12: boltz pins numpy<2.0, which has no prebuilt wheel for newer Pythons) next to BoltzMaker.py and installs boltz, rich, pandas, openpyxl, pyyaml, rdkit, matplotlib, psutil, scipy, gemmi, biopython, plotly, reportlab, and requests into it. This pulls PyTorch (~2-3 GB) and, the first time boltz predict actually runs, Boltz downloads several GB of model weights over the network. Every other command below transparently relaunches itself under this managed environment, so you can keep invoking the script with whatever python3 is on your PATH.

Re-run with --force to recreate the venv from scratch, or -y/--yes to skip the download confirmation prompt.

Optional: setup-plip (protein-ligand interaction analysis)

python3 BoltzMaker.py setup-plip

Entirely optional and separate from the venv above. Builds a .plip_env (via a self-downloaded micromamba, ~1-1.5GB, mostly PyMOL’s own Qt/ Cairo/HDF5 dependencies) and vendors a pinned commit of cif2plip, which converts a Boltz ModelCIF into a strict PDB and runs PLIP on it for real protein-ligand interaction fingerprints (H-bonds, salt bridges, pi-stacking, halogen bonds, metal coordination, etc.). A conda-forge-based environment is used deliberately here rather than pip: PLIP requires OpenBabel and PyMOL as in-process Python imports (not subprocess calls), and empirically, plip‘s own installer forces a broken from-source OpenBabel build unless a working OpenBabel is already present, while the standalone PyPI pymol-open-source wheel has a hardcoded broken library path on this platform — conda-forge’s builds have neither problem.

If .plip_env isn’t present, everything below degrades gracefully: analyze skips interaction analysis (dashboard looks exactly as it did before this feature), and the new wizard simply doesn’t ask about reference structures. Nothing else in BoltzMaker requires it. preflight‘s plip_env check always reports which mode you’re in.

Optional: mkdssp/dssp (for compare-sse‘s SSE-boundary-shift metric)

Not bundled or installed by any BoltzMaker command — a small external binary you may already have (brew install dssp on macOS, or conda install -c salilab dssp). Only needed for one specific compare-sse metric (secondary-structure-element boundary shift, used when a structure has no deposited HELIX/SHEET records — true for every Boltz-predicted structure). Every other compare-sse metric works without it.

Alternative: pixi (one unified environment, macOS + Linux/CUDA)

./install.sh

Installs pixi if it isn’t already on your machine, then solves and installs everything (boltz, rdkit, PLIP’s OpenBabel/PyMOL stack, and the rest of requirements.txt) as one environment from pixi.toml/pixi.lock, replacing the need to separately run setup + setup-plip above. Reproducible (the committed pixi.lock pins every package on both osx-arm64 and linux-64), and the only path here that’s actually tested against Linux/CUDA rather than macOS/MPS alone. Once installed:

pixi run preflight my_campaign.md
pixi run all my_campaign.md

(or pixi shell to activate the environment directly and run python3 BoltzMaker.py ... as normal). PLIP needs one extra one-time step, same spirit as setup-plip above: pixi run postinstall.

No internet on the target machine at all? See docs/tier_b_offline_install.md for building a single self-extracting installer script per platform (pixi-pack --create-executable) that needs no pixi, no conda, and no network to run.

🧪 Examples

Four entirely public-domain campaigns in examples/, run any of them with python3 BoltzMaker.py all examples/<name>/boltz_input.md:

Verified end-to-end (generate -> preflight -> real boltz predict -> analyze, including cif2plip interaction analysis) on an Apple M1 Max, 64GB:

Run time scales with complex size, not just target count: ADRB2_ISO1‘s two-chain receptor+Gs-partner complex took disproportionately longer than the single-chain examples, since attention-style operations scale worse than linearly with sequence length — confirmed directly by AR2NG_PRO1 (same receptor, no partner) finishing in a fraction of the time. One contributing factor on Apple Silicon specifically: torch.linalg.svd (used in the diffusion step) has no MPS implementation and silently falls back to CPU — worth budgeting for on large multi-chain campaigns.

5ht2_gq_panel‘s six large 4-chain receptor+Gq-heterotrimer targets (~1250-1280 tokens) originally crashed on Apple Silicon: boltz’s triangular attention computes the full row-wise QK^T score matrix for the whole complex in one unchunked matmul, which exceeds MPS’s single-tensor size ceiling past roughly 1250 residues and crashes the process inside PyTorch’s internal tiled-bmm fallback. Each row’s attention is independent, so chunking along that axis is exact, not an approximation — setup now patches this directly into the installed boltz package (idempotent, and checked against boltz’s exact source so a future upgrade can’t be silently mis-patched). run also wraps boltz predict with caffeinate automatically (macOS only, silently skipped if unavailable) as general sleep-prevention hygiene for long GPU jobs. All 15 5ht2_gq_panel targets, including the six large complexes, now complete successfully — see CHANGELOG.md for the fix in full.

🧭 boltz_input.md format

Plain labelled text — no markdown, no YAML, no brackets, no quoting. One rule: blocks are Label: value lines with a blank line between them; comments start with #. Field names are plain English (Output folder, Predict affinity, Pocket contact) rather than Boltz-internal snake_case. Don’t want to hand-write it at all? Run python3 BoltzMaker.py new and answer plain questions instead — see Commands below.

The format has two layers: a family x partners x ligand cross-product (the ergonomic layer: write each protein/ligand once, get every combination as a separate target), and standalone constraint sentences for the two/three-ended relationships (covalent bonds, distance constraints) that don’t fit inside one block — each names the protein it belongs to and can be written anywhere in the file.

Settings:
Output folder: ./boltz_yamls    # where generated per-target YAMLs are written
Predict affinity: no            # off by default -- it's a heavier prediction pass

Protein: RECP1                  # short name, MAX 5 CHARACTERS (Boltz stores chain names
                                # in a fixed 5-char field internally and silently
                                # truncates longer ones, which then crashes later with a
                                # confusing error -- `preflight` catches this for you).
                                # Also names the output file: {protein}_{ligand}.yaml
Sequence: MDILC...              # required
Partners: CHNX, CHNY            # optional: co-folded chains, defined as their own
                                # Partner: blocks below
# Ligands: LIG1, LIG3           # optional: restrict this protein to a ligand subset
                                # (default: crossed with every ligand below)
# Ligands: none                 # optional: ligand-free (apo) target -- no ligand entity,
                                # no pocket constraint, no affinity property, whatever
                                # `Predict affinity:` says. Stem is just the protein name
                                # (e.g. `RECP1.yaml`, not `RECP1_LIG1.yaml`), runs through
                                # the same generate/preflight/run/analyze pipeline and the
                                # same staged `boltz predict` batch as every other target.
# Modifications: SEP:5          # optional: CCD:position tokens for modified residues
                                # (e.g. phosphoserine)
# Cyclic: yes                   # optional: cyclic polymer (e.g. a cyclic peptide)
# MSA: empty                    # optional: path to a precomputed MSA, or "empty" for
                                # single-sequence mode (skip MSA generation)
# Templates: reference_structure.cif
                                # optional: structural template file(s), applied to all
                                # protein chains (no per-chain mapping -- hand-edit the
                                # generated YAML for that rarer case)
# Apo structure: reference/apo.pdb
                                # optional: a reference apo/unbound structure, used only
                                # by `compare-sse` (see below), never by generate/run.
                                # No genuinely apo experimental structure? Predict one:
                                # give another `Protein:` block the same `Sequence:` and
                                # `Ligands: none` (see above), run the campaign once, then
                                # point `Apo structure:` at its output in `boltz_cif/`.
# Apo chain: A                 # optional: explicit chain id in the apo structure above
                                # (omit to auto-detect via sequence identity)
# Family type: gpcr            # optional: gpcr / kinase / auto (default) -- selects
                                # `compare-sse`'s motif annotator
# Group: RECP1                  # optional: shared display/report name for multiple
                                # `Protein:` blocks that are the same underlying receptor
                                # (e.g. with/without a partner, or a predicted apo
                                # variant) -- defaults to this block's own name if unset

Partner: CHNX
Sequence: MTLES...
# Type: dna                     # optional: protein (default) / dna / rna
# Copies: X1, X2                # optional: homo-oligomer chain-id override -- this one partner
                                # sequence becomes multiple chains

Ligand: LIG1
SMILES: FC(F)CNC(...)=O         # exactly one of SMILES/CCD is required
# Role: agonist                 # optional: agonist / antagonist -- reporting only (dashboard
                                # chart shapes), never affects generate/run

Ligand: LIG2
CCD: GOL                        # a Chemical Component Dictionary code (e.g. common crystallization
                                # additives/ions) instead of a SMILES

Covalent bond: RECP1 residue 44 atom SG to LIG1 residue 1 atom C3
Pocket contact: RECP1 residue 148
Distance constraint: RECP1 residue 10 to RECP1 residue 80 within 8.0 Angstrom

Every protein is crossed with every ligand (unless a protein sets Ligands: to scope itself to a subset, or Ligands: none for a single ligand-free/apo target), producing one {protein}_{ligand}.yaml per pair. See example.md for the full copy-paste template and examples/ for complete working campaigns.

🚀 Commands

python3 BoltzMaker.py new      [boltz_input.md]  # write a new campaign by answering plain questions
python3 BoltzMaker.py format   boltz_input.md    # auto-align comments/blank-lines (cosmetic only)
python3 BoltzMaker.py generate boltz_input.md    # write the target YAMLs + manifest
python3 BoltzMaker.py preflight boltz_input.md   # environment + input sanity checks
python3 BoltzMaker.py run      boltz_input.md    # boltz predict, live progress, resumable
python3 BoltzMaker.py analyze  boltz_input.md    # CSV / XLSX / HTML dashboard
python3 BoltzMaker.py all      boltz_input.md    # generate -> preflight -> run -> analyze
python3 BoltzMaker.py boltz_input.md             # same as `all` (subcommand is optional)
python3 BoltzMaker.py compare-sse boltz_input.md # apo-vs-holo secondary-structure motif shifts (see below)

new interviews you (proteins, partners, ligands, and the three constraint sentence types) and writes the file for you — it won’t overwrite an existing file without asking first. It covers the common case only; rarer fields (modifications, cyclic, MSA override, templates, homo-oligomer copies) are left for hand-editing the file it writes. If setup-plip has been run, it also asks whether you have a reference structure with a ligand already bound (a co-crystal or homology model) for each protein — if so, it runs cif2plip on it, lets you pick the relevant ligand if more than one is detected, and suggests the contacted residues as Pocket contact: constraints, remapped onto your target’s own numbering via sequence alignment (BLOSUM62 + affine gaps) so the reference structure’s residue numbers don’t have to match your target’s.

format re-aligns trailing comments to a clean column and normalizes blank-line spacing around section/record boundaries, purely cosmetic (it validates the file parses first, and never changes meaning). Pass --check to report whether reformatting is needed without writing anything (exit 1 if so, e.g. for a pre-commit check).

Any field BoltzMaker doesn’t recognize (a typo like Predict afinity: instead of Predict affinity:) prints a WARNING naming the block, its name, and the line number, and is otherwise silently dropped, so a misspelled field never just vanishes without a trace.

Common options:

Memory-control options (see below for why these matter on Mac/unified-memory hardware):

run is idempotent: targets with a complete prediction (cif + confidence json, and an affinity json if predict_affinity is on) are skipped on re-run, so an interrupted batch can just be re-run as-is.

compare-sse options (see the section below for what it does — it now also runs automatically as part of analyze/all for every family with an Apo structure: set; the standalone command below is for re-running just this analysis on its own, e.g. after adding an apo structure without re-running boltz predict):

🛠️ Memory on Mac (unified-memory) hardware

A real 4-chain GPCR+G-protein complex (~1250 combined residues/atoms) used ~65GB RAM on a 64GB M1 Max during testing and swap-thrashed for 20+ minutes with zero progress before being killed, worth knowing about before running anything large. Mitigations built in:

• --mps-watermark sets PYTORCH_MPS_HIGH_WATERMARK_RATIO, which caps how much memory MPS will allocate relative to the device’s recommended maximum. At the default 1.0, an oversized complex now raises a clean MPS out-of-memory error in the log instead of silently spilling into swap.
• --workers defaults to 2 and --max-parallel-samples to 1: both trade a little parallelism for a much smaller memory footprint, which matters more on unified memory than on a dedicated-VRAM GPU.
• preflight‘s memory_heuristic check WARNs when a target’s total residue+ligand-atom count crosses --memory-warn-tokens (default 1000), citing the empirical data point above. It’s a rough heuristic, not a precise memory model.
• run‘s progress bar shows live memory usage (RSS summed across the whole boltz predict process tree), and logs a warning if usage stays above 90% of system RAM for 60+ seconds with no new completed target: a sign of thrashing, not genuine progress.
• run/all auto-retries (--max-retries, default 2) any target that doesn’t complete, isolating every still-incomplete target to its own single-target boltz predict invocation from the first retry onward — a real 4-target cascade on 5ht2_gq_panel (an OOM on 2 of 6 large targets run together crashed the shared affinity phase for 2 more that had already succeeded) recovered cleanly this way. This means a large campaign can be started and left unattended: a transient OOM no longer needs a human to notice, wait, and manually re-run just the affected targets.

If a target still fails after every automatic retry, that’s a real finding (this hardware may not be viable for a complex that size), not something to force through.

⚙️ Progress bar

Two rows during run: the outer bar shows targets done/total, elapsed time, an ETA, and live memory usage. The inner row shows which phase Boltz is in (MSA generation / structure prediction / affinity prediction) and that phase’s own progress, parsed from Boltz’s own log output. Note: Boltz doesn’t expose diffusion- or recycling-step-level progress anywhere in its output (verified against the installed package’s source), so this is the finest granularity actually available, not a per-step diffusion counter.

📊 Outputs

Written next to boltz_input.md:

🔬 Ligand validation & scaffold highlighting

Two related but distinct checks run over every SMILES ligand before you commit hours of boltz predict time to them, and both surface directly in the dashboard.

Why this exists: Boltz folds whatever chemistry it’s given — an undefined stereocentre, an unintended protonation state, or a stray counterion left in a SMILES string doesn’t raise an error, it just silently changes the predicted pose and affinity. These are exactly the mistakes a non-specialist (or a tired specialist) makes typing SMILES by hand, and they’re invisible until you’re staring at a confusing result with no idea the input was ever wrong.

Ligand preparation (validity checks)

At parse time, every ligand SMILES is canonicalized (RDKit) so the same molecule is represented consistently everywhere downstream — the generated YAML, the summary table, and cif2plip’s own ligand-matching (see the InChIKey-based matching note in CHANGELOG.md). Then, both at preflight (as the ligand_preparation check) and again in the dashboard’s “Ligand preparation” card, each ligand is checked for:

All of this is advisory, not a hard failure — these can be legitimate, deliberate modelling choices — but they’re the kind of thing worth a second look before trusting downstream numbers.

Scaffold highlighting (the “Ligand structures” grid)

Separately, the dashboard’s ligand grid tries to answer a different question: do any of these ligands share a chemical core? This matters most for SAR (structure-activity relationship) campaigns, where a chemist is usually testing close analogues on purpose, and seeing the shared scaffold at a glance (with the parts that differ jumping out) is more useful than reading each SMILES individually. Two tiers, in order, and nothing is highlighted unless one of them actually finds something real:

1. Exact Bemis-Murcko scaffold match — ligands whose ring systems + connecting linkers are chemically identical are grouped, threshold-free. This is the dominant case for a real SAR series.
2. Fallback for near-analogues: ligands left over are grouped by Morgan/Tanimoto fingerprint similarity, then a maximum common substructure (MCS) is computed across the whole group and verified to actually match every member — so the claim is a proven substructure match, not just an assigned similarity score.

Small or trivial shared fragments (below 8 heavy atoms — e.g. “they all contain a benzene ring”) are deliberately not highlighted; a group has to share something structurally meaningful to be called out. Ligands in the same scaffold group also have their 2D depiction aligned to a common orientation, so the shared core is drawn in the same position across cells and visually “snaps together.”

What’s highlighted and how, directly on each rendered structure — the same badges shown on each ligand cell and spelled out in the panel’s own legend:

A specific finding (stereocentre, ionizable group) always takes priority over the softer scaffold highlight if they overlap on the same atom, since it’s the more actionable signal. If no ligand shares a real scaffold with any other, the panel says so plainly (“no shared scaffold or substructure detected”) rather than forcing a highlight onto something coincidental. CCD-code ligands have no SMILES to render and show a plain placeholder instead of an empty cell.

🧬 compare-sse: apo vs holo secondary-structure shifts

Why this exists: a confidence score tells you what Boltz predicted, not how the protein moved in response to ligand binding — a real structural question whenever you have both a reference apo (unbound) structure and a predicted holo one for the same protein. compare-sse answers it in terms a structural biologist actually reasons in (“TM6 swung out 4.2 Angstrom”, “the DFG motif flipped from in to out”), not raw DSSP fragment coordinates.

It’s a core part of analyze/all: any family with an Apo structure: field set (see boltz_input.md format above) gets compared automatically, no separate command needed, and the result is embedded directly into boltz_dashboard.html. A family with no apo structure configured isn’t silently skipped either — the dashboard’s “Family coverage” table says so explicitly, alongside any family that was compared. Pass --skip-sse to analyze/all to opt out, or use the standalone compare-sse command below to re-run just this analysis on its own (its own --family/--target flags let you target one family/target instead of the whole campaign).

Motifs are annotated by one of three pluggable sources, auto-selected per family (or set explicitly with Family type:):

Apo is superposed onto holo using only the family’s stable, non-binding-site-adjacent residues (via gemmi’s superpose_positions), so a ligand-induced local shift can’t skew the global fit. Each motif then gets:

A metric that genuinely wasn’t computed for a given motif (e.g. axis rotation for a loop, DFG state for a non-kinase family, boundary shift with no DSSP data available) shows as an explicit N/A in both the CSV and every dashboard table, not a blank cell.

Above the per-motif table, both boltz_dashboard.html‘s embedded card and the standalone boltz_sse_comparison.html show:

python3 BoltzMaker.py compare-sse boltz_input.md

Writes, next to boltz_input.md (or --out-dir): boltz_sse_comparison.csv (one row per family/target/motif) and boltz_sse_family_status.json (the family-coverage table above, machine-readable), a standalone self-contained boltz_sse_comparison.html (Plotly bar chart + motif x target heatmap, vendored the same way as the main dashboard), and boltz_sse_comparison_sessions/<target>.pml — a plain-text PyMOL script per target that colours/labels each motif and highlights the ones with a significant shift. It’s just text: opens in any local PyMOL install, no pymol dependency in BoltzMaker’s own venv.

When auto-run by analyze/all, a campaign with no apo structures configured anywhere just gets a dashboard section saying so — it never aborts the rest of the pipeline over an optional, additive feature. The standalone command above still exits with a clear error if you explicitly pass a --family/--target that matches nothing, since that’s a real mistake worth stopping for.

🩹 Troubleshooting / FAQ

🌐 Web deployment

Live at boltzmaker.mdeller.com. A Flask frontend for the non-GPU stages of the pipeline — upload a boltz_input.md (or build one with the wizard), run generate/preflight and download the results, or upload a completed campaign folder (from a run you did locally) for full analyze, PLIP interaction detection, and compare-sse, all in the browser. The GPU run step is deliberately never hosted: there’s no GPU on the droplet, so that stage still runs on your own hardware and you bring the boltz_output/ back for analysis.

Source and tested-CLI isolation. The web app lives in web/, developed on a separate web git branch/worktree so the tested BoltzMaker.py on main is never touched by web-app work. BoltzMaker.py was never designed to be imported (it relaunches itself into a managed venv at module import time), so the Flask app only ever invokes it as a subprocess, with an explicit minimal environment and a per-command timeout, through a dedicated trimmed venv (.venv/, torch/boltz-free, ~500MB — every torch/boltz reference in the script is a function-local lazy import) kept separate from the Flask-serving venv (web/.venv/).

Optional PLIP. If the droplet’s .plip_env (the same conda-forge PyMOL/OpenBabel environment setup-plip builds locally, ~1-1.5GB) is present, analyze runs full protein-ligand interaction detection and compare-sse automatically; if not, both degrade gracefully rather than erroring, exactly as they do locally.

Serving stack: gunicorn (3 sync workers, 900s timeout to cover PLIP rendering and compare-sse’s GPCRdb/KLIFS/PDBe lookups) behind nginx (Let’s Encrypt TLS via certbot, HTTP/2, rate-limited upload endpoints, 200MB body cap), as a hardened systemd service (dedicated unprivileged user, memory/CPU caps). Every request gets its own scratch directory, deleted when the request finishes and swept by a five-minute cleanup timer as a backstop; uploaded zips are checked for zip-slip and zip-bomb payloads (path-traversal/absolute-path rejection, uncompressed-size and entry-count caps) before anything is extracted.

🧫 Testing

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest tests/

27 tests covering compare-sse‘s annotators against real fixture data (a real apo EGFR kinase-domain structure vs the egfr_covalent example’s real holo prediction; a real apo beta2-adrenergic-receptor structure vs adrb2_gs_panel‘s real holo predictions), with GPCRdb/KLIFS/PDBe network calls swapped for an injectable fake client seeded with real, previously-verified API responses — fully offline and fast (~2s). Plus grammar and CLI-resolution tests for the parser fields above.

📚 Citation

Passaro, S., Corso, G., Wohlwend, J., Reveiz, M., Thaler, S., Somnath, V.R., Getz, N., Portnoi, T., Roy, J., Stark, H., Kwabi-Addo, D., Beaini, D., Jaakkola, T., Barzilay, R. (2025). Boltz-2: Towards Accurate and Efficient Binding Affinity Prediction. bioRxiv. https://doi.org/10.1101/2025.06.14.659707

Mirdita, M., Schütze, K., Moriwaki, Y., Heo, L., Ovchinnikov, S., Steinegger, M. (2022). ColabFold: making protein folding accessible to all. Nature Methods. https://doi.org/10.1038/s41592-022-01488-1

Schake, P., Bolz, S.N. et al. (2025). PLIP 2025: introducing protein-protein interactions to the protein-ligand interaction profiler. Nucleic Acids Research, gkaf361. https://doi.org/10.1093/nar/gkaf361

The PyMOL Molecular Graphics System, Version 3.1, Schrödinger, LLC.

Rego, N., Koes, D. (2015). 3Dmol.js: molecular visualization with WebGL. Bioinformatics, 31(8), 1322-1324. https://doi.org/10.1093/bioinformatics/btu829

📄 License

MIT © Marc C. Deller

📋 To do

• ⬜ Share pip cache between the two environments (PIP_CACHE_DIR) so setup-plip doesn’t re-download wheels the main venv already fetched
• ✅ Pin exact dependency versions and add a cached/offline install mode for reproducible installs — via pixi.toml/pixi.lock and install.sh (see Alternative: pixi above and docs/tier_b_offline_install.md), not by pinning setup/setup-plip‘s own unpinned requirements.txt-driven installs, which remain as they were
• ⬜ Add BoltzMaker.py doctor — a post-install check that imports boltz/rdkit/plip/openbabel/pymol in-process and reports exactly which env/feature is broken
• ⬜ Add an explicit Boltz model-weights cache dir + a preflight check for it (ties into the existing iCloud dataless-file eviction check)
• ⬜ Detect the MPS torch.linalg.svd CPU-fallback at preflight and warn with an estimated runtime multiplier for large multi-chain complexes
• ⬜ Add a residue/chain-count-based runtime pre-estimator, plus a toggle to log which ops fall back to CPU on MPS
• ⬜ Checkpoint run at the per-sample level (not just per-target) so an interrupted multi-hour complex resumes without recomputing completed diffusion samples
• ⬜ Add a cross-target selectivity/triage view to the dashboard (confidence-vs-affinity quadrant flags for “high-confidence, high-affinity” hits)
• ✅ Bundle Plotly.js locally instead of via CDN so the dashboard renders fully offline/air-gapped
• ⬜ Add a smoke-test suite: an end-to-end fixture run in CI plus unit tests for the boltz_input.md parser and JSON-metric flattening
• ✅ Add a ligand-preparation/validation step (canonicalization, stereocentre/protonation-state flagging, disconnected-fragment detection) so bad input chemistry is caught before hours of compute, not silently mispredicted
• ⬜ Add a retrospective benchmark mode: pull known actives/co-crystal data for a target family (ChEMBL/BindingDB/PDB) and report predicted-vs-measured pIC50 correlation + pose RMSD, so a user has a per-target-family trust score before committing to a real campaign
• ✅ Add a 3Dmol.js rotating structure view to each target’s binding-site panel, placed next to the existing static PyMOL image (keep the static image, add a “Download image” link for it — doesn’t exist yet — and add the interactive 3Dmol.js view alongside rather than replacing anything)

👤 Author

Marc C. Deller, D.Phil. Structural biologist & drug discovery scientist