# calvin-zcx/moflow architecture

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

- Interactive diagram: https://gitdiagram.com/calvin-zcx/moflow
- Repository: https://github.com/calvin-zcx/moflow

## Overview

##### Project Type & Purpose
- MoFlow is a deep learning project focused on the generative modeling of molecular graphs using invertible flow architectures.
- The project involves data preprocessing (for handling molecular datasets like QM9 and ZINC250K), model training using specialized invertible flow techniques (including coupling layers and Glow variants), generation via reconstruction, random sampling, and interpolation, and finally property optimization (e.g., QED and plogp optimization).

##### File Structure
- At the top level, you see configuration files (.idea, License.md, README.md) and two main directories:
- The "data" directory contains Python modules for:
▪ Data loading (data_loader.py)
▪ Preprocessing (data_preprocess.py)
▪ Parsing and transforming datasets (data_frame_parser.py, transform_qm9.py, transform_zinc250k.py)
▪ Converting SMILES to graphs (smile_to_graph.py)
▪ Relevant data files (CSV and JSON files).
- The "mflow" directory contains the core modeling code:
▪ "models" subdirectory defines various neural network model components (basic, coupling, glow, hyperparams, and utility functions).
▪ "utils" subdirectory includes supporting modules (environment setup, model utilities, molecular metrics, timing, etc.).
▪ Stand-alone scripts for training (train_model.py), generation (generate.py), and property optimization (optimize_property.py).
▪ A “fig” directory for saving figures from experiments (e.g., interpolation outputs and optimization results).
- This clear separation indicates an architecture that divides pre-processing, model definition/training, and inference/optimization.

##### README for Additional Insights
- The README explains installation steps, pre-processing commands, training commands (for different datasets), and how to run various experiments (reconstruction, random generation, interpolation, and molecular optimization).
- It provides command-line examples that imply a pipeline where the output from training (model snapshots, hyperparameters) is fed into generation and optimization scripts.
- It outlines details on experimental configuration (e.g., setting batch sizes, temperature, interpolation parameters) that are key to understanding the system's data flow and control paths.

##### Relationships and Data Flow
– From raw molecular data → Data Preprocessing.
– From Preprocessing → Model Training.
– From Model Training → Generation (for reconstruction, random sampling, and interpolation).
– From Generation → Property Optimization (when optimized output is needed).
- Optionally, include external dependency notes (e.g., PyTorch powering the training, RDKit for chemical informatics).

##### Architectural Patterns & Design Principles
- Modular design: Each component (data processing, training, inference, optimization) is separate and can be worked on independently.
- Command-line driven pipeline: The README scripts illustrate a clear, linear workflow.
- Reusability and extensibility: The project is built such that new datasets or additional property predictors can be integrated.
- Use appropriate designs such as functional separation (separating model code from utilities) and layered architecture (data, model, inference, optimization).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Raw Molecular Data
    RAW["Raw Molecular Data"]:::raw

    %% Data Preprocessing & Input Module
    subgraph "Data Preprocessing"
        DP1["Data Loader"]:::datamodule
        DP2["Data Preprocessor"]:::datamodule
        DP3["Graph Transformer (SMILES to Graph)"]:::datamodule
        DP4["Data Transformation (QM9)"]:::datamodule
        DP5["Data Transformation (ZINC250K)"]:::datamodule
        DP6["Data Parsing"]:::datamodule
    end

    %% Model Architecture & Training Module
    subgraph "Model Training"
        subgraph "Invertible Flow Model"
            MT_A["Basic Model"]:::model
            MT_B["Coupling Layers"]:::model
            MT_C["Glow Model"]:::model
            MT_D["Model Integration"]:::model
        end
        MT_E["Hyperparameter Configuration"]:::model
        MT_F["Training Engine"]:::model
    end

    %% Generation & Inference Module
    subgraph "Generation/Inference"
        GI1["Reconstruction"]:::inference
        GI2["Random Sampling"]:::inference
        GI3["Interpolation"]:::inference
        GI4["Generation Script"]:::inference
    end

    %% Molecular Property Optimization Module
    subgraph "Optimization"
        OP1["Property Predictor Training"]:::optimization
        OP2["Constrained/Unconstrained Optimization"]:::optimization
        OP3["Optimization Script"]:::optimization
    end

    %% Visualization & Evaluation
    subgraph "Visualization & Results"
        VR1["Experimental Figures & Plots"]:::visualization
    end

    %% Data Flow Connections
    RAW -->|"raw_data"| DP1
    RAW -->|"raw_data"| DP2
    RAW -->|"raw_data"| DP3
    RAW -->|"raw_data"| DP4
    RAW -->|"raw_data"| DP5
    RAW -->|"raw_data"| DP6

    %% From Data Preprocessing to Model Training
    DP1 -->|"preprocessed_data"| MT_F
    DP2 -->|"preprocessed_data"| MT_F
    DP3 -->|"preprocessed_data"| MT_F
    DP4 -->|"preprocessed_data"| MT_F
    DP5 -->|"preprocessed_data"| MT_F
    DP6 -->|"preprocessed_data"| MT_F

    %% Within Model Training, connecting invertible model to hyperparameters & training engine
    MT_A --- MT_B
    MT_B --- MT_C
    MT_C --- MT_D
    MT_D -->|"model_details"| MT_E
    MT_E -->|"configured_model"| MT_F

    %% From Model Training to Generation/Inference
    MT_F -->|"trained_checkpoint"| GI4
    MT_F -->|"trained_checkpoint"| GI1
    MT_F -->|"trained_checkpoint"| GI2
    MT_F -->|"trained_checkpoint"| GI3

    %% From Generation/Inference to Optimization
    GI4 -->|"generated_samples"| OP2
    GI1 -->|"generated_samples"| OP1
    GI2 -->|"generated_samples"| OP1
    GI3 -->|"generated_samples"| OP1

    %% From Generation/Inference & Optimization to Visualization
    GI4 -->|"inference_results"| VR1
    OP2 -->|"optimized_outputs"| VR1

    %% Click Events for Data Preprocessing Components
    click DP1 "https://github.com/calvin-zcx/moflow/blob/master/data/data_loader.py"
    click DP2 "https://github.com/calvin-zcx/moflow/blob/master/data/data_preprocess.py"
    click DP3 "https://github.com/calvin-zcx/moflow/blob/master/data/smile_to_graph.py"
    click DP4 "https://github.com/calvin-zcx/moflow/blob/master/data/transform_qm9.py"
    click DP5 "https://github.com/calvin-zcx/moflow/blob/master/data/transform_zinc250k.py"
    click DP6 "https://github.com/calvin-zcx/moflow/blob/master/data/data_frame_parser.py"

    %% Click Events for Model Training Components
    click MT_A "https://github.com/calvin-zcx/moflow/blob/master/mflow/models/basic.py"
    click MT_B "https://github.com/calvin-zcx/moflow/blob/master/mflow/models/coupling.py"
    click MT_C "https://github.com/calvin-zcx/moflow/blob/master/mflow/models/glow.py"
    click MT_D "https://github.com/calvin-zcx/moflow/blob/master/mflow/models/model.py"
    click MT_E "https://github.com/calvin-zcx/moflow/blob/master/mflow/models/hyperparams.py"
    click MT_F "https://github.com/calvin-zcx/moflow/blob/master/mflow/train_model.py"

    %% Click Events for Generation & Inference Module
    click GI4 "https://github.com/calvin-zcx/moflow/blob/master/mflow/generate.py"

    %% Click Events for Optimization Module
    click OP3 "https://github.com/calvin-zcx/moflow/blob/master/mflow/optimize_property.py"

    %% Click Event for Visualization & Evaluation
    click VR1 "https://github.com/calvin-zcx/moflow/tree/master/mflow/fig"

    %% Styles
    classDef raw fill:#F5B7B1,stroke:#333,stroke-width:1px;
    classDef datamodule fill:#FAD7A0,stroke:#333,stroke-width:1px;
    classDef model fill:#AED6F1,stroke:#333,stroke-width:1px;
    classDef inference fill:#D2B4DE,stroke:#333,stroke-width:1px;
    classDef optimization fill:#F9E79F,stroke:#333,stroke-width:1px;
    classDef visualization fill:#ABEBC6,stroke:#333,stroke-width:1px;
```
