Add reproducible Epoch AI frontier training compute (@fig-ai-compute-growth) and single-run pretraining energy (@fig-frontier-training-energy) figures to Volume II, Chapter 15, paired with builder-reported anchors at declared measurement boundaries, deterministic CSV extraction and manifest receipts, and structured provenance enforcement across book CSV series and figure cells.
Bug fixes
- Single-file --path now scans in nine scopes that treated a file as a
directory and passed having checked nothing.
- Citations: vol3/vol4 chapters were skipped since the bib unification;
every volume now falls back to the shared references.bib, and a missing
bib is reported. Line numbers match the exact key.
- Table caption scopes resume correctly after fences; pdf-entry-numbering
reads the index files it exists to check; python-dollar-collision no
longer stops at a one-line $$...$$; rendered-python-leak line offsets;
float-flow handles :::: openers; pdf-verify no longer passes a failed
edge-overflow row; checklist labels vol3/vol4 correctly.
- --check-scope reports check_scope_retired instead of crashing.
Output
- Checks that cannot run (missing PDF, EPUB, pdfplumber, PyMuPDF, aspell,
unparsable YAML, a crashing checker) report an error with the command
that fixes it instead of passing.
- Book-relative paths everywhere; index/registry findings carry file:line.
- Issues without a suggestion take the fix from check_catalog.yaml.
- Failures end with the command to rerun each failing scope; a clean run
prints one summary line (suppressed by --quiet).
Cleanup
- One helper each for the index, LEGO/registry, and repo registry
wrappers; merged audit-check runners and shared violation conversion.
- Removed dead helpers, aliases, constants, and unused imports.
Check counts on the books are unchanged for every pre-commit invocation.
All four books are clean after the plain-language pass; the check keeps the
word from returning. It flags and never fixes, because the plain replacement
(list, log, table, record, account) depends on what the record holds.
Vol IV chapters shaped to their concept maps; a new chapter 17,
Responsible Physical AI, after Release, with Frontier renumbered to 18;
the fourth law renamed permission must be earned and the new record the
approval record; ledger replaced with plain words; review, fact, and
final-read fixes. Conflicts in Data and Enforcement keep dev's unit
aliases with the branch's renamed comments and messages; the new
chapter's cells use the exported unit aliases dev now requires.
L009 read a fixed list of ten units, so about 1,150 inline ureg.<unit>
uses across the books went unflagged; it now reads the aliases
mlsysim.core.units exports. L002 now catches any physical unit glued on
with suffix=" ..." (volts, hours, Mb/s, N/mm, rad/s², TWh, Mt, g), while
a bare count marker such as suffix="K" still passes. Lands after the
per-volume sweep, which clears every finding in all four volumes.
check structure --scope concept-maps now validates schema v2 maps: claims
cover exactly the owned concepts, one owner per concept per volume, and
every preview or touch names its real owner (previews point later).
concept-order lists concepts used before their owning chapter (opt-in).
info concept-map renders a volume's ownership map from its contracts.
The structure hook also runs when a *_concepts.yml file changes.
Only bibs/ conflicted (adjacent additions on both sides). references.bib
keeps both sides; the Waymo data hub title takes dev's sentence case.
manifest.json is the union, dev winning on shared keys; the offline
ledger check passes.
Body figures are scaled to the text block, so printed text size is the
font size times text width over cropped image width. The style module
fixes the font sizes; nothing measured the other half, and vol2 canvases
drifted from 0.62x to 1.04x with no check failing.
The scope executes each chapter's python cells in a subprocess, measures
every figure inside a #fig- div, and flags print-scale (outside the
range), figure-font (a literal size below the floor), raw-figure (a
figure made without setup_plot/set_book_style), and figure-exec. Limits
are read from mlsysim.viz.style, not defined in the check.
default=False: vol2 and vol3 pass; vol1 (96 findings) and vol4 (72) still
use 8-10 in canvases and await their migration passes.
Branch commits skipped hooks; the full suite at the merge tip found these.
- Bib: drop duplicate epochai2026benchmarks from the merge; rename
villalobos2022will to villalobos2024will to match its year; re-record
ledger hashes for 24 entries whose content is unchanged (tidy reformat)
- Checks: scope cross-chapter-callout-ref to vol1 (vol2-4 carry 113 legacy
refs); add Whetstone to heading proper nouns; lego-dead-code skips
render output
- Units: computed sizes in decimal units, hardware capacities through
fmt_memory_capacity (ch6, ch11, ch14, ch16)
- Prose: abbreviation first-use expansions after content moves, footnote
marker placement, two footnote fixes, margin caption, bracketed source
citations, index main, orphan and duplicate equation labels, dead
LEGO exports
- Auto-fixers: Black on hidden cells, whitespace, blank lines, tables,
bibtex tidy, canonical spellings
Accepted (standard notation the checker rejected): index ranges (s_{0:T}),
an optimum with a transpose (u^{*\top}), an indexed macro in a power
(L_f^{r_i}) or derivative order (y^{(r_i)}), a function's argument as a
subscript (I_x), and \Glyph{...} inside a script. Caption attributes are
unescaped as Pandoc does, so fig-cap="$\\Delta$" is read as \Delta.
Notation tables may put the symbol in the column the header names Symbol.
Rejected (KaTeX renders them, LaTeX does not): an accented macro with a
subscript indexed as {\Macro}_i (TeX unwraps the braces; write
{\Macro{}}_i), and in the registry an unbraced command script such as
\tau_\max.
glyph_collisions takes a heading level. A back-matter appendix that collects
derivations reuses each home chapter's notation in its own ### section, so
the unit there is the derivation, not the ## section; checking at ## forced
book-wide recolors of symbols that never meet on a reader's page.
_macro_extent took the longest run whose normalized text matched the macro's
LaTeX, and trailing whitespace normalizes away, so a replacement at the end
of a display-math line swallowed the line break (rendering unchanged, source
lines joined). It now never ends on whitespace.
Also accept a bootstrap replicate on an optimum (^{*(b)}) and an
order-statistic rank written as a rounded expression (_{(\lceil Bq \rceil)}).
A macro whose LaTeX already carries a subscript, indexed bare
(\RouterGateProbability_{i,j}), is a double subscript; a multi-token macro
used as a script without braces (\sup_\MonitoredFeatureLevel) gives LaTeX only
its first token. KaTeX verification expanded macros in braces and passed both;
the PDF build failed. Report them as double-script and unbraced-script.
Also accept spacing inside a power (^{\,i}) and an order statistic's
parenthesized rank (p_{(1)}).
- Raw text is compared normalized (T_N and T_{N} are the same).
- A macro's extent is the longest exact match within a length bound; stopping
at the first non-prefix missed brace groups (B^{*} left a stray ^{*}).
- Braces around any single token normalize away, not only letters and digits.
- The before-side table of notation verify defines \Glyph too, so unchanged
\Glyph spans are no longer reported.
- Collisions skip pairs listed in vocabulary.yaml same_glyph_ok.
A reader works through a chapter one ## section at a time, so one letter may
mean different things in different sections but never two things in one. The
notation chapter is skipped: it lists every meaning by design. Author decision
2026-10-08.
When a site is wider than the macro it receives (A_{i0} for a macro rendering
A), the leftover is kept only if it is an index or power; a text label belonged
to the symbol being replaced and is dropped with it. Exemptions for the applier
now come from the repo's exempt.yaml, not the defaults.
New scope check notation --scope collisions. Two registry entries may share
LaTeX across the book, but a reader of one chapter must never see one letter
mean two things. Enforced for volumes in STRICT_CONVERTED_VOLUMES (renamed
from STRICT_DEAD_ROW_VOLUMES; it now gates both this and dead-row coverage).
Registry. data/vocabulary.yaml: every unit is built from a closed list with
base dimensions (data, compute, money and counted things are dimensions of
their own), and a name ending in a quantity word (Time, Count, Probability,
Rate, Bandwidth, Matrix, ...) must have that word's kinds and dimension. Names
ending in no such word stay free; field idioms (LearningRate) are listed with a
reason. Design reviewed by an empirical test on all entries, a usability test
and a skeptic review; a mandatory suffix vocabulary, an explicit quantity field
and pint dimension checks were dropped on that evidence. Free-text units become
`varies` with the old wording in notes; two kinds fixed; \AccuracyAtTime ->
\AccuracyAfterDeployment and \StoragePricePerByteTime -> \StorageCapacityPrice
(aliases kept). The 752 entries the vol1 conversion needs are registered (no
chapter uses them yet).
Checker and applier, from what the first vol1 run taught:
- A macro whose LaTeX spans several tokens (P_t, \Pr(E)) replaces the whole
run; a site wider than the macro (A_{i0} for a macro rendering A) keeps its
leftover subscript. Both used to print wrong; the KaTeX check caught it.
- Inline `{python}` values inside math are one token, not a string of letters.
- Matrix-entry positions (ij, i0, 0j) are indices.
- A macro may carry an index macro as subscript, a power by another macro, a
parenthesized layer or block index, * for the optimum, and a prime when it is
a function. Text labels still make a new symbol.
- \Glyph{B} marks a letter that prose mentions rather than uses; it renders
unchanged and replaces the unused per-line notation-ok hatch.
Strict baseline regenerated: 42,880 -> 42,427 sites (the wider rules remove
findings, none are added).
binder notation concordance <Macro> lists every use of one macro in the
book with its sentence, so a reviewer can see in one place whether all
uses mean what the registry says. The glossary assigner now matches a row
by exact site (line, col, token) when one line holds a symbol with two
meanings, and reads the 'symbol' field of the glossary brief.
A raw symbol's site now includes a descriptive subscript (A_{\text{component}}),
because the registry entry's LaTeX carries it; replacing only the base letter
would render the subscript twice. Index, power and transpose subscripts stay
outside the symbol.
binder notation assign turns a chapter glossary into exact edits with no
judgment: each site takes the glossary row for its glyph and line; retired
aliases take their canonical name; unmatched or doubly matched sites are
returned for review instead of guessed.
Nested escaped braces (2^{{-{alpha:.3f}}}) left field names in the text,
which read as stray letters; fields now become a numeral, which can never
count as a symbol. Baseline regenerated for the corrected reading.
Every symbol in math must be a registered mlsysim macro. The check reads
math the way Pandoc does (body math matches Pandoc's AST on all 151 files)
plus figure/table captions, quiz JSON and fmt_math strings, and reports
raw letters, Greek letters, font/accent forms, decorated macros, retired
aliases, unknown commands, and macros a chapter has not declared.
- check notation --scope strict: ratchet on fingerprints (symbol + span),
so a commit can remove raw symbols but never add one; baseline
44,527 sites in 145 files
- check notation --scope conventions: registry naming and field rules
- binder notation report|find|verify|apply: work packages grouped by
section with candidate macros and meanings; registry search by meaning;
KaTeX MathML comparison proving an edit renders exactly as before
(including registry LaTeX changes); a deterministic applier that edits
only the exact tokens it is given and refuses anything that moved
- Exemptions by role, not glyph (exempt.yaml): index letters only in
subscripts, d as a differential, e as a base, T as a transpose
- 23 unit tests plus the Pandoc cross-check
Volume I is in print, so the goal was consistency with the fewest changes.
A 17-auditor read of vol1 against the notation table found 284 distinct
findings; one fixer per chapter applied the regressions (23, from the
earlier pattern-based passes), mechanical fixes (208), and the approved
conventions, matching the surrounding prose.
Notation table (prints in vol1):
- Errata: the subscript sentence (the subscript is upright, not the
root); the decimal-units rule now states the nameplate-capacity
exception the assumptions appendix already used; notes no longer
point at symbols the table never defines.
- Rows only where chapters improvised for want of one: d_in/d_out,
y-hat, T_distill, T_memory/T_compute, N_GPU, L_lat,total, s_sample,
s_loss; sentences for GEMM M,N,K, \mathcal{O}, l_p norms, mu, power
subscripts, and upright p99.
Structure for four volumes:
- The shared body is split into a series core (head + tail, printed in
every volume) and a vol1-only degradation extension, so vol2-4 no
longer print tau/lambda meanings their extensions use differently.
Vol1's assembled text differs only by the intended edits.
- New `binder check notation --scope vol1-print-pin`: fails when vol1's
printed notation text changes; re-pin only for an approved erratum
(binder/tools/audit/repin_vol1_notation.py).
- Tooling updated for the new file names (notation, currency-style,
layout, math-render audits).
Also restores footnote markers and index tags dropped by the figure
reference rewrites (5 footnotes, 6 index entries), fixes the MIT Press
spellings and abbreviation expansions those rewrites introduced, a
residual-block Jacobian evaluated at the wrong layer, and the Kaplan
exponent arithmetic in Appendix B. Margin SVGs regenerated from the
generator for p99, r_pipe, and nameplate GB labels; TikZ labels updated
to the same symbols. Vol1 PDF builds cleanly with all validations.
Pre-commit: skipped book-check-footnotes, -code, -prose, -punctuation,
-numbers, -notation. Every remaining failure in them is pre-existing on
dev (vol2-4, plus unchanged vol1 percent and literal-number items); the
vol1 notation and pin scopes pass.
Relocate master bibliography (references.bib), cryptographic ledger
(manifest.json), curated external provenance (canonical_provenance.json),
and staging candidate inbox (inbox.bib) into unified bibs/ directory.
Maintain books/references.bib as git-tracked relative symlink to
../bibs/references.bib for seamless Quarto and compiler compatibility.
Update Binder CLI, verification engines, pre-commit guards, codespell
rules, and gateway test fixtures to point to bibs/ paths.
- New tested helpers: calc_partial_slowdown_stretch and
calc_stall_share_breakeven (Ch13, Amdahl), importance-sampling and
cross-entropy helpers (Ch15), calc_conjunctive_confidence and
calc_multilegged_confidence (Ch16); chapters now call them.
- fmt_motor_constant recognized by the math-canonical and code checkers.
- OS1-64 max_range marked needs-source.
- Ch12 handover sentence matches the ISO/TS 15066 two-body contact model
(free hand 0.24 m/s ceiling; clamped hand fails at the 0.10 m/s cap).
Skipped hooks, all failing only outside vol4 (0 vol4 findings each):
book-check-headers, book-check-labels-orphans (pre-existing vol3);
book-check-bib (shared references.bib required fields), book-check-refs
and book-check-footnotes (vol3 content merged from dev in 402fc86cc9).
Conflicts resolved: provenance_catalog.py and hardware/types.py kept both add-only blocks; test_vol4_lego_cells.py kept the branch's CAN FD assertions (ISO 11898-1 accounting). MLSysIM tests pass.
- Bibliography: 17 staged chapter files merged into references-vol4.bib
(192 -> 416 entries; 228 new, 21 corrected, 14 duplicate works
consolidated to one key each, 4 uncited removed); standards in one
house form; RSS proceedings publisher allowed in bib_lint.
- MLSysIM (in progress when stopped): ISO hand contact model, D435i RGB
rolling shutter, OS1-64 datasheet fields, provenance entries, formatter
for motor constants, unit-alias fixes.
Committed with --no-verify at a stopping point. Known open failures:
math-canonical at 02_body.qmd:1136 and exec in appendix_systems data
sheet (124 vs 125 registry rows); MLSysIM full test run not yet done.
- Complete 100% academic verification of 2,063 entries across all .bib files against Crossref, DataCite, IEEE, ACM, and official DOIs
- Prune 14 fabricated/hallucinated citations and replace damaged citations with authentic references (Wu et al. CVPR 2018 BlockDrop, Schelter et al. PVLDB 2018 AWS Deequ, Thompson et al. IEEE Spectrum 2021, Patterson et al. IEEE Computer 2022)
- Add professional notice headers across all active .bib files prohibiting fabricated entries
- Add Scope('verify', '_run_bib_verify') to 'binder check bib' for cryptographic SHA-256 ledger integrity and live Crossref/DataCite checks
- Expand CANONICAL_PUBLISHERS with standard academic publishers (Addison-Wesley, Manning, Academic Press, Chapman & Hall, CRC Press, No Starch Press, etc.)
- Add test_bib_verify.py unit test suite and check in verification manifest ledger
- appendix_math, appendix_systems: sentence-case 23 headings per heading-case
- lego_units L020: a memory unit multiplied by time (GB * second) is not a
memory quantity, so it no longer demands a memory formatter
- Add exec scope to binder check code and test_all_qmd_execution.py to verify live execution across all volumes
- Unify per-token and aggregate KV cache calculations across Volume 3 chapters using calc_kv_cache_bytes_per_token
- Standardize reference model definitions with CodingAgents.SWE_Bench_Runner in Chapter 04
- Added 12 new domain formatters (thermal resistance, heat capacity, density, mass flow rate, volumetric flow rate, charge/battery capacity, angle, inductance, capacitance, power rate, stiffness, volume) and updated temperature detection for Kelvin vs Celsius.
- Re-exported all 93 canonical formatters in mlsysim.__init__.py and updated binder check linters.
- Migrated all fmt_qty calls in Volume 4 chapters and backmatter to domain formatters.
- Removed all 10 Volume 4 L020 entries from lego_units_baseline.json.
Vijay Janapa Reddi