# mirunacrt/synflownet architecture

> Architecture diagram of the GitHub repository mirunacrt/synflownet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mirunacrt/synflownet
- Repository: https://github.com/mirunacrt/synflownet

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DS["Data Source & Preprocessing"]:::data
    ENV["Environment & Context"]:::env
    RT["Reward Calculation (ReactionTask)"]:::reward
    MODEL["GFlowNet Model (GraphTransformerSynGFN)"]:::model
    TRAIN["Training Coordinator (ReactionTrainer)"]:::train
    VINA["Optional External - Docking (GPU Vina)"]:::external

    DS -->|"datainput"| ENV
    ENV -->|"state"| MODEL
    ENV -->|"state"| RT
    MODEL -->|"policyupdate"| TRAIN
    RT -->|"rewardsignal"| TRAIN
    VINA -->|"dockingscore"| RT
    TRAIN -->|"update"| ENV

    click DS "https://github.com/mirunacrt/synflownet/tree/main/src/synflownet/data/building_blocks"
    click ENV "https://github.com/mirunacrt/synflownet/blob/main/src/synflownet/envs/synthesis_building_env.py"
    click RT "https://github.com/mirunacrt/synflownet/blob/main/src/synflownet/tasks/reactions_task.py"
    click MODEL "https://github.com/mirunacrt/synflownet/blob/main/src/synflownet/models/graph_transformer.py"
    click TRAIN "https://github.com/mirunacrt/synflownet/blob/main/src/synflownet/online_trainer.py"
    click VINA "https://github.com/mirunacrt/synflownet/blob/main/src/synflownet/utils/gpu_vina.py"

    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef env fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef reward fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef model fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef train fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef external fill:#F7DC6F,stroke:#B9770E,stroke-width:2px,shape:diamond;
```
