BoltzGen Workflow

The --method boltzgen workflow automates the design of binders using the BoltzGen generative model. The key advantage of this workflow is improved parallelization across multiple GPUs and better resource allocation on HPC clusters.

It supports the protein-anything, peptide-anything, protein_small-molecule and nanobody-anything protocols.

Overview

The BoltzGen workflow performs the following steps, as per boltzgen run:

• Design: Generates binder backbone structures based on a YAML configuration.
• Inverse Folding: Generates sequences for the designed backbones.
• Folding: Re-folds the designed binder in complex with the target.
• Design Folding: Re-folds the designed binder alone.
• Affinity: (Optional - protein_small-molecule protocol only) Calculates affinity scores for protein-small molecule complexes.
• (Merge batches: nf-binder-design --method boltzgen merges independently generated batches of designs, ready for analysis and filtering)
• Analysis & Filtering: Aggregates scores and filters designs based on user-defined criteria.

General Information

Command-line Options

You can see available options with --method boltzgen --help:

nextflow run Australian-Protein-Design-Initiative/nf-binder-design \
  --method boltzgen --help

YAML Configuration

The BoltzGen workflow is controlled by a YAML configuration file passed via --config_yaml. This file defines the input structure, constraints, and design objectives. Refer to the BoltzGen documentation on how to prepare your configuration file.

Note: ⚠️ BoltzGen expects residues specified as indices starting at 1, irresepctive of the numbering in your PDB/mmCIF file. You may find it easier to use bin/renumber_chains.py to renumber your input PDB to be sequentially numbered starting at 1 to simplify choosing hotspot residues in ChimeraX/Pymol/Molstar etc.

Usage

Basic Execution

To run the workflow with a configuration file:

nextflow run Australian-Protein-Design-Initiative/nf-binder-design \
  --method boltzgen \
  --config_yaml config/my_design.yaml

Key Parameters

Flag	Default	Description
--config_yaml	(required)	Path to the BoltzGen YAML configuration file
--outdir	results	Output directory for results
--design_name	config basename	Name of the design, used for output file prefixes
--protocol	protein-anything	Protocol type: protein-anything, peptide-anything, protein-small_molecule, or nanobody-anything
--num_designs	100	Total number of designs to generate
--inverse_fold_num_sequences	1	Number of sequences to generate per backbone during inverse folding
--batch_size	10	Number of designs to process per batch
--budget	10	Final number of designs to keep after diversity optimization and filtering
--devices	1	Number of GPU devices to use
--num_workers		Number of DataLoader workers

Filtering Parameters

Flag	Default	Description
--alpha		Trade-off for sequence diversity selection: 0.0=quality-only, 1.0=diversity-only
--filter_biased	true	Remove amino-acid composition outliers (use --filter_biased false to disable)
--metrics_override		Per-metric inverse-importance weights for ranking. Format: metric_name=weight (e.g., 'plip_hbonds_refolded=4' 'delta_sasa_refolded=2')
--additional_filters		Extra hard filters. Format: feature>threshold or feature<threshold (e.g., 'design_ALA>0.3' 'design_GLY<0.2')
--size_buckets		Constraint for maximum designs in size ranges. Format: min-max:count (e.g., '10-20:5' '20-30:10')
--refolding_rmsd_threshold		Threshold used for RMSD-based filters (lower is better)

Key Outputs

The results directory (or specified --outdir) will contain:

• params.json: A record of the parameters used for the run.
• boltzgen/batches: Each independent design batch, in folders for each step (design, inverse_folding, folding, design_folding)
• bolzgen/merged: All batches merged, after the 'analysis' step.
• boltzgen/filtered: Final designs are in filtered/final_ranked_designs after the 'filtering' step.

boltzgen/merged should be equivalent to the output of a non-Nextflow execution of boltzgen run - see the BoltzGen docs for details on the pipeline output.

Re-running Filtering

Use boltzgen_filter.nf to re-run filtering on existing results with different parameters:

nextflow run boltzgen_filter.nf --run results/boltzgen/merged --budget 20 --alpha 0.05

The --config_yaml and --protocol are auto-detected from params.json if not specified. All filtering parameters from the main workflow are available.

Results are saved to results/boltzgen/filtered/final_ranked_designs/.

FoldSeek Structural Search (Optional)

After filtering, you can optionally run FoldSeek structural similarity search on the final designs. The design (shorter/binder) chain is automatically extracted from each complex mmCIF — only the binder is searched, not the full target–binder complex.

FoldSeek summary results are output to {outdir}/foldseek/{database_name}/. See FoldSeek output format for details.

Enabling FoldSeek

Add --do_foldseek to your boltzgen command:

nextflow run Australian-Protein-Design-Initiative/nf-binder-design \
  --method boltzgen \
  --config_yaml config/my_design.yaml \
  --do_foldseek

FoldSeek Flags

Flag	Default	Description
--do_foldseek	false	Enable FoldSeek search on final designs

All common --foldseek_* flags (database, search mode, output options, CATH annotation) are documented in the FoldSeek subworkflow docs.

Examples

The examples/ directory contains complete working examples for BoltzGen workflows:

• examples/pdl1-boltzgen: PD-L1 protein binder (protein-anything)
• examples/boltzgen-protein: Protein binder design (protocol protein-anything)
• examples/boltzgen-cyclic-peptide: Cyclic peptide binder design (protocol peptide-anything)
• examples/boltzgen-small-molecule-binder: Small molecule binder design (protocol protein-small_molecule)
• examples/boltzgen-nanobody: Nanobody binder design (protocol nanobody-anything)

See the examples/README.md for details.