Adds newsletter infrastructure: CLI commands (new, list, preview, publish,
fetch, status) integrated into binder, Quarto archive site config for
mlsysbook.ai/newsletter/, and 12-month editorial content plan. Drafts
are gitignored for private local writing; sent newsletters are committed
as the public archive.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Refactors numerous embedded TikZ diagrams in Quarto markdown files to external SVG images. This improves rendering performance, streamlines content management, and enhances cross-platform consistency.
Introduces interactive "Napkin Math" `callout-notebook` blocks, featuring Python code to generate dynamic visualizations for key system trade-offs and scenarios. Expands the `mlsysim` library with new constants and plotting utilities to support these interactive calculations and comparisons.
Set output-file to Machine-Learning-Systems-Vol1 and
Machine-Learning-Systems-Vol2 in all PDF and EPUB configs.
This makes output filenames clean and distinguishable,
serving as single source of truth for downstream packaging.
- Add PYTHONUTF8=1 env var to all Windows Docker run commands (PEP 540)
- Fix generate_figure_list.py to explicitly use encoding='utf-8' in
write_text() instead of relying on system default (cp1252 on Windows)
- The ≈ character (\u2248) in Vol I content triggered charmap codec errors
Restore Windows container build support that was accidentally removed
in commits a76aab467..a90c8803f. This restores:
- Windows Docker infrastructure (book/docker/windows/)
- Windows container build workflow (infra-container-windows.yml)
- Windows matrix entries in book-build-container.yml
- Windows health check support in infra-health-check.yml
- Windows build flags in book-validate-dev.yml and book-publish-live.yml
Restored from pre-removal state at f85e319d6.
Per request, removed all traces of Windows container builds from the project.
This simplifies the CI pipeline to be Linux-only.
- Deleted `book/docker/windows/` directory and its Dockerfile
- Deleted `.github/workflows/infra-container-windows.yml`
- Removed Windows matrix jobs and steps from `book-build-container.yml`
- Removed Windows inputs and outputs from `book-build-container.yml`
- Removed Windows health checks from `infra-health-check.yml`
- Removed Windows references from `book-publish-live.yml`
- Removed Windows references from `book-validate-dev.yml`
Visual audit identified ~85 high-priority figure gaps across Vol 2.
Three categories of work completed:
- Activated ~22 shelved SVGs (renamed from _prefix, wired into QMD)
- Created ~66 new SVGs from scratch following svg-style.md standards
- Replaced ~15 TikZ-in-callout blocks with proper @fig- labeled SVGs
All figures use sandwich prose pattern: intro sentence before the
figure div (telling students what to look for) and takeaway sentence
after (stating the key insight). 47 figures received prose fixes to
ensure complete integration.
SVG standards: viewBox 0 0 680 460, semantic color palette,
Helvetica Neue typography, arrow markers in defs, ≤250-char alt text.
Drop explicit .pdf from output-file in both vol1 and vol2 PDF configs.
Quarto appends the format extension automatically, so including it
produced Machine-Learning-Systems.pdf.pdf.
Remove 14 duplicate .callout-principle blocks from chapter files,
replacing each with prose containing \ref{nte-...} back-references
to the canonical declaration in the part-level principles files.
This mirrors Vol 1's "declare once, reference everywhere" pattern.
Also reclassifies 3 orphan chapter-level observations from
.callout-principle to .callout-perspective, and adds 7 new
cross-references threading principles across chapters.
Adds a utility script to enforce proper Markdown list rendering. This addresses an issue where Quarto/Pandoc might incorrectly parse lists as paragraph continuations if not preceded by a blank line. Applies this formatting fix across all Quarto files by inserting the necessary blank lines.
Add explicit per-check preflight logging and matrix failure instance reporting in the container build workflow, and update stale documentation links and workflow/file path references.
Eliminates the `llms-txt` configuration option from the Quarto website settings. This directive is no longer relevant or required for the site's operation, simplifying the overall configuration.
FP8 is a data format relevant to single-node systems (H100 supports
it natively), so it belongs in Vol 1's precision list rather than as
an orphaned bullet in Vol 2. Network throughput units (Gbps vs GB/s)
remain Vol 2-only under a proper "Additional Units" subsection.
Vol 1 owns its notation (vol1/frontmatter/notation.qmd) as a
standalone document free of distributed systems concepts. Vol 2
(vol2/frontmatter/notation.qmd) uses {{< include >}} to pull in
Vol 1's notation, then adds distributed systems notation on top.
This eliminates duplication while keeping Vol 1 independent of
Vol 2's publication timeline.
- Remove shared/notation.qmd (single shared file)
- Create vol1/frontmatter/notation.qmd (core ML systems notation)
- Create vol2/frontmatter/notation.qmd (extends Vol 1 via include)
- Update all 8 config files to point to volume-specific paths
- Remove contents/shared/ render glob from HTML configs
Replace D_{vol}, R_{peak}, L_{lat} with D_{\text{vol}},
R_{\text{peak}}, L_{\text{lat}} in all QMD files and notation.qmd
to match the canonical notation convention. Also escape bare
FLOPs/$ to FLOPs/\$ in vol1 introduction. 288 replacements
across 24 files.
The "Scaling the Machine: From Node to Fleet" section, including the
TikZ stack-comparison figure and layer walkthrough prose, belongs in
Vol2 where the reader crosses the scaling boundary. Vol1 now flows
directly from Samples/Dollar into ML vs. Traditional Software, with
a two-sentence scope statement in Book Organization. The fn-gpu-parallel
footnote is relocated next to its callsite on line 116.
Use single-quoted python -c code in the Docker RUN command so the command parses correctly under pwsh -Command and avoids parser errors during image build.
Preserve container PATH during Windows docker-run steps and create/verify a python3 alias from Scoop Python so Quarto/Jupyter kernels that invoke python3 work reliably in both install-time and final verification checks.
Update Dockerfile and workflow final verification steps to normalize native command exit detection and fail explicitly on non-zero exits, avoiding false positives and false negatives in PowerShell checks.
Avoid checking $LASTEXITCODE after a piped lualatex command by capturing command output first and normalizing exit-code detection, preventing false non-zero failures.
Keep fail-fast installation checks for Ghostscript command presence, but defer executing Ghostscript until the final verification phase where full runtime dependencies and PATH are in place.
Verify Ghostscript through the Scoop shim (`gs`) and restore the Ghostscript `lib` path in image PATH so DLL-dependent checks pass during install and final verification.
Add immediate per-tool post-install checks with explicit command resolution and exit handling, keep end-of-job final verification with isolated per-tool reporting, and ensure rsvg-convert is installed/verified for Quarto PDF SVG conversion.
- Add explicit ENV PATH directive (Phase 15) so Docker layers
inherit tool paths instead of relying on registry writes
- Reorder phases: TeX Live moved last (slowest, fail last)
- Create stable symlink C:\texlive\bin\windows for year-agnostic PATH
- Skip pip self-upgrade to avoid WinError 3 shim lock
- Use gswin64c (correct Scoop binary name) instead of gs
- Add rsvg-convert fallback to Chocolatey if Scoop fails
- Replace fragile verification loop with Test-Tool function
- Relax ErrorActionPreference for Chocolatey TeX Live in baremetal
Add fallback search for tlmgr.bat when year-directory pattern
fails, validate bin directory exists before use, and verify
lualatex.exe path explicitly. Adds diagnostic output to help
debug future path resolution issues.
Replace double-quoted string interpolation in throw statement
with -f format operator to prevent Docker RUN flattening from
stripping quotes and causing PowerShell parse errors.
Applies consistent decimal formatting to f-string representations of various metrics throughout the book, enhancing readability. Also updates specific hardcoded numerical examples for clarity.
Improves math expression rendering in the Log-Sum-Exp example for clarity and LaTeX robustness.
Standardizes the display of "MTBF" by removing unnecessary `\text{}` commands throughout the 'Fault Tolerance' chapter.
Updates various internal cross-references and section IDs to ensure correct linking and improved navigation.
Clarifies explanations in the error feedback worked example and the communication-computation overlap condition.
Adds a new bibliography entry for the Goodfellow et al. (2016) Deep Learning book.
- Baremetal workflow: verification step now tracks failures and exits
non-zero when tools are missing (previously always reported success)
- Baremetal workflow: R.exe --version replaced with Rscript --version
to avoid PowerShell Invoke-History alias collision
- Windows Dockerfile: Quarto install switched from direct zip download
(C:\quarto-1.9.27\bin) to scoop install extras/quarto for consistent
PATH handling via Scoop shims
- Windows Dockerfile: final verification rewritten with failure tracking
and exit 1 on missing tools
Introduces a pre-commit hook to ensure SVG image files are well-formed XML,
preventing potential rendering or processing issues. This leverages `lxml` for
parsing, which has been added as a new dependency.
Corrects missing whitespace between attributes in existing SVG figures to
comply with the new validation requirements.
Streamlines in-text references by removing redundant author mentions and consolidating to Quarto's native `@` syntax. Improves consistency and readability of academic citations.
Standardizes the narrative to a third-person, objective perspective.
Improves conciseness and flow of explanations throughout the content.
Refines punctuation for better readability and impact.
Updates various sections to use more general and impactful language.
Replaces specific numerical examples and ranges with qualitative descriptions (e.g., "orders of magnitude," "substantial fraction," "staggering capital expenditure").
Improves the timelessness and broad applicability of the content by reducing reliance on potentially outdated figures.
Adds rsvg-convert to the Windows Dockerfile to enable SVG-to-PDF conversion for Quarto, including its verification.
Refactors Quarto document source:
- Renames a speculative decoding footnote for improved clarity.
- Standardizes an internal TikZ drawing macro boolean flag from `\ifbox@dashed` to `\ifboxdashed` across several files.
Enhances the `inference` chapter with several new SVG diagrams, providing visual explanations for complex topics. These figures illustrate:
- Tensor, pipeline, and expert parallelism request routing
- Horizontal scaling with shard groups
- Global load balancing across multiple regions
- Edge caching strategies (hit/miss paths)
- Spot-aware traffic distribution
Updates the `inference.qmd` document to integrate these new diagrams, replacing previous textual and ASCII-art descriptions for improved clarity and presentation.
Applies a widespread style standardization to existing SVG diagrams, uniformly setting the main background fill color to `#fff` (pure white) and a consistent corner radius (`rx="4"`) for the primary canvas rectangle to enhance visual consistency throughout the book.
Removes trailing blank lines from 14 chapters, fixes table column
alignment and missing newline at end of file in vol2 conclusion,
and adds missing section ID to dedication page.
- Move chapter title (# Title) to immediately after YAML frontmatter in all vol1/vol2 chapters
- Move chapter-start Python cells to after Learning Objectives callout (not before cover image)
- Remove empty chapter-start cells (no executable code) from vol1 conclusion, data_engineering, introduction
- Move conclusion-roofline-setup cell (vol1 conclusion) to after Learning Objectives
- Add missing blank lines after chapter titles before ::: blocks
- Add missing blank lines before/after all ::: div markers across all chapter files (2028 insertions)
Configures explicit `render` paths for both volumes to ensure complete and correct builds, particularly for selective rendering workflows.
Replaces the static cross-reference fix script with a dynamic version. This new script automatically discovers and resolves internal links from QMD sources, improving maintainability and ensuring links remain functional during partial book builds.
Adds a new script to check and auto-fix bibliography completeness, facilitating self-contained volumes.
Removes redundant empty Python code blocks from chapter QMDs and refines frontmatter content for consistency.
Deletes temporary files generated during Quarto book compilation, including index files and the figure manifest. This keeps the repository clean by untracking build artifacts.
