Repoint mlsysim.core.<engine-mod> -> mlsysim.engine.<mod>, the
from-mlsysim.core-import-calibration form, and mlsysim.infra -> mlsysim.infrastructure
across the deferred consumers: docs prose + tutorials, tutorial slides/cheatsheet/
exercises, paper.tex, README, cli/DESIGN.md, and the mlsysim_constants audit README.
Also fix two docstrings inside the moved engine modules (calibration.py, pipeline.py)
that still named the old core paths. Update the quartodoc config (sections list) to
the new module paths and add the engine package.
NOTE: the generated quartodoc API stubs under mlsysim/docs/api/ (core.*.qmd,
infra*.qmd) still carry the old paths — they regenerate from the updated config via
`quartodoc build` (toolchain not installed in this worktree), so they are left
untouched here rather than hand-edited. Run `quartodoc build` to refresh them.
482 passed; import clean.
Pure rename so the package name matches its public namespace (Infrastructure).
All internal + example + doc importers repointed; public mlsysim.Infrastructure
unchanged. Generated docs/api/infra*.qmd stubs left for quartodoc regen (P10).
482 passed, import clean.
- Updated all GitHub Actions workflows (build-pdfs, preview-dev, publish-live, update-pdfs) to loop over `tutorial_module1` through `tutorial_module4` instead of the legacy `part1`/`part2`.
- Updated Quarto documentation (`slides.qmd`, `_quarto-html.yml`) to correctly surface the 4 new module PDFs on the website.
- Updated the tutorial Makefile to compile all 4 modules.
- Updated `.gitignore` and instructor quickstart documentation to reflect the new slide outputs.
- Split the previous 'Part 1' and 'Part 2' monolithic presentations into four distinct, pedagogically cohesive modules (Module 1 through 4) suitable for a Half-Day or Full-Day conference tutorial.
- Module 1 (Foundations & Architecture): Added slides on the new Pydantic registries, the Provenance system ('Zero Hallucinations'), and dimensional strictness with 'pint'.
- Module 2 (Advanced Single-Node Analysis): Integrated the new 'Reasoning Wall' (InferenceScalingModel) and the Data Wall.
- Module 3 (Scale, Dollars, and Carbon): Integrated Cross-Domain Carbon Accounting (Cookbook Scenario B).
- Module 4 (DSE & Synthesis): Integrated SLA-Driven Synthesis (Cookbook Scenario D).
- Replaced fragmented code snippets with the concrete, runnable scenarios from the paper's Code Examples Cookbook.
Align part 1/2 slide imports with post-migration solver paths, add registry API stubs, extend doc CI to scan .tex slides, and fix release-note examples.
Delete the catch-all defaults module and relocate assumptions into
Literature, Systems, Infrastructure, Ops, Platforms, and core.calibration.
Update textbook QMD cells, labs, audit tooling, and CI gates so registry
paths are authoritative with no package-root aliases or defaults shims.
Switches 35 chapter decks (slides/vol1 + slides/vol2) and 2 mlsysim
tutorial decks (mlsysim/tutorial/slides/tutorial_part{1,2}.tex) from
xelatex+fontspec+texgyreheros to pdflatex+helvet+courier.
Why
---
Yesterday's slides-publish-live shipped PDFs with completely blank text
(see https://github.com/harvard-edge/cs249r_book/releases/download/
slides-latest/vol1_00_course_overview.pdf — Liberation Sans was
embedded but glyphs were missing because xelatex on Ubuntu CI could
not find texgyreheros.otf and silently fell back). The mlsysim
tutorial decks fared no better, requiring four rounds of fixes
(Helvetica Neue → texgyreheros → tex-gyre apt + mktexlsr → Latin
Modern) before they would even compile.
The root cause is engine choice: fontspec on xelatex makes runtime
OS-font discovery the build's critical path. If the host TeX install
or fontconfig doesn't have the requested font, fontspec either errors
hard (mlsysim's experience) or silently substitutes (slides' silent
broken-PDF failure mode). Either way the build is fragile.
paper.tex has been using pdflatex+helvet+mathpazo+courier for months
without a single font issue. Bringing slides + mlsysim tutorial onto
the same engine + font convention eliminates the entire failure class.
Changes
-------
* 35 chapter decks: replace
\usepackage{fontspec}
\setsansfont{texgyreheros}[Extension=.otf, ...]
\setmonofont{texgyrecursor}[Extension=.otf, ...]
with
\usepackage[T1]{fontenc}
\usepackage[scaled=0.9]{helvet}
\usepackage{courier}
\renewcommand{\familydefault}{\sfdefault}
Same Helvetica-class look (NimbusSans = URW's Helvetica clone in
helvet), shipped via texlive-fonts-recommended Depends.
* 2 mlsysim tutorial decks: same swap (was Latin Modern from the prior
retry).
* slides/Makefile: LATEX := xelatex → pdflatex.
* mlsysim/tutorial/Makefile: same.
* slides-build-pdfs.yml: drop texlive-xetex (engine), drop
texlive-fonts-extra (was for tex-gyre). Result: smaller apt-install,
no fontspec silent-fallback class of bugs.
* mlsysim-build-pdfs.yml: same engine + apt cleanup; drop JetBrains
Mono manual fc-cache step (we no longer reference JetBrains Mono).
Bar copy
--------
* mlsysim/docs/config/announcement.yml: append Lecture Slides to the
"Alongside the book" row — the mlsysim tutorial deliverable IS slides,
so cross-linking is natural.
* site/config/announcement.yml: drop the "🎓 Teach with it: Lecture
Slides · Instructor Hub" line entirely from the landing bar. Landing
is for learners; teachers find Instructor Hub via the navbar Teach
menu, and Slides via Instructor Hub.
Verification
------------
Local Mac builds with pdflatex:
- vol1/01_introduction: 52 pages, NimbusSans-Regu/Bold embedded
- vol2/05_distributed_training: 48 pages, NimbusSans embedded
- mlsysim tutorial_part1: 90 pages, NimbusSans embedded
- mlsysim tutorial_part2: 47 pages, NimbusSans embedded
All Type 1, sub-set, Unicode tag yes — renders cleanly.
After three rounds of trying to get texgyreheros to resolve on the
Ubuntu mlsysim-build-pdfs runner (explicit `tex-gyre` apt install,
explicit `mktexlsr` post-install, 40-min job timeout), xelatex still
errored with 'The font texgyreheros-regular cannot be found'. The .otf
files were present on disk but invisible to kpsewhich; the slides-build
workflow with the same package set somehow finds them, the mlsysim
workflow doesn't, and that environmental delta is opaque after several
diagnostic passes.
Switch the tutorial decks to Latin Modern Sans / Mono via file-pattern
lookup against the `lm` family (lmsans10, lmmono10). These ship in
the `lmodern` apt package which is a hard Depends already installed
in the workflow and which the Mac TeX Live install also has — both
environments resolve cleanly.
Visual cost: tutorial decks now use Latin Modern instead of a Helvetica
clone — slightly more 'TeX-looking' than the chapter decks, but
internally consistent and pixel-stable across macOS and Ubuntu. Local
Mac build verified: 47-page PDFs, fonts embedded as LMSans10 +
LMMono10.
Strategic note: the chapter decks still use texgyreheros and work on
their own runner. We could unify both onto Latin Modern in a follow-up,
or unify both onto texgyreheros once the package-resolution mystery
is understood — see proposed composite `setup-texlive` action.
The tutorial decks use the canonical lecture-deck font pattern
(\setsansfont{texgyreheros}[Extension=.otf, UprightFont=*-regular,
...]) which routes through kpsewhich on the texmf tree. On Ubuntu the
matching .otf files ship in the standalone `tex-gyre` apt package,
which is only a *Suggests* of texlive-fonts-extra — never a Depends.
The mlsysim-build-pdfs workflow uses --no-install-recommends, which
filters out both Recommends and Suggests, so tex-gyre was never
installed. xelatex then failed with:
! Package fontspec Error: The font "texgyreheros-regular"
cannot be found.
Pin tex-gyre into the apt install list explicitly. Leaves the .tex
preambles on the canonical lecture-deck pattern (which works on macOS
TeX Live for the same kpsewhich reason). Mac local build verified
producing 47-page PDFs with TeXGyreHeros + TeXGyreCursor embedded.
Both tutorial deck preambles were hardcoded to Helvetica Neue (Apple-only)
and Courier New (Microsoft-only), which broke xelatex on the Ubuntu runner
with `Package fontspec Error: The font "Helvetica Neue" cannot be found`.
This blocked the entire mlsysim-publish-live pipeline (PDF build job
failure cascaded to skip deploy).
Switch to the same texgyreheros/texgyrecursor pattern already in use by
every lecture deck (slides/vol1/01_introduction et al.). Those fonts ship
with texlive-fonts-extra, which mlsysim-build-pdfs.yml already installs,
so no workflow change is needed and macOS builds are visually unchanged
(TeX Gyre Heros is the canonical Helvetica clone).
Verified locally with `cd mlsysim/tutorial && make slides`: both decks
build, pdffonts confirms TeXGyreHeros + TeXGyreCursor embedded.
Replaced bare Metropolis with the mlsys Beamer theme used by the
textbook lecture slides. Both decks now have:
- Crimson section navigation bar in header
- Branded footer (book logo + Harvard logo + page numbers)
- Helvetica Neue body font + JetBrains Mono/Courier code font
- Section divider pages with progress indicator
- \mlsysfocus for key equation slides
Part 1: 90 pages, 0 errors. Part 2: 47 pages, 0 errors.
1. Added 'Understanding eta' slide with table and CPI analogy (before first demo)
2. Added concrete AllReduce example with numbers BEFORE formula
3. Added 'Compression Changes Fleet Architecture' slide with cost table
Addresses top 3 issues from simulation feedback round 1.
- Changed A100-vs-H100 comparisons to H100-vs-MI300X-vs-Gaudi3 three-way
- Added Hardware Zoo slide showing all 22 platforms across 6 vendors
- Added timing markers [N min] to speaker notes throughout
- Added "turn to your neighbor" discussion prompts after predict slides
- Added roadmap "You Are Here" slides after each break
- Stripped code boilerplate (import only shown once, aliases for later demos)
- Added figure references for new SVGs (multi-vendor-roofline, parallelism-3d,
memory-hierarchy, pareto-front)
- Updated related_work.tex comparison table to highlight vendor breadth
1. Added $200M opening hook (2 slides before learning objectives)
2. Wired \input{related_work} between Part 0 and Part 1
3. Replaced figure placeholders with real SVG PDFs (carbon, hardware)
4. Added predict-then-reveal prompts before Aha #3 (256 GPU scaling)
and Aha #4 (INT4 fleet halving)
5. Added "Name That Wall" personal transfer moment before closing
Addresses all 5 P0 blockers from Patterson's presentation review.
All font-size values < 10px bumped to 9.5-11px minimum across all 6
figures. At 900x500 viewBox on a 16:9 projection, this ensures text
is readable from the back of a 300-person room.
Parts 5-9 were lecture-only (0 code blocks). Now every section has
live demo code using real mlsysim API: EconomicsModel, SustainabilityModel,
DSE search, Engine.sweep, ESP32/nRF52840/H100 comparison, Pipeline
composition, SensitivitySolver, capstone starter code.
Figure placeholders added for carbon-geography and hardware-spectrum SVGs.
Comparison table of 7 tools (ASTRA-sim, Calculon, DeepSpeed, LLMPerf, etc.).
Fidelity-speed spectrum TikZ diagram. Honest 'What We Don't Do' slide.
Iron Law wall-to-term mapping. CPI analogy for the efficiency parameter.
22 walls at a glance compact table. Designed for \input{} into main deck.
