# malswadi/tmgl architecture

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

- Interactive diagram: https://gitdiagram.com/malswadi/tmgl
- Repository: https://github.com/malswadi/tmgl

## Overview

TMGL is a molecular-property prediction framework: training loads labeled molecular records, turns SMILES into molecular graphs, derives topology and motif features, and trains a multi-level graph model for binary, multi-label, or regression tasks. Model inference encodes local, motif, and global representations, fuses them, and predicts task outputs; training evaluates validation metrics and saves the best checkpoint. The README documents the model capabilities, while sampled source confirms data preparation, model components, and trainer behavior; unsampled evaluation wiring is shown only where supported by the tree.

Main entry points: [`src/model.py`](https://github.com/malswadi/tmgl/blob/main/src/model.py) (Fusion and prediction), [`src/train.py`](https://github.com/malswadi/tmgl/blob/main/src/train.py) (Training entry), [`src/utils.py`](https://github.com/malswadi/tmgl/blob/main/src/utils.py) (Batch preparation), [`Datasets`](https://github.com/malswadi/tmgl/tree/main/Datasets) (Property datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Molecular data"]
  node_datasets["Property datasets"]
  node_csv_ingest["CSV loaders<br/>[utils.py]"]
  node_smiles_validation["SMILES validation<br/>[utils.py]"]
  node_graph_conversion["Molecule graphs<br/>[utils.py]"]
  node_data_splits["Task splits<br/>[utils.py]"]
end

subgraph group_representation["Graph representations"]
  node_topology_features["Topology features<br/>[utils.py]"]
  node_motif_features["Motif features<br/>[utils.py]"]
  node_precomputed_loader["Batch preparation<br/>[utils.py]"]
end

subgraph group_learning["Model and learning"]
  node_local_encoder["GIN encoder<br/>[model.py]"]
  node_global_encoder["Graph transformer<br/>[model.py]"]
  node_motif_encoder["Motif encoder<br/>[model.py]"]
  node_contrastive_loss["Contrastive loss<br/>[model.py]"]
  node_topology_loss["Topology loss<br/>[model.py]"]
  node_motif_loss["Motif consistency<br/>[model.py]"]
  node_fusion_classifier["Fusion and prediction<br/>[model.py]"]
end

subgraph group_execution["Training and evaluation"]
  node_training_cli["Training entry<br/>[train.py]"]
  node_task_trainers["Task trainers<br/>[train.py]"]
  node_test_entry["Evaluation entry<br/>[test.py]"]
  node_checkpoint["Best checkpoint"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts training"| node_training_cli
node_datasets -->|"supplies records"| node_csv_ingest
node_training_cli -->|"loads task data"| node_csv_ingest
node_csv_ingest -->|"validates molecules"| node_smiles_validation
node_smiles_validation -->|"converts SMILES"| node_graph_conversion
node_graph_conversion -->|"provides graphs"| node_data_splits
node_data_splits -->|"batches splits"| node_precomputed_loader
node_precomputed_loader -->|"extracts topology"| node_topology_features
node_precomputed_loader -->|"extracts motifs"| node_motif_features
node_training_cli -->|"runs task training"| node_task_trainers
node_training_cli -->|"prepares batches"| node_precomputed_loader
node_task_trainers -->|"invokes model"| node_local_encoder
node_local_encoder -->|"encodes global context"| node_global_encoder
node_local_encoder -->|"encodes motifs"| node_motif_encoder
node_fusion_classifier -->|"uses local features"| node_local_encoder
node_fusion_classifier -->|"uses global features"| node_global_encoder
node_fusion_classifier -->|"uses motif features"| node_motif_encoder
node_fusion_classifier -->|"computes contrast"| node_contrastive_loss
node_fusion_classifier -->|"computes topology loss"| node_topology_loss
node_fusion_classifier -->|"computes motif loss"| node_motif_loss
node_task_trainers -->|"trains and predicts"| node_fusion_classifier
node_task_trainers -->|"saves best model"| node_checkpoint
node_researcher -.->|"requests evaluation"| node_test_entry

click node_datasets "https://github.com/malswadi/tmgl/tree/main/Datasets"
click node_csv_ingest "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_smiles_validation "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_graph_conversion "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_data_splits "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_topology_features "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_motif_features "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_precomputed_loader "https://github.com/malswadi/tmgl/blob/main/src/utils.py"
click node_training_cli "https://github.com/malswadi/tmgl/blob/main/src/train.py"
click node_local_encoder "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_global_encoder "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_motif_encoder "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_contrastive_loss "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_topology_loss "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_motif_loss "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_fusion_classifier "https://github.com/malswadi/tmgl/blob/main/src/model.py"
click node_task_trainers "https://github.com/malswadi/tmgl/blob/main/src/train.py"
click node_test_entry "https://github.com/malswadi/tmgl/blob/main/src/test.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_datasets,node_csv_ingest,node_smiles_validation,node_graph_conversion,node_data_splits toneBlue
class node_topology_features,node_motif_features,node_precomputed_loader toneAmber
class node_local_encoder,node_global_encoder,node_motif_encoder,node_contrastive_loss,node_topology_loss,node_motif_loss,node_fusion_classifier toneMint
class node_training_cli,node_task_trainers,node_test_entry,node_checkpoint toneRose
class node_researcher toneIndigo
```

## Components

### Molecular data

- [Property datasets](https://github.com/malswadi/tmgl/tree/main/Datasets): `Datasets`
- [CSV loaders](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`
- [SMILES validation](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`
- [Molecule graphs](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`
- [Task splits](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`

### Graph representations

- [Topology features](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`
- [Motif features](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`
- [Batch preparation](https://github.com/malswadi/tmgl/blob/main/src/utils.py): `src/utils.py`

### Model and learning

- [GIN encoder](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Graph transformer](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Motif encoder](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Contrastive loss](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Topology loss](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Motif consistency](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`
- [Fusion and prediction](https://github.com/malswadi/tmgl/blob/main/src/model.py): `src/model.py`

### Training and evaluation

- [Training entry](https://github.com/malswadi/tmgl/blob/main/src/train.py): `src/train.py`
- [Task trainers](https://github.com/malswadi/tmgl/blob/main/src/train.py): `src/train.py`
- [Evaluation entry](https://github.com/malswadi/tmgl/blob/main/src/test.py): `src/test.py`
- **Best checkpoint**

### Other components

- **Researcher**

## Connections

- Researcher → Training entry: starts training
- Property datasets → CSV loaders: supplies records
- Training entry → CSV loaders: loads task data
- CSV loaders → SMILES validation: validates molecules
- SMILES validation → Molecule graphs: converts SMILES
- Molecule graphs → Task splits: provides graphs
- Task splits → Batch preparation: batches splits
- Batch preparation → Topology features: extracts topology
- Batch preparation → Motif features: extracts motifs
- Training entry → Task trainers: runs task training
- Training entry → Batch preparation: prepares batches
- Task trainers → GIN encoder: invokes model
- GIN encoder → Graph transformer: encodes global context
- GIN encoder → Motif encoder: encodes motifs
- Fusion and prediction → GIN encoder: uses local features
- Fusion and prediction → Graph transformer: uses global features
- Fusion and prediction → Motif encoder: uses motif features
- Fusion and prediction → Contrastive loss: computes contrast
- Fusion and prediction → Topology loss: computes topology loss
- Fusion and prediction → Motif consistency: computes motif loss
- Task trainers → Fusion and prediction: trains and predicts
- Task trainers → Best checkpoint: saves best model
- Researcher → Evaluation entry: requests evaluation