nndl-practice: a PyTorch companion repository that builds its own training framework chapter by chapter

The gap between reading a backpropagation derivation and writing one

Most deep learning books end a chapter with a formula and start the next one with a library call. The reader can follow the derivation and still not know what a convolution loop looks like when the padding is asymmetric, or why a loss function returns a scalar instead of a per-sample vector. nndl-practice is built against that gap. The README describes the book's approach as putting model, principle and engineering practice on one line: understand the model, implement the key components from scratch in PyTorch, then apply them to a runnable case. Ten chapters cover linear models, feedforward networks, convolutional networks, recurrent networks, optimization and regularization, attention, graph neural networks, and large language models with agents. The stated audience is students and engineers with Python basics who want hands-on work and who may read it alongside the theory book. Chapter 1 assumes no data download, which tells you the entry point is deliberately low-friction: tensors, broadcasting, autograd, nn.Module, Dataset and DataLoader. The repository also carries a historical layer. It was renamed from nndl/exercise, the legacy directory holds NumPy and early PyTorch exercises from the first edition of the theory book, and the 2022 PaddlePaddle companion lives in a separate repository, nndl/practice-in-paddle, with eight chapters. If you are looking for the PaddlePaddle version, you are in the wrong place.

RunnerV1, RunnerV2, RunnerV3: a framework that grows in front of you

The mechanism that separates this repository from a folder of notebooks is the nndl package under pytorch/nndl/. It is not introduced all at once. Chapter 2 presents RunnerV1, which the README ties to closed-form solving, evaluation, prediction and parameter saving. Chapter 3 adds RunnerV2 for gradient training, validation-set evaluation and saving the best model. Chapter 4 brings RunnerV3, which uses DataLoader, state_dict, decoupled metrics and a training history. The README states the rule explicitly: notebooks show the full implementation the first time a key component appears, and later chapters reuse the engineered version through from nndl import. That rule is the whole design. It means you can read chapter 5's from-scratch convolution and then see the same idea consumed as a library call in a later chapter. It also means the package's shape is a record of the book's pedagogical order, not a design someone would choose from scratch. A single Runner class that changes signature three times across three chapters is a teaching artifact. If you copy RunnerV3 into a project, you are copying an object whose API was determined by what chapter 4 needed to explain.

Getting a notebook open: Python 3.11+, PyTorch 2.7+, and a CPU wheel

The README gives a concrete sequence. Clone the repository, create a virtual environment with python -m venv .venv, activate it (source .venv/bin/activate on macOS or Linux, .venv\Scripts\Activate.ps1 in Windows PowerShell), then install the CPU build on Windows or Linux with python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu. macOS and NVIDIA GPU users are pointed at the official PyTorch install page to pick a platform command instead. After that, python -m pip install -r pytorch/requirements.txt installs the remaining dependencies, and python -m jupyter notebook "pytorch/chap1实践基础/实践基础.ipynb" opens the first chapter. Note the directory names: the chapter folders use Chinese characters, so quoting the path matters in a shell. The stated environment requirement is 64-bit Python 3.11 or newer and PyTorch 2.7 or newer. Notebooks default to CPU. Chapters 5, 6, 8, 9 and 10 contain long training runs, and the README instructs readers to pick a short configuration from each chapter's notes before starting. Data preparation is only needed for some chapters: chapter 1 needs nothing, while chapters 6 and 8 require IMDB and LCQMC respectively, with commands and cache locations documented in pytorch/README.md. That split matters. A first pass through chapters 1 to 5 does not require you to download a dataset before you can see anything run.

The pytest suite checks shapes and conclusions, not accuracy

Each chapter ships a set of sanity tests. The README describes them as checking key operators, model shapes and core conclusions, and gives two commands: python -m pytest pytorch/tests/ -v for the whole suite, and python -m pytest pytorch/tests/test_chap8.py -v for a single chapter. The word sanity is doing real work here. A test that asserts a tensor shape or that a hand-written gradient matches an autograd gradient is a correctness check on an implementation. It is not a claim about model quality, and the README makes no such claim. This is a reasonable design for a book repository, because the failure mode a reader actually hits is a shape mismatch or a sign error in a manual backward pass, not a two-point drop in test accuracy. The limitation follows from the same choice: nothing in the described suite tells you whether a training run converged, and nothing pins the numerical output of a full training loop. If you are trying to reproduce a number from the book, the tests will not confirm it for you.

Where this repository is the wrong tool

The README states plainly that the second edition is in pre-publication preparation and that the PDF and companion code will keep being updated before publication. It also warns that the repository and the manuscript share the same ten-chapter structure but are both still being revised, so individual code, outputs or page numbers may fall out of sync in the short term. When reporting a discrepancy, the README asks you to include the manuscript date, chapter, notebook name and specific cell. Read that as a description of the repository's current state rather than a caveat: you are working with a moving target. The second limitation is structural. The nndl package is organized around explanation. Its operators, losses and optimizers expand chapter by chapter toward CNN, RNN and attention, which means the package surface is a teaching sequence. Using it as a training library means inheriting an API that was shaped by what each chapter needed to demonstrate, and inheriting its revision schedule. The third limitation is compute. Long training in chapters 5, 6, 8, 9 and 10 on default CPU settings is the practical barrier for anyone without a GPU, and the README's answer is to use the short configurations rather than to promise the full runs are cheap. If your goal is a tuned model on a real dataset, a textbook companion is the wrong starting point.

How it differs from the PaddlePaddle first edition and the legacy exercises

The repository's own version table makes the comparison concrete. The first edition's companion code, nndl/practice-in-paddle, corresponds to the 2022 published book and has eight chapters, and its framework is PaddlePaddle. The second edition has ten chapters and is PyTorch. The extra chapters are not a cosmetic expansion: the table lists attention with multi-head attention, positional encoding and Transformer in chapter 8, graph neural networks with GCN, GraphSAGE, GAT and GIN in chapter 9, and chapter 10 covering nanoGPT, decoding and KV cache, LoRA, SFT, DPO, ReAct and RAG. The legacy directory is a third thing again: the original nndl/exercise content, using NumPy and early PyTorch, kept as an archive. So the choice is not between two equivalent ports. If you want the material that covers graph networks and a small GPT implementation, only the PyTorch line has it, and only in a pre-publication state. If you need a stable, published reference with a fixed chapter list, the eight-chapter PaddlePaddle edition is the one that has already shipped. The difference in approach is the framework, not just the tensor library: both editions build their own training loop rather than wrapping a high-level trainer, which is the point of the exercise in either language.

Maintenance, licence status, and what the repository does not tell you

The repository is not archived, and the most recent push recorded here is 2026-09-07. The only listed release is book-pdf, published 2026-06-22, which the README links as the full-book PDF download. The README's maintenance notes are thin and specific: _meta.yml is the data source for the book cards on the main site, and the site build aggregates book metadata through nndl.github.io/scripts/aggregate-books.py. Beyond that, the README does not describe a compatibility policy, a support window, or what happens to the notebooks after publication. The licence is listed as unknown in the material available here, and the README does not state one either. That is a real gap, not a formality. Without a declared licence you cannot tell what redistribution, modification or commercial reuse is permitted for the code, the notebooks or the PDF, and the PDF is a separate artifact from the code in any case. Treat the licence question as unresolved until you find a licence file or a statement in the repository, and do not assume that a public repository implies permissive terms. Upgrading is the other open cost. The stated floor is PyTorch 2.7 and Python 3.11, and since the code is a teaching sequence rather than a pinned library, a future PyTorch release that changes an operator signature would surface as a broken chapter, not as a version constraint you can read off a manifest. The pytest suite is the closest thing to a compatibility check, and it is per chapter.

Editorial conclusion

Adopt nndl-practice if you want to implement convolutions, attention and a small GPT by hand in PyTorch and you accept that the text and code may drift apart before publication. Do not adopt it as a dependency for a production training pipeline: the nndl package exists to expose mechanisms, not to serve models. Before committing time, verify two things yourself: that pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu resolves on your platform, and that python -m pytest pytorch/tests/ -v passes on the chapter you intend to study. If those two commands fail, the rest of the repository will not help you.

Official sources

1. Issues
2. nndl/nndl-practice on GitHub
3. Project website
4. README
5. Releases