Learn graph neural networks by building them from scratch on real molecules. Every notebook runs in Google Colab with one click, and no prior experience with GNNs is required - we build the concepts from the ground up.
In the browser (recommended): Start with Notebook 01 and work through the core sequence below.
Locally:
git clone https://github.com/HFooladi/GNNs-For-Chemists.gitThen open any notebook in notebooks/. Each notebook installs its own dependencies in the first cell.
This repository serves as an educational resource for chemists and researchers interested in applying Graph Neural Networks to chemical problems. Each notebook progressively builds upon fundamental concepts, from basic graph representation of molecules to advanced molecular property prediction models.
To get the most out of this tutorial series, you should have:
- Python: Basic to intermediate Python programming skills
- Chemistry: Fundamental understanding of molecular structures and properties
- Machine Learning: Basic familiarity with neural network concepts
- Mathematics: Basic understanding of linear algebra and calculus fundamentals
- Packages: Familiarity with PyTorch, NumPy, and RDKit (installation instructions provided in notebooks)
The following notebooks (01, 02, 03, ...) form the main learning path and are essential for understanding GNN fundamentals:
| Notebook | Description | Open in Colab | Status |
|---|---|---|---|
| 01_GNN_representation | Representing molecules as graphs | ✅ | |
| 02_GNN_message_passing | Understanding the message-passing concept | ✅ | |
| 03_GNN_molecular_activity_predictor | Build and train the first GNN | ✅ | |
| 04_GNN_GCN | Graph convolutional network | ✅ | |
| 05_GNN_GAT | Graph attention network | ✅ | |
| 06_GNN_GIN | Graph isomorphism network | ✅ | |
| 07_GNN_SchNet | SchNet: continuous-filter convolutions on 3D atomic positions | coming soon | 🚧 |
| 08_GNN_DimNet | DimeNet: directional message passing with bond angles | coming soon | 🚧 |
| 09_GNN_EGNN | E(3)-equivariant graph neural network | coming soon | 🚧 |
| 10_GNN_GT | Graph Transformer / Graphormer | coming soon | 🚧 |
These notebooks (01.1, 01.2, ...) provide additional details and advanced topics that complement the main series:
| Notebook | Description | Open in Colab | Status |
|---|---|---|---|
| 01.1_GNN_3D_representation | Interactive 3D molecular visualizations and stereochemistry | ✅ | |
| 01.2_GNN_alternative_representations | Alternative graph encodings: dual graphs, atom-bond networks | coming soon | 🚧 |
| 01.3_GNN_fragment_representation | Fragment-based molecular representations (BRICS, functional groups, ring systems) | coming soon | 🚧 |
| 01.4_GNN_frameworks | Framework comparison: PyTorch Geometric vs. DGL vs. Jraph | coming soon | 🚧 |
| 01.5_GNN_graph_characteristics | What molecular graphs look like statistically — size, sparsity, degree, diameter — and why GNNs use 3–5 layers | ✅ | |
| 02.1_GNN_oversmoothing | Visualizing oversmoothing: why very deep GNNs fail | ✅ |
Contributions are welcome! Please see CONTRIBUTORS.md for guidelines on how to contribute.
This project is licensed under the MIT License - see the LICENSE file for details.
If this repository helped you, a ⭐ on GitHub helps other chemists find it.
If you use this repository in your research, please cite it as:
@misc{gnns_for_chemists,
author = {Fooladi, Hosein},
title = {GNNs For Chemists: Implementations of Graph Neural Networks from Scratch for Chemical Applications},
year = {2025},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/HFooladi/GNNs-For-Chemists}},
note = {Educational resource for chemists, pharmacists, and researchers interested in applying Graph Neural Networks to chemical problems}
}