How jwohlwend/boltz works
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).