Volume I is in print, so the goal was consistency with the fewest changes.
A 17-auditor read of vol1 against the notation table found 284 distinct
findings; one fixer per chapter applied the regressions (23, from the
earlier pattern-based passes), mechanical fixes (208), and the approved
conventions, matching the surrounding prose.
Notation table (prints in vol1):
- Errata: the subscript sentence (the subscript is upright, not the
root); the decimal-units rule now states the nameplate-capacity
exception the assumptions appendix already used; notes no longer
point at symbols the table never defines.
- Rows only where chapters improvised for want of one: d_in/d_out,
y-hat, T_distill, T_memory/T_compute, N_GPU, L_lat,total, s_sample,
s_loss; sentences for GEMM M,N,K, \mathcal{O}, l_p norms, mu, power
subscripts, and upright p99.
Structure for four volumes:
- The shared body is split into a series core (head + tail, printed in
every volume) and a vol1-only degradation extension, so vol2-4 no
longer print tau/lambda meanings their extensions use differently.
Vol1's assembled text differs only by the intended edits.
- New `binder check notation --scope vol1-print-pin`: fails when vol1's
printed notation text changes; re-pin only for an approved erratum
(binder/tools/audit/repin_vol1_notation.py).
- Tooling updated for the new file names (notation, currency-style,
layout, math-render audits).
Also restores footnote markers and index tags dropped by the figure
reference rewrites (5 footnotes, 6 index entries), fixes the MIT Press
spellings and abbreviation expansions those rewrites introduced, a
residual-block Jacobian evaluated at the wrong layer, and the Kaplan
exponent arithmetic in Appendix B. Margin SVGs regenerated from the
generator for p99, r_pipe, and nameplate GB labels; TikZ labels updated
to the same symbols. Vol1 PDF builds cleanly with all validations.
Pre-commit: skipped book-check-footnotes, -code, -prose, -punctuation,
-numbers, -notation. Every remaining failure in them is pre-existing on
dev (vol2-4, plus unchanged vol1 percent and literal-number items); the
vol1 notation and pin scopes pass.
TinyTorch, MLSys·im, MLPerf EDU, the slides, and the instructor site return
from packages/ and materials/ to the top level, so each folder carries the
name of its site URL (tinytorch/ is mlsysbook.ai/tinytorch/). main still has
this layout, so the GitHub links on the published pages, existing tito
installs, and the release hashes keep working.
References follow: workflows, the binder toolchain, book configs, tests,
docs, contributor tooling, .gitignore, and pre-commit patterns. Relative
paths inside the moved projects drop the extra ../ they gained under
packages/ and materials/, which also repairs the MLSys·im contributing guide
and tutorial decks that pointed at the removed slides symlink. The TinyTorch
installer and updater return to a single sparse path. REPO_LAYOUT.md and
CI-VARIABLES.md describe the result.
The top-level mlsysim, tinytorch, mlperf-edu, slides, and instructors
entries were symlinks into packages/ and materials/. Every reference now
names the real path, and the symlinks are removed.
- Workflows: path filters, working directories, artifact and publish
paths, and the TINYTORCH_SITE, MLSYSIM_DOCS, SLIDES_ROOT, and
INSTRUCTORS_ROOT variables, which now carry fallbacks. The gh-pages
deploy trees and the site URLs keep their top-level names.
- Book builds: PYTHONPATH in the PDF configs and execute-env.yml points
at packages/mlsysim. The execute-env.yml value was still written for
the old publishing/quarto project root.
- The binder toolchain, labs, and tests load mlsysim from
packages/mlsysim, and the root pytest config puts it on sys.path. That
clears the binder test failures caused by importing the symlink as a
namespace package (now 362 passed).
- The TinyTorch installer and `tito system update` fetch packages/tinytorch
and fall back to tinytorch/ for tags that predate the move. Binder launch
links and postBuild open packages/tinytorch.
- READMEs, CONTRIBUTING, SECURITY, contributor tooling, area labels,
.gitignore, and pre-commit patterns name the real paths.
A repository variable that still holds an old top-level path overrides
the new fallback and breaks its workflow, so those variables need
updating before these workflows run.
The toolchain folder is now binder/, and the root ./binder symlink is gone.
The command is ./binder/binder: a plain path to the script, with no link and
no install step. Every invocation moved with it: pre-commit entries, workflow
steps, the VS Code extension's command palette, help text, and docs.
- bindery/ paths and bindery.* imports, including the chapter code cells
that import binder.tools.figures, now name binder/.
- Binder (mybinder.org) reads its configuration from a root binder/ folder
and refuses to build when binder/ and .binder/ both exist. .binder/postBuild
and .binder/requirements.txt move into binder/, so the TinyTorch "Launch
Binder" buttons keep working; binder/README.md records which file names the
toolchain must not use there.
- contributors/projects.json still pointed the book's contributor record at
publishing/; it now names binder/, where that .all-contributorsrc lives.
- The margin-figure reader-link audit report linked its 222 figures through
the retired quarto/ tree; the links now resolve under books/.
The hooks reformatted hidden Python cells and trimmed whitespace in the
Volume II chapters whose figure imports this rename touches.
Checks: ./binder/binder check cli passes (contract and canonical hooks),
binder.tools.figures imports, and every workflow YAML file parses.
binder test suite, excluding the four modules that cannot import mlsysim
through the root symlink (fixed separately): 7 failed, 346 passed.
The GitHub repository variables BOOK_ROOT, BOOK_TOOLS, BOOK_DEPS, and
BOOK_DOCKER still name the retired book/ layout and must change when this
reaches origin.