run_boltz.zsh

A minimal, auditable wrapper for Boltz-1/2. Every run logged, timed, and reproducible.

A minimal, production-ready shell wrapper for running Boltz-1/Boltz-2 structure predictions from the command line. Handles logging, runtime tracking, and input sanitisation automatically so every run is reproducible and auditable.

Why it matters: running co-folding predictions by hand invites silent failures: overwritten logs, stray macOS dot-files derailing a batch, no record of how long a run took or what flags were used. run_boltz.zsh wraps Boltz in a thin, production-minded shell layer that timestamps every log, tracks wall-clock runtime, sanitises the input directory, and tees output to both screen and file. It is useful for anyone running Boltz at scale or in a regulated setting where reproducibility and an audit trail matter: drop it in, point it at your inputs, and every prediction becomes self-documenting.

Features

• Timestamped log files — every run writes to boltz_run_YYYYMMDD_HHMMSS.log; nothing is ever silently overwritten
• Runtime tracking — total wall-clock time reported at the end of each run
• Input sanitisation — removes macOS/Linux hidden dot-files (.DS_Store, ._*, etc.) from the inputs directory before prediction
• MPS fallback — sets PYTORCH_ENABLE_MPS_FALLBACK=1 for Apple Silicon compatibility
• Unified stdout + log — all output is tee’d to the terminal and the log file simultaneously via 2>&1 | tee

Requirements

• Boltz installed and on your $PATH
• zsh (macOS default; also available on Linux)
• A CUDA-capable GPU (the script passes --accelerator gpu)
• Internet access if MSA server lookups are needed (--use_msa_server)

Directory layout

project/
├── run_boltz.zsh       # this script
├── inputs/             # place your input YAML / FASTA / CIF files here
└── output/             # Boltz outputs written here (created automatically)

Usage

chmod +x run_boltz.zsh
./run_boltz.zsh

That’s it. The script picks up all inputs from ./inputs/, writes predictions to ./output/, and creates a timestamped log in the current directory.

Configuration

All key parameters are set at the top of the script:

Boltz prediction flags can be edited directly in the boltz predict call:

Output

Each run produces:

output/
└── boltz_results_<input_name>/
    ├── predictions/
    │   └── <model>_model_0.cif      # ModelCIF-format predicted structure
    ├── confidence_<model>_model_0.json
    └── ...

boltz_run_20250611_143022.log        # full stdout/stderr capture

Predicted structures are written as ModelCIF files. These can be loaded directly in PyMOL, UCSF ChimeraX, or processed downstream with tools such as Biotite or a PLIP-based interaction pipeline.

Notes

• The cleanup_input_dir function removes hidden files silently before each run. This prevents spurious Boltz errors on macOS where Finder writes ._<filename> resource fork files alongside legitimate inputs.
• Log files accumulate in the working directory; archive or delete them periodically if running many predictions.
• To run multiple diffusion samples for ensemble analysis, increase --diffusion_samples (e.g. 5) and downstream results will include model_0 through model_N.

👤 Author

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