# pineapplek/ed2mol architecture

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

- Interactive diagram: https://gitdiagram.com/pineapplek/ed2mol
- Repository: https://github.com/pineapplek/ed2mol

## Overview

##### Project type and purpose
- This is a command-line, Python-based molecular-generation pipeline (“ED2Mol”) that stitches together data-processing, ML inference, fragment libraries, and docking to generate or optimize small molecules in a given binding pocket. The `Generate.py` script orchestrates everything via a YAML config (in configs/).

##### Main components of the system
a. CLI & Configuration
- Generate.py (entry point)
- configs/*.yml (denovo.yml, hitopt.yml)
b. Data & Resource Layer
- cases/ (example PDB and core SDF for testing)
- frag_lib/ (static fragment and core libraries: Cores.sdf, Frags.sdf)
c. Preprocessing & Feature Extraction
- utils/DataProcessing.py (load PDB, prepare grids/maps)
- utils/EDExtract.py (extract electron-density features)
- utils/CorePlacement.py (position core in pocket)
d. Model Inference
- models/ED_Generator.py (ED‐guided generative model)
- models/Mol_Generator.py (fragment‐extension model)
- models/EGNN_Block.py (graph neural network layers)
e. Scoring & Post-processing
- utils/Score.py (calls smina.static for docking/scoring)
- utils/Utils.py (common helpers, I/O)
f. Output
- output_dir as specified in configs/ → generated molecules, logs

##### Relationships & Data Flow
1) CLI reads config →
2) DataProcessing loads receptor PDB → creates grid/ED map →
3) EDExtract pulls out features → CorePlacement anchors seed core →
4) ED_Generator proposes electron-density–driven fragment candidates →
5) Mol_Generator assembles full molecules using frag_lib →
6) Score docks & ranks candidates via smina.static →
7) Utils writes final molecules to disk

##### Architectural patterns & design principles
- Pipeline pattern: a clear sequence of steps, each module has single responsibility
- Config-driven orchestration: Generate.py dispatches tasks based on YAML
- Modular ML inference: separate models folder for each network
- External tool integration: smina.static called as subprocess for docking

##### Relevant technologies & frameworks
- Python 3.8
- PyTorch 1.13.1 + PyTorch Geometric 2.3.0
- RDKit for chemistry I/O
- Biopython, cctbx for structural biology
- smina for docking
- Conda/mamba for environment management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration"
        direction TB
        DenovoConfig["denovo.yml"]:::config
        HitoptConfig["hitopt.yml"]:::config
    end

    %% Entry Point
    Generate["Generate.py\n(entry point)"]:::io

    %% Data & Resource Layer
    Cases[(cases/)]:::io
    FragLib[(frag_lib/)]:::io

    %% Preprocessing & Feature Extraction
    DataProcessing["DataProcessing.py\n(load PDB, prepare grids)"]:::preprocessing
    EDExtract["EDExtract.py\n(extract ED features)"]:::preprocessing
    CorePlacement["CorePlacement.py\n(position core)"]:::preprocessing

    %% Model Inference
    subgraph "ML Inference"
        direction TB
        ED_Generator["ED_Generator.py\n(ED-driven proposals)"]:::models
        Mol_Generator["Mol_Generator.py\n(fragment assembly)"]:::models
        EGNN_Block["EGNN_Block.py\n(GNN layers)"]:::models
    end

    %% Scoring & Post-processing
    Score["Score.py\n(docking & ranking)"]:::preprocessing
    Utils["Utils.py\n(common I/O helpers)"]:::io
    Smina["smina.static\n(docking engine)"]:::external

    %% Output
    Output[(output_dir)]:::io

    %% Data Flow
    DenovoConfig --> Generate
    HitoptConfig --> Generate
    Generate --> DataProcessing
    Cases --> DataProcessing
    DataProcessing --> EDExtract
    EDExtract --> CorePlacement
    CorePlacement --> ED_Generator
    ED_Generator --> Mol_Generator
    ED_Generator --> EGNN_Block
    Mol_Generator --> EGNN_Block
    Mol_Generator --> Score
    Utils --> Score
    Score --> Smina
    Score --> Output

    %% Click Events
    click DenovoConfig "https://github.com/pineapplek/ed2mol/blob/main/configs/denovo.yml"
    click HitoptConfig "https://github.com/pineapplek/ed2mol/blob/main/configs/hitopt.yml"
    click Generate "https://github.com/pineapplek/ed2mol/blob/main/Generate.py"
    click Cases "https://github.com/pineapplek/ed2mol/tree/main/cases/"
    click FragLib "https://github.com/pineapplek/ed2mol/tree/main/frag_lib/"
    click DataProcessing "https://github.com/pineapplek/ed2mol/blob/main/utils/DataProcessing.py"
    click EDExtract "https://github.com/pineapplek/ed2mol/blob/main/utils/EDExtract.py"
    click CorePlacement "https://github.com/pineapplek/ed2mol/blob/main/utils/CorePlacement.py"
    click ED_Generator "https://github.com/pineapplek/ed2mol/blob/main/models/ED_Generator.py"
    click Mol_Generator "https://github.com/pineapplek/ed2mol/blob/main/models/Mol_Generator.py"
    click EGNN_Block "https://github.com/pineapplek/ed2mol/blob/main/models/EGNN_Block.py"
    click Score "https://github.com/pineapplek/ed2mol/blob/main/utils/Score.py"
    click Utils "https://github.com/pineapplek/ed2mol/blob/main/utils/Utils.py"
    click Smina "https://github.com/pineapplek/ed2mol/blob/main/utils/smina.static"

    %% Styles
    classDef preprocessing fill:#D6E4F0,stroke:#1F497D,color:#1F497D;
    classDef models fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef io fill:#EEEEEE,stroke:#333333,color:#333333;
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef config fill:#F0F0F0,stroke:#000000,color:#000000;
```
