# ethmodlab/bimodal architecture

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

- Interactive diagram: https://gitdiagram.com/ethmodlab/bimodal
- Repository: https://github.com/ethmodlab/bimodal

## Overview

##### Main Components
- Data Ingestion and Preprocessing: Represent the pipeline that loads raw molecular data (from files in the “data” folder, e.g., “chembl_smiles.tar.xz”) and processes it via the scripts in the “preprocessing” directory.
- Experimental Configuration: Include the “experiments” folder that holds parameter (.ini) files for different network models and training settings.
- Model Architecture and Training:
- “model” folder components (bimodal.py, fb_rnn.py, forward_rnn.py, nade.py, etc.) as the core modules responsible for constructing various RNN architectures.
- Distinguish between training scripts such as “main_trainer.py”, “trainer.py”, and “main_fine_tuner.py” for fine-tuning.
- Evaluation and Sampling:
- “evaluation” component which handles both performance evaluation (loss plots, molecule statistics) and a sampling module (using Sampler from the “sample.py” file) for generating new SMILES.
- Supporting Utilities and Helpers: Don’t forget to note the helper files (like “one_hot_encoder.py”, “helper.py”) that provide essential functions used throughout the modules.

##### Relationships and Data Flow
- A flow from the saved/pre-trained models to the Sampling Component (using Sampler class in “model/sample.py”), which then generates new SMILES.
- A feedback loop from Evaluation back to Training if one wants to improve performance based on results (e.g., via fine-tuning, using “model/main_fine_tuner.py”).

##### Architectural Patterns and Design Principles
- Modularity: Show how clear separation exists between data preparation, model training, fine-tuning, and evaluation/sampling.
- Configuration-driven Execution: Highlight the role of the .ini files from the “experiments” directory that parameterize training, data paths, learning rate, batch size, etc.
- Reproducibility: Indicate how pre-trained models are stored and can be re-used for sampling or fine-tuning; include versioning information from the README.

##### Detailing Interactions
- That the “experiments” parameters are fed into the “model” training scripts.
- That the “evaluation” scripts are not only for model performance but also for quality control for the generated SMILES.
- Fine-tuning process as an overlay on the training branch – using pre-trained models from evaluation as starting points for further training.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline
    subgraph "Data Pipeline"
        A["Raw SMILES Data"]:::data
        B["Preprocessing Module"]:::data
    end

    %% Experiment Configuration
    subgraph "Configuration"
        C["Experiment Configuration (.ini)"]:::config
    end

    %% Model Training Section
    subgraph "Model Training"
        subgraph "Model Architectures"
            D["BIMODAL"]:::model
            E["FB-RNN"]:::model
            F["Forward RNN"]:::model
            G["NADE"]:::model
        end
        subgraph "Training Scripts"
            H["Main Trainer"]:::training
            I["Trainer"]:::training
        end
        subgraph "Fine-Tuning"
            J["Main Fine-Tuner"]:::training
            K["Fine Tuner"]:::training
        end
    end

    %% Evaluation and Sampling Section
    subgraph "Evaluation & Sampling"
        L["Pre-trained Models"]:::eval
        N["Main Sampler"]:::eval
        O["Sampler"]:::eval
    end

    %% Supporting Utilities
    subgraph "Utilities"
        P1["Helper"]:::util
        P2["One Hot Encoder"]:::util
    end

    %% Data Flow Arrows
    A --> B
    B --> H
    C --> H
    D --> H
    E --> H
    F --> H
    G --> H
    H --> L
    I --> L
    L --> N
    N --> O
    %% Feedback loop for fine-tuning
    L --> J
    J --> K
    K --> L

    %% Technologies Annotation
    %% Note: This project is built using Python and PyTorch with a conda environment.

    %% Click Events
    click A "https://github.com/ethmodlab/bimodal/tree/master/data/"
    click B "https://github.com/ethmodlab/bimodal/blob/master/preprocessing/main_preprocessor.py"
    click C "https://github.com/ethmodlab/bimodal/tree/master/experiments/"
    click D "https://github.com/ethmodlab/bimodal/blob/master/model/bimodal.py"
    click E "https://github.com/ethmodlab/bimodal/blob/master/model/fb_rnn.py"
    click F "https://github.com/ethmodlab/bimodal/blob/master/model/forward_rnn.py"
    click G "https://github.com/ethmodlab/bimodal/blob/master/model/nade.py"
    click H "https://github.com/ethmodlab/bimodal/blob/master/model/main_trainer.py"
    click I "https://github.com/ethmodlab/bimodal/blob/master/model/trainer.py"
    click J "https://github.com/ethmodlab/bimodal/blob/master/model/main_fine_tuner.py"
    click K "https://github.com/ethmodlab/bimodal/blob/master/model/fine_tuner.py"
    click L "https://github.com/ethmodlab/bimodal/tree/master/evaluation/"
    click N "https://github.com/ethmodlab/bimodal/blob/master/model/main_sampler.py"
    click O "https://github.com/ethmodlab/bimodal/blob/master/model/sample.py"
    click P1 "https://github.com/ethmodlab/bimodal/blob/master/model/helper.py"
    click P2 "https://github.com/ethmodlab/bimodal/blob/master/model/one_hot_encoder.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef config fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef model fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef training fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef eval fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
