Replace confusing horizontal timeline with vertical lines at module boundaries
to show discrete activation points rather than continuous progression.
Key improvements:
- Vertical dotted lines at each module boundary (M01, M03, M05, M09, M13, M20)
- Module 05 activation shown as thick red vertical line with 'ACTIVATE' label
- Removed circular ACTIVATE button - replaced with simple red text label
- Removed horizontal dashed/solid lines that suggested continuous flow
- Features now clearly shown before/after Module 05 boundary
Visual logic now clearer:
- Left of M05 vertical line = dormant features (gray boxes)
- Right of M05 vertical line = active features (orange boxes)
- Vertical alignment shows the exact moment of activation
This addresses user feedback: 'horizontal line really doesn't make sense' and
'put vertical lines that align with each of the milestones'. The redesign makes
it immediately clear WHEN features activate (at Module 05 boundary) rather than
suggesting a gradual continuous transition.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Figure 3 (progressive-timeline) was created but never referenced in the text,
leaving readers without guidance on when to consult it.
Added reference at line 627 in the Pattern Implementation subsection, right
after introducing the dormant/activation concept via code listings. The
reference reads: 'Figure 3 visualizes this activation timeline across the
curriculum.'
This ensures all figures in the paper are properly referenced and integrated
into the narrative flow. All other figures and tables were already correctly
referenced.
Reference audit:
✓ Figure 1 (code-comparison) - line 183
✓ Figure 2 (module-flow) - line 290
✓ Figure 3 (progressive-timeline) - line 627 [NEW]
✓ Table 1 (framework-comparison) - line 421
✓ Table 2 (objectives) - line 478
✓ Table 3 (performance) - lines 811, 1013
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Transform figure captions from purely descriptive to explanatory, matching
the pedagogical style used for code listings.
Figure 2 (Module dependency flow):
- Before: Basic description of color coding and dotted lines
- After: Explains HOW students build incrementally, WHY the structure matters
(mirrors compiler courses), and WHAT each tier accomplishes (foundation
enables architectures enables optimization)
- Adds concrete examples: autograd M05 requires tensors M01, benchmarking
M19 requires all architectures
Figure 3 (Progressive disclosure):
- Before: Technical description of dormant vs active features
- After: Explains the LEARNING BENEFITS with numbered list:
(1) Early API familiarity avoids interface surprise
(2) Forward compatibility demonstrated through unchanged code
(3) Curiosity-driven motivation through visible inactive features
- Adds concrete example: 'Why does .backward() exist if we can't use it yet?'
question motivates curriculum progression
Both captions now explain not just WHAT the figure shows, but WHY it matters
for learning and HOW it supports the pedagogical approach. This addresses
user feedback about making figures as explanatory as code listings.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add questioning comments to PyTorch and TensorFlow code examples to create
pedagogical contrast with TinyTorch's answer-providing comments.
PyTorch additions:
- How much memory? before Linear layer initialization
- Why does Adam need more memory than SGD? before optimizer
- What cost? How fast? in training loop
TensorFlow additions:
- What's happening inside? before model definition
- Why Adam over SGD? Memory cost? before compile
- How does it work? What's the complexity? after fit
This creates the intended question vs answer dynamic where students see
black-box abstractions on the left raising systems questions, while TinyTorch
code on the right provides concrete answers with memory calculations,
complexity analysis, and optimizer state explanations.
Addresses user feedback about making one side look like the question and
the other like the answer.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Applied \resizebox to all three tables in the paper:
- Table 1 (Framework comparison): \resizebox{\textwidth}{!}{...}
- Table 2 (Module concepts): \resizebox{\textwidth}{!}{...}
- Table 3 (Performance): \resizebox{\columnwidth}{!}{...}
This ensures tables scale appropriately whether in two-column or full-width
layouts, preventing overflow and maintaining readability.
Paper compiles successfully: 24 pages, 388KB PDF
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes:
- Reverted invalid natbib options (maxcitenames/maxbibnames are biblatex-only)
- natbib with plainnat already uses "et al." for in-text citations with 3+ authors
- Bibliography shows full author lists (standard academic practice)
- Restored full author lists in references.bib for proper attribution
Current behavior:
- In-text: "Reddi et al. (2020)" for papers with many authors
- Bibliography: Shows all authors (e.g., all 51 authors for MLPerf paper)
To truncate bibliography author lists to "10 + et al.", would need:
1. Custom .bst bibliography style file, OR
2. Switch from natbib to biblatex package
Compiled successfully: paper.pdf (22 pages)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Reduced excessive author lists in bibliography entries to improve
readability and save space. Papers with >10 authors now show first
10 followed by 'and others' which BibTeX renders as 'et al.'
Changes:
- perkins1992transfer: Fixed corrupted entry (was 300+ author Nature
paper, now correct Perkins & Salomon 1992 encyclopedia entry)
- reddi2020mlperf: Truncated from 51 authors to 10 + others
- banbury2021widening: Truncated from 24 authors to 10 + others
- banbury2021benchmarking: Truncated from 17 authors to 10 + others
This is standard practice in academic publishing - showing all
authors for papers with hundreds of contributors wastes space and
provides no additional value to readers.
Paper size reduced from 24 pages back to 22 pages.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replaced placeholder numbers with actual measurements from benchmarking
script. Numbers show TinyTorch's pure Python implementations are
100-10,000× slower than PyTorch, demonstrating the pedagogical value
of experiencing performance reality.
Real benchmark results:
- MatMul (1K×1K): 1.0s vs 0.9ms = 1,090× slower
- Conv2d (CIFAR batch): 97s vs 10ms = 10,017× slower
- Softmax (10K elem): 6ms vs 0.05ms = 134× slower
Methodology:
- MatMul: Double-loop with numpy dot for inner loop
- Conv2d: Pure 7-nested-loop implementation as shown in paper
- Softmax: Pure Python loops for max, exp, sum, normalize
Created benchmark_quick.py script that measures actual performance
using implementations that match what students write in the curriculum.
Conv2d uses single-image timing extrapolated to full batch for speed.
Updated paper text to reference actual measured values (97s vs 10ms)
instead of placeholders, strengthening the experiencing performance
reality pedagogical argument.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added citations for sustainable ML, energy-efficient computing, mixed
precision training, and TinyML benchmarking to strengthen the future
work discussion.
New citations:
- Strubell et al. (2019): Energy and Policy Considerations for Deep
Learning in NLP - foundational work on ML carbon footprint
- Patterson et al. (2021): Carbon Emissions and Large Neural Network
Training - comprehensive analysis of energy use in large models
- Micikevicius et al. (2018): Mixed Precision Training - ICLR paper on
FP16/FP32 training techniques
- Banbury et al. (2021): Benchmarking TinyML Systems - TinyMLPerf
benchmarking framework for edge AI
Citations integrated into:
- Roofline Models section (mixed precision advantages)
- Energy and Power Profiling section (sustainable ML and edge AI)
These citations ground the future work proposals in established
research on green AI, energy-efficient ML, and edge deployment.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Converted all paragraph headings to bold text format for consistent
styling throughout the document. This improves visual consistency and
follows the requested formatting guidelines.
Changes:
- Paper Organization (introduction)
- Build/Use/Reflect cycle descriptions
- Why Milestones Matter
- The Six Historical Milestones
- Experiencing Performance Reality
- All future work subsection headings (Roofline Models, ASTRA-sim,
Energy and Power Profiling, The Three-Tier Systems Pedagogy)
Table 3 remains correctly positioned in Systems Integration section
where performance trade-offs are discussed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Cleaned up:
- FIGURE_SUMMARY.txt (temporary figure notes)
- INTRODUCTION_REVISED.tex (draft version, now integrated)
Build artifacts (.aux, .bbl, .blg) left unstaged as working files.
Research team reference documents retained for review:
- CITATIONS_TO_ADD.md
- CLAIM_EVIDENCE_MATRIX.md
- EVIDENCE_INVENTORY.md
- LITERATURE_REVIEW_ASSESSMENT.md
- NEW_CITATIONS.bib
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
CRITICAL FIXES (blocking issues):
1. Fixed corrupted bruner1960process citation (was citing 2023 infant mortality paper)
- Now correctly cites Bruner's "The Process of Education" (1960)
2. Fixed corrupted perkins1992transfer citation (was citing wrong paper)
- Now correctly cites Perkins & Salomon "Transfer of Learning" (1992)
3. Added systems thinking citation (Meadows 2008) for tacit knowledge framing
4. Added compiler pedagogy citation (Aho et al. 2006 Dragon Book)
HIGH-PRIORITY IMPROVEMENTS:
5. Consolidated validation caveats into ONE comprehensive scope paragraph
- Removed defensive tone from individual contributions
- Stronger framing: "demonstrated design patterns" vs "unvalidated claims"
- Clear separation: technical correctness (proven) vs learning outcomes (hypothesized)
6. Broke dense introduction paragraph into two for readability
- Para 1: Workforce statistics and demand
- Para 2: Tacit knowledge problem and automation resistance
7. Sharpened MiniTorch comparison with concrete differentiation
- Added: math-first vs systems-first pedagogical inversion
- Added: progressive disclosure (unified API) vs separate abstractions
- Made competitive positioning clearer and more specific
8. Added transitional bridge in Paper Organization paragraph
- Improved flow from introduction to body sections
9. Renamed Contribution 3: "Replicable Educational Artifact" → "Open Educational Infrastructure"
- More accurate, less generic
- Added concrete details (historical milestone range, specific section references)
10. Added proper citations throughout contributions for grounding
- Situated cognition, constructionism, cognitive load theory, cognitive apprenticeship
- NBGrader infrastructure cited
Paper now compiles successfully (22 pages, 373KB).
Addresses all blocking issues identified by research team review.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Removed temporary analysis and revision files:
- ACADEMIC_WRITER_BRIEF.md
- FIGURE_PROPOSALS.md
- FINAL_QUALITY_ASSESSMENT.md
- README_FIGURES.md
- REVISION_QUICK_REFERENCE.md
These files were created during iterative review process and are no longer needed.
Kept essential files:
- README.md (paper directory documentation)
- CRITICAL_FIXES_REMAINING.md (tracking document - can be removed once all fixes verified)
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Title changes:
- Old: "A Framework for Learning ML Systems from Scratch, from Tensors to Systems"
- New: "Build Your Own Machine Learning Framework From Tensors to Systems"
- More active, clearer action-oriented framing
Module flow diagram improvements:
- Increased spacing: node distance 0.8cm→1.0cm (vertical), 1.2cm→1.8cm (horizontal)
- Added minimum width 1.8cm to all nodes for consistency
- Simplified arrows to show primary linear flow within each tier
- Reduced visual complexity while maintaining dependency clarity
- Better readability in two-column format
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Strategic reordering with flow improvements:
Old order (mechanism → philosophy → artifact):
1. Progressive Disclosure Pattern
2. Systems-First Curriculum Architecture
3. Replicable Educational Artifact
New order (WHAT → HOW → DELIVERABLE):
1. Systems-First Curriculum Architecture - leads with core novelty
2. Progressive Disclosure Pattern - explains enabler ("To make systems-first learning tractable...")
3. Replicable Educational Artifact - validates both innovations ("Both innovations are validated through...")
Flow improvements:
- Contribution 1: Added "directly addresses the workforce gap" to link back to introduction
- Contribution 2: Opens with "To make systems-first learning tractable" (flows from #1)
- Contribution 2: Added "solves the cognitive load challenge inherent in teaching both"
- Contribution 3: Changed to "Both innovations are validated through" (flows from #1+#2)
- Paper Organization: Reordered section references to match (sec:curriculum,sec:systems,sec:progressive)
Rationale: Systems-first is the headline contribution that differentiates from micrograd/MiniTorch.
Progressive disclosure becomes the answer to "but won't that overwhelm students?"
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Academic writer improvements to introduction:
- Strengthen problem statement: algorithms vs systems separation creates workforce gap
- Add concrete evidence: students use loss.backward() without understanding graphs
- Reframe three fundamental questions with evidence-based answers
- Enhance compiler course analogy with specific examples (lexical → parsing → codegen)
- Clarify audience with prerequisites (CS229, fast.ai) and exclusions
- Upgrade pedagogical patterns to 'innovations' with measurable outcomes
- Add concrete metrics: Conv2d 109× efficiency, O(N²) scaling, 4× compression
Key structural changes:
- Paragraph 2: Show the gap with concrete missing knowledge examples
- Paragraph 4: Three questions framework provides clearer narrative arc
- Paragraph 5: Compiler analogy promoted and strengthened
- Paragraph 6: Audience scope tightened with specific prerequisites
- Paragraph 7: Pedagogical innovations with bold emphasis and measurements
Maintains honest scope on empirical validation while strengthening demonstrated contributions.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Reframe introduction to emphasize ML systems engineering workforce shortage as core problem:
- Open with 3.2:1 supply/demand ratio and 150K global practitioners
- Position tacit knowledge (not algorithmic ML) as bottleneck for systems engineering
- Contrast automation of model design vs. manual judgment for memory/performance tradeoffs
- Add workforce citations: Robert Half 2024 talent gap, Keller Executive Search 2025 AI gap
Introduction now grounds TinyTorch's pedagogical approach in workforce development necessity.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Add JavaScript to dynamically fix GIF image paths in hero carousel
for both main site and dev subdirectory deployments. The fix detects
the current page directory and prepends it to relative _static paths.
- Add orange-red accent bar on left side of header
- Style header with grey text for TinyTorch branding and author name
- Move page numbers to bottom center for cleaner layout
- Add subtle separator line with proper spacing
- Keep first page completely clean with no header
- Adjust header spacing for better visual balance
- Add checks for carousel elements existence before initializing
- Prevent auto-advance from starting if no slides exist
- Add safety checks for dots/indicators that may not be present
- Fixes TypeError when carousel is not on the page
- Remove carousel text labels, rely on larger terminal frame titles (20px bold)
- Fix navigation arrow positioning: moved to top: 405px with z-index: 100
- Reduce carousel height from 500px to 450px for better spacing
- Add clickable sidebar link to mlsysbook.ai via JavaScript
- Fix quickstart button link to use .html extension
- Add mobile responsive CSS for logo, headings, and carousel
- Update Terminalizer configs with larger frame title font
- Add textbook link with hover effects in intro page
Changes to HTML:
- Move carousel-nav outside carousel-track container
- Navigation now appears as separate element below the carousel
Changes to CSS:
- Remove absolute positioning (no longer needed)
- Use simple flexbox layout with margin-top: 1rem
- Remove bottom/left/right positioning properties
This fixes the overlap issue where arrows were positioned at the bottom
of the carousel-track, overlapping the GIF content. Arrows now appear
cleanly below the entire carousel as a separate row.
Changes to CSS:
- Position carousel-nav at bottom:0 instead of vertical center
- Use centered horizontal layout with 1rem gap
- Reduce arrow size to 32px (smaller, less intrusive)
- Remove semi-transparent background, use solid #e2e8f0
- Simplify shadow to 0 2px 6px
The vertical center placement with arrows overlapping the GIF content
looked messy and busy. This cleaner approach positions compact arrows
centered below the heading ("Clone & Setup" etc.), keeping them visible
but not interfering with the terminal content display.
Changes to CSS:
- Position carousel-nav absolutely at top:50% with translateY(-50%)
- Use space-between to place arrows on left/right edges
- Increase arrow size to 44px for better visibility
- Add semi-transparent background: rgba(226, 232, 240, 0.95)
- Enhance shadow for better visibility over content
- Use pointer-events:none on container, auto on arrows
Changes to HTML:
- Move carousel-nav inside carousel-track for proper positioning
- Remove carousel-indicators div (not using dot indicators)
- Simplify to just prev/next arrow buttons
This follows standard carousel UX conventions where navigation arrows
appear at the vertical center of the content, positioned on the left/right
edges. Arrows are now centered on the heading text ("Clone & Setup" etc.)
rather than below it, making them more visible and easier to use.
Removed the <p> description lines from all carousel items:
- "git clone → ./setup → tito system doctor"
- "tito module start 01 → Code → Test inline"
- "tito module complete → Your code becomes tinytorch/"
- "tito milestone run 03 → 1986 MLP uses YOUR code"
Now carousel shows only clean headings (Clone & Setup, Build in Jupyter, etc.)
below each GIF. The workflow details are already visible in the GIF animations,
making the text descriptions redundant.
Changes to CSS:
- Remove absolute positioning from .carousel-nav
- Use flexbox centered layout with 2rem gap between arrows
- Reduce arrow size back to 36px (from 40px)
- Add margin-top: 1.5rem for spacing from carousel text
Changes to HTML:
- Move carousel-nav outside carousel-track
- Navigation now appears below carousel text instead of overlaid on GIF
This fixes overlap issues - arrows are now cleanly positioned
below the carousel text labels, not on top of the GIF terminal window.
Changes to CSS:
- Position carousel-nav absolutely at top:40% of carousel-track
- Move arrows to sides (space-between) instead of center bottom
- Increase arrow size to 40px for better visibility
- Add box-shadow to arrows for depth
- Use pointer-events:none on nav container, auto on arrows
Changes to HTML:
- Move carousel-nav inside carousel-track for proper absolute positioning
This fixes the overlap where left/right navigation arrows were appearing
on top of the carousel heading text ("Build in Jupyter" etc).
Arrows now appear on the left/right sides of the GIF at the vertical center.
Changes:
- Increase carousel-track min-height from 410px to 500px
- Change overflow from hidden to visible to prevent text cutoff
- Add margin-top and padding to carousel-text for better spacing
- Reduce heading size from 1.75rem to 1.5rem for better fit
- Add monospace font to carousel description text
- Update mobile responsive breakpoint with overflow:visible
- Change fixed height to auto for GIF preview on mobile
This ensures carousel text labels ("Clone & Setup", "Build in Jupyter", etc.)
are fully visible below the GIF demos without being cut off.
Vijay Janapa ReddiandClaude