# marcusolivecrona/reinvent architecture

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

- Interactive diagram: https://gitdiagram.com/marcusolivecrona/reinvent
- Repository: https://github.com/marcusolivecrona/reinvent

## Overview

##### Project type and purpose
- This is an open‑source molecular‐generation tool that uses a Recurrent Neural Network “Prior” plus a reinforcement‐learning “Agent” to sample chemical structures (SMILES).
- It includes data preprocessing, model training (Prior & Agent), scoring, logging, and a lightweight Bokeh‐based visualization (“Vizard” app).

##### File structure
- Top level:
– data_structs.py, train_prior.py → Data ingestion & Prior training
– train_agent.py (called by main.py), scoring_functions.py → RL Agent training
– model.py, utils.py → Core model definitions & helpers
– multiprocess.py → Parallel sampling/training support
– vizard_logger.py → Logging interface to the Vizard app
– Vizard/ → Bokeh web‐app (templates + run scripts)
– data/ → SMILES files, vocab, model checkpoints, classifier pickles
– images/ → Demo GIFs and static assets
- Configuration: theme.yaml for Vizard styling, run.sh to launch the UI.

##### README for additional insights
- The workflow is command‐line‐driven: first filter and build vocabulary; then train a “Prior”; then launch Agent training via main.py.

##### Main components and their interactions
a. Data Ingestion & Preprocessing
– data_structs.py parses raw SMILES, filters them, builds a token vocabulary → outputs filtered .smi and Voc → stored in data/
b. Prior Training Pipeline
– train_prior.py + model.py + utils.py → consumes data/Voc & filtered SMILES → produces a pre‐trained “Prior” checkpoint (Prior.ckpt)
c. Reinforcement Learning Agent
– main.py / train_agent.py + multiprocess.py + scoring_functions.py → loads Prior, interacts with external scoring (e.g. QSAR model via clf.pkl), computes rewards, updates Agent RNN
d. Logging & Visualization
– vizard_logger.py writes training metrics, sampled SMILES, model weights → outputs logs to data/logs
– Vizard run.sh + templates/index.html + styles.css + theme.yaml → Bokeh server reads logs, hosts a live web UI at localhost:5006/Vizard
e. External dependencies
– PyTorch (model & training loops)
– RDKit (SMILES parsing & chemical operations)
– Scikit‑Learn (QSAR scoring functions)
– pexpect, tqdm, standard Python3.6 ecosystem

##### Architectural patterns & design principles
- Pipeline pattern: clear separation of data preparation → Prior pretraining → RL Agent training → logging → visualization
- Modular design: each major step is a standalone script or module

##### Final checklist
- Callouts for key frameworks and file artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Storage Layer
    subgraph "Data & Storage" 
        direction TB
        RawSMILES["Raw SMILES<br/>(data/ChEMBL_filtered)"]:::storage
        Filtered["Filtered SMILES"]:::storage
        Voc["Vocabulary<br/>(data/Voc)"]:::storage
        PriorCKPT["Prior.ckpt<br/>(data/Prior.ckpt)"]:::storage
        Logs["Logs<br/>(data/logs/)"]:::storage
        Clf["QSAR Model<br/>(data/clf.pkl)"]:::storage
    end

    %% ML Compute Layer
    subgraph "ML Compute" 
        direction TB
        DI["Data Ingestion Module<br/>python data_structs.py"]:::ml
        PT["Prior Training Module<br/>train_prior.py, model.py, utils.py"]:::ml
        AT["Agent Training Module<br/>main.py, train_agent.py, multiprocess.py"]:::ml
        SS["Scoring Services<br/>scoring_functions.py"]:::ml
        LS["Logging Service<br/>vizard_logger.py"]:::ml
    end

    %% Visualization UI
    subgraph "Vizard Visualization UI" 
        direction TB
        RunUI["run.sh"]:::ui
        UIApp["Vizard App<br/>main.py"]:::ui
        Index["index.html"]:::ui
        Styles["styles.css"]:::ui
        Theme["theme.yaml"]:::ui
    end

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        PyTorch["PyTorch"]:::ext
        RDKit["RDKit"]:::ext
        SK["Scikit-Learn"]:::ext
        Pexpect["pexpect"]:::ext
        Tqdm["tqdm"]:::ext
    end

    %% Data Flow
    RawSMILES -->|"SMILES files"| DI
    DI -->|"filtered SMILES"| Filtered
    DI -->|"vocabulary"| Voc
    Filtered -->|"input data"| PT
    Voc -->|"input vocabulary"| PT
    PT -->|"Prior checkpoint"| PriorCKPT
    PriorCKPT -->|"pre-trained Prior"| AT
    AT -->|"training metrics & samples"| LS
    AT -->|"reward queries"| SS
    SS -->|"QSAR scores"| AT
    LS -->|"log JSON"| Logs
    Logs -->|"read logs"| UIApp
    RunUI -->|"launch Bokeh server"| UIApp
    UIApp --> Index
    UIApp --> Styles
    UIApp --> Theme

    %% External usage
    PT --> PyTorch
    AT --> PyTorch
    DI --> RDKit
    SS --> SK
    AT --> Pexpect
    AT --> Tqdm

    %% Click Events
    click DI "https://github.com/marcusolivecrona/reinvent/blob/master/data_structs.py"
    click RawSMILES "https://github.com/marcusolivecrona/reinvent/tree/master/data/ChEMBL_filtered"
    click Voc "https://github.com/marcusolivecrona/reinvent/tree/master/data/Voc"
    click PT "https://github.com/marcusolivecrona/reinvent/blob/master/train_prior.py"
    click PT "https://github.com/marcusolivecrona/reinvent/blob/master/model.py"
    click PT "https://github.com/marcusolivecrona/reinvent/blob/master/utils.py"
    click PriorCKPT "https://github.com/marcusolivecrona/reinvent/blob/master/data/Prior.ckpt"
    click AT "https://github.com/marcusolivecrona/reinvent/blob/master/main.py"
    click AT "https://github.com/marcusolivecrona/reinvent/blob/master/train_agent.py"
    click AT "https://github.com/marcusolivecrona/reinvent/blob/master/multiprocess.py"
    click SS "https://github.com/marcusolivecrona/reinvent/blob/master/scoring_functions.py"
    click Clf "https://github.com/marcusolivecrona/reinvent/blob/master/data/clf.pkl"
    click LS "https://github.com/marcusolivecrona/reinvent/blob/master/vizard_logger.py"
    click RunUI "https://github.com/marcusolivecrona/reinvent/blob/master/Vizard/run.sh"
    click UIApp "https://github.com/marcusolivecrona/reinvent/blob/master/Vizard/main.py"
    click Index "https://github.com/marcusolivecrona/reinvent/blob/master/Vizard/templates/index.html"
    click Styles "https://github.com/marcusolivecrona/reinvent/blob/master/Vizard/templates/styles.css"
    click Theme "https://github.com/marcusolivecrona/reinvent/blob/master/Vizard/theme.yaml"

    %% Styles
    classDef ml fill:#e0f7fa,stroke:#0288d1,color:#000
    classDef storage fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef ui fill:#fff3e0,stroke:#ef6c00,color:#000
    classDef ext fill:#f3e5f5,stroke:#6a1b9a,color:#000
```
