# alexarnimueller/smiles_generator architecture

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

- Interactive diagram: https://gitdiagram.com/alexarnimueller/smiles_generator
- Repository: https://github.com/alexarnimueller/smiles_generator

## Overview

##### Project Type and Purpose
- This is a Python-based command-line generative AI tool for de novo molecular design.
- It ingests molecular SMILES data, trains an LSTM-based RNN (via TensorFlow 1.14) to learn SMILES syntax, then samples new molecules and analyzes them using RDKit (and optionally FCD).

##### Main Architectural Components
a. Data Layer
- Raw SMILES datasets (data/*.csv)
- Generated SMILES (generated/*.csv)
b. Preprocessing Module
- preprocess.py: tokenizes & cleans SMILES
- descriptors.py: computes molecular descriptors (via RDKit)
c. Model Definition
- model.py: defines the LSTM RNN architecture and loss/optimizer
d. Training Pipelines
- train.py: standard training loop, checkpoint saving
- finetune.py: transfer-learning on new datasets
e. Sampling Module
- sample.py: loads a checkpoint, generates new SMILES strings at configurable temperature/fragments
- generator.py: core sampling routines
f. Analysis Module
- .py: computes fingerprint metrics (e.g., ECFP4 similarity) and optional FCD scores
- plotting.py: visualization of distributions and metrics
g. Utilities
- utils.py: shared helper functions (file I/O, logging, seed management)

##### Relationships and Data Flow
1) User provides raw SMILES CSV → preprocess.py cleans & encodes → descriptors.py (optional descriptor features)
2) Encoded data → train.py / finetune.py → model.py defines network → checkpoints stored on disk
3) Upon completion, sample.py (invoking generator.py) loads checkpoint → produces generated SMILES CSV
4) .py reads generated SMILES + reference data → computes metrics → plotting.py for graphs

##### Key Architectural Patterns and Technologies
- Pipeline pattern: modular CLI scripts connected in sequence
- Checkpoint–based persistence: model artifacts on file system
- Dependency injection of hyperparameters via argparse
- External libraries:
- TensorFlow 1.14 for RNN training
- RDKit for chemistry operations
- Optional FCD library for generative model evaluation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        RawData[(Raw SMILES CSV)]:::data
        GeneratedData[(Generated SMILES CSV)]:::data
    end

    %% Preprocessing Module
    subgraph "Preprocessing Module"
        Preprocess["preprocess.py\ntokenize & clean"]:::process
        Descriptors["descriptors.py\ncompute descriptors"]:::process
    end

    %% Model Definition
    ModelDef["model.py\nLSTM RNN architecture"]:::model

    %% Training Pipelines
    subgraph "Training Pipelines"
        Train["train.py\nstandard training loop"]:::model
        Finetune["finetune.py\ntransfer learning"]:::model
        Checkpoint[(Model Checkpoints)]:::data
    end

    %% Sampling Module
    subgraph "Sampling Module"
        Sample["sample.py\ngenerate SMILES"]:::gen
        Generator["generator.py\ncore sampling routines"]:::gen
    end

    %% Analysis Module
    subgraph "Analysis & Visualization"
        Analyze["analyze.py\nmetrics & FCD"]:::analysis
        Plotting["plotting.py\nvisualization"]:::analysis
    end

    %% Utilities
    Utils["utils.py\nshared helpers"]:::util

    %% External Libraries
    TensorFlow["TensorFlow 1.14"]:::external
    RDKit["RDKit"]:::external
    FCD["FCD Library"]:::external

    %% Data Flow
    RawData --> Preprocess --> Descriptors
    Descriptors --> Train
    Descriptors --> Finetune
    Train --> Checkpoint
    Finetune --> Checkpoint
    Checkpoint --> Sample --> Generator --> GeneratedData
    GeneratedData --> Analyze --> Plotting

    %% Dependencies
    ModelDef --> Train
    ModelDef --> Finetune
    Utils --> Preprocess
    Utils --> Descriptors
    Utils --> Train
    Utils --> Finetune
    Utils --> Sample
    Utils --> Generator
    Utils --> Analyze
    Utils --> Plotting
    TensorFlow --> Train
    TensorFlow --> Finetune
    RDKit --> Descriptors
    RDKit --> Analyze
    FCD --> Analyze

    %% Click Events
    click RawData "https://github.com/alexarnimueller/smiles_generator/blob/master/data/chembl24_10uM_20-100.csv"
    click GeneratedData "https://github.com/alexarnimueller/smiles_generator/blob/master/generated/chembl24_augment5_generated.csv"
    click Preprocess "https://github.com/alexarnimueller/smiles_generator/blob/master/preprocess.py"
    click Descriptors "https://github.com/alexarnimueller/smiles_generator/blob/master/descriptors.py"
    click ModelDef "https://github.com/alexarnimueller/smiles_generator/blob/master/model.py"
    click Train "https://github.com/alexarnimueller/smiles_generator/blob/master/train.py"
    click Finetune "https://github.com/alexarnimueller/smiles_generator/blob/master/finetune.py"
    click Sample "https://github.com/alexarnimueller/smiles_generator/blob/master/sample.py"
    click Generator "https://github.com/alexarnimueller/smiles_generator/blob/master/generator.py"
    click Analyze "https://github.com/alexarnimueller/smiles_generator/blob/master/analyze.py"
    click Plotting "https://github.com/alexarnimueller/smiles_generator/blob/master/plotting.py"
    click Utils "https://github.com/alexarnimueller/smiles_generator/blob/master/utils.py"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#024B8C,stroke-width:1px;
    classDef process fill:#E8F4D0,stroke:#6C8C0D,stroke-width:1px;
    classDef model fill:#D0FFD8,stroke:#028C3C,stroke-width:1px;
    classDef gen fill:#FFE8D0,stroke:#8C4B0D,stroke-width:1px;
    classDef analysis fill:#F4D0FF,stroke:#72088C,stroke-width:1px;
    classDef util fill:#F0F0F0,stroke:#555555,stroke-width:1px,stroke-dasharray: 2 2;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,stroke-width:1px,stroke-dasharray: 2 2;
```
