# mariewelt/openchem architecture

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

- Interactive diagram: https://gitdiagram.com/mariewelt/openchem
- Repository: https://github.com/mariewelt/openchem

## Overview

##### Project Type and Purpose
- OpenChem is an open-source deep learning toolkit (library) for computational chemistry and drug design.
- It provides a unified, modular API on top of PyTorch to build, train, and evaluate sequence- and graph-based molecular models via configuration files.

##### Top-Level Architecture Components
a. Entry Points & Configuration
- run.py, launch.py, example_configs/…
- Configuration reader → builds model, data loader, criterion, optimizer, trainer
b. Data Processing Layer
- openchem/data/: various DataLayer classes (smiles, graph, siamese, protein)
- benchmark_datasets/…: CSVs and pickled datasets
- Preprocessing utilities (openchem/data/utils.py, graph_utils.py)
c. Model Definition Layer
- openchem/modules/: embeddings (onehot, basic, openchem), encoders (RNN, GCN, CNN, edge-attention), mlp
- openchem/layers/: building blocks (conv_bn_relu, gcn, stack_augmentation)
- openchem/models/: high-level Model classes (MoleculeProtein2Label, GenerativeRNN, MolecularRNN, SiameseModel, etc.)
d. Criterion & Optimization
- openchem/criterion/: loss functions (multitask_loss, policy_gradient_loss)
- openchem/optimizer/: scheduler and optimizer wrappers (openchem_optimizer, openchem_lr_scheduler)
e. Training Engine & Utilities
- Training loop orchestration and multi-GPU support (openchem/utils/comm.py)
- Logging & monitoring (openchem/utils/logger.py, textlogger.py → Tensorboard integration)
- Metrics & RL utilities (metrics.py, rl_utils.py, sa_score/)
f. Infrastructure & Dev-Ops
- Dockerfile, .travis.yml, devtools/: CI scripts, conda environments, build recipes
- docs/: Sphinx-generated HTML and source; example usage and tutorials
- setup.py, requirements.txt: packaging and dependencies

##### Component Interactions and Data Flow
- The user invokes run.py/launch.py with a config → Configuration Loader
↓
- Config instantiates DataLayer → loads benchmark or user data, applies tokenization/graph conversion
↓
- Data fed to Model instance → composed from embeddings → encoder → output head
↓
- Output and ground truth passed to Criterion → loss computed
↓
- Optimizer updates model parameters via Training Engine (supports multi-GPU)
↓
- Training Engine calls Logger → writes metrics to Tensorboard and logs/…
- At checkpoints, model snapshots saved in logs/…/checkpoint

##### Architectural Patterns & Design Principles
- Modular plugin architecture: each layer (data, modules, models, criterion, optimizer) implements a base interface for interchangeability.
- Configuration-driven instantiation: no hard-coded wiring—everything wired via YAML/Python config.
- Separation of concerns: data handling, model definition, training loop, and logging live in distinct packages.
- Extensibility: new DataLayer, Encoder, or Model classes drop-in under openchem/… and referenced in config.

##### Essential Details to Capture
- Entry points and config reader that wire everything together.
- Data preprocessing pipelines converting SMILES → tensors/graphs.
- Modular breakdown: embeddings → encoders → model head → loss → optimizer.
- Multi-GPU training orchestration and logging outputs.
- Extensibility hooks (where new modules plug in).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points & Configuration
    subgraph "User Scripts" 
        direction TB
        Run(["run.py"]):::entry
        Launch(["launch.py"]):::entry
        Examples(["example_configs/"]):::entry
        ConfigReader(["Configuration Reader"]):::core
        Run -->|invokes| ConfigReader
        Launch -->|invokes| ConfigReader
        Examples -->|provides| ConfigReader
    end

    %% Data Processing Layer
    subgraph "Data Processing" 
        direction TB
        DataLayer(["DataLayer Classes"]):::data
        Benchmark(["benchmark_datasets/"]):::data
        UtilsDP(["utils.py, graph_utils.py, smiles_enumerator.py"]):::data
        ConfigReader -->|instantiates| DataLayer
        DataLayer -->|loads from| Benchmark
        DataLayer -->|uses| UtilsDP
    end

    %% Model Definition Layer
    subgraph "Model Definition" 
        direction TB
        Embeddings(["Embeddings"]):::model
        Encoders(["Encoders"]):::model
        Layers(["Layers"]):::model
        HighModel(["High-level Models"]):::model
        DataLayer -->|feeds tensors| Embeddings
        Embeddings -->|encoded features| Encoders
        Encoders -->|representations| HighModel
        Layers -->|building blocks| Encoders
    end

    %% Criterion & Optimization
    subgraph "Criterion & Optimization" 
        direction TB
        Criterion(["Loss Functions"]):::train
        Optimizer(["Optimizer & Scheduler"]):::train
        HighModel -->|outputs + labels| Criterion
        Criterion -->|loss| Optimizer
    end

    %% Training Engine & Utilities
    subgraph "Training Engine & Utils" 
        direction TB
        Engine(["Training Engine"]):::train
        Logger(["Logger & Metrics"]):::train
        Engine -->|multi-GPU orchestration| Logger
        Optimizer -->|updates| Engine
        Logger -->|writes to| Tensorboard
    end

    %% Infrastructure & Dev-Ops
    subgraph "Infrastructure & Dev-Ops"
        direction TB
        Docker(["Dockerfile"]):::infra
        CI([".travis.yml, devtools/"]):::infra
        Docs(["docs/"]):::infra
        Setup(["setup.py, requirements.txt"]):::infra
    end

    %% External Dependencies
    subgraph "External" 
        direction TB
        PyTorch(["PyTorch"]):::external
        RDKit(["RDKit"]):::external
        Conda(["Conda"]):::external
        Tensorboard(["Tensorboard"]):::external
        DockerExt(["Docker"]):::external
    end

    %% Data flows
    ConfigReader -->|"builds"| DataLayer
    Engine -->|uses| PyTorch
    Embeddings -->|built on| PyTorch
    Benchmark -->|optionally uses| RDKit
    CI -->|sets up| Conda
    Docker -->|builds| DockerExt

    %% Click Events
    click Run "https://github.com/mariewelt/openchem/blob/master/run.py"
    click Launch "https://github.com/mariewelt/openchem/blob/master/launch.py"
    click Examples "https://github.com/mariewelt/openchem/tree/master/example_configs/"
    click Benchmark "https://github.com/mariewelt/openchem/tree/master/benchmark_datasets/"
    click UtilsDP "https://github.com/mariewelt/openchem/blob/master/openchem/data/utils.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/feature_data_layer.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/graph_data_layer.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/siamese_data_layer.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/smiles_data_layer.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/smiles_protein_data_layer.py"
    click DataLayer "https://github.com/mariewelt/openchem/blob/master/openchem/data/vanilla_data_layer.py"
    click UtilsDP "https://github.com/mariewelt/openchem/blob/master/openchem/data/graph_utils.py"
    click UtilsDP "https://github.com/mariewelt/openchem/blob/master/openchem/data/smiles_enumerator.py"
    click Embeddings "https://github.com/mariewelt/openchem/blob/master/openchem/modules/embeddings/basic_embedding.py"
    click Embeddings "https://github.com/mariewelt/openchem/blob/master/openchem/modules/embeddings/onehot_embedding.py"
    click Embeddings "https://github.com/mariewelt/openchem/blob/master/openchem/modules/embeddings/openchem_embedding.py"
    click Encoders "https://github.com/mariewelt/openchem/blob/master/openchem/modules/encoders/rnn_encoder.py"
    click Encoders "https://github.com/mariewelt/openchem/blob/master/openchem/modules/encoders/gcn_encoder.py"
    click Encoders "https://github.com/mariewelt/openchem/blob/master/openchem/modules/encoders/cnn_encoder.py"
    click Encoders "https://github.com/mariewelt/openchem/blob/master/openchem/modules/encoders/edge_attention_encoder.py"
    click Encoders "https://github.com/mariewelt/openchem/blob/master/openchem/modules/encoders/openchem_encoder.py"
    click Layers "https://github.com/mariewelt/openchem/blob/master/openchem/layers/conv_bn_relu.py"
    click Layers "https://github.com/mariewelt/openchem/blob/master/openchem/layers/gcn.py"
    click Layers "https://github.com/mariewelt/openchem/blob/master/openchem/layers/stack_augmentation.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/GenerativeRNN.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/MolecularRNN.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/Graph2Label.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/MLP2Label.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/Smiles2Label.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/MoleculeProtein2Label.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/SiameseModel.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/openchem_model.py"
    click HighModel "https://github.com/mariewelt/openchem/blob/master/openchem/models/vanilla_model.py"
    click Criterion "https://github.com/mariewelt/openchem/blob/master/openchem/criterion/multitask_loss.py"
    click Criterion "https://github.com/mariewelt/openchem/blob/master/openchem/criterion/policy_gradient_loss.py"
    click Optimizer "https://github.com/mariewelt/openchem/blob/master/openchem/optimizer/openchem_optimizer.py"
    click Optimizer "https://github.com/mariewelt/openchem/blob/master/openchem/optimizer/openchem_lr_scheduler.py"
    click Engine "https://github.com/mariewelt/openchem/blob/master/openchem/utils/comm.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/logger.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/textlogger.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/metrics.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/rl_utils.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/utils.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/utils_3d.py"
    click Logger "https://github.com/mariewelt/openchem/blob/master/openchem/utils/graph.py"
    click Logger "https://github.com/mariewelt/openchem/tree/master/openchem/utils/sa_score/"
    click Docker "https://github.com/mariewelt/openchem/tree/master/Dockerfile"
    click CI "https://github.com/mariewelt/openchem/blob/master/.travis.yml"
    click CI "https://github.com/mariewelt/openchem/tree/master/devtools/"
    click Docs "https://github.com/mariewelt/openchem/tree/master/docs/"
    click Setup "https://github.com/mariewelt/openchem/blob/master/setup.py"
    click Setup "https://github.com/mariewelt/openchem/blob/master/requirements.txt"

    %% Styles
    classDef entry fill:#e7f3ff,stroke:#1f78b4;
    classDef data fill:#e0f2f1,stroke:#00796b;
    classDef model fill:#e8f5e9,stroke:#388e3c;
    classDef train fill:#fff3e0,stroke:#f57c00;
    classDef infra fill:#eceff1,stroke:#546e7a;
    classDef external fill:#fce4ec,stroke:#d81b60;
    classDef core fill:#ffffff,stroke:#000000,stroke-width:1px;
```
