README.md

---
frameworks:
- PyTorch
language:
- en
license: mit
tags:
- OneScience
- bioscience
- protein-design
- binder-design
- BoltzGen
tasks:
- protein-design
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">BoltzGen</span>
  </strong>
</p>

# 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](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 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:

```bash
python -m pip install -U huggingface_hub

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

### Install the Runtime Environment

**DCU Environment**

```bash
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:

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

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

```bash
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:

```bash
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:

```bash
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:

```text
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:

```bash
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:

```text
--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:

```bash
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:

```text
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:

```text
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:

```bash
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:

```text
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.