# Coding a neural network A guided, text-led MNIST lesson: **manual NumPy → explicit PyTorch tensors/autograd → PyTorch layers and SGD**. It assumes programming and matrix multiplication, but no Python ML tooling experience. ## Source of truth and page mapping **`content/lesson.md` → `index.html`**, one continuous webpage with eight teaching sections and one `article`. The complete manuscript contains goals, explanations, worked examples, literal code listings, controls, initial numerical readouts, 27 questions with full answers, transitions, and sources. Its clearly marked implementation-source appendix contains all shared interface wording and 40 alternate-message templates. The webpage and `content/compiled.json` are generated from that manuscript. JavaScript supplies computed values and chooses reviewed alternatives; it contains no independent lesson prose. The 15 Python excerpts are checked against the runnable source files when building. `verification/EDITORIAL_REVIEW.md` records the content review; `content/review.json` records the reviewed source hash. The initial HTML-first prototype was superseded by this Markdown-authored revision, not exported into Markdown. ## Open the webpage From the DigitRecognition project directory: ```bash python3 -m http.server 8786 --bind 127.0.0.1 --directory learning_assets/coding_lesson_interactive ``` Open **http://127.0.0.1:8786/**. Leave that terminal running; use another for the Python exercises. There are no webpage packages to install, no runtime CDN, and no cloud computation. Mathematical notation is pre-typeset using locally bundled KaTeX and fonts. The entry file is `index.html`. Use HTTP for working interactions. The full initial explanation, equations, and readouts are already in the generated HTML; they are not fetched as disconnected chapter fragments. ## What runs where - Browser arithmetic uses a checked JavaScript equivalent, **not a Python interpreter**. - Autograd-buffer and loss-contract experiments display explicitly labeled **recorded actual PyTorch runs**. - The Python project implements and trains the real 784 → 16 ReLU → 10 model. NumPy/PyTorch installation is needed only to run that project. - Browser experiments share fixed starting weights. The learning-step walkthrough changes a copy, not the baseline of another section. - The browser starts with B=1; the Python training configuration defaults to B=8. Browser choices do not edit configuration files. ## Run the Python project Download `coding_lesson_code.zip`, extract it, and open a terminal in `coding_lesson_code`. Work in this copy for your experiments. Tested on Apple Silicon with Python 3.13.5, NumPy 2.4.4, and PyTorch 2.14.0, using CPU float64. ```bash python3 -m venv .venv .venv/bin/python -m pip install -r requirements-numpy.txt .venv/bin/python python/train_numpy.py --config experiment.json --mode overfit .venv/bin/python -m pip install -r requirements-torch.txt .venv/bin/python python/torch_tensors.py --config experiment.json .venv/bin/python python/verify.py --config experiment.json .venv/bin/python python/train_torch.py --config experiment.json --mode overfit .venv/bin/python python/train_numpy.py --config experiment.json --mode train .venv/bin/python python/train_torch.py --config experiment.json --mode train ``` Windows PowerShell command variants are authored in the lesson; they were not directly executed during validation. No GPU, notebook, Node.js, or running webpage is required for the Python project. `overfit` repeats one fixed batch. `train` uses the 200-image teaching training split and evaluates the 100-image held-out split once afterward. Settings are explicit in `experiment.json`; missing settings cause an error. Scripts report results and exit; **trained weights are not saved**. ## Edit and rebuild the lesson Start every wording change in **`content/lesson.md`**, including dynamic observations and control labels. Review the changed manuscript before updating `content/review.json` with its new SHA-256. Do not change generated prose in HTML or JSON, or add new explanations in a JS renderer. Rebuilding requires Python, the build packages, and Node.js for local KaTeX rendering. These are build-time tools, not requirements for reading the webpage or running the Python training project. ```bash python3 -m venv .build-venv .build-venv/bin/python -m pip install -r requirements-build.txt .build-venv/bin/python tools/build.py .build-venv/bin/python tools/build.py --check ``` The build checks the reviewed hash, all Python excerpts, and an independent plain-Markdown versus HTML reading-order comparison. It generates the page, message templates, and parity expectations. All authored code files remain below 300 lines; generated HTML is compact, while the complete Markdown remains readable. To regenerate the numerical browser evidence after a model change: ```bash .venv/bin/python python/verify.py --config experiment.json --export ``` Changing this lesson's actual numerical baseline also requires reviewing/updating the manuscript's concrete values and rebuilding. The web lesson deliberately teaches the fixed 16-unit example; use the downloaded Python copy for architecture experiments. Rebuild the Python-only download after Python edits with `python3 verification/package.py`. ## Verification ```bash # Actual Python numerical comparison .venv/bin/python python/verify.py --config experiment.json # Generated text/source parity .build-venv/bin/python tools/build.py --check # Optional developer checks, Node.js 22+ npm test npm run test:browser ``` The browser suite uses a Chromium-family debugging browser already opened to this lesson on port **9437**, as configured in `lesson.json`. It checks the complete initial reading order, 126 static text units, 18 initial readouts, all 40 template variants, all controls/questions, proper fractions, state isolation, navigation, keyboard focus, and desktop/narrow layouts. The design uses the skill's paper/sage/forest-green palette and typography. The layout breakpoint is 850px, recorded in `lesson.css`. The page does not shrink body text or fractions to fit a narrow viewport; large tables/code/equations may scroll internally. ## Data, math rendering, and limits Images are genuine MNIST by Yann LeCun, Corinna Cortes, and Christopher J. C. Burges. The local subset retains original train/test indices from . Archive SHA-256: `731c5ac602752760c8e48fbffcf8c3b850d9dc2a2aedcf2cc48468fc17b673d1`. KaTeX 0.16.22 is locally bundled with its MIT license under `vendor/katex/`. Python, NumPy, and PyTorch sources actually consulted are listed in the manuscript and webpage. Numerical verification is not a full-MNIST benchmark or a guarantee of generalization. See `verification/VALIDATION.md` for the checks performed.