How bioinfomachinelearning/flowdock works
Project type and purpose
• FlowDock is a full-stack research codebase for generative protein–ligand docking and affinity prediction.
• Core technologies: PyTorch + PyTorch Lightning for model training, Hydra for configuration management, assorted bioinformatics tools (ESM2, ESMFold, US-align), and experiment tracking/logging frameworks (WandB, MLflow, Comet, TensorBoard, etc.).
Top-level structure (from the file tree)
• CLI entry points:
• flowdock/train.py (training)
• flowdock/eval.py (evaluation)
• flowdock/sample.py (inference/sampling)
• Configuration: configs/ (Hydra config groups: data, model, trainer, strategy, callbacks, logger, etc.)
• Core package: flowdock/
• flowdock/data (data modules & preprocessing scripts)
• flowdock/models (model definitions, loss, flow-matching modules)
• flowdock/utils (helper functions, logging utils, metric utils)
• Data storage: data/ (raw & preprocessed datasets), checkpoints/ (model weights)
• Supporting scripts, notebooks, Dockerfile, CI, Makefile, tests
Main components
a. Configuration Manager (Hydra)
• Loads YAML configs from configs/
• Injects settings into CLI scripts and instantiation of components
b. CLI Layer
• Entry points: train.py, eval.py, sample.py
• Parse CLI args → initialize Hydra → instantiate components
c. Data Pipeline
• Raw data (PDBBind, MOAD, DockGen, PLINDER…) in data/
• flowdock/data/components:
• sequence preparation → FASTA
• ESM2 embedding extraction
• ESMFold structure prediction
• apo-to-holo alignment (US-align)
• Datamodules (PyTorch Lightning DataModule) for batching and loading
d. Model + Training Engine
• flowdock/models/components: flow-matching modules, encoder, loss functions
• flowdock/models/flowdock_fm_module.py: LightningModule wrapping model forward, loss, optimizer, schedulers
• PyTorch Lightning Trainer: orchestrates training loop, validation, checkpointing
e. Callbacks & Loggers
• Hydra-configured callbacks: EarlyStopping, ModelCheckpoint, EMA, LR monitor, RichProgressBar, custom summaries
• Loggers: WandB, Comet, MLflow, TensorBoard, Neptune, CSV, etc.
f. Evaluation & Sampling
• eval.py: loads checkpoint + test DataModule → runs inference → collects metrics
• sample.py: loads checkpoint + prepares receptor/ligand inputs (single vs. batched) → runs generative sampler (VDODE, etc.) → outputs PDB trajectories + affinity estimates
g. Storage & Outputs
• Checkpoints (checkpoints/)
• Sampled structures (PDB files)
• Prediction metrics & plots (notebooks/)
Relationships & data flow
• CLI script → Hydra config → instantiate (DataModule, LightningModule, Trainer, Callbacks, Logger).
• DataModule reads raw data → applies preprocessing steps (ESM embeddings, ESMFold, alignment) → yields PyTorch batches.
• Trainer orchestrates forward/backward passes on model → uses callbacks to store checkpoints & track metrics via loggers.
• Eval pipeline mirrors train but with trainer.test(); metrics saved to disk / logger.
• Sample pipeline takes sequence + SMILES + optional template → model generates docking poses → writes output PDB files; logger optional.
Architectural patterns & design principles
• Modular separation: data, model, utils, configs, scripts
• Inversion of control via Hydra config
• Dependency injection: all components are hydra-instantiated
• PyTorch Lightning pattern: clear separation of data (DataModule), model logic (LightningModule), training loop (Trainer)
• Extensible logging & callback system (Hydra plugin pattern)