# chython/chytorch architecture

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

- Interactive diagram: https://gitdiagram.com/chython/chytorch
- Repository: https://github.com/chython/chytorch

## Overview

##### Project type and purpose
- This is a Python machine-learning library (no UI) for modeling molecules and reactions in a “torch” way. It provides:
- Neural modules (e.g., MoleculeEncoder, ReactionEncoder, LoRA layers, Voting classifiers).
- Data utilities (datasets, collate functions, LMDB mapping, SMILES parsing).
- A light “models zoo” interface.
- There is no “frontend” or web layer—this is a pure library for researchers and developers.

##### File structure
- Top-level:
- build.py, pyproject.toml: build and packaging scripts.
- chytorch/: the core library.
- examples/: usage examples.
- .github/workflows: CI for packaging/tests.
- Under chytorch/:
- nn/: all neural-network components grouped further by purpose (transformer, lora, molecule, reaction, voting, losses, slicer).
- utils/: data-handling layers (datasets, collate, LMDB, SMILES, molecule unpacking, reaction encoding).
- zoo/: model-zoo interface (small README).
- No external services or microservices—pure library.

##### README for additional insights
- Core encoder: Graphormer-style MoleculeEncoder built on torch.nn.TransformerEncoder.
- Data pipeline: MoleculeDataset, SMILESDataset, collate functions.
- Voting interfaces for ensembling.
- Dependencies implicitly include PyTorch, chython (for MoleculeContainer), RDKit (optional), LMDB.

a. Main components:
1. Data Ingestion Layer (chytorch.utils.data):
- SMILESDataset
- MoleculeDataset
- LMDBMapper
- collate functions
2. Neural Network Layer (chytorch.nn):
- MoleculeEncoder (Graphormer)
- ReactionEncoder
- LoRA adapters (linear, embedding)
- Slicer
- VotingClassifier / Regressor
- Loss functions
3. External Dependencies:
- PyTorch
- chython (MoleculeContainer, ReactionContainer)
- RDKit (for molecule handling, optional)
- LMDB (for storage)
4. Packaging & CI:
- build.py / pyproject.toml
- GitHub workflows

b. Relationships & interactions:
- User code or examples → instantiate SMILESDataset/MoleculeDataset → DataLoader
- DataLoader + collate → Batch tensor input → MoleculeEncoder/ReactionEncoder → tensor outputs
- Outputs → optional Voting modules for ensemble predictions
- Losses computed → optimizer/backprop via PyTorch
- Model parameters saved/loaded via standard torch API
- Packaging layer wraps library for pip install; CI ensures tests/builds succeed

c. Architectural patterns / design principles:
- Modular layering: data layer separated from network layer
- Pluggable adapters (LoRA), plug-and-play encoder stacks
- Dataset and collate functions follow torch.utils.data interfaces
- Ensemble (Voting) pattern for predictions
- Build & test automation via GitHub Actions

d. Key technologies & frameworks:
- Python 3
- PyTorch (core ML)
- Cython (unpacking modules .pyx)
- LMDB (data storage)
- RDKit (chemistry toolkit)
- chython (molecule representation)

##### Detailed architectural elements
- Package boundaries: utils vs. nn vs. zoo
- Subcomponents: transformer.attention → Graphormer, lora modules, molecule encoders
- Data containers (MoleculeContainer) entry point
- Collate functions bridging raw containers to tensor batches
- Voting heads as parallel branches after core encoder

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        direction TB
        SMILES["SMILESDataset"]:::data
        Collate["Collate Functions"]:::data
        MoleculeData["MoleculeDataset + Unpack/Encoder/Conformer/Dummy"]:::data
        LMDBMapper["LMDBMapper"]:::data
        ReactionData["ReactionEncoder"]:::data
    end

    %% Neural Network Layer
    subgraph "Neural Network Layer"
        direction TB
        MoleculeEnc["MoleculeEncoder\n(Graphormer-style)"]:::ml
        ReactionEnc["ReactionEncoder"]:::ml
        TransformerCore["Transformer Core"]:::ml
        GraphormerAttn["Graphormer Attention"]:::ml
        LoRA["LoRA Adapters"]:::ml
        Slicer["Slicer Module"]:::ml
        Voting["Voting Ensemble\n(Binary/Classifier/Regressor)"]:::ml
        Losses["Loss Functions"]:::ml
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch(("PyTorch")):::ext
        Chython(("chython\n(MoleculeContainer/ReactionContainer)")):::ext
        RDKit(("RDKit (optional)")):::ext
        LMDBExt(("LMDB Storage")):::ext
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        direction TB
        BuildScript["build.py"]:::pkg
        Pyproject["pyproject.toml"]:::pkg
        CI["GitHub Actions\n(python-package.yml)"]:::pkg
    end

    %% Data Flow Arrows
    SMILES --> Collate
    MoleculeData --> Collate
    Collate --> Batch["Batch Tensor"]
    LMDBMapper --> SMILES
    ReactionData --> Batch
    Batch --> MoleculeEnc
    Batch --> ReactionEnc
    MoleculeEnc --> TransformerCore
    ReactionEnc --> TransformerCore
    TransformerCore --> GraphormerAttn
    GraphormerAttn --> LoRA
    LoRA --> Slicer
    Slicer --> Voting
    Voting --> Predictions["Predictions"]
    Predictions --> Losses
    PyTorch --> MoleculeEnc
    PyTorch --> ReactionEnc
    PyTorch --> Losses
    Chython --> SMILES
    Chython --> MoleculeData
    RDKit --> MoleculeData
    LMDBExt --> LMDBMapper
    BuildScript --> CI
    Pyproject --> CI

    %% Click Events
    click SMILES "https://github.com/chython/chytorch/blob/master/chytorch/utils/data/smiles.py"
    click Collate "https://github.com/chython/chytorch/blob/master/chytorch/utils/data/_utils.py"
    click MoleculeData "https://github.com/chython/chytorch/tree/master/chytorch/utils/data/molecule"
    click LMDBMapper "https://github.com/chython/chytorch/blob/master/chytorch/utils/data/lmdb.py"
    click ReactionData "https://github.com/chython/chytorch/blob/master/chytorch/utils/data/reaction/encoder.py"
    click MoleculeEnc "https://github.com/chython/chytorch/blob/master/chytorch/nn/molecule/encoder.py"
    click ReactionEnc "https://github.com/chython/chytorch/blob/master/chytorch/nn/reaction.py"
    click TransformerCore "https://github.com/chython/chytorch/blob/master/chytorch/nn/transformer/encoder.py"
    click GraphormerAttn "https://github.com/chython/chytorch/blob/master/chytorch/nn/transformer/attention/graphormer.py"
    click LoRA "https://github.com/chython/chytorch/tree/master/chytorch/nn/lora"
    click Slicer "https://github.com/chython/chytorch/blob/master/chytorch/nn/slicer.py"
    click Voting "https://github.com/chython/chytorch/tree/master/chytorch/nn/voting"
    click Losses "https://github.com/chython/chytorch/blob/master/chytorch/nn/losses.py"
    click CI "https://github.com/chython/chytorch/blob/master/.github/workflows/python-package.yml"
    click BuildScript "https://github.com/chython/chytorch/blob/master/build.py"
    click Pyproject "https://github.com/chython/chytorch/blob/master/pyproject.toml"

    %% Styles
    classDef data fill:#AED6F1,stroke:#1F618D,color:#1B4F72;
    classDef ml fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef ext fill:#D5DBDB,stroke:#626567,color:#1B2631;
    classDef pkg fill:#F9E79F,stroke:#B9770E,color:#7E5109;
```
