How junjie-zhu/idpfold works
1. Overall shape
IDPFold is a PyTorch Lightning project wrapped in Hydra configuration. The repository is organized around two executable entrypoints, src/train.py for model training and src/eval.py for ensemble generation/evaluation, with src/read_seqs.py handling sequence preprocessing. The codebase is aimed at protein conformation generation from sequence, specifically intrinsically disordered proteins.
2. Top-level workflow
The main data flow is: FASTA sequence input → sequence embedding extraction with ESM → model inference or training data loading → diffusion-based structure sampling → output analysis/metrics/checkpoints. The repo is built to support both offline training on curated protein datasets and standalone inference from user-provided sequences.
3. Configuration and experiment management
The configs/ tree is the control plane. Hydra config groups cover data, model, trainer, logging, callbacks, paths, debugging, and hyperparameter search. This means most runtime behavior is selected declaratively rather than hardcoded, and the architecture is split between reusable Python modules and experiment-specific YAML composition.
4. Data ingestion boundary
src/data/ contains the dataset and Lightning datamodule layer. src/data/components/dataset.py likely defines dataset objects, while src/data/protein_datamodule.py bridges raw protein data into Lightning-ready loaders. The config files configs/data/protein.yaml and configs/data/sampling.yaml suggest separate paths for training data versus sampling/inference data.
5. Sequence preprocessing
src/read_seqs.py is a distinct preprocessing stage for input sequences. The README says it extracts sequence embeddings before inference, and the repo includes src/utils/esm_extract.py, indicating ESM is used as an external sequence encoder. This is an important boundary: the model does not consume raw FASTA directly at inference time; it consumes derived sequence features.
6. Core generative model
src/models/diffusion_module.py is the main LightningModule for training and inference. It likely wraps the denoising network, loss computation, sampling logic, and optimizer configuration. The model stack is organized so that training orchestration lives in the diffusion module, while the neural architecture itself is split into subpackages.
7. Network and geometric modeling
src/models/net/ contains the denoising architecture, including denoising_ipa.py, ipa.py, and layers.py. This points to an invariant-point-attention style protein model operating over geometric representations. The model is structured to predict or refine 3D conformations rather than simple sequence labels.
8. Score/geometry subsystems
src/models/score/ holds frame, SO(3), and R3 scoring utilities. This indicates the diffusion process is geometry-aware and explicitly models rigid-body/rotation components. That separation matters architecturally: the network predicts denoising updates in protein coordinate space, and the score code handles the mathematical representation of rotations and translations.
9. Protein geometry and common utilities
src/common/ is the shared protein-geometry foundation: atom-level utilities, rigid transforms, residue constants, PDB handling, rotation helpers, and coordinate/data transforms. These modules are infrastructure for both training and inference, and they define the repository’s internal protein representation boundary.
10. Losses and training objectives
src/models/loss.py centralizes the optimization objective. In a diffusion-based protein generator, this typically combines geometric denoising terms and structural supervision. Keeping losses separate from the model module suggests the repo is designed for experimentation with alternative objectives.
11. Training, evaluation, and runtime orchestration
src/train.py and src/eval.py are the executable orchestration layers. They likely instantiate configs, datamodules, models, loggers, callbacks, and checkpoint loading. The structure follows the Lightning-Hydra template pattern, so training/eval are thin wrappers around reusable components rather than monolithic scripts.
12. Logging, checkpoints, and debugging
src/utils/ contains cross-cutting runtime support: checkpoint utilities, logging helpers, rich terminal output, tensor helpers, multiprocessing helpers, plotting, and instantiation helpers. The configs/logger/ and configs/callbacks/ folders show support for multiple experiment trackers and training callbacks such as checkpointing, early stopping, summaries, and progress bars.
13. External dependencies and environment
The repo depends materially on PyTorch, Lightning, Hydra, and fair-esm. It also uses an .env-based path setup initialized by initialize.py, which means dataset and artifact locations are treated as environment-specific infrastructure rather than hardcoded paths. This is important for diagramming deployment boundaries.
14. Artifact and output boundaries
The repository includes example input data in data/example.fasta and expects pretrained checkpoints from external storage. Outputs are likely generated conformational ensembles plus logs/metrics/plots depending on the selected logger and callbacks. So the system boundary is sequence-in plus checkpoint-in, ensemble-out, with optional experiment tracking side effects.
15. What is not in scope
There is no evidence of a web server, API service, or interactive UI in this repository. The architecture is a research/ML pipeline centered on offline training and inference, with the main components being preprocessing, geometric diffusion modeling, and experiment management.
Main entry points: diffusion_module.py Diffusion module · eval.py Eval · denoising_ipa.py Denoising IPA · train.py Train
Components 19
Control plane
Hydra configs and runtime entrypoints
Data flow
Sequence input, datasets, and dataloading
- Read seqs · Sequence preprocessing and feature preparation
src/read_seqs.py - ESM extract · Sequence embedding extraction using ESM
src/utils/esm_extract.py - Dataset · Protein dataset objects and sample assembly
src/data/components/dataset.py - Protein DM · Lightning data module bridging raw protein data to loaders
src/data/protein_datamodule.py
Model stack
Diffusion model, network, and geometric score components
- Diffusion module · Training, inference, loss, and sampling orchestration
src/models/diffusion_module.py - Losses · Diffusion and structural training objectives
src/models/loss.py - Denoising IPA · Main denoising architecture for protein structure refinement
src/models/net/denoising_ipa.py - IPA · Invariant-point-attention building blocks
src/models/net/ipa.py - Layers · Shared neural network layers and blocks
src/models/net/layers.py - Frame score · Rigid-frame scoring utilities
src/models/score/frame.py - R3 score · Translation-space scoring utilities
src/models/score/r3.py - SO3 score · Rotation-space scoring utilities
src/models/score/so3.py
Shared infra
Protein geometry, utilities, and runtime support
- Protein core · Atom, residue, rigid-body, and coordinate utilities
src/common/protein.py - Rigid utils · Rigid transforms and rotation helpers
src/common/rigid_utils.py - Transforms · Coordinate and data transformation helpers
src/common/data_transforms.py - Runtime utils · Logging, checkpoints, plotting, instantiation, and multiprocessing helpers
src/utils
Connections 22
- Configs → Train: configures · Hydra composes training runtime settings
- Configs → Eval: configures · Hydra composes evaluation runtime settings
- Read seqs → ESM extract: uses · Preprocessing derives embeddings from sequences
- Read seqs → Eval: feeds · Sequence preprocessing prepares inference inputs
- ESM extract → Protein DM: features · Embedded sequence features enter the data pipeline
- Dataset → Protein DM: loads · Datasets are wrapped by the Lightning data module
- Protein DM → Train: provides data · Training consumes batches from the data module
- Protein DM → Eval: provides data · Evaluation and sampling consume prepared inputs
- Train → Diffusion module: instantiates · Training creates the Lightning diffusion module
- Eval → Diffusion module: loads · Evaluation restores the model for inference
- Diffusion module → Denoising IPA: wraps · The Lightning module delegates to the denoising network
- Diffusion module → Losses: optimizes · Training objective is computed from diffusion losses
- Denoising IPA → IPA: builds on · The denoiser is centered on IPA blocks
- Denoising IPA → Layers: uses · Network internals reuse shared layers
- Diffusion module → Frame score: scores · Geometric diffusion uses frame-space scoring
- Diffusion module → R3 score: scores · Geometric diffusion uses translation scoring
- Diffusion module → SO3 score: scores · Geometric diffusion uses rotation scoring
- Denoising IPA → Protein core: operates on · The model consumes protein geometry primitives
- Protein core → Rigid utils: relies on · Core geometry uses rigid transform math
- Protein core → Transforms: relies on · Protein representations are transformed for modeling
- Train → Runtime utils: uses · Training uses logging, checkpoints, and instantiation helpers
- Eval → Runtime utils: uses · Evaluation uses logging and output utilities