MIT Press requires inline cross-references to use lowercase prefixes
("figure 1", "table 2", "section 3") with capitalization only at
sentence starts. Quarto supports this via *-prefix config options
paired with the @Fig- / @Tbl- / @Sec- syntax for sentence starts.
Config: add fig-prefix, tbl-prefix, sec-prefix, eq-prefix, lst-prefix
to the shared crossref base config (crossref-video.yml).
Resolver: update fallback labels in resolve_cross_references.py to
match the new lowercase convention.
Next step: sweep ~1,173 sentence-start refs across vol1+vol2 QMD files
to use the @Fig- / @Tbl- / @Sec- / @Eq- / @Lst- capitalized syntax.
The original prefix choices for callout-definition (def-), callout-example
(exm-), and callout-theorem (thm-) collided with Quarto's built-in
crossref types. Quarto auto-wraps any div with one of those IDs in a
\begin{definition} / \begin{example} / \begin{theorem} theorem env that
prints its own "Definition X.Y." / "Example X.Y." header into body
prose — which then visually duplicates with our custom callout's title
bar (which the Lua filter renders WITHOUT the number, because it
detects the outer wrapping).
Visible symptom: a stray "Definition 1.2." line above the callout
box, plus a callout title bar showing only "Definition: <name>"
without the number.
Fix: rename to prefixes Quarto does not recognize as built-ins, so no
outer wrapping happens. The custom Lua filter then puts the number
directly in the callout's title bar — matching how Principle, Napkin
Math, Checkpoint, etc. already work.
Renames applied book-wide:
def- → dfn- (definition)
exm- → exmp- (example)
thm- → thrm- (theorem)
YAML prefix: declarations updated to match. 202 ID and \ref{} changes
across 30 QMD files.
Verified by rebuilding the Introduction chapter: title bars now read
"Definition 1.1: …", "Example 1.1: …", "Theorem 1.1: …" exactly as
the Notebook / Principle / Checkpoint title bars already do.
Adds the `prefix:` field to each numbered callout class in
custom-numbered-blocks.yml so the convention is declared once and
discoverable by tooling. Prefixes are short (3-letter) and match the
group's role:
callout-example → exm
callout-notebook → nbk
callout-theorem → thm
callout-war-story → ws
callout-lighthouse → lhs
callout-definition → def
callout-perspective → psp
callout-checkpoint → chk
callout-principle → pri (book-wide global)
Then sweeps all 31 chapters and inserts `{#prefix-chapter-slug-…}`
identifiers on every numbered callout that didn't already have one,
deriving the slug from the callout's title. 662 IDs added across
both volumes.
The cross-reference resolution itself was already wired up in the
custom-numbered-blocks Lua filter (it handles `\ref{}` matching against
any identifier on a numbered callout). Adding the IDs is purely
declarative — authors can now write `\ref{exm-inference-dynamic-
batching-resnet50}` and it resolves to "Example 10.1" automatically.
Verified by rebuilding vol2 — no regressions, no visual breakage,
flagged-page count slightly improved (57 → 54).
Previously every chapter's Learning Objectives used the native Quarto
.callout-tip with title='Learning Objectives'. Native callouts have
different DOM structure, CSS padding, and LaTeX rendering than the
book's custom foldbox callouts (Napkin Math, War Story, Example, etc.),
which produced two problems:
1. Visible spacing inconsistency in HTML/EPUB: the .callout-tip header
was 17 px taller than foldbox <summary> headers because of
padding-bottom: 1em on .callout-icon-container / .callout-title-
container. Previous commits tried to patch this via CSS overrides,
but the fix was fragile and only covered HTML.
2. No PDF styling parity: native .callout-tip in PDF uses Quarto's
default tcolorbox rendering, which differs from foldbox.tex. Colors,
borders, and header geometry all mismatched the rest of the book's
callouts.
Fix: register a custom foldbox callout class called
'callout-learning-objectives' in custom-numbered-blocks.yml with:
- colors: ['E8F2EA', '4A7C59'] (green, matching native callout-tip)
- collapse: false
- numbered: false
- label: 'Learning Objectives'
Add icon assets (SVG, PNG at 128×128, PDF) — a lightbulb matching the
native callout-tip lightbulb metaphor, in the same green stroke color.
Sweep every chapter (vol1 + vol2 + appendices + frontmatter, 44 files)
to replace ':::{.callout-tip title="Learning Objectives"}' with
':::{.callout-learning-objectives}'.
Benefits:
- One source of truth: YAML config drives HTML/EPUB (foldbox.css) and
PDF (foldbox.tex) consistently.
- Uniform spacing: summary_h=36.9 px, summary_pt/pb=8.5 px across all
callouts now — verified via Playwright measurements.
- PDF rendering: foldbox.tex auto-generates \definecolor from YAML,
so LO PDF callout inherits the same tcolorbox geometry as other
foldbox callouts. Verified by rendering the Conclusion chapter PDF
(page 11).
* fix(tests): make mlsysim.core importable from CI without pip install
`book/tests/test_units.py` did `sys.path.insert(0, _repo_root)` and
then `from mlsysim.core.constants import *`. That only works if a
top-level `mlsysim/__init__.py` exists at the repo root — but the
actual package layout is two levels deep:
<repo_root>/mlsysim/ ← project dir, NOT a package
<repo_root>/mlsysim/mlsysim/__init__.py ← actual Python package
<repo_root>/mlsysim/mlsysim/core/ ← submodule
Locally, the import succeeded because `mlsysim` is `pip install -e`'d
in dev environments. CI has no editable install, so Python 3.3+
treated `<repo_root>/mlsysim/` as an implicit namespace package and
then `mlsysim.core` was unfindable, producing
`ModuleNotFoundError: No module named 'mlsysim.core'`.
Result: `book-mlsys-test-units` has been Failed on every dev
`book-validate-dev` run since 2026-04-18 (last green: 2026-04-17).
The hook is what blocks the publish guard for the upcoming book
release, so this also unblocks B1–B6 of the staged-rollout plan.
Fix: point `sys.path` at `<repo_root>/mlsysim/` (the directory that
*contains* the package), not `<repo_root>/`. Validated:
- hook passes locally via `pre-commit run book-mlsys-test-units`.
- emulating CI (no editable install, plain sys.path), the import
chain now resolves `mlsysim.core` correctly; runtime deps
(pint, pydantic, numpy, pyyaml, rich) are already in
`book/tools/dependencies/requirements.txt` which CI installs.
* fix(quarto): restore mlsysim importability after PR #1397 outer-init removal
Quarto's execute env sets PYTHONPATH="../.." (= repo root) so that
.qmd Python chunks can do `from mlsysim.core.constants import *`. That
worked because there used to be an outer `mlsysim/__init__.py` that
made `<repo_root>/mlsysim/` itself a Python package — even though the
real package is one level deeper at `<repo_root>/mlsysim/mlsysim/`.
PR #1397 ("MLSys·im 0.1.0 release-prep audit") cleaned up that
nested-with-same-name layout by removing the outer init (correct
packaging hygiene). After that, `<repo_root>/mlsysim/` became an
implicit namespace package without `core/`, and every .qmd that
imports `mlsysim.core` started failing in the build container with
`ModuleNotFoundError: No module named 'mlsysim.core'`.
This was masked behind another failure for 3 days: `book-validate-dev`
was already red on the `book-mlsys-test-units` pre-commit hook (fixed
in PR #1419), so the container build matrix was being SKIPPED, not
RUN. As soon as PR #1419 unblocked the matrix, every Linux container
build started failing with the same import error, plus the symmetric
Windows ones.
Concrete blast radius: 15+ vol1 chapters and a similar count in vol2
import `mlsysim.core` directly in their Python chunks (benchmarking,
nn_architectures, hw_acceleration, model_serving, training, ml_ops,
etc.), so this affects every HTML/PDF/EPUB build.
Fix: prepend `<repo_root>/mlsysim/` (where the real package lives) to
PYTHONPATH so `import mlsysim` resolves to the correct file without
requiring `pip install`. Keep the original `<repo_root>` entry so any
existing imports that rely on repo-root scope continue to work.
Verified locally by emulating the Quarto execution context:
cd book/quarto && PYTHONPATH="../..:../../mlsysim" python3 -c \
'from mlsysim.core.constants import *; ...'
resolves cleanly. The fix touches all five Quarto config files that
duplicate the PYTHONPATH line (the shared base + 4 PDF variants), so
HTML, PDF, and PDF-copyedit builds all benefit.
Companion to PR #1419 (test_units.py path fix); same root cause,
different surface area.
- Rename 409 unused image files with _ prefix across vol1 (272) and
vol2 (137) so they are visually identifiable without being deleted
- Restore polished TikZ figures from main branch into vol2 chapters:
fault_tolerance, edge_intelligence, security_privacy, distributed_training,
responsible_ai, sustainable_ai, robust_ai
- Remove all tikz-source backup blocks (0 remaining across vol2)
- Prefix 33 SVG files superseded by restored TikZ with _
- Add GreenL0, chains, shapes.arrows, decorations.pathreplacing to diagram.yml
Moves the mlsysim package from book/quarto/mlsysim/ to the repo root
so it is importable as a proper top-level package across the codebase.
Key changes:
- mlsysim/fmt.py: new top-level module for all formatting helpers (fmt,
sci, check, md_math, fmt_full, fmt_split, etc.), moved out of viz/
- mlsysim/viz/__init__.py: now exports only plot utilities; dashboard.py
(marimo-only) is no longer wildcard-exported and must be imported
explicitly by marimo labs
- mlsysim/__init__.py: added `from . import fmt` and `from .core import
constants`; removed broken `from .viz import plots as viz` alias
- execute-env.yml: fixed PYTHONPATH from "../../.." to "../.." so
chapters resolve to repo root, not parent of repo
- 51 QMD files: updated `from mlsysim.viz import <fmt-fns>` to
`from mlsysim.fmt import <fmt-fns>`
- book/quarto/mlsys/: legacy shadow package contents cleaned up;
stub __init__.py remains for backward compat
- All Vol1 and Vol2 chapters verified to build with `binder build pdf`
Introduces reusable `pic` definitions for common elements across numerous TikZ diagrams, enhancing modularity and visual consistency. Improves diagram readability through explicit node positioning and refined styling.
Standardizes hardware and model constants in Python code by using specific `mlsys.constants` and dedicated setup classes, improving maintainability and clarity.
Addresses minor LaTeX formatting in math blocks and refines unit-aware calculations.
Refactors the build process to leverage shared output file resolution logic, ensuring consistency across build and debug commands.
Improves validation by streamlining bibliography handling and adding stricter citation matching.
Updates diagram dependencies and adjusts content for clarity and accuracy.
Replace four distinct colors (Brown, Blue, Green, Red) with ETHZ Blue
intensity gradient (25%→50%→75%→100%) in fig-fleet-stack and
fig-vol2-roadmap, matching vol1 mlsysstack crimson gradient pattern.
Refines book abstracts, table of contents, and diagram configurations for improved clarity and structure.
This commit enhances the descriptions of both Volume I and Volume II, emphasizing their respective focuses. It also introduces a framework decision tree to guide the selection of parallel training strategies and inference frameworks, and diagrams for visualizing hardware constraints.
- Add war story callout definition in custom-numbered-blocks.yml
- Create war story icon in all three formats (SVG, PNG, PDF) matching
the 64x64 stroke-only style used by all other callout icons
- Add war story bibliography and PDF config entry
- Add first war story ("The Quadratic Wall") in nn_architectures
- Include icon conversion utility script
Checkpoint the branch-wide content/config revisions together with workbench enhancements so chapter rendering and developer workflows stay aligned. This captures the current validation-driven formatting and parallel build/debug improvements in one commit.
Moves common diagram and PDF title/build settings into shared metadata layers, simplifies per-volume configs to keep only volume-specific values, and carries related chapter figure text/asset updates needed in the current working set.
Unifies Quarto metadata into shared base/format/volume fragments while carrying through chapter path, asset, and tooling updates to keep the repository consistent and easier to maintain.
Vijay Janapa Reddi
Zeljko HrcekandGitHub
Zeljko Hrcek