BoltzGen

For symmetric complexes like homo-dimers, you can ensure symmetric sequence generation during the inverse folding step by assigning the same symmetric_group ID to the corresponding chains in the entities section. The protein-redesign protocol supports scoring these complexes without needing separate binders and targets.

entities:
  - file:
      path: symmetric_dimer.cif
      include:
        - chain:
            id: A
            res_index: 100..300
            symmetric_group: 1
        - chain:
            id: B
            res_index: 100..300
            symmetric_group: 1
      design:
        - chain:
            id: A
            res_index: 200..210
        - chain:
            id: B
            res_index: 200..210

When creating a .yaml design specification, you must use the correct residue indexing:

CRITICAL: All residue indices must start at 1 and use the canonical mmcif residue index label_asym_id. Do not use auth_asym_id (the author residue index).

To verify the correct index, open your mmcif file in Mol* and hover over a residue. The index shown in the bottom right is the label_asym_id you should use in your YAML file.

To use Docker, build the image and run it with volume mounts for your work directory, cache, and examples.

Build the image:

docker build -t boltzgen .

Run an example:

docker run --rm --gpus all -v "$(realpath workdir)":/workdir -v "$(realpath cache)":/cache -v "$(realpath example)":/example boltzgen \
    boltzgen run /example/vanilla_protein/1g13prot.yaml --output /workdir/test \
 	--protocol protein-anything \
  	--num_designs 2

Bake model weights into the image at build time:

docker build -t boltzgen:weights --build-arg DOWNLOAD_WEIGHTS=true .

Before running a full design pipeline, verify your .yaml specification using the check command. This ensures your target and binding sites are correctly defined.

1. Run the check:

   boltzgen check example/vanilla_peptide_with_target_binding_site/beetletert.yaml

2. Visualize: Open the resulting .mmcif file in a viewer like PyMOL, Chimera, or Mol* (https://molstar.org/viewer/).
3. Confirm: Ensure the binding site is highlighted in a different color than the rest of the target.

The boltzgen run command processes a .yaml design specification to produce ranked designs.

Key considerations:

• Model Weights: Downloads ~6GB to ~/.cache. Use --cache YOUR_PATH or set $HF_HOME to change this.
• Resuming: If interrupted, use the --reuse flag to restart without losing progress.
• Design Volume: For production, use --num_designs between 10,000 and 60,000. For testing, start with a small number like 50.
• Diversity: Use --budget to specify how many designs should be in the final diversity-optimized set.

Example command:

boltzgen run example/vanilla_protein/1g13prot.yaml \
  --output workbench/test_run \
  --protocol protein-anything \
  --num_designs 10 \
  --budget 2

The provided SLURM example requires manual configuration to match your specific cluster environment and analysis task. You must modify the following files:

• run.sh: The wrapper script used to submit or process jobs.
• run_job_array.slurm: The SLURM job array definition script.

Once modified, use bash run.sh submit to start the generation phase and bash run.sh process to execute the merge and filtering phase.

For complex workflows, you can separate configuration generation from execution using configure and execute.

1. Configure: Use boltzgen configure to create a directory of configuration files based on a design spec without running the pipeline. This allows for manual editing of the generated configs.
2. Execute: Use boltzgen execute to run the pipeline using the files in the pre-configured directory.

This pattern is useful for fine-tuning parameters in a controlled environment before committing to a long run.

# 1. Generate configuration files
boltzgen configure example/cyclotide/3ivq.yaml \
  --output workbench/test-peptide-protein \
  --protocol peptide-anything \
  --num_designs 2 \
  --reuse

# 2. Run the pre-configured workflow
boltzgen execute workbench/test-peptide-protein

For a managed environment, follow these steps:

1. Install Miniconda for your OS (Windows, macOS, or Linux).
2. Create a Python 3.12 environment named bg:

   conda create -n bg python=3.12

3. Activate the environment (required for every new terminal session):

   conda activate bg

4. Install BoltzGen:

   pip install boltzgen

Alternatively, to install an editable version from source:

pip install -e .

BoltzGen uses .yaml files to define design specifications, including protein sequences, ligands, and target structures.

CRITICAL: Residue Indexing All residue indices must use the canonical mmCIF label_asym_id (starting at 1). Do NOT use the auth_asym_id (author residue index).

Verification Workflow

1. Construct your .yaml file.
2. Run the check command to validate the specification:

   boltzgen check path/to/your_spec.yaml

3. Open the resulting .mmcif file in a viewer (e.g., PyMOL, Chimera, or Mol*). The binding site should be visually distinct from the rest of the target.

File Paths All file references (e.g., to .cif files) inside the YAML are interpreted relative to the directory containing the YAML file.

boltzgen check example/vanilla_peptide_with_target_binding_site/beetletert.yaml