The MLSysIM taxonomy refactor moved the solver classes from core.solver to
engine.solver and regenerated the quartodoc API stubs accordingly
(api/engine.solver.*.qmd), but five hand-written doc pages still linked to the
old api/core.solver.* paths, breaking 43 internal links (caught by
check-internal-links).
- solver-guide.qmd, models-and-solvers.qmd, math.qmd, zoo/infra.qmd,
zoo/datasets.qmd: repoint every api/core.solver.<Model> link to the existing
api/engine.solver.<Model> stub; table links that pointed at the bare module
page now point at the specific model page matching their link text.
- The generic "Solver API Reference" link → api/engine.qmd.
- Stale GitHub source link mlsysim/core/solver.py → mlsysim/engine/solver.py.
Run quartodoc build against the refactored package (engine/ extracted from core/,
infra->infrastructure): regenerate the API reference so every stub points at the new
paths. Adds engine.*/infrastructure.* stubs, removes the 41 stale core.solver.* /
core.engine.* / core.scenarios.* / core.config.* / core.evaluation.* / infra*.qmd
orphans, and refreshes the package pages (core now primitives-only) + index.
Verified: all 47 documented symbols resolve in the new package; every index link
resolves; zero stale mlsysim.core.<engine-mod> / mlsysim.infra references anywhere in
docs/. (objects.json inventory is gitignored -- regenerated at build.)
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.
- Extracted all hardcoded repository and slide download URLs into a central _variables.yml configuration file.
- Replaced 100+ hardcoded URL strings across the website documentation (.qmd, .md, and _quarto-html.yml) with {{< var slides_latest >}} and {{< var github_repo >}} shortcodes.
- Ensures the website correctly points to the canonical cs249r_book repository while enabling instantaneous, single-file URL updates in the future.
- 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.
- Ensured 100 percent docstring coverage for all internal private methods and functions across the codebase.
- Documented private optimization backends, plugin loaders, CLI formatting hooks, and provenance auditing utilities.
- Makes the codebase fully self-documenting for open-source contributors navigating the internals.
- Added 'make docs', 'make docs-preview', and 'make audit' targets to Makefile for easier local development.
- Added comprehensive README.md to the vscode-ext workbench extension.
- Refactored test_engine.py to dynamically import calibration constants rather than hardcoding physics assumptions, ensuring tests don't break if base parameters are tuned.
- Fixed a registry path alias in philosophy.qmd caught by the doc drift linter.
- Replaced default light-blue stroke colors with the site's primary accent color (#0284c7) for consistency.
- Applied the highlighting style to the Solvers layer (Layer E) across all architectural diagrams.
- Added Mermaid diagram illustrating the Provenance chain in philosophy.qmd.
- Added Mermaid diagram illustrating the Demand vs. Supply abstraction in philosophy.qmd.
- Added Mermaid diagram illustrating the 3-Tier Resolver Architecture in models-and-solvers.qmd.
Set Quarto figure defaults, cap notebook image width in site CSS, export web plots at 120 DPI, and let Quarto capture matplotlib figures without fig.show().
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.
Resolve training.qmd conflicts: keep UtilizationGap ProfilingScenarios cell,
drop duplicate static tables in favor of LEGO-generated tables, fix loss-scaling
math to use MarkdownStr equation exports. Tutorial docs use shared includes.
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.
Adds provenance_catalog records, metadata.provenance on every hardware/model
zoo entry, infra grid profiles, and catalog-linked TraceableConstants; CI
enforces via test_provenance_audit and audit_provenance --strict.
Remove BERT/ResNet/MobileNet/YOLO/KWS/AlexNet/WakeVision symbols now canonical in
Models.*; fix BERT-Large inference_flops to 72 GFLOPs and extend parity tests.
Wire registry parity tests, inline fabric bit-rates in Systems.Fabrics, and update
labs, tutorials, and unit tests to use registry paths instead of loose constants.
Establish verified dead-symbol inventory and chapter-level migration manifest
so registry cleanup can proceed with parity gates and one commit per step.
Codex chapter-by-chapter audit findings applied across vol1 and vol2:
prose rewrites where the cited source supported only a narrower or
adjacent claim, plus new audit tooling
(book/tools/scripts/build_citation_reference_packets.py and the
companion workflow doc).
Author-form cleanup pass on top of the audit:
- 19 narrative @key conversions where prose already named the author
(e.g., "Sambasivan et al. describe ... [@sambasivan2021]" -> narrative
"@sambasivan2021 describe ...", rendering "Sambasivan et al. (2021)
describe ...") - removes the citeproc duplication that the
manual-bracket regex did not catch.
- 4 [-@key] suppressed-author conversions for possessive eponyms
(Han et al., Vaswani et al., Patarasuk and Yuan, Linnainmaa).
- 2 [-@key] conversions where the prose names an author/entity that
matches the cited author (Patterson and Hennessy's iron law,
Google's data centers + Google whitepaper).
- 1 Horowitz footnote rewritten to narrative so the inline year
replaces a duplicated "(ISSCC 2014, ...) (Horowitz 2014)" pair.
- 1 narrative @russell2021 anchoring "As Russell argues" that was
previously a bare attribution.
- 1 pre-existing narrative fix for "Graham et al. report ..." in
collective_communication that had no cite on the line.
Pre-commit cleanups landing with this commit:
- subramanya2019diskann: add publisher = Curran Associates (NeurIPS
proceedings, per bib-check rule 3).
- Remove orphaned @misc{Wu2016} GNMT bib entry in vol2; it had no
citations and collided case-insensitively with @inproceedings{wu2016}
(the cited Quantized CNNs paper) under bibtex-tidy's normalization.
- vol1/training/training.qmd: drop the dead UtilizationGap LEGO cell
(gpu_real_tflops_*, cluster_*_tflops_*) and the dead
TrainingModels.{gpt3_gpu_years,gpt3_compute_cost}_str exports plus
their unused upstream values.
- vol2/distributed_training/distributed_training.qmd: anchor the
orphaned [^fn-parameter-server] footnote on the body-prose mention
of "parameter-server systems" rather than deleting the definition.
manual-bracket hook (book-check-refs) green at this tip.
The three Self-Paced Tutorial sidebar entries pointed at .md files
that were either outside the docs/ Quarto project (../tutorial/*.md)
or had a .md href Quarto won't serve as a page (laws-explained.md).
Bring all three under docs/ as .qmd so Quarto renders them:
- copy tutorial/{exercises,cheatsheet}.md -> docs/tutorial/{...}.qmd
- rename docs/laws-explained.md -> docs/laws-explained.qmd
- update sidebar hrefs in config/_quarto-html.yml
Every subsite's announcement bar Line 1 carried a 'Start reading →' / 'Start building →' / 'Get started →' link that pointed at the very subsite the reader was already on. Clicking it was a no-op self-navigation.
Strip the CTA from Line 1 across all 8 sites that have the regression:
- announcement-vol1.yml drop 'Start reading →'
- announcement-vol2.yml drop 'Start reading →'
- tinytorch drop 'Start building →'
- mlsysim drop 'Get started →'
- kits drop 'Get started →'
- labs drop 'Preview →'
- slides drop 'Browse decks →'
- instructors drop 'Start here →'
Line 1 keeps the bold identity statement, which is what readers came for. The other lines (Vol I / II links, sibling row, newsletter CTA) keep their navigations since they DO lead somewhere new.
announcement-book.yml is unchanged — its Line 1 already points at the ecosystem root (https://mlsysbook.ai/), not at /book/ where the reader is.
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.
For the public launch, every site's "Alongside the book" (or "Build
with your students") row now lists StaffML alongside TinyTorch, Hardware
Kits, MLSys·im, and Labs. Two coupled changes:
• StaffML appended with verb "practice" — pairs cleanly with the
existing verbs (build / deploy / model / explore / practice).
• MLSys·im verb changed from "simulate" to "model" to match the
project's own self-description ("first-principles analytical
modeling for ML training and inference; model the physics before
you build"). MLSys·im is analytical, not Monte-Carlo simulation;
the new verb is more honest and the audience reads it cleanly.
Also restores tinytorch/quarto/config/announcement.yml to the canonical
4-line ecosystem template. That file had been silently rewritten to a
release-only banner ("🎉 v0.1.11 released — ...") by the
tinytorch-publish-live workflow, dropping the ecosystem cross-links
entirely. Restoration here; workflow fix is a separate commit.
Per-site row state after this commit (each site omits itself):
site, vol1, vol2: TinyTorch · Kits · MLSys·im · Labs · StaffML
instructors: TinyTorch · Kits · Slides · StaffML
kits: TinyTorch · MLSys·im · Labs · StaffML
labs: TinyTorch · Kits · MLSys·im · StaffML
mlsysim: TinyTorch · Kits · Labs · StaffML
tinytorch: Kits · MLSys·im · Labs · StaffML
slides: (teacher-focused row, unchanged)
The staffml site itself has its own Next.js ecosystem navbar
(EcosystemBar.tsx) which is out of scope for this Quarto-only sweep
and audited separately.
Source notes wrapped in *...* italics tripped the source-note check's
asterisk-wrapping rule. The italics carried no semantic weight; the
trailing period was already present. Strip the asterisks so the notes
render as plain prose, matching the convention used elsewhere in
mlsysim/docs/.
Five PDFs in the source tree are pure build artifacts that CI
re-deploys at every run; the committed copies served no purpose
beyond local-preview convenience and accumulated as stale snapshots.
- mlsysim/docs/mlsysim-paper.pdf
CI overwrites at deploy: mlsysim-publish-live.yml runs
cp ./pdf-artifacts/paper.pdf to MLSYSIM_DOCS/mlsysim-paper.pdf.
Local quarto preview now requires building the paper first
(cd mlsysim/paper && make).
- mlsysim/paper/figures/solver-chaining.pdf
- periodic-table/paper/figures/{mamba,molecular_ml,periodic_table_hero}.pdf
All FORCE-regenerated from SVG by the per-paper Makefiles whose
own comment is the rationale: "a stale committed PDF cannot mask
a freshly edited SVG."
Drop the matching ! whitelist entries from .gitignore so the global
*.pdf rule prevents accidental re-commit. Tutorial slide PDFs and
callout icons remain whitelisted, those are sources not build outputs.
Note: tinytorch/quarto/assets/downloads/00_tinytorch.pdf is NOT
removed. Despite the slide-deck-like filename, no Beamer/Quarto
source exists for it and big-picture.qmd consumes it directly via
pdf.js viewer and download link. Treating it as a binary source
asset until a source is authored or LFS Phase 2 is set up.
Round 2 of the bib audit, covering paper subprojects (mlsysim,
tinytorch, periodic-table, mlperf-edu) that the textbook-focused first
pass deferred. Same pattern as round 1: surname/year prefixes did not
match the entry's actual paper, plus several corrupt entries from
Crossref misidentification.
Renames:
- mlsysim/{docs,paper}: barrett2024 -> zheng2024sglang (SGLang paper,
Zheng is first author).
- mlsysim/paper: zhao2025 -> deepseek2025v3 (DeepSeek-V3 ISCA paper,
corporate author DeepSeek-AI).
- tinytorch: key499f5624 -> tanenbaum1987os (hash-fallback for
Tanenbaum OS textbook); fry1985 -> abelson1996sicp (SICP 2nd ed,
Fry is not in author list); wooster1982 -> papert1980mindstorms
(Mindstorms by Papert, Wooster not in author list); collins2018 ->
collins1989apprenticeship (Cognitive Apprenticeship paper is 1989).
- tinytorch + periodic-table: vaswani2025 -> vaswani2017attention
(Attention paper is 2017; entries had a corrupt publisher and bogus
DOI from Crossref misidentification).
Body fixes accompanying renames:
- tanenbaum1987os, abelson1996sicp, papert1980mindstorms: rebuilt as
@book entries (were @article with stale review/journal DOIs).
- vaswani2017attention: rebuilt with canonical NeurIPS 2017 metadata
(Curran Associates, vol 30, pp 5998-6008); dropped corrupt DOI.
Orphan deletions:
- tinytorch keybe9561f4 (hash-fallback, no cite sites).
- mlperf-edu vaswani2017attention (orphan).
21 cite-site updates across 4 paper subprojects. bib_lint reports 0
errors across all 5 modified bibs.
Per-file audit caught 14 cite keys whose surname prefix or year did not
match the entry's actual paper, plus 4 DOI duplicates and 3 corrupted
orphan entries. Renames preserve the cited paper; only the key changes.
Renames (key -> first-author-surname-year-shortform):
- vol2: agarwal2022 -> ouyang2022instructgpt; alistarh2024 ->
ashkboos2024quarot; belkada2022 -> dettmers2022llmint8; borgeaud2022 ->
hoffmann2022chinchilla; bosma2022 -> wei2022cot; ermon2023 ->
rafailov2023dpo; koyejo2023 -> schaeffer2023mirage; nofal2023 ->
beyer2016sre (year/publisher also corrected to O'Reilly 2016).
- vol1: mccarthy2006 -> mccarthy1955dartmouth; krizhevsky2017 ->
krizhevsky2012imagenet; zhang2021 -> zhang2017rethinking; ford2012 ->
savage2009flaw; wonyoung_kim2008 -> kim2008dvfs; estrada2026 ->
dehghani2022datamesh; michelucci2018 -> glorot2010xavier (entry was
Michelucci textbook chapter, prose wanted Glorot/Bengio AISTATS 2010);
chapelle2009 -> chapelle2006semisupervised (entry was 1-page IEEE
review, prose wanted the actual MIT Press book).
- interviews: key555befcd -> gierl2013automatic; chiang2023 ->
zheng2023judging; boylan1989 -> tay2024interview (Grind 75 web
resource); stenbeck1992 -> hambleton1991 (entry was 1992 review of the
1991 IRT book, content was the book).
DOI dedup:
- vol1 palmer1980 + palmer1980intel8087 -> palmer1980intel8087 (same
paper, redirected cite, deleted dupe).
- vol2 masanet2020 + masanet2020energy -> masanet2020energy (same paper,
redirected cite, deleted dupe).
- vol1 abadi2016tensorflow had wrong DOI pointing to the 2018 EuroSys
Dynamic Control Flow paper; rebuilt as the OSDI 2016 TensorFlow paper
it claims to be. Mirrored same correction into vol2's duplicate entry.
Orphan deletions (zero cite sites, corrupted metadata):
- vol1 acun2023; vol1 aggarwal2018; interviews gallifant2024 (the clean
GPT-4 entry already exists at openai2023gpt4).
- vol1 yu2018 (legitimate paper but unused).
- vol2 mckinsey2018ai and triton.jit (orphans flagged for missing year;
triton.jit was a false positive from a Python decorator inside a code
block, not a citation).
Field repairs:
- aws2020s3: added year=2020, fixed corrupted author "A. W. Services"
to {Amazon Web Services}, added howpublished + url.
51 cite-site updates across 25 files in vol1/vol2/interviews/mlsysim.
All book-prose.md §5 cite-mechanics audit greps return zero hits.
bib_lint reports 0 errors across all three modified bibs.
Wraps up the bib-verify sweep across vol1, vol2, and the paper sub-projects,
and corrects three citation issues introduced earlier in the branch:
- Restore tang20211bit (1-bit Adam, Tang et al. ICML 2021) in vol2 bib and
in collective_communication.qmd. The earlier sweep had renamed the cite
to li2022, which now resolved to AlphaCode or 1-Bit LAMB.
- Restore micikevicius2018mixed in vol1 bib to point at "Mixed Precision
Training" (Micikevicius et al. ICLR 2018). The entry had been overwritten
with an unrelated OpenSeq2Seq paper while the cite key stayed the same.
- Drop the unused li2022 (AlphaCode) entry and the duplicate li2022 (1-Bit
LAMB) entry from vol2 bib.
Also remove eight same-paper duplicate entries that the sweep had left
behind (vol1: lawson1979, gholami2022, lange2009, ribeiro2016; vol2:
bursztein2024, rasley2020, sevilla2022, narayanan2019).
After this commit the bibs have zero duplicate keys and zero orphan
citations across both volumes and all five paper sub-projects.
Vijay Janapa Reddi
Rocky
Farhan AsgharandGitHub