How mirunacrt/synflownet works
Project Type and Purpose
• SynFlowNet is a research-oriented machine learning framework that uses a GFlowNet model to generate novel, synthesizable molecules. Its purpose is to combine chemical reaction templates and available building blocks to explore molecule design.
• The README clearly mentions model training, reward functions (e.g., binding proxies, QED, docking), and the use of multiple data sources including reaction templates and docking data.
File Structure
• The code is organized in a “src/synflownet” directory with clearly separated submodules:
• /algo: Contains core algorithms (graph sampling, reaction sampling, soft Q-learning, trajectory balance) used for model training and inference.
• /data: Handles data preparation, precomputation of building block masks, and management of various docking datasets.
• /envs: Contains the definitions for environments (e.g., ReactionTemplateEnv, synthesis_building_env) used to simulate the chemical reaction processes.
• /models: Contains the implementation of the main GFlowNet model, notably the GraphTransformerSynGFN along with configuration and caching logic.
• /tasks: Defines tasks (especially ReactionTask) that govern reward calculation and training data sampling.
• /utils: Provides auxiliary modules that support conditioning, configuration management, multiprocessing, evaluation metrics, etc.
• Also included are directories related to hyperparameter optimization (hyperopt), documentation (docs), and installation/build management (setup.py, requirements, pyproject.toml).
Key Components of the System
a. Data & Preprocessing:
• Data sources: Reaction templates, building block files, and docking datasets.
• Preprocessing scripts: Found under the building_blocks subdirectory, these include cleaning, duplicate removal, subsampling, and mask precomputation.
b. Environment & Context:
• The ReactionTemplateEnv and its corresponding Context module handle the simulation of chemical reactions as a Markov Decision Process (MDP). They are responsible for state transitions, mapping actions, and creating required masks.
c. Task & Reward:
• The ReactionTask class encapsulates reward functions and sampling strategies which guide molecule generation (e.g., via docking scores, QED, etc.).
d. Model (Policy) & Action Sampling:
• The GraphTransformerSynGFN in models module, together with ActionCategorical, parameterizes the policy. It computes action probabilities, especially when continuous action embeddings are used.
e. Training Loop:
• The ReactionTrainer class (and scripts such as online_trainer.py) instantiates the environment, model, and task, while managing the training iterations.
f. Additional Components:
• Supporting modules for hyperparameter optimization (with WandB demos) and optional GPU-accelerated Vina integration for docking rewards.
Relationships and Interactions
• Data flows from the data preparation stage (e.g., building block masks, chemical templates) into the environment.
• The environment (ReactionTemplateEnv) receives inputs and defines state transitions which are interpreted by the model (GraphTransformerSynGFN).
• The ActionCategorical module handles probabilistic action choices based on the model’s outputs.
• The ReactionTask class computes rewards based on the current state (e.g., a synthesized molecule) and informs the training loop.
• The ReactionTrainer coordinates the training by linking together the environment, model, and reward computations.
• Optional external modules (like GPU-accelerated Vina) are used to calculate docking scores when needed.
Architectural Patterns and Design Principles
• Clear separation of concerns is maintained across data handling, environment simulation, model definition, and task reward computation.
• Modularity: Each aspect (data, environment, model, task, training) is organized in separate directories, making the system extensible and easy to maintain.
• Configurability: Numerous configuration files (e.g., config.py files in different modules) indicate a design that allows tuning parameters across different parts of the system.
Final Steps for the Principal Software Engineer
• Configuration, utility, and optional modules to give a complete view of how various functionalities interoperate within the SynFlowNet framework.