A six-week, research-oriented course that re-implements modern Graph Neural Networks from first principles. Every notebook derives the underlying mathematics, builds the operators in pure NumPy / PyTorch (without torch_geometric, dgl, or any high-level GNN library), visualizes the mechanics, and applies the result to real data.
The notebooks are self-contained: each one consists of a theoretical foundation, a step-by-step Python implementation, focused visualizations, a real-data application, and a set of exercises.
| Week | Notebook | Topics |
|---|---|---|
| 1 | 01_graphs_spectra_and_signal_processing.ipynb |
Adjacency, incidence, the graph Laplacian, Dirichlet energy, the eigenbasis as a Fourier basis, graph signal processing, heat-kernel filtering, the Fiedler vector and spectral clustering on Karate Club |
| 2 | 02_graph_convolutional_networks.ipynb |
Chebyshev polynomial filters, the GCN derivation, the renormalization trick, GCN from scratch in PyTorch, semi-supervised node classification with just two labels, structure-blind MLP baseline |
| 3 | 03_message_passing_sage_and_attention.ipynb |
The generic message → aggregate → update abstraction, scatter operations on edge lists, GraphSAGE with mean/max aggregators and neighbor sampling, multi-head Graph Attention (GAT) from scratch, attention-weight visualization on Les Misérables |
| 4 | 04_graph_pooling_and_expressive_power.ipynb |
Permutation-invariant readouts, the Weisfeiler–Lehman test by hand, where mean-pool provably fails, the Graph Isomorphism Network (GIN) and its injectivity argument, cycle-vs-path graph classification |
| 5 | 05_oversmoothing_oversquashing_and_depth.ipynb |
Over-smoothing as repeated low-pass filtering, Dirichlet-energy collapse, residual connections, PairNorm, Jumping Knowledge networks, over-squashing through bottlenecks measured via Jacobian, graph rewiring |
| 6 | 06_capstone_minignn_library_and_applications.ipynb |
A reusable minignn mini-library, train/val/test protocol with early stopping, controlled GCN/SAGE/GIN comparison on a stochastic block model, end-to-end link prediction with negative sampling and ROC-AUC evaluation, embedding visualization |
- From first principles. Each operator is derived mathematically before any code is written. The aim is to understand GNNs, not just call them.
- No high-level GNN libraries. Only NumPy, PyTorch tensors, NetworkX for graph construction, and Matplotlib for visualization. Scatter/gather and segmented softmax are implemented by hand.
- Visualize everything. Graphs, spectra, attention weights, embeddings — every concept is anchored by a plot.
- Real data, not just toys. Karate Club, Les Misérables, stochastic block models, and link-prediction tasks are used to ground the theory.
graph_neural_networks/
├── notebooks/
│ ├── 01_graphs_spectra_and_signal_processing.ipynb
│ ├── 02_graph_convolutional_networks.ipynb
│ ├── 03_message_passing_sage_and_attention.ipynb
│ ├── 04_graph_pooling_and_expressive_power.ipynb
│ ├── 05_oversmoothing_oversquashing_and_depth.ipynb
│ └── 06_capstone_minignn_library_and_applications.ipynb
├── requirements.txt
├── README.md
└── LICENSE
git clone https://github.com/HAYDARKILIC/graph_neural_networks.git
cd graph_neural_networks
pip install -r requirements.txt
jupyter lab notebooks/Each notebook runs end-to-end on CPU in a few minutes; no GPU is required.
- Linear algebra: eigendecomposition, positive semi-definite matrices, the SVD.
- Calculus / probability: gradients, softmax, basic expectations.
- Python + PyTorch basics: tensors, autograd,
nn.Module, optimization loops.
Familiarity with deep learning fundamentals (forward/backward pass, training loops) is assumed. The course is suitable for graduate students and engineers who want to understand GNNs deeply rather than treat them as a black box.
- Read and critically evaluate GNN papers, understanding the spectral and message-passing perspectives.
- Implement any standard GNN architecture from scratch in PyTorch.
- Diagnose practical failure modes (over-smoothing, over-squashing) and choose the right architectural fix.
- Build complete pipelines for node classification, graph classification, and link prediction.
- Extend the
minignnlibrary to your own research or production problem.
MIT.