# deepgraphlearning/confgf architecture

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

- Interactive diagram: https://gitdiagram.com/deepgraphlearning/confgf
- Repository: https://github.com/deepgraphlearning/confgf

## Overview

##### Project type and purpose
- This is a research-oriented Python library and command-line toolkit for molecular conformation generation using graph neural networks (the ConfGF model).
- It provides data preprocessing, model definition, training, generation, evaluation, and visualization scripts.

##### File structure
Top-level layout
- assets/            → static images
- config/            → experiment YAMLs for different datasets (qm9, drugs, iso17)
- confgf/            → core library package
- dataset/        → Dataset classes and loading logic
- layers/         → Graph network layer implementations (common, GIN)
- models/         → Model definitions (ScoreNet)
- runner/         → Orchestration of training and generation loops
- utils/          → Utility code (chemistry, torch helpers, metrics)
- script/            → CLI entry points (train.py, gen.py, processing scripts, evaluation scripts)
- setup.py, env.yml  → installation and environment setup

##### README for additional insights
- ConfGF uses PyTorch and PyTorch Geometric for GNNs, RDKit for chemistry operations.
- Workflow stages: data preprocessing → model training → conformation generation → evaluation → visualization.

a. Main components
1. Data Ingestion & Preprocessing
- script/process_*.py
- confgf.dataset
- Input: raw GEOM/ISO17 files
- Output: pickled dataset files
2. Configuration Loader
- config/*.yml
- easydict or custom loader in runner
3. Training Runner
- script/train.py → confgf.runner.default_runner
- Uses confgf.models.ScoreNet and confgf.layers
- Reads preprocessed data via confgf.dataset
- Writes model checkpoints
4. Generation Runner
- script/gen.py → confgf.runner.default_runner (generation mode)
- Loads checkpoints, generates conformations
5. Evaluation
- script/get_task1_results.py, get_task2_results.py
- confgf.utils.evaluation computes COV/MAT/MMD
6. Visualization
- scripts or user code using PyMol and RDKit via confgf.utils.chem
b. Relationships & interactions
- Runners invoke dataset loaders, model builders, training loops
- Trainer outputs checkpoints → Generator inputs checkpoints
- Generator produces output conformations → Evaluator measures quality
c. Architectural patterns
- Modular Python package dividing concerns (dataset, model, runner, utils)
- Configuration-driven design (YAML)
- CLI scripts as thin wrappers invoking core library
d. Key technologies
- Python, PyTorch, PyTorch Geometric, RDKit
- YAML configs, Conda environment

##### Essential architectural elements to capture
- Separation between core library (confgf/) and CLI scripts (script/)
- Configuration driving behavior (config/*.yml)
- Data flow from raw files through preprocessing to model input
- Control flow in runner coordinating model, data, and training/generation loops
- Output artifacts: checkpoints, generated conformations, evaluation metrics

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Raw Data and Preprocessing
    RawData[/"Raw GEOM/ISO17 Files"/]:::data
    subgraph "Preprocessing" 
        direction TB
        ProcessGEOM["process_GEOM_dataset.py"]:::script
        ProcessISO17["process_iso17_dataset.py"]:::script
        DatasetModule["confgf.dataset"]:::core
        PickledData[(Pickled Dataset)]:::dataStore
    end
    RawData -->|preprocess| ProcessGEOM
    RawData -->|preprocess| ProcessISO17
    ProcessGEOM --> DatasetModule
    ProcessISO17 --> DatasetModule
    DatasetModule --> PickledData

    %% Configuration
    subgraph "Configuration" 
        direction TB
        ConfigQM9["qm9_default.yml"]:::config
        ConfigDrugs["drugs_default.yml"]:::config
        ConfigIso17["iso17_default.yml"]:::config
    end

    %% Training
    subgraph "Training" 
        direction TB
        TrainScript["train.py"]:::script
        RunnerTrain["default_runner"]:::core
        ScoreNetTrain["confgf.models.ScoreNet"]:::core
        LayersCommon["confgf.layers.common"]:::core
        LayersGIN["confgf.layers.gin"]:::core
        Checkpoints[(Model Checkpoints)]:::dataStore
    end
    ConfigQM9 -->|load| TrainScript
    ConfigDrugs -->|load| TrainScript
    ConfigIso17 -->|load| TrainScript
    PickledData -->|input| TrainScript
    TrainScript --> RunnerTrain
    RunnerTrain --> ScoreNetTrain
    RunnerTrain --> LayersCommon
    RunnerTrain --> LayersGIN
    ScoreNetTrain --> Checkpoints
    LayersCommon --> Checkpoints
    LayersGIN --> Checkpoints

    %% Generation
    subgraph "Generation" 
        direction TB
        GenScript["gen.py"]:::script
        RunnerGen["default_runner"]:::core
        ScoreNetGen["confgf.models.ScoreNet"]:::core
        GeneratedConfs[(Generated Conformations)]:::dataStore
    end
    ConfigQM9 -->|load| GenScript
    ConfigDrugs -->|load| GenScript
    ConfigIso17 -->|load| GenScript
    Checkpoints -->|load| GenScript
    GenScript --> RunnerGen
    RunnerGen --> ScoreNetGen
    ScoreNetGen --> GeneratedConfs

    %% Evaluation
    subgraph "Evaluation" 
        direction TB
        EvalTask1["get_task1_results.py"]:::script
        EvalTask2["get_task2_results.py"]:::script
        EvalRDKit["get_rdkit_results.py"]:::script
        EvalModule["confgf.utils.evaluation"]:::core
        Metrics[(COV/MAT/MMD Metrics)]:::dataStore
    end
    GeneratedConfs -->|evaluate| EvalTask1
    GeneratedConfs -->|evaluate| EvalTask2
    GeneratedConfs -->|evaluate| EvalRDKit
    EvalTask1 --> EvalModule
    EvalTask2 --> EvalModule
    EvalRDKit --> EvalModule
    EvalModule --> Metrics

    %% Visualization
    subgraph "Visualization" 
        direction TB
        ChemUtils["confgf.utils.chem"]:::core
        Assets["assets"]:::data
    end
    GeneratedConfs --> ChemUtils
    ChemUtils --> Assets

    %% External Dependencies
    subgraph "External Libraries"
        direction TB
        PyTorch[(PyTorch & PyG)]:::external
        RDKit[(RDKit)]:::external
    end
    RunnerTrain --> PyTorch
    RunnerGen --> PyTorch
    ChemUtils --> RDKit

    %% Click Events
    click ProcessGEOM "https://github.com/deepgraphlearning/confgf/blob/main/script/process_GEOM_dataset.py"
    click ProcessISO17 "https://github.com/deepgraphlearning/confgf/blob/main/script/process_iso17_dataset.py"
    click DatasetModule "https://github.com/deepgraphlearning/confgf/blob/main/confgf/dataset/dataset.py"
    click ConfigQM9 "https://github.com/deepgraphlearning/confgf/blob/main/config/qm9_default.yml"
    click ConfigDrugs "https://github.com/deepgraphlearning/confgf/blob/main/config/drugs_default.yml"
    click ConfigIso17 "https://github.com/deepgraphlearning/confgf/blob/main/config/iso17_default.yml"
    click TrainScript "https://github.com/deepgraphlearning/confgf/blob/main/script/train.py"
    click RunnerTrain "https://github.com/deepgraphlearning/confgf/blob/main/confgf/runner/default_runner.py"
    click ScoreNetTrain "https://github.com/deepgraphlearning/confgf/blob/main/confgf/models/scorenet.py"
    click LayersCommon "https://github.com/deepgraphlearning/confgf/blob/main/confgf/layers/common.py"
    click LayersGIN "https://github.com/deepgraphlearning/confgf/blob/main/confgf/layers/gin.py"
    click GenScript "https://github.com/deepgraphlearning/confgf/blob/main/script/gen.py"
    click RunnerGen "https://github.com/deepgraphlearning/confgf/blob/main/confgf/runner/default_runner.py"
    click ScoreNetGen "https://github.com/deepgraphlearning/confgf/blob/main/confgf/models/scorenet.py"
    click EvalTask1 "https://github.com/deepgraphlearning/confgf/blob/main/script/get_task1_results.py"
    click EvalTask2 "https://github.com/deepgraphlearning/confgf/blob/main/script/get_task2_results.py"
    click EvalRDKit "https://github.com/deepgraphlearning/confgf/blob/main/script/get_rdkit_results.py"
    click EvalModule "https://github.com/deepgraphlearning/confgf/blob/main/confgf/utils/evaluation.py"
    click ChemUtils "https://github.com/deepgraphlearning/confgf/blob/main/confgf/utils/chem.py"
    click Assets "https://github.com/deepgraphlearning/confgf/tree/main/assets/"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef script fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef config fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
    classDef dataStore fill:#E1BEE7,stroke:#6A1B9A,stroke-width:1px
    classDef data fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#E65100,stroke-width:1px
```
