How igashov/difflinker works
Project Type and Purpose
• DiffLinker is an open-source ML tool for 3D-conditional molecular linker design.
• It implements an equivariant diffusion model (EDM) and a size-prediction GNN, orchestrated with PyTorch Lightning.
• It provides data preparation pipelines, model training, inference (generation), and evaluation scripts.
High-Level Architectural Components
a. Data Layer
• case_studies/ : example fragment–protein datasets
• data/ : raw data pipelines (CASF, GEOM, pockets, ZINC)
• configs/ : YAML configs driving training/inference parameters
b. Preprocessing & Dataset
• data/** scripts → clean, fragment, generate conformers, split datasets → output .pt files
• src/datasets.py → PyTorch Dataset/DataModule definitions
• src/delinker_utils/ → utility functions (fragmentation, scoring, RDKit/OpenBabel wrappers)
c. Model Core
• src/edm.py → diffusion model implementation
• src/egnn.py → equivariant GNN layers
• src/linker_size_lightning.py & src/lightning.py → LightningModules for diffusion & size prediction
• src/delinker.py → high-level model wrapper combining EDM + EGNN
• src/molecule_builder.py → reconstructs 3D molecules from model output
d. Training & Validation
• train_difflinker.py → trains diffusion model using configs/*.yml
• train_size_gnn.py → trains GNN for linker size prediction
• environment.yml → reproducible conda environment
• logs/, models/ directories for checkpoints & TensorBoard/WandB logs
e. Inference & Sampling
• generate.py, generate_with_pocket.py, generate_with_protein.py → entry points for linker generation
• sample.py, sample_trajectories.py → batch sampling & trajectory saving
• run_obabel.py, reformat_data_obabel.py → OpenBabel calls for format conversions
f. Evaluation & Metrics
• compute_metrics.py → computes metrics (recovery, validity, novelty, etc.)
• resources/ → ground-truth references & evaluation CSVs
Relationships & Data Flow
• Raw data → data/ preprocessing scripts → saved .pt datasets
→ src/datasets.py wraps them into DataLoader
→ train scripts feed DataLoader into LightningModules → model checkpoints
• Inference scripts load checkpoints + config → call model wrapper → generate 3D coordinates → molecule_builder
→ optional OpenBabel reformat → saved output files
• Evaluation scripts consume generated samples + ground-truth → compute metrics
Architectural Patterns & Design Principles
• Modular separation: data preparation, model definition, training logic, inference, evaluation
• Config-driven workflows: all hyperparameters & file paths in YAML or CLI args
• Reusable utilities: src/delinker_utils houses shared functions (fragmentation, scoring)
• PyTorch Lightning organizes training/validation loops and checkpointing
• Clear I/O contracts: each script reads from defined folders (datasets/, models/, samples/)