How sail-sg/gdpo works
Project type and purpose
• This is a research-oriented machine-learning framework (“Graph Diffusion Policy Optimization”) for graph generation tasks. It implements graph diffusion models optimized via reinforcement learning (GDPO), supporting arbitrary objectives (e.g., molecular docking scores). It provides pipelines for data preparation, model definition, RL training (PPO), generation, evaluation, and analysis.
File structure
Top-level directories and responsibilities:
• analysis: post-hoc analysis and visualization tools (Python + ORCA C++ bindings).
• configs: all experiment, dataset, model, and training hyperparameters (YAML) organized by subfolders.
• dataset: PyTorch/Lightning DataModule wrappers for various graph datasets (ZINC, MOSES, Planar, SBM, toy, protein docking).
• diffusion: core diffusion model logic (noise schedules, layers, distributions, extra feature support).
• model: neural nets (transformers, attention, diffusion-discrete, InfoMax modules, etc.).
• metrics: computation of training and graph/molecular evaluation metrics.
• scorer: external scoring interfaces (docking via QVina, SA score, receptor files, RDKit utilities).
Other files:
• main_train / main_ppo / main_generate / process.py: entry points for training, RL fine-tuning, generation, data processing.
• run_*.sh: convenience scripts for common experiments.
• environment.yml, requirements.txt: dependency specifications (Conda, pip).
Extract architectural insights from README
• Uses Hydra-style config overrides via CLI (bare “+experiment=…”).
• Supports multi-seed parallel runs.
• Builds on PyTorch Lightning for checkpointing and resume functionality.
• Requires external tools: RDKit, ORCA for quantum or molecular analysis, QVina for docking.
1. Configuration Manager (YAML + Hydra)
2. Data Pipeline
• Raw dataset sources (./dataset folder, downloads)
• Dataset loaders (dataset/*)
3. Model Components
• Diffusion model (diffusion/*)
• Neural network modules (model/*)
4. Reinforcement Learning Engine
• PPO trainer (main_ppo.py, PyTorch Lightning)
• Policy gradient wrapper (analysis/dist_helper.py)
5. Scoring & Reward Module
• Molecular scorer (scorer/*)
• ORCA integration (analysis/orca)
6. Evaluation & Metrics
• Generation pipeline (main_generate.py)
• Metrics calculators (metrics/*)
• Visualization & analysis (analysis/visualization.py)
7. Execution & Orchestration
• Shell scripts (run_*.sh)
• Process manager (process.py)
8. External Dependencies
• RDKit, QVina, ORCA, Conda environment
• Configuration Manager → Data Pipeline, Model Components, RL Engine (feeds hyperparameters)
• Data Pipeline → RL Engine (batches of graphs)
• RL Engine → Model Components (forward + backward passes)
• Model Components → Scoring Module (generated graphs → reward signals)
• Scoring Module → RL Engine (reinforcement signals)
• RL Engine → Checkpoint storage (outputs/)
• Evaluation & Metrics ← Model Components + Scoring Module + Data Pipeline (test mode)
• Visualization ← Evaluation & Metrics
c. Architectural patterns & principles
• Modular separation of concerns: data, model, training, scoring, analysis.
• Config-driven experiments (Hydra style): decouples code from hyperparameters.
• Plugin architecture for datasets, models, and scorers.
• Use of PyTorch Lightning for standardized training loops and checkpointing.
• Interoperability with C++ (ORCA) and CLI tools (QVina).
d. Key technologies & frameworks
• Python 3.x, PyTorch, PyTorch Lightning
• Hydra/YAML for configs
• RDKit for molecular graphs
• QVina / docking for reward computation
• ORCA (C++) for quantum calculations
• Conda for environment management