Equivariant Graph Neural Networks with e3nn#
Machine learning interatomic potentials (MLIPs) are transforming how chemistry, physics, and materials science simulate matter at the atomic scale. By learning the potential energy surface from quantum-mechanical reference data, they deliver near first-principles accuracy at an reasonable fraction of the cost: serving as force fields in molecular dynamics simulations, accelerating the discovery and design of catalysts, screening electrolytes and electrode materials for next-generation batteries, predicting molecular and materials properties, and exploring solid-state physics problems such as phase transitions, defects, and thermal transport to system sizes far beyond the reach of many current electronic structure methods. Behind these advances lies one shared architectural principle: neural networks built to respect the Euclidean symmetries of physical space.
This course offers a comprehensive, step-by-step and user-friendly tutorial series which takes you from the mathematical foundations of Euclidean symmetry to complete and working implementations of state-of-the-art invariant baseline models SchNet, DimeNet and equivariant interatomic potentials such as NequIP, Allegro, and MACE.
Under active development
Lessons are being written and revised continuously. If something is unclear, wrong, or missing, please open an issue. Your feedback is important to us.
The teaching philosophy#
Five commitments shape every lesson in this book.
Theory first. Each operation is derived and motivated mathematically before presenting any code. We chose to trade some mathematical rigor for user friendliness but we still maintain a strong connection to theory and attempt to cite the key manuscripts.
Theory and experiment, side-by-side. Implementations are broken into code blocks of small to moderate sizes while being connected to their corresponding equations.
Verifications. Every key equivariant operation is unit-tested numerically,
using shared helper functions from the local
course_utils
folder. Feel free to inspect and modify them at your own convenience! If a block
claims to be equivariant, the notebook proves it to \(\approx10^{-15}\).
Visualizations. Spherical harmonics, tensor-product selection rules, learned features, training curves, and MD trajectories are plotted throughout to assist the reader in building intuition and gaining visual insight: several of them are designed as interactive 3D figures.
Modularity and simplicity. Long lessons are split into *_a, *_b, *_c
notebooks that can be followed in one sitting, individually.
What you will build#
By the end of the course, you will develop a working understanding of \(\mathrm{E}(3)\)-equivariant models and the e3nn library, and will be able to implement:
an equivariant point convolution (Tensor Field Networks) that passes a numerical \(\mathrm{O}(3)\)-equivariance test;
a small equivariant GNN that classifies chiral 3D shapes: something no distance-only model can do;
SchNet and DimeNet++ as invariant baselines, including a concrete demonstration of the incompleteness of distance-only descriptors;
NequIP, Allegro and MACE, block by block, trained on small datasets;
an ASE calculator wrapping a trained potential, driving real molecular dynamics with energy-conservation and radial distribution function (RDF) sanity checks.
Prerequisites#
Linear algebra (matrices, eigenvalues, change of basis), basic group theory helps but is introduced from scratch in Lesson 01.
PyTorch basics (tensors, autograd,
nn.Module, training loops).Some exposure to molecular systems / atomistic simulation is helpful for Parts III–V but not required.
Start here#
Install the course environment with uv, register the Jupyter kernel, and check your
install with a one-line equivariance test.
How each lesson is structured, suggested paths through the course, and how to keep the stored notebook outputs current.
All twenty-two lessons in five parts, with what each one teaches and the e3nn API it introduces.
Jump straight into the first lesson: why symmetry is the right inductive bias, and why data augmentation is not enough.
Citing this course#
If you have found this course useful in your research, please cite it as follows:
APA:
Mostafanejad, M. (2026). Equivariant Graph Neural Networks with e3nn. The Molecular Sciences Software Institute. https://doi.org/10.34974/BDKQ-0J86
BibTeX:
@misc{https://doi.org/10.34974/bdkq-0j86, doi = {10.34974/BDKQ-0J86}, url = {https://github.com/molssi-ai/e3nn-course}, author = {Mostafanejad, Mohammad}, keywords = {FOS: Physical sciences, FOS: Chemical sciences}, language = {en}, title = {Equivariant Graph Neural Networks with e3nn}, publisher = {The Molecular Sciences Software Institute}, year = {2026}, copyright = {MIT License} }