OneScience-Group/BoltzGen

BoltzGen

Model Introduction

BoltzGen is a generative model for biomolecular binder design. Given a protein, peptide, nucleic acid, or small-molecule target together with design constraints, BoltzGen can generate candidate three-dimensional structures, perform inverse folding to generate amino acid sequences, and use Boltz-2 for structure refolding, confidence analysis, filtering, and ranking.

Official project: https://github.com/HannesStark/boltzgen

Model Description

The complete design pipeline consists of six stages:

1. design: A diffusion model generates candidate three-dimensional backbones satisfying the target and design constraints;
2. inverse_folding: An inverse-folding model generates amino acid sequences for the candidate backbones;
3. folding: Boltz-2 predicts structures for the designed sequences;
4. design_folding: The designs are folded again under the design conditions to evaluate adherence to the specified constraints;
5. analysis: RMSD, confidence scores, sequence composition, and other quality metrics are calculated;
6. filtering: Candidates are filtered and ranked according to predefined thresholds, and structure files, CSV files, and summary PDFs are generated.

The model package contains the following major pretrained checkpoints:

• boltzgen1_diverse.ckpt: diffusion design model emphasizing structural diversity;
• boltzgen1_adherence.ckpt: diffusion design model emphasizing adherence to design conditions;
• boltzgen1_ifold.ckpt: inverse-folding model for amino acid sequence generation;
• boltz2_conf_final.ckpt: Boltz-2 structure prediction and confidence model;
• boltz2_aff.ckpt: affinity model used for protein-small-molecule tasks.

Use Cases

Use Case	Description
Protein binder design	Generate binder backbones and amino acid sequences for a specified protein target.
Peptide and cyclic peptide design	Generate linear peptides, cyclic peptides, disulfide-containing peptides, and related candidate structures.
Antibody and nanobody design	Generate candidate designs using framework, CDR, or binding-site constraints.
Small-molecule binder design	Design proteins targeting small molecules and optionally calculate affinity-related model scores.
Inverse folding	Generate candidate amino acid sequences for a given protein backbone.
Training pipeline validation	Use the official training entry point to validate data loading, forward propagation, loss computation, backward propagation, and parameter updates.

Usage

1. OneCode

You can use the OneCode online environment for an intelligent one-click AI4S programming experience:

Try OneCode for AI4S Programming

2. Manual Installation

Hardware Requirements

• Supports DCU devices in the OneScience DTK environment;
• DTK/HIP devices are accessed through PyTorch's torch.cuda compatibility interface;
• The complete design pipeline is recommended to run on DCU;
• CPU execution is currently suitable mainly for package import, configuration validation, and lightweight data inspection.

Download the Model Package

Install the Hugging Face command-line tool and download the model repository:

python -m pip install -U huggingface_hub

hf download OneScience-Group/BoltzGen --local-dir ./BoltzGen
cd BoltzGen

Install the Runtime Environment

DCU Environment

conda create -n onescience311 python=3.11 -y
conda activate onescience311

python -m pip install "onescience[bio-dcu]" \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai

Install the additional BoltzGen dependencies on top of the OneScience environment.

The bf16-mixed configuration used by BoltzGen cannot be parsed by the older pytorch-lightning==1.8.6, so PyTorch Lightning has been upgraded to pytorch-lightning==2.5.6 in the adapted environment:

python -m pip install --no-deps -r requirements.txt

Verify that the BoltzGen command-line entry point can be imported successfully:

python scripts/boltzgen.py --help

Weights and Molecular Dictionary Preparation

The official checkpoints are stored under weight/:

Relative Path	Purpose
weight/boltzgen1_diverse.ckpt	Binder backbone diffusion model emphasizing structural diversity
weight/boltzgen1_adherence.ckpt	Binder backbone diffusion model emphasizing adherence to design conditions
weight/boltzgen1_ifold.ckpt	Inverse-folding model for sequence generation
weight/boltz2_conf_final.ckpt	Boltz-2 structure prediction and confidence model
weight/boltz2_aff.ckpt	Affinity model for protein-small-molecule tasks
weight/mols	CCD molecular dictionary required for inference

Minimal DCU Inference

Purpose: Use the official 1g13 example and local checkpoints to run a complete protein binder design pipeline with one candidate.

First, enable offline mode:

export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export HF_DATASETS_OFFLINE=1

These environment variables prevent compute nodes from attempting to access external networks.

Generate the pipeline configuration:

python scripts/boltzgen.py configure \
  conf/example/vanilla_protein/1g13prot.yaml \
  --output output/dcu_minimal \
  --protocol protein-anything \
  --num_designs 1 \
  --budget 1 \
  --devices 1 \
  --num_workers 0 \
  --use_kernels false \
  --moldir weight/mols \
  --design_checkpoints \
    weight/boltzgen1_diverse.ckpt \
    weight/boltzgen1_adherence.ckpt \
  --inverse_fold_checkpoint weight/boltzgen1_ifold.ckpt \
  --folding_checkpoint weight/boltz2_conf_final.ckpt

This command only generates the stage-specific configuration files under:

output/dcu_minimal/config/

It does not execute model inference.

Successful configuration indicates that the design input, checkpoint paths, molecular dictionary, and pipeline parameters can be parsed correctly.

Execute the complete pipeline:

python scripts/boltzgen.py execute output/dcu_minimal

This command executes all six configured stages.

If every stage exits with code 0, the end-to-end engineering pipeline is operational. Whether the final candidates are useful designs must still be evaluated using the filtering CSV files, structural quality metrics, and experimental validation.

For protein-small-molecule protocols, add the following option during configuration:

--affinity_checkpoint weight/boltz2_aff.ckpt

This enables the affinity checkpoint.

The resulting affinity-related values are intended for model-based evaluation and candidate comparison and should not be interpreted directly as experimentally measured binding constants.

Stage-Specific Recovery

Purpose: Reuse existing configuration files and intermediate results when a pipeline is interrupted or only one stage needs to be rerun.

For example, to rerun only the final filtering stage:

python scripts/boltzgen.py execute output/dcu_minimal --steps filtering

After successful execution, the command regenerates the ranking table, candidate structures, and summary PDF under:

output/dcu_minimal/final_ranked_designs/

Successful filtering does not necessarily mean that any candidate passes the default thresholds. The number of accepted candidates and the specific failed metrics should also be inspected.

Inference Outputs

The main output structure is:

output/dcu_minimal/
├── config/                         # Actual configuration for the six pipeline stages
├── design/                         # Candidate backbones generated by the diffusion models
├── inverse_folding/                # Sequences generated by inverse folding
├── folding/                        # Refolded sequence structures
├── design_folding/                 # Design-conditioned refolding results
├── analysis/                       # Candidate quality metrics
└── final_ranked_designs/           # Ranked candidates, structures, and summary PDF

Use final_ranked_designs/ to inspect candidate rankings and quality summaries.

The absence of NaN or Inf values in structural coordinates only indicates that the numerical output is valid. It does not by itself establish structural plausibility, binding activity, or experimental validity.

Minimal Training Pipeline

BoltzGen provides an official PyTorch Lightning training entry point for the following model configurations:

Configuration	Trainable Model
inverse_folding.yaml	Inverse-folding sequence generation model
boltzgen_small.yaml	Small BoltzGen structural diffusion model
boltzgen.yaml	Large BoltzGen structural diffusion model

Run the prepared minimal training configuration:

python scripts/train.py conf/train_boltzgen_small_smoke.yaml

This command invokes the official training entry point.

If one batch completes successfully and the process exits with code 0, the following components have been validated:

• DataLoader;
• Feature construction;
• Forward propagation;
• Loss computation;
• Backward propagation;
• optimizer.step.

This smoke test only verifies that the training pipeline is executable. It does not indicate model convergence or usable prediction quality.

Formal training requires data in the official BoltzGen format, including:

targets/structures/
targets/records/
manifest.json
MSA
mols

Legacy OpenFold structure NPZ files require field-level compatibility conversion before they can be used by the BoltzGen training pipeline.

The complete training dataset must therefore be prepared according to the official BoltzGen data schema.

OneScience Official Resources

Platform	OneScience Main Repository	Skills Repository
Gitee	https://gitee.com/onescience-ai/onescience	https://gitee.com/onescience-ai/oneskills
GitHub	https://github.com/onescience-ai/OneScience	https://github.com/onescience-ai/oneskills

Citation and License

• Official implementation: https://github.com/HannesStark/boltzgen
• The upstream BoltzGen source code is distributed under the MIT License. See the top-level LICENSE file for details.
• Model checkpoints, RCSB PDB-derived data, OpenFold-derived data, training datasets, and other third-party assets remain subject to their respective original licenses, copyright notices, and terms of use.