How to use this book

How to use this book#

Reading a lesson#

Every lesson follows the same rhythm, so you always know where you are:

  1. Header: the lesson number and title, a “What you will learn” list, and prerequisites;

  2. Setup cell: imports, seeds, device selection. No hidden magic; you can always see exactly what is in scope;

  3. Sections, equations first: a markdown cell stating the mathematics, then a short code cell (\(\leq\) 25 lines) implementing the theoretical concept;

  4. Equivariance check: every new equivariant operation is immediately tested numerically;

  5. Visualization: at least one figure per major concept;

  6. Summary: what was built, and a pointer to the next lesson;

  7. Exercises: rated 🌶️ to 🌶️🌶️🌶️ (see below), with solutions hidden behind collapsible blocks. Try them yourself first before expanding the solution.

The buttons in the top-right#

The four GitHub actions share one menu; the rest are buttons of their own.

Button

What it does

Repository

Opens the course on GitHub: the source of every lesson, helper and figure.

Show source

Opens this page’s unrendered source on GitHub: to access the notebook itself rather than the built page.

Suggest edit

Jumps straight to this page’s source on GitHub.

Open issue

Starts a new issue on the course repository, with this page already filled into the title.

Download

Grabs the raw .ipynb, or renders a printable PDF of the lesson via your browser’s print dialog.

Fullscreen

Switch to fullscreen mode.

Color mode

Cycles between your system setting, dark and light; the icon shows the mode in effect.

Tip

To run a lesson, download it (or clone the repository) and open it from the repository’s notebooks/ directory, so that the setup cell’s sys.path.insert(0, "..") puts course_utils/ on the path. See Setting up the environment.

Interactive figures#

Figures rendered with Plotly are live: drag to rotate, scroll to zoom, double-click to reset. These are used where 3D orientation genuinely carries the meaning: spherical harmonics, atomistic graphs and cutoff spheres, and MD trajectories. Static Matplotlib figures are used everywhere else, deliberately, because they are cheaper and print well.

The pages are laid out to use the full width of your screen; on a wide monitor the 3D figures and the tensor-product tables get considerably more room. Use the fullscreen button for more space.

Exercise difficulty#

Every exercise carries a chilli rating in its title, so you can pick what suits the time you have:

meaning

typically

🌶️

Easy. Apply a rule the lesson just stated, or run and read off a result. Often a few lines built on code already in the notebook.

5-15 minutes

🌶️🌶️

Moderate. Modify the lesson’s code and interpret what changes, derive a result and verify it numerically, or run a single training job and explain the outcome.

30-60 minutes

🌶️🌶️🌶️

Hard. Prove something on paper, build a component that is not in the lesson, or run several experiments and compare them. Expect open-ended reasoning rather than one right number.

an hour or more

The ratings measure effort and open-endedness, not importance. Several of the three-chilli exercises are the ones that make a lesson’s point land hardest, and the deliberate-sabotage ones (break the envelope, break the symmetry, break the equivariance) are worth the time precisely because a model that has stopped being equivariant looks perfectly healthy until you test it.

Timings assume you have read the lesson and are running on the course environment. Anything involving training is quoted for a GPU, and will take substantially longer on a CPU.

Suggested paths through the course#

The full course (recommended). Lessons 01a \(\rightarrow\) 11 in order. Roughly 15-30 minutes of reading per notebook, plus exercises.

“I just want to build MACE.” 02a \(\rightarrow\) 02b \(\rightarrow\) 03a \(\rightarrow\) 03b \(\rightarrow\) 04 \(\rightarrow\) 06a \(\rightarrow\) 10a \(\rightarrow\) 10b \(\rightarrow\) 10c. You will miss the invariant-baseline contrast, but the equivariant machinery is self-contained.

“I know e3nn, I want the potentials.” Skim Part I, then 05a \(\rightarrow\) 06a \(\rightarrow\) 08a \(\rightarrow\) 08b \(\rightarrow\) 09a \(\rightarrow\) 09b \(\rightarrow\) 10b \(\rightarrow\) 10c \(\rightarrow\) 11.

“I’m here for the theory.” The *a notebooks mainly focus on the theory, but other notebooks may offer additional theoretical content as well: 01a, 01b, 02a, 03a, 08a, 09a, 10a, 10b.

Running and modifying the code#

Running the lesson notebooks requires a local Python environment with PyTorch installed. See Setting up the environment.

Keeping stored outputs current#

This book renders the outputs already stored in each .ipynb, rather than re-executing on every build. That is a deliberate choice: several lessons train models, and a CPU-only CI runner would need approximately 45 minutes and could fail the deploy on a single flaky cell. Stored outputs also mean the published figures are the ones produced on real hardware.

The cost is that outputs can drift from code. To refresh them after editing a lesson:

# Re-execute one notebook in place (uses the project .venv, so torch + GPU should be available).
python book/scripts/execute_notebooks.py notebooks/04_nonlinearities_and_gates.ipynb

# Re-execute every notebook that has at least one output-less code cell.
python book/scripts/execute_notebooks.py --missing-only

# Re-execute everything (slow: trains all the models).
python book/scripts/execute_notebooks.py --all

Then, check nothing was left behind and rebuild:

# Reports code cells with no stored output
python book/scripts/check_outputs.py

# Rebuilds the HTML book
make -C book html

check_outputs.py also runs in CI as a non-blocking report, so a pull request that adds an unexecuted cell is visible in the build log rather than silently shipping a code block with no result.

Contributing#

The authoring style guide is the contract every notebook follows: structure, citation format, the shared math notation, code conventions, and figure rules. Read it before opening a pull request.

We welcome corrections, clarifications and new exercises. Please open an issue before starting a pull request, so we can discuss the change and avoid duplicated work. See: github.com/molssi-ai/e3nn-course.