Setting up the environment

Setting up the environment#

You do not need a local install to read this book: every lesson page shows its stored outputs, figures and training curves. You need an environment only when you want to run and modify the code on your own machine.

Local installation#

The project is managed with uv. If you don’t have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then:

git clone https://github.com/molssi-ai/e3nn-course.git  # Clone the repository
cd e3nn-course                # Change directory into the repository root

uv sync                       # Create .venv from pyproject.toml + uv.lock
source .venv/bin/activate     # Activate it

uv run jupyter lab            # Launch JupyterLab

Every notebook records the standard python3 kernel, which uv run jupyter lab resolves to this .venv automatically. So, there is nothing else to configure. If you prefer the environment to appear under its own name in the kernel selector (useful when you juggle several projects), you can register it explicitly:

.venv/bin/python -m ipykernel install --user --name e3nn-course \
                 --display-name "Python (e3nn-course)"

Requirements: Python ≥ 3.13 and PyTorch 2.7.1. A CUDA GPU is optional: every training cell in the course is sized to finish in \(\leq\) 2 min on a GPU or \(\leq\) 10 min on CPU.

Verify the installation#

Run the following code block in a fresh notebook cell or with python -c. It builds an equivariant tensor product and checks it numerically against a random rotation:

# From the repository root
import sys; sys.path.insert(0, ".")      
import torch
from e3nn import o3
from course_utils.equivariance import model_equivariance_error

torch.set_default_dtype(torch.float64)

tp = o3.FullyConnectedTensorProduct("1o", "1o", "0e + 1o + 2e")
err = model_equivariance_error(tp, [o3.Irreps("1o"), o3.Irreps("1o")], o3.Irreps("0e + 1o + 2e"))
print(f"torch {torch.__version__} | equivariance error: {err:.2e}")

You should see an error around 1e-15. Anything near 1e-6 means the default dtype is still float32; anything larger means something is genuinely wrong. Please open an issue and provide a minimalistic and reproducible code snippet that generates the error.

What the environment contains#

Package

Used for

torch 2.7.1

tensors, autograd, training

e3nn

irreps, spherical harmonics, tensor products, gates

torch-geometric

graph batching and scatter operations

ase

atomistic structures, neighbor lists, MD integrators (Lesson 11)

matplotlib

static figures

plotly

the rotatable 3D figures (spherical harmonics, graphs, trajectories)

sympy

symbolic Clebsch–Gordan and Wigner algebra

Shared helpers live in course_utils/ and are imported by every lesson:

  • course_utils.equivariance: the numerical equivariance test harness

  • course_utils.plotting: spherical harmonics, irreps, point clouds, training curves

  • course_utils.data: small datasets, neighbor lists, train/val splits

Rebuilding this book locally#

The book is built with Jupyter Book 1.x from a separate, lightweight environment. It does not need torch or e3nn, because it renders the outputs already stored in the notebooks:

uv venv --python 3.13 .venv-docs # Create a separate environment for the docs
uv pip install --python .venv-docs/bin/python -r book/requirements-docs.txt # Install Jupyter Book

Then, from the repository root directory:

make -C book html      # Build the HTML book at book/_build/html
make -C book serve     # Serve at http://localhost:8000

See How to use this book for the notebook-execution workflow that keeps those stored outputs current.