Introduces a detailed build manifest that appears in a dedicated output channel prior to any build or debug command execution.
The manifest provides key information about the upcoming operation, including the target volume, build format, execution mode (sequential or parallel), the Quarto configuration file in use, and a comprehensive list of all chapters slated for compilation. The chapter list is derived directly from the Quarto YML, acting as a single source of truth that reflects the full intended book structure, even for entries that are currently commented out.
Additionally, the manifest clearly displays the exact shell command that will be executed, enhancing transparency and aiding in debugging.
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.
This commit standardizes percentage formatting across the entire codebase to prevent critical rendering bugs (like the `19250000000000%` effective utilization bug in Vol 2).
Root Cause:
When dividing two Pint Quantities (e.g., `flop/second` by `TFLOPs/second`), Pint creates a mixed unit (`flop/TFLOPs`). The raw `.magnitude` of this fraction is $10^{12}$. When passed to `fmt(x * 100)`, it multiplied that massive magnitude by 100, resulting in an incorrect display.
Fix:
1. Fortified `fmt_percent` and `display_percent` in `mlsys/formatting.py` to defensively strip units using `.m_as('')`. This forces Pint to cancel out the units (e.g., `flop/TFLOPs` becomes `1.0`) *before* extracting the number.
2. Replaced all instances of `fmt(X * 100)` with the fortified `fmt_percent(X)` across Vol 1 and Vol 2.
3. Fixed inline f-strings in `appendix_assumptions.qmd` by moving formatting logic into the Python setup cell as `_str` variables, adhering to the book's standard practice.
Validation:
- Audited all `.magnitude` extractions in the codebase to ensure they are safe (e.g., explicitly converting to dimensionless units first).
- Ran `validate_inline_refs.py` and confirmed no Python variables are trapped inside LaTeX math mode.
- Successfully built full PDFs for both Volume 1 and Volume 2.
- Add missing attributes to FleetFoundations in appendix_fleet.qmd
- Fix regression_testing.png image path in fault_tolerance.qmd
- Add pgfplots package to header-includes.tex for TikZ compatibility
- Fortify fmt_percent in formatting.py to handle Pint Quantities properly, fixing the 19250000000000% display bug
Introduces `--only-from-report` and `--only-keys` arguments to the `references` validation command.
These allow re-validating only specific citation keys, either from a previous validation report or a custom list.
This significantly improves the workflow for correcting references by enabling focused re-runs and reducing validation time.
Removes the standalone `README_REFERENCE_CHECK.md` documentation, as its content is now implicitly handled by the integrated CLI help and broader documentation.
Flagged by the sustainable_ai editor agent as newly discovered during fixing:
- line 635: "If your cluster consumes...how much...actually went...how much was wasted?"
→ impersonal declarative; removes "your", two embedded rhetorical questions, two "actually"
- line 2261: "You want to fine-tune a small language model" in .callout-notebook
→ "Consider fine-tuning a small language model" (impersonal)
Post-commit verification found 6 additional violations not caught by the
initial audit agents:
distributed_training (4 fixes):
- line 108: second person "If you could purchase a single GPU" → impersonal
- line 280: rhetorical Q "How exactly do 1,024 GPUs...agree" → declarative
- line 784: second person "Your AllReduce...Where do you look?" in
.callout-perspective → impersonal problem statement
- line 1347: rhetorical Q "where did the missing 25%...go?" → declarative
sustainable_ai (2 fixes):
- line 2047: embedded rhetorical Q "where does the dominant share of energy go?" → declarative
- line 2414: closing rhetorical Q "what happens to these clusters...?" → declarative noun phrase
