# jwohlwend/boltz architecture

> Architecture diagram of the GitHub repository jwohlwend/boltz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jwohlwend/boltz
- Repository: https://github.com/jwohlwend/boltz

## Overview

##### Project type and purpose
- Boltz is a Python-based biomolecular interaction modeling toolkit that provides both inference (structure & affinity prediction) and training pipelines. It exposes a CLI (`boltz predict` / `boltz train`) and a library (`src/boltz/...`) for data processing, modeling, and evaluation.

##### File structure
- Top level
- CLI entrypoint: `src/boltz/main.py`
- Library code: `src/boltz/data` (all data preprocessing, featurization, filtering, parsing, tokenization, sampling, writing) and `src/boltz/model` (layers, losses, modules, optim, potentials)
- Scripts:
– `scripts/process` (raw → processed dataset)
– `scripts/train` (configuration, training driver, asset lists)
– `scripts/eval` (evaluation driver, metric calculators)
- Examples (YAML input files) and docs (usage & architecture guidance)
- Config files: `pyproject.toml`, `scripts/process/requirements.txt`, YAML config under `scripts/train/configs`

##### README for additional insights
- Two main workflows:
- Inference (`boltz predict`), optionally contacting an MSA server, producing structure & affinity predictions
- Training (currently Boltz-1, soon Boltz-2), driven by YAML configs, outputting model weights & metrics
- Dependencies: Python, PyPI package `boltz`, optional external MSA server, RCSB mmCIF resources

Components & I/O:
1. User Interface (CLI / Python API)
- Input: `input_path` (YAML or directory of YAML)
- Output: prediction job submitted to pipeline
2. Input Parser & Validator (`src/boltz/data/parse/*.py`)
- Input: raw YAML → `ParsedSpec` objects
- Output: standardized object with molecule identifiers & prediction types
3. MSA Retrieval Service
- Input: sequence from `ParsedSpec`
- Output: MSA files (A3M) or `None` if disabled
4. Feature Construction (`src/boltz/data/feature/featurizer*.py`)
- Input: raw sequence + MSA
- Output: feature tensors (e.g. residue indices, pairwise features)
5. Model Inference (`src/boltz/model/modules` + `src/boltz/model/models/boltz*.py`)
- Input: feature tensors, model weights
- Output:
– Structure prediction (atom coordinates)
– Affinity outputs: `affinity_pred_value`, `affinity_probability_binary`
6. Post-Processing & Writer (`src/boltz/data/write/*.py`)
- Input: raw model outputs
- Output: PDB/mmCIF files, JSON summary with affinity fields
7. CLI Output
- Input: file paths + summary
- Output: console logs, result files in working directory

Components & I/O:
1. Raw Data Sources (PDB/mmCIF, FASTA, MSA directories)
- Input: external repositories (RCSB, local FASTA)
- Output: raw data files
2. Data Processing Scripts (`scripts/process/*.py`)
- Input: raw data files
- Output: processed dataset shards (serialized feature files)
3. Training Configuration (`scripts/train/configs/*.yaml`)
- Input: user-selected config (e.g. `full.yaml`, `confidence.yaml`, `structure.yaml`)
- Output: hyperparameters, data splits (`scripts/train/assets/*.txt`)
4. Training Driver (`scripts/train/train.py`)
- Input: processed dataset, config
- Output: training loop initialization
5. Data Loader & Sampler (`src/boltz/data/sample/*.py`)
- Input: processed dataset shards
- Output: batches of feature & label tensors
6. Model & Loss Computation (`src/boltz/model/modules` + `src/boltz/model/loss`)
- Input: batch tensors, model weights
- Output: loss values, gradients
7. Optimizer & Scheduler (`src/boltz/model/optim/*.py`)
- Input: gradients, hyperparameters
- Output: updated model weights (checkpoints)
8. Checkpoint & Metrics Logger
- Input: model weights, loss/accuracy metrics
- Output: saved checkpoints, TensorBoard logs, evaluation on validation set

##### Architectural patterns & design principles
- Modular layering: clear separation between data ingestion (`data/`), model definition & training (`model/`), and orchestration (CLI + `scripts/`).
- Pipeline pattern: streaming data through parse → feature → model → write stages.
- Config-driven via YAML for experiment reproducibility.
- Use of external services abstracted behind interfaces (e.g. MSA server, RCSB fetcher).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Inference Pipeline
    subgraph "Inference Pipeline"
        UI["UI (CLI / Python API)\n• Input: input_path\n• Output: job submission"]:::orchestration
        Parser["Input Parser & Validator\n• Input: raw YAML\n• Output: ParsedSpec objects"]:::preprocess
        MSA["MSA Retrieval Service\n• Input: sequence\n• Output: MSA files or None"]:::external
        Feature["Feature Construction\n• Input: sequence + MSA\n• Output: feature tensors"]:::preprocess
        Inference["Model Inference\n• Input: feature tensors + weights\n• Output: structure coords, affinity preds"]:::model
        Post["Post-Processing & Writer\n• Input: raw model outputs\n• Output: PDB/mmCIF, JSON summary"]:::preprocess
        CLIOut["CLI Output\n• Input: file paths + summary\n• Output: console logs, result files"]:::orchestration
    end

    UI --> Parser --> MSA --> Feature --> Inference --> Post --> CLIOut

    %% Training Pipeline
    subgraph "Training Pipeline"
        RawData["Raw Data Sources\n• Input: external repos\n• Output: raw data files"]:::external
        DataProc["Data Processing Scripts\n• Input: raw data files\n• Output: processed dataset shards"]:::preprocess
        Config["Training Configuration\n• Input: YAML config\n• Output: hyperparams, data splits"]:::orchestration
        TrainDrv["Training Driver\n• Input: processed dataset, config\n• Output: training init"]:::orchestration
        DataLoad["Data Loader & Sampler\n• Input: shards\n• Output: batches"]:::preprocess
        ModelComp["Model & Loss Computation\n• Input: batches, weights\n• Output: loss, gradients"]:::model
        Opt["Optimizer & Scheduler\n• Input: gradients, hyperparams\n• Output: updated weights"]:::model
        Check["Checkpoint & Metrics Logger\n• Input: weights, metrics\n• Output: checkpoints, logs"]:::orchestration
    end

    RawData --> DataProc --> TrainDrv
    Config --> TrainDrv
    TrainDrv --> DataLoad --> ModelComp --> Opt --> Check

    %% Click Events
    click UI "https://github.com/jwohlwend/boltz/blob/main/src/boltz/main.py"
    click Parser "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/parse/*.py"
    click MSA "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/msa/mmseqs2.py"
    click Feature "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/feature/featurizer.py"
    click Feature "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/feature/featurizerv2.py"
    click Inference "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/models/boltz1.py"
    click Inference "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/models/boltz2.py"
    click Inference "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/modules/*.py"
    click Post "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/write/*.py"
    click CLIOut "https://github.com/jwohlwend/boltz/blob/main/src/boltz/main.py"

    click RawData "https://github.com/jwohlwend/boltz/blob/main/scripts/process/ccd.py"
    click RawData "https://github.com/jwohlwend/boltz/blob/main/scripts/process/cluster.py"
    click RawData "https://github.com/jwohlwend/boltz/blob/main/scripts/process/mmcif.py"
    click RawData "https://github.com/jwohlwend/boltz/blob/main/scripts/process/msa.py"
    click RawData "https://github.com/jwohlwend/boltz/blob/main/scripts/process/rcsb.py"
    click DataProc "https://github.com/jwohlwend/boltz/blob/main/scripts/process/ccd.py"
    click DataProc "https://github.com/jwohlwend/boltz/blob/main/scripts/process/cluster.py"
    click DataProc "https://github.com/jwohlwend/boltz/blob/main/scripts/process/mmcif.py"
    click DataProc "https://github.com/jwohlwend/boltz/blob/main/scripts/process/msa.py"
    click DataProc "https://github.com/jwohlwend/boltz/blob/main/scripts/process/rcsb.py"
    click Config "https://github.com/jwohlwend/boltz/blob/main/scripts/train/configs/*.yaml"
    click TrainDrv "https://github.com/jwohlwend/boltz/blob/main/scripts/train/train.py"
    click DataLoad "https://github.com/jwohlwend/boltz/blob/main/src/boltz/data/sample/*.py"
    click ModelComp "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/modules/*.py"
    click ModelComp "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/loss/*.py"
    click Opt "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/optim/ema.py"
    click Opt "https://github.com/jwohlwend/boltz/blob/main/src/boltz/model/optim/scheduler.py"
    click Check "https://github.com/jwohlwend/boltz/blob/main/scripts/eval/aggregate_evals.py"
    click Check "https://github.com/jwohlwend/boltz/blob/main/scripts/eval/physcialsim_metrics.py"

    %% Styles
    classDef preprocess fill:lightgreen,stroke:#333,stroke-width:1px
    classDef model fill:lightblue,stroke:#333,stroke-width:1px
    classDef orchestration fill:orange,stroke:#333,stroke-width:1px
    classDef external fill:lightgray,stroke:#333,stroke-width:1px
```
