Skip to content

About

Implementations of different GNNs from scratch for chemists

Topics

Resources

Stars

187 stars

Watchers

2 watching

Forks

Latest commit

 

History

147 Commits

Folders and files

Repository files navigation

GNNs For Chemists Banner

GNNs For Chemists

Open In Colab License: MIT Python 3 GitHub stars

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.

Start Here

In the browser (recommended): Open In Colab Start with Notebook 01 and work through the core sequence below.

Locally:

git clone https://github.com/HFooladi/GNNs-For-Chemists.git

Then open any notebook in notebooks/. Each notebook installs its own dependencies in the first cell.

Project Description

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.

Prerequisites

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)

Resources

Core Tutorial Sequence

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 Open In Colab ✅
02_GNN_message_passing Understanding the message-passing concept Open In Colab ✅
03_GNN_molecular_activity_predictor Build and train the first GNN Open In Colab ✅
04_GNN_GCN Graph convolutional network Open In Colab ✅
05_GNN_GAT Graph attention network Open In Colab ✅
06_GNN_GIN Graph isomorphism network Open In Colab ✅
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 🚧

Supplementary Deep-Dive Notebooks

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 Open In Colab ✅
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 Open In Colab ✅
02.1_GNN_oversmoothing Visualizing oversmoothing: why very deep GNNs fail Open In Colab ✅

Contributing

Contributions are welcome! Please see CONTRIBUTORS.md for guidelines on how to contribute.

License

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.

Citation

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}
}

About

Implementations of different GNNs from scratch for chemists

Topics

Resources

Stars

187 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages