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.
Quarto auto-applies !default to every variable in scss:defaults, and
Quarto compiles the theme list in order: style.scss is processed before
dark-mode.scss. style.scss declares `$mlsysim-accent: #0284C7` (the light
cyan); dark-mode.scss reassigning the same name to #38BDF8 was silently
ignored because the variable was already locked by !default. Result:
every `rgba($mlsysim-accent, X)` call in dark-mode.scss compiled with the
light value, so the active sidebar link and active TOC link rendered with
Bootstrap's --bs-primary cyan instead of the brighter dark accent.
Renamed the dark variable to $mlsysim-accent-dark across the file.
Also tightened the active-state cascade by moving color/background/weight
into the high-specificity #quarto-sidebar guard block, matching the look
in instructors/ (white text on subtle 15% accent tint, weight 500).
Documented the gotcha inline so future edits don't repeat it.
Extends PR #1633's instructors fix to the rest of the Quarto ecosystem.
Quarto renders floating sidebars with `<a class="sidebar-link">` and
`<a class="sidebar-item-toggle">` directly (not nested inside an
`.sidebar-item a` wrapper), so the legacy selector missed all real DOM
nodes.
Sites updated:
* slides, interviews, tinytorch/quarto, mlsysim/docs: full hardening
(toggle, leaf-link, active-state, search input, TOC rail).
* labs, kits, book/quarto: added missing search-input theming
(core sidebar and TOC fix already present from earlier work).
Each site's accent color is preserved: indigo for instructors and
interviews, pink for slides, amber for tinytorch, cyan for mlsysim,
teal for kits and labs, crimson for book.
Two issues caused the deployed slide PDFs to be unusable:
1. Every chapter .tex declared `\setsansfont{Helvetica Neue}` — proprietary
to Apple, not installed on the Ubuntu CI runner. xelatex bombed mid-frame,
the workflow's `|| true` swallowed the error, and the resulting PDF had
most text never typeset (blank pages with only logos/rules surviving).
Switch all 35 decks to TeX Gyre Heros (sans) and TeX Gyre Cursor (mono),
both bundled with texlive-fonts-extra — no external font downloads needed.
Drop the JetBrains Mono wget step and fonts-liberation from both slide
workflows accordingly.
2. Vol1 and Vol2 each ship `00_course_overview.pdf` and `01_introduction.pdf`.
The publish workflow uploaded them to a flat GitHub Release namespace, so
the second upload silently overwrote the first — clicking Vol I's Course
Overview actually downloaded Vol II's deck. Stage prefixed copies
(vol1_*.pdf, vol2_*.pdf) before upload, and update slides/vol{1,2}.qmd
plus the mlsysim cross-links to point at the new prefixed URLs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
check-internal-links was failing on 4 dead refs that tipped book validate-dev
into red, blocking the navbar republish:
- interviews/vault/README.md, interviews/vault/TESTING.md
referenced ../vault-cli/docs/CUTOVER_QA.md, which was deleted in
c824ac6e (retire prod static-fallback). Both refs removed.
- mlsysim/docs/slides.qmd referenced tutorial_part{1,2}.pdf, which are
built from the .tex sources in mlsysim/tutorial/slides/ but are not
yet wired into mlsysim-build-pdfs.yml. Production was 404'ing on both.
Replaced the download buttons with a "build from source" placeholder
+ commented-out original markup + TODO note pointing at the missing
workflow step.
Also: book-format-python (Black at 70 chars) wanted PEP-8-style two blank
lines between top-level Python functions in three code blocks of
frameworks.qmd. Auto-applied.
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
Same regression as vol1/vol2 references.bib (commit 42bc54275 figure-audit
feat) — five auxiliary bib files (interviews/paper, mlsysim/docs,
mlsysim/paper, periodic-table/paper, tinytorch/paper) had brace patterns
mangled in titles, e.g. 'Throughput-Latency Tradeoff in {LLM} Inference'
became 'Throughput-Latency Tradeoff in {LLM}} Inference', which
bibtex-tidy refuses to parse.
Restored to the parent of 42bc54275 (state at 9ebdf77d0) and
re-formatted via the bib_apply_mechanical + bibtex-tidy hooks.
Iterates on the post-merge 404 redesign across all 8 sub-sites:
- SVG roofline-plot fonts bumped for readability without changing
layout: axis labels 9.5pt to 14pt, region labels 9.5pt to 14pt,
title and "your page (404)" annotation 11pt to 16pt.
- Random-joke font shrunk from 1.6rem to 1.3rem (1.1rem on mobile)
so the joke no longer dominates the SVG above it.
- Removed the static "Looks like this page slipped past our load
balancer" subline from 6 sub-sites — it read as a competing static
joke alongside the random rotation. Slides and instructors keep
their informational sublines.
- Joke pool tightened 97 to 79 via a strict ML-systems-centric test:
if you could swap "page" for any generic web/ops resource and the
joke still works, cut. Cuts removed the H&P canonical material
(Amdahl's Law, TLB miss, Dennard scaling, false sharing, fat-tree
topology) that is general computer architecture rather than ML
systems specifically. 19 borderline jokes were rewritten to anchor
punchlines in concepts only ML practitioners decode (KV cache,
gradient AllReduce, prefill, ZeRO, speculative-decode acceptance,
1F1B schedule, ridge point, BPE merges).
Replace the inline-game 404 across all 8 sub-sites with a unified
design: roofline-plot illustration, random pick from a 97-joke
editorial-curated pool, dual CTA (home + playground), and a
GitHub-issue-backed contribute link for community submissions.
The joke pool was curated through a multi-agent editorial process:
4 generators (each with a different ML systems lens) produced 240
candidates; 5 reviewer personas (architect, NLP researcher, production
engineer, undergrad, copy editor) scored each; the synthesizer kept 92
surviving jokes plus 5 new canonical-architecture additions (Amdahl,
TLB, Dennard, false sharing, fat-tree topology) the architect flagged
as missing from the H&P-tradition canon.
Self-contained CSS with prefers-color-scheme: dark adapts to host
themes without coupling to each sub-site's bespoke styling. SVG
follows the book's semantic palette (blue memory-bound slope, green
compute roof, MIT red error annotation). Per-site navigation
preserved across all sub-sites.
Adds .github/ISSUE_TEMPLATE/404_joke.yml so contributions arrive
structured (joke text, theme dropdown, license checkbox) and
auto-tagged (site, 404-joke, good-first-issue) for triage.
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.
Four user-facing identity statements referenced an earlier working title
("A Composable Analytical Framework for Machine Learning Systems") that
no longer matches the actual paper title fixed in 0.1.1 ("MLSys·im:
First-Principles Infrastructure Modeling for Machine Learning Systems").
Align each identity-claiming statement to the paper title.
This covers user-facing *name-claims* only — the places where mlsysim
describes itself. Descriptive uses of "analytical framework" as a
technical category inside the paper and related technical prose are
retained (they situate mlsysim among other analytical tools like
Paleo, Calculon, Vidur; those uses are legitimate).
- mlsysim/pyproject.toml : project description
- mlsysim/mlsysim/cli/main.py : `mlsysim --help` text
- mlsysim/docs/tutorials/index.qmd: tutorial landing blurb
- mlsysim/tutorial/prerequisites.md: prerequisites preamble
Before: four Quarto sites each shipped their own copy of the
`.sidebar-navigation .sidebar-item a` rule block, each hard-wired to a
different accent variable ($accent, $kits-accent, $colabs-accent,
$mlsysim-accent). Plus one 1350-line orphan file
(book/quarto/assets/styles/style.scss) that was referenced nowhere and
carried yet another copy of the same rules.
After: every site imports shared/styles/partials/_sidebar.scss once.
Each site aliases $accent to its own site-accent (book does it via
themes/_theme-harvard which sets `$accent: $brand-crimson`; kits/labs/
mlsysim already had `$accent: $site-accent` at the top of their
style.scss), so the partial's accent-keyed hover/active states resolve
to the right color per site without needing a per-site rule copy.
Files:
- shared/styles/partials/_sidebar.scss
(unchanged in this PR — already is the canonical form after #1514)
- book/quarto/assets/styles/_base-styles.scss
replace ~40 lines of local sidebar rules + .part-divider with
`@import '.../partials/sidebar'`
- book/quarto/assets/styles/style.scss
DELETE (1350 lines, zero build references — confirmed by grep
across _quarto*.yml, Makefile, .sh, .py, .js)
- kits/assets/styles/style.scss
replace local sidebar rules with partial import; keep the
site-specific `.sidebar-title` rule (not part of the shared shape)
- labs/assets/styles/style.scss
replace local sidebar rules with partial import
- mlsysim/docs/styles/style.scss
replace local sidebar rules with partial import; the
.sidebar-navigation > .sidebar-menu-container dividers below
are site-specific and stay
Net: +23 / -1531 lines. Behavior is identical (the partial was already
tightened to these same values in PR #1514, so this is a
refactor-not-redesign). slides and instructors already had no sidebar
overrides and are not touched.
TinyTorch was already importing the partial directly and is unchanged.
The ecosystem now has one sidebar rule block, in one file, controlling
every Quarto site.
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.
Brings the TinyTorch lab guide's Quarto project in line with
book/quarto/, the only other in-tree Quarto publication that builds
both web and PDF outputs from a single source. The previous name had
three redundancies:
- already under tinytorch/, so "site-" prefix wasn't disambiguating
- also produces the PDF lab guide, so "site-" was misleading
- the top-level site/ dir made "site-quarto" read as "the site's
quarto config" rather than "the tinytorch site, in quarto"
After this rename the convention is straightforward:
book/quarto/ -> the textbook (web + PDF)
tinytorch/quarto/ -> the TinyTorch lab guide (web + PDF)
mlsysim/docs/ -> mlsysim API reference (kept as docs/, since it
really is API reference, not a publication)
Touches 7 GitHub workflows, both .gitignore files, the rename target's
own self-references (Makefile, _quarto.yml configs, STYLE.md,
measure-pdf-images.py), and 6 copies of subscribe-modal.js plus a few
shared scripts/configs whose comments documented the old path.
Verified: rebuilt pdf/TinyTorch-Guide.pdf (2.1M) cleanly from the new
location with 'make pdf' from tinytorch/quarto/.
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.
Clean up planning, kickoff, audit, and persona-feedback documents
accumulated during prior AI-assisted work sessions. These are
session artifacts, not durable documentation — the decisions they
captured have either shipped, been retired, or are traceable via
git history.
interviews/vault/REVIEWS.md is intentionally kept: it is cited by
section ID (H-6, H-7, H-21, C-6, ...) from production code in
interviews/vault-cli/ and interviews/vault/ and published as the
pyproject.toml Review-Ledger URL, which makes it engineering
documentation rather than a session artifact.
Deletions:
- RELEASE-PREP.md, review_prompt.md (root handoff / review prompts)
- interviews/vault/KICKOFF.md, BOOK_LINKING_PLAN.md, EXPANSION_PLAN.md
- interviews/staffml/FEEDBACK_SYNTHESIS.md, V1_REDESIGN_SPEC.md,
STAFFML_UX_PLAN.md, VAULT_DESIGN_PLAN.md
- interviews/staffml/.gemini-reviews/ (2 review call logs)
- book/docs/SVG_FIGURE_AUDIT_PLAN.md, book/tools/agent_personas.md
- mlsysim/docs/WEBSITE_AUDIT.md
- periodic-table/iteration-log.md, refinement-log.md
Reference fixes for pointers into deleted files:
- interviews/vault/ARCHITECTURE.md: drop section 21 (pointed at KICKOFF.md)
- interviews/vault/schema/question_schema.yaml: drop BOOK_LINKING_PLAN.md
reference in the author-curated resource description
- interviews/staffml/src/components/Footer.tsx: drop BOOK_LINKING_PLAN.md
reference from the docstring; rationale preserved
Also removes the untracked gemini_prompts/ directory at repo root.
* fix(content): clear two mitpress-above-below pre-commit failures
The "📚 Book · ✅ Validate (Dev)" workflow has been failing on dev for
8+ consecutive runs because the mitpress-above-below pre-commit hook
flags spatial references like "above"/"below" inside body prose and
figure captions (the MIT Press style guide wants @sec-/@fig- cross-refs
or "earlier"/"later" instead). Two pre-existing violations were tripping
the hook on every push:
- book/quarto/contents/vol1/responsible_engr/responsible_engr.qmd:1604
fig-cap for fig-data-governance-pillars said "obligations discussed
below: privacy, security, compliance, and transparency" — but those
four obligations are *immediately* listed in the same caption, so
"discussed below" was redundant. Reworded to "obligations of
privacy, security, compliance, and transparency …".
- book/quarto/contents/vol2/network_fabrics/network_fabrics.qmd:1217
fig-cap for fig-congestion-cascade said "the PFC backpressure
cascades described below." Reworded to "described later in this
section." which is what the hook wants.
After our 4 release-prep merges (PR-1/2/7/12) cleaned up the other
hook failures (spelling, bibtex tidy, pipe tables, contractions,
mitpress-vs-period, …), this was the last remaining failing hook.
Verified locally:
pre-commit run mitpress-above-below --all-files
MIT Press: No above/below spatial refs (use cross-refs).....Passed
These are pure copy-edits to figure captions; no semantic change to
the diagrams or surrounding text.
* fix(check-internal-links): suppress 4 categories of false positives
The Tier 1 link checker (shipped in PR #1404) was over-eager and
flagged author content as broken in four documented patterns:
1. TikZ source inside HTML comments. Link regex matched `\node[mycycle](B1)`
as a Markdown link `[mycycle](B1)`. Fix: strip `<!-- ... -->` bodies
before scanning, preserving line/column offsets so any *real* failure
we report stays accurate.
2. Quarto cross-references like `[Foo](@sec-bar)`, `@fig-x`, `@tbl-y`.
These resolve through the project xref index at render time, not the
filesystem; book/binder owns that validation. Fix: skip targets whose
first token is `@sec-/@fig-/@tbl-/@eq-/@lst-/@thm-/@cor-/@def-/@exr-/
@exm-/@prp-`.
3. Uppercase URL schemes (`HTTPS://`, `HTTP://`) — common after mobile
auto-capitalize or copied citations. Fix: case-insensitive prefix
match for the EXTERNAL_SCHEMES tuple.
4. GitHub-style emoji-prefix slugs in `.md` READMEs (e.g.
`## 🎯 20 Progressive Modules` produces anchor `#-20-progressive-modules`
on github.com, but Pandoc would slugify to `progressive-modules`).
Fix: register both Pandoc-style and GitHub-style slugs as valid
anchors so neither rendering target trips the checker.
Drops repo-wide broken-link count from 150 → 84 (false positives only;
no real link rot is masked). Real rot is fixed in a separate commit so
the checker improvement can be reviewed independently.
* fix(content): repair internal-link rot across 10 files
Concrete link rot the new checker (PR #1404) surfaced once its false
positives were cleared. None of these are stylistic; each link points
at a path or anchor that does not exist.
- README/README_{zh,ja,ko}.md (24 links): translation files live in
README/ so paths to repo-root targets need a `../` prefix
(`book/README.md` -> `../book/README.md`, etc.).
- mlsysim/docs/contributing.qmd (21 links): `../slides/...` pointed
inside `mlsysim/`; the slides root is two levels up
(`../../slides/...`).
- mlsysim/docs/cli-reference.qmd: `getting-started.qmd#bring-your-own-yaml-byoy`
removed; retarget to `#defining-custom-models` (closest surviving
section about user-supplied model specs).
- mlsysim/docs/for-engineers.qmd, for-instructors.qmd:
`solver-guide.qmd#extending-mlsysim` no longer exists; retarget to
`#writing-a-custom-solver` (the surviving custom-solver guide).
- book/tools/scripts/README.md: `../docs/BINDER.md` resolved to
`book/tools/docs/BINDER.md` (nonexistent); the file actually lives
at `book/docs/BINDER.md`, which is `../../docs/BINDER.md` from here.
- book/quarto/contents/frontmatter/index.qmd:
`about.qmd#about-the-book-unnumbered` anchor was removed when the
About heading was simplified; drop the anchor so the link lands at
the top of the page (which IS the About section).
- tinytorch/datasets/tinytalks/README.md: `scripts/README.md` was
never created; point at the directory listing instead.
* chore(pre-commit): exclude 3 forward-looking files from internal-link checker
Three files reference content that does not (yet) exist on the
filesystem; the references are intentional rather than rot, so they
should not block CI:
- labs/index.qmd: lists the 33 planned labs (vol1/lab_00..lab_16,
vol2/lab_01..lab_16) as a roadmap. Links go live as each lab ships.
De-linking now would lose the visual roadmap. When a lab lands the
exclusion narrows naturally on its own.
- labs/PROTOCOL.md, labs/TEMPLATE.md: internal authoring docs that
reference `../.claude/docs/labs/{PROTOCOL,TEMPLATE}.md`. The
`.claude/` tree is per-worktree and not always present at the same
relative path; these are author-tooling refs, not user-facing.
Net effect: the link checker is now green on a clean checkout. The
exclude block uses comments per existing convention so the rationale
is discoverable from the config alone.
* fix(content): clear codespell, contractions, and vs. pre-commit failures
Three pre-existing pre-commit hooks were failing on the dev branch
prior to the release-prep merges. Each is a small content normalization:
- codespell (2): re-declares -> redeclares (book/quarto/config/shared/README.md);
unparseable -> unparsable (handled in the check-internal-links rewrite).
- contractions (2):
* socratiq/socratiq.qmd callout: "If you're" -> "If you are".
* nn_architectures fig-alt for the attention-visualization figure:
"didn't" -> "did not". Alt-text is descriptive prose for screen
readers, not a verbatim transcription of pixels, so expanding the
contraction matches MIT Press style without changing the figure
itself.
- mitpress-vs-period (6): bare `vs` -> `vs.` per MIT Press 2026 §10.5
in benchmarking.qmd, distributed_training.qmd (x3 across two Python
docstrings rendered in code listings), fault_tolerance.qmd, and
inference.qmd. Code-listing strings are visible prose in the rendered
PDF, so the rule applies there as well.
* chore: bibtex-tidy auto-format outputs
Outputs of the bibtex-tidy pre-commit hook (which auto-fixes its own
input). Picked up here so that running pre-commit on a clean checkout
no longer reports a "files were modified" failure for the same files
on every invocation. Pure formatting; no entry semantics changed.
Quarto's resource-copy step preserves symlinks rather than dereferencing
them, which breaks both local builds (AlreadyExists on the second pass)
and gh-pages deploys (relative symlink targets fall outside _build/).
And Sass resolves @import relative to the importing file's physical
location, not the symlink target. So symlinks inside the resource path
are not a viable dedup mechanism.
Instead, keep real file copies in each consumer subsite and enforce
dedup at edit time with shared/scripts/sync-mirrors.sh:
- bash shared/scripts/sync-mirrors.sh # propagate canonicals
- bash shared/scripts/sync-mirrors.sh --check # CI: fail on drift
Mirror map (source | mirrors):
shared/scripts/subscribe-modal.js -> {site, book/quarto, labs, kits,
mlsysim/docs}/.../subscribe-modal.js
Intentional non-mirrors (left untouched, customized variants):
tinytorch/site-quarto/assets/scripts/subscribe-modal.js (TinyTorch-branded)
tinytorch/site/_static/subscribe-modal.js (legacy Sphinx)
Also dedupe the SocratiQ widget bundle via a symlink (safe here because
book/tools/ sits outside any Quarto project, so the resource walker
never touches it):
book/tools/scripts/socratiQ/bundle.js -> ../../../quarto/tools/scripts/socratiQ/bundle.js
The shared canonical (book/quarto/tools/scripts/socratiQ/bundle.js) is
the version actually referenced and served in production.
- 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
The 0.1.0 release prep moved the package from `mlsysim/` to `mlsysim/mlsysim/`
to support `pip install -e .`. Two CI jobs still depended on the old layout:
1. **Docs build (`mlsysim-preview-dev`)** — every tutorial and zoo page used
a hand-rolled `importlib.util.spec_from_file_location` block to load
`<repo>/mlsysim/__init__.py` directly from source. After the restructure,
that path no longer exists. Replaced the hack in 17 docs/.qmd files with
a plain `import mlsysim` — the package is already pip-installed in the
docs build environment via `pip install ".[docs]"`. Updated the matching
guidance in `contributing.qmd`.
2. **Lab static tests** — `test_no_localstorage_import` hard-coded
`mlsysim/labs/state.py`; updated to the new nested path
`mlsysim/mlsysim/labs/state.py`.
Verified locally: `pytest labs/tests/test_static.py::TestStateImplementation`
passes, and `quarto render docs/zoo/models.qmd` succeeds end-to-end.
Restructure mlsysim into the standard nested layout (`mlsysim/mlsysim/...`)
so `pip install -e .` works out of the box. The previous flat layout used
a Hatch `sources = {"." = "mlsysim"}` prefix-add rewrite that the
`editables` backend cannot handle, breaking editable installs entirely.
Packaging
- pyproject.toml: drop `sources` rewrite, set `packages = ["mlsysim"]`,
add explicit `[tool.hatch.build.targets.sdist]` include list.
- Wheel and sdist now contain only the package and project metadata
(no `tests/`, `docs/`, `examples/`, `paper/`, `vscode-ext/` leakage).
- Update `pyright.exclude` for nested layout.
- Update GitHub source links in `docs/math.qmd` and
`docs/models-and-solvers.qmd` to point to `mlsysim/mlsysim/...`.
Lint configuration
- Add `[tool.ruff]` to pyproject.toml with sensible per-file ignores:
`__init__.py` re-export pattern (F401/F403/F405/F811),
`core/constants.py` star import from unit registry,
tests/examples idioms.
- `ruff check .` reports zero issues (down from 621).
Real bug fixes uncovered by lint cleanup
- `core/solver.py`: remove unused `from pydantic import BaseModel` that
was being shadowed by the local `BaseModel = ForwardModel` alias.
- `sim/simulations.py`: remove redundant local `Fleet` import that was
shadowing the module-level import and triggering F823 (referenced
before assignment) on the earlier `isinstance(..., Fleet)` check.
- `cli/commands/audit.py`, `cli/commands/eval.py`: narrow three bare
`except:` clauses to specific exception types.
- `tests/test_sota.py`: add the missing speculative-decoding ITL
assertion (`res_opt.itl < res_base.itl`) — `res_base` was previously
computed but never compared.
- `cli/commands/eval.py`: drop unused `is_json` local.
- `labs/components.py`: drop unused `energy` placeholder local.
Examples
- `examples/06_multi_objective_pareto.py`: rewrite around the actual
`BatchingOptimizerResult` API (which has no `pareto_front` attribute);
build the front explicitly by sweeping batch sizes through
`ServingModel` + `TailLatencyModel`, then highlight the optimum
returned by `BatchingOptimizer`.
- `examples/gemini_design_loop.py`: fix multi-line f-string syntax errors
(`f"\n[…]"` instead of an embedded literal newline) so the file imports
on every supported Python version.
Dev scripts
- `generate_appendix.py` and `paper/scripts/validate_anchors.py`: switch
from package-relative imports to absolute `from mlsysim... import` so
they run cleanly under the nested layout.
Docs / release notes
- `docs/getting-started.qmd`: replace the editable-install caveat with
`pip install -e ".[dev]"` (now supported).
- `RELEASE_NOTES_0.1.0.md`: drop the three "known limitations" entries
that this commit resolves (editable install, pareto example, gemini
example).
- `CHANGELOG.md`: add a "Packaging & Tooling" section describing the
layout change and the resolver bug fixes.
Verification
- `python -m pytest tests/` → 367 passed (was 367, no regressions).
- `ruff check .` → All checks passed.
- `pip install -e .` → succeeds; live source picked up.
- Fresh-venv wheel install + CLI smoke test → succeeds.
- `examples/06_multi_objective_pareto.py` and
`examples/gemini_design_loop.py` → both exit 0.
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.
Replace duplicated navbar/mobile responsive rules in satellite sites
(instructors, kits, labs, mlsysim, slides) with a single import of
shared/styles/partials/_mobile.scss. Removes ~169 lines of copy-pasted
CSS that would drift out of sync when the shared partial is updated.
- instructors: remove rogue desktop padding, add _mobile import
- kits: remove ~50 lines of duplicated mobile rules, add _mobile import
- labs: remove ~55 lines of duplicated mobile rules, add _mobile import
- mlsysim: remove ~55 lines of duplicated mobile rules, add _mobile import
- slides: add _mobile import (had no mobile rules before)
Every subsite now sets $accent to its brand color and imports
shared/styles/partials/_navbar.scss instead of duplicating the
~40-line navbar block locally. Single source of truth for link
color, hover/active states, brand image height, icon-collapse
media query, and color-scheme toggle.
Drift fix: before this, instructors had font-size: 0.9rem +
weight 500 (making navbar look smaller than peer sites) and
slides had no navbar CSS at all (fell back to Bootstrap defaults).
Both now match the ecosystem.
Also renames $accent in labs/style.scss (previously hot pink
#e94560, used only by .coming-badge) to $coming-badge-pink to
free $accent for the ecosystem convention.
Net: -168 lines of duplicated SCSS across 6 files.
More result_dp["key"] → result_dp.key conversions in cells 4-6
(fabric comparison, pipeline sweep, and 3D parallelism tables).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The restored solver.py returns Pydantic result objects (attribute access)
not dicts (subscript access). Fix result_dp["key"] → result_dp.key and
node_performance → node_profile to match DistributedResult schema.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The solver.py refactoring renamed most solver classes from *Solver to
*Model (e.g. DistributedSolver → DistributedModel). The docs still
referenced the old names, causing the Quarto site build to fail with:
ImportError: cannot import name 'DistributedSolver' from 'mlsysim'
- Fix executable code cells in tutorials/distributed.qmd
- Update non-executable code examples across 10 doc files
- Rename 19 API reference files from *Solver.qmd to *Model.qmd
- SensitivitySolver and SynthesisSolver retain their names (correct)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parallel-agent bibliography verification sweep applied to the paper
bibliography files outside the book proper. These are academic papers
that live in the repo (mlsysim tutorial paper, tinytorch paper,
interviews paper, periodic-table paper) and were previously only subject
to bibtex-tidy formatting, not §5 hygiene validation.
Batches F and G of the Pass 16 parallel sweep processed 77 entries
total across 6 files; 73 auto-applied at HIGH+MEDIUM confidence.
Per-file summary:
mlsysim/paper/references.bib 50 entries applied (0 open)
mlsysim/docs/references.bib 15 entries applied (0 open)
tinytorch/paper/references.bib 7 entries applied (1 open)
interviews/paper/references.bib 3 entries applied (0 open)
periodic-table/paper/ref.bib 11 entries applied (0 open)
Each applied entry carries:
publisher or journal (primary field) + doi (when present on source)
+ x-verified = "2026-04-08"
+ x-verified-by = "pass-16-bib-sweep"
+ x-verified-source = <authoritative URL from DBLP, Crossref, arXiv, etc.>
One open finding (intentional skip):
tanenbaum1987minix — typed @article but the actual publication is
A. S. Tanenbaum's 1987 book "Operating Systems: Design and
Implementation" (Prentice-Hall), not a journal article. The fix is
to re-type as @book, not fill a wrong `journal` field. Flagged for
a future type-refactor pass.
Cross-file duplicate keys are expected and correct: dao2022flashattention,
mattson2020mlperf, and vaswani2017attention each appear in multiple
paper .bib files because each paper independently cites these
foundational works. Each copy was verified and annotated separately.
This is the first pass that the repo-wide bib_lint + bibtex-tidy
pre-commit hooks have been applied to these paper .bib files.
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
