Add shared/config/footer-common.yml (mirrors navbar-common.yml) and point
slides, labs, kits, and instructors at it via metadata-files, replacing their
drifted inline footers. The release pill now lives in the footer right slot
(not dangling below the page) as a fixed muted-gray chip, pinned so it looks
identical regardless of each site's theme accent. mlsysim and the book keep
their own footers (dual license / build stamp) but carry the same pill span.
release-pill.html is now assets-only and populates every data-release-pill
span from each site's own release-manifest.
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.
- 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.
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.
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.
Adopts the shared versioning pattern for the MLSYSIM docs site without
touching the paper LaTeX or PyPI publish flow — both deliberately stay
under their existing identities. The site release_id binds to the docs
corpus + python source via release_hash, and the paper PDF rides
alongside as a bundled artifact (with its own LaTeX-driven version).
mlsysim/docs/_quarto.yml:
- <meta name="release-manifest" content="/mlsysim/release-manifest.json">
in include-in-header.
- shared/release/release-pill.html added to include-after-body.
.github/workflows/mlsysim-publish-live.yml:
- workflow_dispatch inputs: release_type, description, site_only,
explicit_version, confirm — same shape as staffml-publish-live.
- New `prepare:` job calls _release-prepare.yml for release_id math.
- New "Emit release manifest" step writes release-manifest.json into
the build dir before deploy. Hashes mlsysim/docs + mlsysim/python +
mlsysim/pyproject.toml; excludes _build/, .quarto, etc.
- New `create-tag:` job tags mlsysim-v<release_id> and drafts a
GitHub Release with auto notes after deploy succeeds.
- The existing `mlsysim-pypi-publish.yml` (tag-triggered, OIDC PyPI
push) remains untouched. Pushing the new mlsysim-v* tag will fire
it as before. Pyproject.toml's version field is unchanged — it
remains PyPI's source of truth, separate from this site's.
The mlsysim docs hero linked "Slide Decks" to mlsysbook.ai/slides/, the
textbook teaching site, which has no relationship to the MLSys·im ISCA
tutorial. Wire the tutorial decks into the same publish path the paper
uses so the link resolves to mlsysim's own slides.
- mlsysim-build-pdfs.yml: split into build-paper / build-slides; new
job installs xelatex + JetBrains Mono and uploads MLSYSIM-Slides
- mlsysim-publish-live.yml, mlsysim-preview-dev.yml: download
MLSYSIM-Slides and inject tutorial_part{1,2}.pdf into MLSYSIM_DOCS
- mlsysim-update-pdfs.yml: redeploy slide PDFs in PDF-only hot-fix path
- mlsysim/tutorial/Makefile: build both decks (was part1 only) with
proper target tracking
- mlsysim/docs/slides.qmd: new landing page with download buttons and
a pointer disambiguating the textbook lecture decks
- mlsysim/docs/index.qmd: hero CTA now targets slides.qmd
- mlsysim/docs/config/_quarto-html.yml: register slide PDFs as
resources and add navbar entry
Align the MLSys·im code, docs, paper, website, workflows, and lab wheel for the 0.1.1 release. This also fixes runtime/API issues found during release review and prepares the paper PDF plus archive package.
Switch mlsysim from CC-BY-NC-SA-4.0 to Apache-2.0 for the Python
package. Creative Commons itself advises against CC licenses for
software: they do not cover patent grants, source/object distinctions,
or derivative-work definitions the way a software license does, and
the NonCommercial clause makes the package unusable in any corporate
setting — defeating the goal of a teaching tool intended for working
engineers.
Apache-2.0 preserves full copyright-holder rights to commercialize
(dual-license future versions, sell commercial editions, offer paid
support/SaaS), while enabling the broad adoption appropriate for a
textbook companion.
The textbook prose remains CC-BY-NC-SA-4.0. The docs site footer is
updated to state both licenses explicitly so readers do not conflate
the two.
- mlsysim/LICENSE.md : full Apache-2.0 text with copyright
- mlsysim/pyproject.toml : license = "Apache-2.0" + OSI classifier
- mlsysim/CITATION.cff : license: Apache-2.0
- mlsysim/RELEASE_NOTES_0.1.0 : license line split (code vs docs)
- mlsysim/paper/paper.tex : "MIT license" → "Apache-2.0 license"
- mlsysim/docs/config/_quarto-html.yml : footer shows both licenses
Every site's announcement bar now follows one template:
Line 1 — identity + primary CTA (what is THIS site)
Line 2 — the book (or, on book sites, the other volume)
Line 3 — "Alongside the book:" sibling row (3 most-relevant verbs)
Line 4 — newsletter
The book is the anchor of the curriculum; every other site is a verb
applied to it — TinyTorch (build), Hardware Kits (deploy), MLSys·im
(simulate), Labs (explore), Slides + Instructors (teach). Making that
shape visible in every bar turns nine independent sites into chapters
of one curriculum.
Removed stale copy: "Happy New Year!" on kits + labs, "coming in 2026"
on labs (we are in 2026; replaced with "Coming Summer 2026"), TinyTorch
v0.1.10 single-line release notice (belonged in a release changelog,
not the always-visible nav bar).
Normalized outbound links: /book -> /vol1/ and /vol2/, consistent
trailing-slash hygiene on every URL. Newsletter link points to
https://mlsysbook.ai/newsletter/ (the actual Quarto page) instead of
#subscribe (which only resolves on the landing page).
The landing site (mlsysbook.ai) uses a 5-line variant that covers all
four learner verbs + the teacher-tools row; every other site uses the
4-line form.
StaffML is a Next.js app, not a Quarto site, so its banner is out of
scope for this PR and will ship as a separate React component change.
Mirrors the TinyTorch pattern from the previous commit: the companion
paper PDF belongs next to the site it documents, not in the shared
Build menu. Path follows mlsysim-publish-live's workflow output
(mlsysim-paper.pdf at site root), so the link resolves on production
even though the file is not in this repo.
Completes the restructure — both product sites that previously had
paper entries in the shared Build menu now have site-local dropdown
entries, and Build is a clean 4-row ecosystem index everywhere.
- Replace inline Google Fonts <link> tags in all 8 site configs with
a single `- file: shared/config/site-head.html` reference, so fonts
(Inter 400-800, JetBrains Mono) and Font Awesome are inherited from
one shared file instead of duplicated across every _quarto.yml
- Add missing Inter weight 800 (was only in site-head.html, not configs)
- Add carousel CSS + JS for MLSys·im landing page (arrows, dots, slides,
auto-rotation, keyboard nav) — fixes non-functional < > buttons
Fixes the broken links, stale numerical claims, and naming inconsistencies
surfaced by the 0.1.0 release-prep review. Output of the docs site now matches
what the engine actually computes, internal navigation has no unresolved targets,
and the Hatch announcement banner uses an absolute URL so sub-pages render the
"Get started" link correctly.
Notable changes:
- Hero example on docs/index.qmd and getting-started.qmd now reflect the actual
Engine.solve(ResNet50, A100, bs=1, fp16) output (Memory / 0.54 ms / 1843).
- Update Python version requirement (3.10+) and document the editable-install
limitation (Hatch sources rewrite is not supported by editables).
- Standardize the typographic brand to "MLSys·im" in the navbar, OG/Twitter
metadata, and the shared cross-site dropdown.
- Add the four solvers missing from the quartodoc list
(BatchingOptimizer, ForwardModel, NetworkRooflineModel, PlacementOptimizer)
and surface the orphan tutorials (01_pipeline_callbacks,
02_differential_explainer, 12_design_space_exploration) in the sidebar.
- Rename every reference to the now-deleted hello_world / llm_serving /
sustainability / 11_full_stack_audit tutorials to their current filenames.
- Add the missing @mlsysbook2024 entry to references.bib so whitepaper.qmd
no longer logs a citeproc warning.
- Fix the CLI sample on the parent site/index.qmd card to use real model
identifiers (Llama3_70B H100 --batch-size 1).
- Soften the Colab/Binder copy until launch buttons are wired in.
- Remove the duplicate "Differential Explainer" card on tutorials/index.qmd.
- instructors: remove Outfit display font, use Inter for headers like
all other sites. Remove redundant @import and h1-h4 font override.
- mlsysim: replace site-specific logo.svg with ecosystem shield logo
- tinytorch: replace TinyTorch-specific logo with ecosystem shield logo
All Quarto sites now have identical navbar: same shield logo, same Inter
font stack, same dark mode toggle, same shared responsive behavior.
Tested: Quarto metadata-files merge DOES inherit responsive properties
(background, pinned, collapse, collapse-below) from navbar-common.yml.
Local configs only need logo, search, title, and site-specific left: items.
Removed 4 redundant lines from each of: mlsysim, labs, kits, instructors, site.
Single source of truth: shared/config/navbar-common.yml
Architecture:
- Merge landing, about, community, newsletter into one site/ project
- Move navbar-common.yml to shared/config/ (used by 12 configs)
- Create shared/config/footer-site.yml for centralized footer
- Create shared/scripts/subscribe-modal.js as canonical copy
- Single _quarto.yml replaces 4 independent configs
- One site_libs/ copy replaces four
Features gained:
- Google Analytics on ALL hub pages (was only on book volumes)
- Subscribe modal on landing page (was missing)
- Centralized footer with consistent links
Workflows updated:
- site-preview-dev.yml: matrix strategy → single build job
- site-publish-live.yml: loop over subsites → single build + deploy
- sync-newsletter.yml: builds from unified site project
- publish-all-live.yml: removed stale subsite input
- rewrite-dev-urls.sh: added --shallow flag for unified builds
All 12 navbar-common.yml references updated:
book vol1/vol2, site (unified), slides, instructors, interviews,
kits, labs, mlsysim
Remove pedagogy module, add provenance tracking and design space
exploration. Update evaluation engine, pipeline callbacks, and
documentation including new tutorials.
Replace the generate-navbar.py script approach with direct metadata-files
references to navbar-common.yml. Quarto natively merges navbar arrays,
so site-local dropdowns defined inline in each _quarto.yml get appended
to the shared navbar automatically.
- Delete generate-navbar.py script (no longer needed)
- Delete all _navbar-generated.yml and _navbar-local.yml files
- Each subsite now references ../book/quarto/config/shared/html/navbar-common.yml
directly via metadata-files
- Sites with local dropdowns (slides, instructors, mlsysim) define them inline
in their _quarto.yml navbar.left — Quarto merges with the shared left items
- Zero tooling, zero generated files, zero maintenance scripts
Single source of truth for the navigation bar in navbar-common.yml.
New 5-dropdown structure: Read | Build | Teach | Community | About.
- Add generate-navbar.py script to merge shared + site-local dropdowns
- Add _navbar-local.yml for slides, instructors, mlsysim (site-specific menus)
- Generate _navbar-generated.yml for all 6 subsites (committed, no CI changes needed)
- Strip hardcoded navbars from all _quarto.yml configs (landing, vol1, vol2, slides,
instructors, mlsysim, kits, labs, newsletter)
- Add community/ and about/ paths to rewrite-dev-urls.sh for dev preview
To update navbar: edit navbar-common.yml, run generate-navbar.py --all, commit.
Add subscribe-modal.js and Subscribe navbar button to MLSYSIM docs
site, matching the unified navbar pattern across all components
(Labs, Kits, MLSYSIM). Right-side items now follow the same order:
Downloads, Star, Support, Subscribe, GitHub.
- book-preview-dev.yml: add run_id input for workflow_dispatch to allow
deploying from a specific validate run (bypasses success check when
HTML artifacts exist but EPUB/PDF builds fail)
- mlsysim: add announcement.yml config and metadata-files reference so
the modify_dev_announcement.py script can inject the dev preview banner
Replace 9 old tutorials with 12 new numbered tutorials (00-11) covering
roofline through full-stack audit. Redesign landing page, add
models-and-solvers and extending-the-engine guides. Add __main__.py,
cli.py, and cli/ package for command-line interface.
Add cached_prefix_len parameter to ServingSolver for prefix/prompt
caching (grounded in Zheng et al. SGLang/RadixAttention). TTFT reduces
proportionally to cache hit ratio; ITL and memory unchanged.
Export 4 missing solvers from __init__.py (ContinuousBatchingSolver,
WeightStreamingSolver, TailLatencySolver, CheckpointSolver).
Fix dict-style access in for-engineers.qmd and architecture_comparison
tutorial. Add math sections 3.4-3.6 for prompt caching, disaggregated
serving (Patel et al. Splitwise ISCA'24), and speculative decoding
(Leviathan et al. ICML'23) with literature citations. Update paper.tex
Wall 4 description to include prompt caching. Fix remaining MLSYSIM
branding in _quarto-html.yml.
Update display name from MLSYSIM to MLSys·im (with interpunct) in
paper title, website config, and all 18 QMD documentation pages.
Technical name (imports, file paths) remains lowercase mlsysim.
Paper subtitle updated to "First-Principles Infrastructure Modeling
for Machine Learning Systems". Preserve explicit anchor ID for
cross-referenced #extending-mlsysim heading.
Slim whitepaper.qmd to a thin page that embeds paper.pdf via
<object> tag with download fallback. Add CI steps to both preview
and publish workflows to build paper.tex and copy PDF into docs
before Quarto render. Update sidebar references from "Whitepaper"
to "Research Paper".
Rewrite API reference pages to match domain subpackage structure.
Add solver doc pages for CompressionSolver, DataSolver,
OrchestrationSolver, and ScalingSolver. Update whitepaper,
math reference, getting-started guide, and tutorial index.
Add extending tutorial for custom solvers.
- Add mlsysim-validate-dev, mlsysim-preview-dev, and mlsysim-publish-live workflows
- Move mlsysim docs config to config/ dir with symlink (matching kits/labs pattern)
- Add MLSYSIM to ecosystem navbar across all 7 site configs
- Add mlsysim/ URL rewrite to book-preview-dev for dev site
- Replace hardcoded paths with GitHub variables in kits and labs workflows
- New repo variables: MLSYSIM_ROOT, MLSYSIM_DOCS, DEV_MLSYSIM_PATH, KITS_ROOT,
KITS_DOCS, LABS_ROOT, LABS_DOCS
Vijay Janapa Reddi
Farhan AsgharandGitHub