86 Commits

Author SHA1 Message Date
Vijay Janapa Reddi
a0468aad18 Update paper URLs: prioritize mlsysbook.ai/tinytorch as primary domain
Changed all three URL references in paper.tex:
- Title page: mlsysbook.ai/tinytorch (was tinytorch.ai)
- Abstract: mlsysbook.ai/tinytorch (was tinytorch.ai)
- Conclusion: mlsysbook.ai/tinytorch (or tinytorch.ai)

This emphasizes the ML Systems Book ecosystem connection in academic
context while maintaining tinytorch.ai as alternate URL. The ecosystem
domain is more stable and institutional for paper citations.
2025-11-30 17:05:01 -05:00
Vijay Janapa Reddi
bd5622c129 Remove operational details from paper: focus on pedagogical value
Cleaned up Module 20 Capstone and MLPerf milestone descriptions:
- Removed CLI command examples (BenchmarkReport, generate_submission, tito community submit)
- Removed detailed infrastructure implementation
- Focused on learning outcomes and systems thinking pedagogy
- Maintained academic tone throughout

These changes complete the paper cleanup for release.
2025-11-30 16:30:27 -05:00
Vijay Janapa Reddi
ccf8a0e797 Streamline Community section: remove operational details, focus on pedagogy
Removed:
- Detailed submission infrastructure CLI commands
- Adoption tracking metrics
- Promotional language about leaderboards

Kept:
- MLSysBook ecosystem integration
- Pedagogical value of competitive benchmarking (Module 20)
- Focus on systems thinking and measurement-driven decisions

The section now focuses on educational value rather than infrastructure details.
2025-11-30 16:26:47 -05:00
Vijay Janapa Reddi
3f1021d448 Update paper to reference both tinytorch.ai and mlsysbook.ai URLs
Primary URL is tinytorch.ai with mlsysbook.ai/tinytorch as alternate
2025-11-30 16:24:29 -05:00
Vijay Janapa Reddi
05e29f36f7 Fix MLSysBook author attribution to single author 2025-11-30 16:10:24 -05:00
Vijay Janapa Reddi
c31d49d045 Add ML Systems Book ecosystem integration and hardware simulation future work
Paper additions based on student feedback:
- MLSysBook ecosystem integration in Architecture section
- Hardware simulation integration (scale-sim, timeloop, astra-sim) in Future Work
- Enhanced community sustainability discussion
- Bibliography entries for MLSysBook textbook and hardware simulators

Addresses feedback from Zishen Wan on:
- Connecting TinyTorch to broader ML Systems Book curriculum
- System simulator integration for hardware performance analysis
- Community infrastructure and sustainability
2025-11-30 16:06:35 -05:00
Vijay Janapa Reddi
866abb79a7 Update paper with Module 20 capstone and enhance module with comprehensive markdown explanations
- Update paper/paper.tex to reflect Module 20 submission infrastructure
- Add nbdev export integration to paper build system section
- Integrate community submission workflow into paper
- Enhance Module 20 with ~4,500 words of pedagogical content
- Add 15+ ASCII diagrams for visual learning
- Include comprehensive benchmarking foundations
- Add module summary celebrating 20-module journey
- Complete pre-release review (96/100 - ready for release)
2025-11-29 20:02:11 -05:00
Vijay Janapa Reddi
24b55c4658 Update milestone span to nearly 70 years (1958-2025)
Changed from 66 years (1958-2024) to nearly 70 years (1958-2025):
- Abstract: 66 years → nearly 70 years, 2024 → 2025
- Conclusion: 66 years → nearly 70 years, 2024 → 2025
- Milestone M20: 2024 Capstone → 2025 Capstone

Reflects current year and provides better framing (67 years ≈ 70).
Paper compiles successfully with lualatex (25 pages, 383K).
2025-11-24 15:56:27 -05:00
Vijay Janapa Reddi
f352eb2bd9 Correct technical claims to align with implementation
- Fix CIFAR-10 accuracy: 75%+ → 65-75% (matches capstone.py target)
- Standardize Module 20: Olympics/AI Olympics → Capstone (canonical name)
- Clarify NBGrader: Integrated with markers, but unvalidated
- Correct milestone span: 70 years → 66 years (1958-2024)
- Verify Conv2d loops: 7 loops confirmed correct

All changes align paper with actual TinyTorch implementation.
Paper compiles successfully (26 pages, no errors).
2025-11-24 15:42:23 -05:00
Vijay Janapa Reddi
0539465113 Update documentation references to reflect current repository structure
- Fix README.md: Replace broken references to non-existent files
  - Remove STUDENT_VERSION_TOOLING.md references (file does not exist)
  - Remove .claude/ directory references (internal development files)
  - Remove book/ directory references (does not exist)
  - Update instructor documentation links to point to existing files
  - Point to INSTRUCTOR.md, TA_GUIDE.md, and docs/ for resources

- Fix paper.tex: Update instructor resources list
  - Replace non-existent MAINTENANCE.md with TA_GUIDE.md
  - Maintenance commitment details remain in paragraph text
  - All referenced files now exist in repository

All documentation links now point to actual files in the repository
2025-11-22 21:57:21 -05:00
Vijay Janapa Reddi
0810809b30 Add organizational insights from development history
Integrate four key lessons learned from TinyTorch's 1,294-commit history:

- Implementation-example gap: Name the challenge where students pass unit
  tests but fail milestones due to composition errors (Section 3.3)
- Reference implementation pattern: Module 08 as canonical example that
  all modules follow for consistency (Section 3.1)
- Python-first workflow: Jupytext percent format resolves version control
  vs. notebook learning tension (Section 6.4)
- Forward dependency prevention: Challenge of advanced concepts leaking
  into foundational modules (Section 7)

These additions strengthen the paper's contribution as transferable
curriculum design patterns for educational ML frameworks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-21 03:01:11 -05:00
Vijay Janapa Reddi
d832a258ff Revise abstract and introduction with Bitter Lesson framing
- Reframe abstract around systems efficiency crisis and workforce gap
- Add Bitter Lesson hook connecting computational efficiency to ML progress
- Strengthen introduction narrative with pedagogical gap analysis
- Update code styling for better readability (font sizes, spacing)
- Add organizational_insights.md documenting design evolution

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-21 02:58:40 -05:00
Vijay Janapa Reddi
90223ee8c9 Reduce code font size and spacing in Figure 1
- Change code font from \tiny to \fontsize{6}{7}\selectfont (6pt) for better fit
- Reduce margins: xleftmargin 10pt→5pt, xrightmargin 5pt→3pt
- Reduce spacing: aboveskip/belowskip 8pt→4pt, numbersep 5pt→3pt
- Reduce vspace before subcaptions from 0.3em to 0.15em
- Update numberstyle to match smaller font size
2025-11-19 22:29:40 -05:00
Vijay Janapa Reddi
1be937355e Fix subcaption centering and add distinct styling for PyTorch code
- Remove redundant \centering commands before subcaptions (centering handled by caption package)
- Add pytorchstyle with slightly darker background to distinguish PyTorch/TensorFlow code from TinyTorch code
- Apply pytorchstyle to PyTorch code block and pythonstyle to TinyTorch code blocks in Figure 1
2025-11-19 22:22:59 -05:00
Vijay Janapa Reddi
5640076ee4 Remove paper.pdf from git tracking
PDF files should not be version controlled, only source .tex files
2025-11-19 22:07:29 -05:00
Vijay Janapa Reddi
64ab36a137 Center subfigure captions in Figure 1 2025-11-19 22:05:03 -05:00
Vijay Janapa Reddi
3d5c1f97e4 Center subfigure captions and update text reference
- Added \centering before each \subcaption for proper alignment
- Added \vspace{0.3em} for consistent spacing
- Updated text reference to reflect 3-part progression:
  "from PyTorch's black-box APIs, through building internals,
  to training transformers where every import is student-implemented"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 21:59:36 -05:00
Vijay Janapa Reddi
6b668ed023 Restructure Figure 1 to show culmination with Transformer
Changed from 2-column (PyTorch/TensorFlow vs TinyTorch internals)
to 3-column layout showing complete learning journey:

(a) PyTorch: Black box usage - questions students have
(b) TinyTorch: Build internals - implementing Adam with memory awareness
(c) TinyTorch: The culmination - training Transformer with YOUR code

The new (c) panel shows the "wow moment": after 20 modules, students
can train transformers where every import is something they built.
Comments emphasize "You built this" and "You understand WHY it works."

Removed redundant TensorFlow example (was same point as PyTorch).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 21:57:19 -05:00
Vijay Janapa Reddi
37e254f8d7 Checkpoint: Paper revisions before Figure 1 restructuring
- Table 2 revised with balanced ML/Systems concepts
- Student feedback addressed (abstract, intro examples)
- Repetitions removed, progressive flow improved
- ~1,000 words cut from redundant content

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 21:52:23 -05:00
Vijay Janapa Reddi
2a9b692621 Remove repetitions and improve progressive flow
Major cuts to eliminate redundant content:

1. Introduction:
   - Cut redundant paragraph before contributions (lines 388-389)
   - Removed repeated examples (Adam, Conv2d, KV caching) from contribution 1
   - Simplified contribution 2 (save PyTorch history for Section 4)

2. Related Work:
   - Condensed bullet comparison list to single paragraph
   - Cut ~200 words of repeated distinctions

3. Section 3 (TinyTorch Architecture):
   - Cut redundant problem statement that repeated intro
   - Streamlined opening

4. Section 4 (Progressive Disclosure):
   - Cut re-explanation of pedagogical dilemma
   - Start directly with implementation details

5. Discussion:
   - Removed entire "Pedagogical Flexibility" subsection (7.2)
   - Content was duplicate of Section 6.2 configurations
   - Key rationale points merged into 6.2

Estimated savings: ~1,000 words
Paper now builds progressively without restating same concepts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 21:06:50 -05:00
Vijay Janapa Reddi
ee51a3240b Address student feedback on abstract and intro
1. Clarify progressive disclosure in abstract:
   - Changed from "activates dormant tensor features through monkey-patching"
   - To "gradually reveals complexity: tensor gradient features exist from
     Module 01 but activate in Module 05, managing cognitive load"

2. Add variety to 'why' examples in intro:
   - Changed second Adam example to Conv2d 109x parameter efficiency
   - Intro now covers: Adam optimizer state, attention O(N²), KV caching,
     and Conv2d efficiency (four distinct examples)

The 2x vs 4x Adam figures were actually consistent (2x optimizer state,
4x total training memory) but appeared confusing when repeated. Now varied.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 20:59:33 -05:00
Vijay Janapa Reddi
3c020f13d1 Revise Table 2 with balanced ML and Systems concepts
ML side additions (all actually taught):
- GELU, Tanh activations
- Xavier initialization
- log-sum-exp trick
- AdamW optimizer
- Cosine scheduling, gradient clipping
- Sinusoidal/learned positional encodings
- Causal masking
- LayerNorm, MLP
- Magnitude pruning, knowledge distillation

Systems side improvements (more concrete):
- Contiguous layout, dtype sizes
- Gradient memory multipliers (2x momentum, 3x Adam)
- im2col expansion
- Sparse gradient updates
- Attention score materialization
- KV cache sizing, per-layer memory
- Cache locality, SIMD utilization
- Confidence intervals, warm-up protocols
- Pareto optimization

Renamed "AI Olympics" to "Olympics" in table.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 20:56:32 -05:00
Vijay Janapa Reddi
90d472913b Remove temporary documentation and planning files
Deleted Category 1 temporary documentation files:
- Root directory: review reports, fix summaries, implementation checklists
- docs/development: testing plans, review checklists, quick references
- instructor/guides: analysis reports and implementation plans
- tests: testing strategy document

These were completed work logs and planning documents no longer needed.
All active documentation (site content, module ABOUT files, READMEs) preserved.
2025-11-19 16:21:24 -05:00
Vijay Janapa Reddi
fa814c9f3c Update compiled PDF with em-dash removal and abstract changes
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 15:21:19 -05:00
Vijay Janapa Reddi
7bbf50e928 Combine abstract into single paragraph
Changed abstract from 3 paragraphs to 1 continuous paragraph for better
flow and readability.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 14:11:35 -05:00
Vijay Janapa Reddi
bbbd45ad36 Remove excessive em-dashes to reduce LLM-generated feel
Reduced em-dashes from 44 to 1, keeping only the impactful one at line 961:
"Students aren't 'solving exercises'---they're building a framework they could ship."

Replacements:
- Em-dashes for elaboration → colons (26 instances)
- Em-dashes for apposition → commas (10 instances)
- Em-dashes for contrast → parentheses (7 instances)

This makes the prose feel more naturally academic and less AI-generated
while maintaining clarity and readability.

Paper now compiles successfully at 26 pages.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 13:55:49 -05:00
Vijay Janapa Reddi
bc3faade85 Rename Section 3 to 'TinyTorch Architecture' (not 'Curriculum')
ISSUE:
'The TinyTorch Curriculum' sounds too classroom-focused, as if the paper is
only about education/courses rather than a framework design contribution.

SOLUTION:
Changed to 'TinyTorch Architecture' which:
- Describes the framework structure (20 modules, 3 tiers, milestones)
- Matches systems paper conventions (Architecture sections common in CS)
- Emphasizes this is a design contribution, not just coursework
- Avoids over-emphasizing educational context

Section 3 describes HOW TinyTorch is architected:
- Module organization and dependencies
- Tier-based structure (Foundation/Architecture/Optimization)
- Module pedagogy (Build → Use → Reflect)
- Milestone validation approach

'Architecture' accurately captures this structural design focus.

Paper compiles successfully (26 pages).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 13:45:05 -05:00
Vijay Janapa Reddi
02f0deb021 Fix missing labels and rename Section 3 to 'The TinyTorch Curriculum'
REFERENCE FIXES:
- Added \label{sec:intro} to Introduction section (was missing, caused undefined ref)
- Added \label{subsec:milestones} to Milestone Arcs subsection (was missing)
- Both references now resolve correctly

SECTION TITLE IMPROVEMENT:
Changed Section 3 from 'Curriculum Architecture' → 'The TinyTorch Curriculum'

Reasoning: Section 3 describes the 20-module curriculum structure, tier organization,
module objectives, and milestone validation. 'Curriculum Architecture' was confusing
(sounds like code architecture). 'The TinyTorch Curriculum' is clearer and matches
the actual content.

REFERENCE VALIDATION SCRIPT CREATED:
Created Python script to check:
- Undefined references (\Cref{} or \ref{} to non-existent \label{})
- Unused labels (\label{} never referenced)
- Duplicate labels (same \label{} defined multiple times)

Current status:
- 2 critical undefined references FIXED (sec:intro, subsec:milestones)
- Remaining undefined refs are missing code listings (lst:tensor-memory,
  lst:conv-explicit, etc.) - these listings don't exist in paper yet
- Multi-reference format (\Cref{sec:a,sec:b,sec:c}) works fine with cleveref

Paper compiles successfully (24 pages).

Next steps: Consider whether missing code listings should be added or references
removed (code listings would add significant length to paper).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 13:43:40 -05:00
Vijay Janapa Reddi
14a012fcbf Major improvements: tier configurations, milestone validation, acknowledgments
THREE KEY CHANGES addressing user feedback:

1. RENAMED SECTION: 'Deployment and Infrastructure' → 'Course Deployment'
   - Section primarily about deployment, not just infrastructure
   - More accurate title for content focus

2. ADDED TIER-BASED CURRICULUM CONFIGURATIONS (New subsection in Course Deployment)
   - Configuration 1: Foundation Only (Modules 01-07, 30-40 hours)
     * Core framework internals, Milestones 1-3
     * Ideal for: Intro ML systems courses, capstone projects, bootcamps

   - Configuration 2: Foundation + Architecture (Modules 01-13, 50-65 hours)
     * Adds modern architectures (CNNs, Transformers), Milestones 4-5
     * Ideal for: Semester-long ML systems courses, grad seminars

   - Configuration 3: Optimization Focus (Modules 14-19 only, 15-25 hours)
     * Import pre-built foundation/architecture packages
     * Build only: profiling, quantization, compression, acceleration
     * Ideal for: Production ML courses, TinyML workshops, edge deployment
     * KEY: Students focusing on optimization don't rebuild autograd

   RATIONALE: This was mentioned in Discussion but needed prominent placement
   in Course Deployment where instructors look for practical guidance. Now
   appears in BOTH locations: Course Deployment (practical how-to) and
   Discussion (pedagogical why).

3. RESTORED MILESTONE VALIDATION BULLET LIST
   After careful consideration, bullet list is BETTER than paragraph because:
   - Instructors/students reference this as checklist
   - Each milestone has different criteria - scannable list more useful
   - Easier to see 'what does M07 need to achieve?' at a glance

   Format: Intro paragraph explaining philosophy + 6-item bullet list with
   concrete criteria per milestone (M03, M06, M07, M10, M13, M20)

4. ADDED UNNUMBERED ACKNOWLEDGMENTS SECTION
   - Uses \section*{Acknowledgments} for unnumbered section
   - Content: 'Coming soon.'
   - Placed before Bibliography

All changes compile successfully (24 pages). Paper now has clear tier
flexibility guidance exactly where instructors need it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 13:39:08 -05:00
Vijay Janapa Reddi
da76ede264 Fix unnatural spacing in Phase 1/2/3 validation sections
ISSUE:
Using \noindent\textbf{Phase X:} on separate line before itemized lists created
unnatural vertical spacing that looked awkward and inconsistent with paragraph flow.

FIX:
Converted Phase 1, 2, and 3 sections from:
- \noindent\textbf{Phase X: ...} + blank line + \begin{itemize}

To flowing paragraphs:
- \textbf{Phase X: ...}. Continuous text with research details integrated.

CHANGES:
- Phase 1: Condensed 4 bullet points → flowing paragraph (deployment institutions,
  cognitive load measurement, time tracking, formative assessment)

- Phase 2: Condensed 4 bullet points → flowing paragraph (RCT design, conceptual
  understanding measures, transfer performance, code quality analysis)

- Phase 3: Condensed 3 bullet points → flowing paragraph (retention study,
  advanced course tracking, industry outcomes)

RESULT:
- Removed unnatural spacing before Phase sections
- Text flows naturally like human-written academic prose
- Maintains all technical content and citations
- 23 pages (reduced from 24 by removing extra spacing)

Next: Address 65 remaining em-dashes that create LLM-generated feel.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 13:33:03 -05:00
Vijay Janapa Reddi
7ae5a17291 Streamline paper flow: fix intro detail level and strengthen justifications
Academic-writer performed final sequential review to ensure paper builds logically
from start to finish. Fixed 1 CRITICAL and 2 MODERATE issues affecting flow.

CRITICAL FIX: Introduction Too Detailed (Lines 307-310)
BEFORE: Introduction explained progressive disclosure mechanisms ('runtime
feature activation'), systems-first specifics ('Module 01 onwards'), and
milestone validation details ('70 years of ML breakthroughs'). This created
micro-repetition with dedicated sections later.

AFTER: Simplified to high-level pedagogical challenges only:
'The curriculum addresses three fundamental pedagogical challenges: teaching
systems thinking alongside ML fundamentals... managing cognitive load... and
validating that bottom-up implementation produces working systems. The following
sections detail how TinyTorch's design addresses each challenge.'

Impact: Eliminates technical preview duplication, lets dedicated sections
deliver full explanations without redundancy.

MODERATE FIX #1: Milestone Dual-Purpose Clarification (Line 622)
Added transition sentence explaining milestones serve both pedagogical motivation
(historical framing) AND technical validation (correctness proof):

'While milestones provide pedagogical motivation through historical framing,
they simultaneously serve a technical validation purpose: demonstrating
implementation correctness through real-world task performance.'

Impact: Explicitly signals dual purpose rather than leaving readers to infer.

MODERATE FIX #2: Progressive Disclosure Justification Strengthened (Line 747)
BEFORE: Hedged on cognitive load benefits ('may reduce', 'may create', 'requires
empirical measurement'), made pattern sound uncertain.

AFTER: Emphasized validated benefits first, then acknowledged hypothesis testing:
'Progressive disclosure is grounded in cognitive load theory... provides two
established benefits: (1) forward compatibility... (2) unified mental model...
The cognitive load hypothesis... Empirical measurement planned for Fall 2025
will quantify the net impact.'

Impact: Frames as theoretically grounded design with validated benefits, not
uncertain experiment. Maintains scientific honesty about empirical needs.

NARRATIVE ARC ASSESSMENT:
Paper now flows coherently from Abstract → Conclusion with:
- Clear logical progression of complexity
- Appropriate cross-references throughout
- Each section building on previous content
- No major repetition or gaps

Remaining issues flagged by reviewer are minor (terminology consistency,
conclusion synthesis) and not blocking for publication.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 12:47:35 -05:00
Vijay Janapa Reddi
6d8d9f2a0e Remove remaining specific numbers and consolidate milestone validation
ISSUE 1: Residual specific numbers in milestone descriptions
- Line 611: '95%+ MNIST accuracy' in MLP Revival description
- Line 613: '75%+ CIFAR-10 accuracy' in CNN Revolution description

FIX: Removed specific accuracy targets, focus on conceptual achievements:
- MLP Revival: 'trains multi-layer networks end-to-end on MNIST digits'
- CNN Revolution: 'training both MLP and CNN on CIFAR-10 to measure architectural
  improvements through direct comparison'

ISSUE 2: 'Success Validation' subsection repeated milestone list
Lines 625-632 listed all 6 milestones again with validation criteria, creating
redundancy with 'The Six Historical Milestones' (lines 606-618) just above.

ANALYSIS OF DISTINCT PURPOSES:
- 'The Six Historical Milestones' (606-618): WHAT each milestone is, WHEN it
  happens, WHAT students import/build (historical framing + integration)
- 'Success Validation' (622-632): HOW to validate correctness (validation approach)

FIX: Consolidated 'Success Validation' from itemized milestone list into concise
validation philosophy paragraph:
- Explains validation approach: task-appropriate results, not optimization
- Gives examples across categories: simple problems converge, complex datasets
  show learning, generative models produce coherent outputs
- Emphasizes correctness over speed: 'implementations prove correct by solving
  real tasks, not by passing synthetic unit tests alone'
- Connects to professional practice: mirrors debugging approach

RESULT:
- Eliminated 6-item redundant list
- Reduced from 12 lines to 4 lines
- Clearer distinct purpose: milestone descriptions vs validation philosophy
- No loss of information, better organization

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 12:01:08 -05:00
Vijay Janapa Reddi
ce3353ecf4 Soften quantitative success criteria to qualitative validation
PROBLEM:
Specific numerical targets (75% accuracy, 95% accuracy, 20 epochs, perplexity <10)
create maintenance burden and false precision:
- Numbers will change as curriculum evolves
- Hardware variability affects performance
- Overly specific claims are fragile

SOLUTION:
Replace quantitative thresholds with qualitative success indicators:

BEFORE:
- M03: 100% accuracy on 4-point XOR-like problem
- M06: 100% accuracy on XOR within 20 epochs
- M07: 95%+ accuracy on MNIST within 10 epochs
- M10: 70%+ accuracy on CIFAR-10
- M13: Perplexity <10, generates coherent 20-token continuations

AFTER:
- M03: Solves linearly separable problems (demonstrates convergence)
- M06: Solves XOR classification (proves non-linear capability)
- M07: Achieves strong MNIST accuracy (validates backpropagation)
- M10: Demonstrates meaningful CIFAR-10 learning (substantially better than random)
- M13: Generates coherent multi-token text (demonstrates attention)

BENEFITS:
1. Future-proof: No specific numbers to update when benchmarks change
2. Conceptually accurate: Focus on 'works correctly' not 'hits threshold'
3. Hardware-agnostic: 'meaningful learning' works on any machine
4. Pedagogically sound: Emphasizes correctness over performance

Changed section title from 'Quantitative Success Criteria' to 'Success Validation'
to reflect qualitative approach.

Retained key pedagogical message: 'Correctness matters more than speed' - if
CNN learns meaningful features, implementation composes correctly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 11:59:04 -05:00
Vijay Janapa Reddi
dc800a3baa Fix 5 critical repetitions identified by sequential memory agent
Used academic-writer agent to perform sequential read with concept registry,
identifying repetitions as the paper is read from Abstract→Conclusion.

CRITICAL REPETITIONS FIXED:

1. Systems-First Problem Restatement (line 774):
   BEFORE: Re-explained industry gap already covered in Introduction
   AFTER: Forward reference to curriculum section, focuses on implementation
   Impact: Eliminates 3-sentence redundant problem statement

2. Pure Python Pedagogical Justification (3 appearances):
   - Related Work (line 817): KEPT - detailed explanation with Conv2d example
   - Infrastructure (line 878): REMOVED - duplicate transparency explanation
   - Discussion (lines 1013-1015): TRIMMED - removed convolution loops detail,
     added cross-reference to Section 4
   Impact: Consolidated from 3 full explanations to 1 detailed + 1 brief reference

3. Target Audience Description (lines 489-494):
   BEFORE: Detailed audience description repeated from Introduction
   AFTER: Brief cross-reference to Introduction, focuses on technical prerequisites
   Impact: Removed 5-sentence redundant audience characterization

4. TinyDigits/TinyTalks Dataset Description (line 876):
   BEFORE: Mentioned datasets by name in Infrastructure section
   AFTER: Generic 'offline-first datasets' with cross-reference to curriculum
   Impact: Keeps detailed description in Curriculum section (line 570), avoids
   duplication in Infrastructure

5. Discussion Flexibility vs Integration Models:
   VERIFIED: Already has cross-reference (line 1020) clarifying relationship
   Status: No changes needed - already differentiated

SEQUENTIAL MEMORY APPROACH:
Agent maintained concept registry tracking:
- First appearance location and detail level
- Subsequent appearances with severity classification
- Recommendations: keep first/keep second/consolidate/remove

This approach identified 15 total repetitions (5 CRITICAL, 6 MODERATE, 4 MINOR).
Addressed all 5 CRITICAL issues. MODERATE/MINOR include acceptable thematic
reinforcement (Adam 2× memory, 1958-2024 span) that should remain.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 11:52:04 -05:00
Vijay Janapa Reddi
ccbbda270f Add tier flexibility explanation and fix critical repetitions
TIER FLEXIBILITY ENHANCEMENT:
Strengthened 'Selective implementation' paragraph to explicitly enumerate three
curriculum configurations and explain WHY they matter:

1. Foundation only (M01-07): Introductory ML systems courses, capstone projects
   - Focus on framework internals (tensors, autograd, training loops)

2. Foundation + Architecture (M01-13): Comprehensive ML systems courses
   - Extend to modern deep learning (CNNs, transformers)

3. Optimization focus (M14-19 only): Production ML, edge deployment, TinyML
   - Import pre-built tinytorch.nn/optim, implement only optimization techniques
   - Addresses key limitation: quantization students shouldn't rebuild autograd

Added pedagogical justification:
- Systems-heavy courses build Foundation→Architecture
- Optimization-focused courses skip to production concerns with pre-built deps
- Enables matching curriculum scope to course objectives within semester constraints

CRITICAL REPETITION FIXES (per research coordinator review):

1. Introduction line 307 (systems-first): Removed detailed explanation, added
   forward reference to Section 4 to avoid pre-stating content

2. Introduction line 307 (progressive disclosure): Simplified to brief mention
   with forward reference, removed detailed mechanics

3. Contribution #2 (progressive disclosure): Condensed description, removed
   redundant 'cognitive load challenge' phrase already covered in line 307

These changes follow pattern: Introduction = brief preview + forward reference,
Dedicated sections = full treatment. Eliminates repetition while maintaining flow.

Research coordinator identified 11 repetition categories; addressed 3 critical ones.
Others are either intentional (Adam optimizer, 1958-2024 span as thematic elements)
or acceptable (table vs detailed comparison for MiniTorch).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 11:37:32 -05:00
Vijay Janapa Reddi
94f792a2d6 Fix overlaps and refocus Pedagogical Flexibility on rationale
Identified and resolved overlaps between Discussion and Deployment sections:

OVERLAP ANALYSIS:
- Deployment section (lines 865-869): Describes WHO uses TinyTorch and in WHAT context
  - Model 1: Self-paced learners (individuals, professionals)
  - Model 2: Institutional integration (standalone course, half-semester, honors track)
  - Model 3: Team onboarding (industry bootcamps)

- Discussion section (NEW): Explains WHY and HOW pedagogical configurations work
  - Focuses on pedagogical reasoning, not deployment logistics
  - References deployment models to avoid duplication

CHANGES MADE:
1. Updated section title to 'Pedagogical Flexibility: Rationale and Design Principles'
2. Added forward reference to Integration Models section to clarify relationship
3. Rewrote all content to focus on pedagogical reasoning:
   - Tier-based partitioning → cognitive load theory justification
   - Selective implementation → pedagogical tradeoffs (depth vs coverage)
   - Hybrid integration → resolving application-first vs internals-first tension
   - Consolidation cycles → validate through productive struggle
   - Variable pacing → heterogeneous student preparation

4. Fixed Discussion section header: 'four lenses' → 'three lenses' (removed
   transferable principles and generic implications)

5. Fixed cross-reference: subsec:deployment → subsec:integration

RESULT:
- Deployment section = practical logistics (who, what, where)
- Discussion section = pedagogical theory (why, how these work)
- No content duplication, complementary perspectives

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 10:43:14 -05:00
Vijay Janapa Reddi
f846e1f68d Refocus Discussion on ML systems education pedagogy
Replaced overly broad 'Transferable Design Principles' and 'Implications for Practice'
with focused 'Pedagogical Flexibility and Curriculum Configurations' subsection.

New content addresses practical ML systems education deployment:
- Multi-semester pathways (Foundation S1, Architecture S2)
- Single-tier focus with pre-built packages (import what you need)
- Progressive builds with intermediate validation (build, use, identify gaps)
- Hybrid build-and-use curriculum (TinyTorch modules + PyTorch projects)
- Selective depth based on student background (variable pacing)

This keeps Discussion focused on ML systems education rather than generalizing
to compilers, databases, OS courses. Complements (not overlaps) course deployment
section which covers technical infrastructure (JupyterHub, NBGrader, TA support).

Addresses feedback: Discussion should focus on how educators can actually use
TinyTorch in different pedagogical configurations, not abstract principles.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 10:30:12 -05:00
Vijay Janapa Reddi
f5e56f6001 Restructure Discussion section with transferable principles
Reorganized Discussion section to strengthen contribution for top-tier venues:

1. Reframed Pedagogical Scope as design decision (not limitation)
   - Three deliberate design principles for accessibility
   - Positions constraints as pedagogical choices

2. Added Transferable Design Principles subsection
   - Five generalizable principles for systems education
   - Each principle includes applicability beyond ML
   - Delayed Abstraction Activation, Historical Validation, Systems-First

3. Added Implications for Practice subsection
   - Actionable guidance for three stakeholder groups
   - Educators: 3 adoption pathways (standalone, integrated, selective)
   - Curriculum designers: placement guidance and prerequisites
   - Students: transferable competencies and career pathways

4. Removed Pedagogical Spiral subsection
   - Content was repetitive with Section 3.3
   - Redundant with existing curriculum descriptions

These changes extract genuinely new insights from the design process.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 10:23:17 -05:00
Vijay Janapa Reddi
dda9602daa Restructure Discussion with 3 subsections: Scope, Pedagogical Spiral, Limitations
Added back "Scope: What's NOT Covered" section to clearly state what TinyTorch
deliberately omits (GPU programming, distributed training, production deployment).

Added new "Pedagogical Spiral" subsection discussing how concepts revisit and
reinforce across tiers:
- Memory reasoning: tensor.nbytes → Conv2d memory → attention O(N²) → quantization
- Computational complexity: matrix multiply FLOPs → convolution → attention → optimization
- Backward connections: later modules illuminate why earlier abstractions matter

Renamed final subsection to "Limitations and Future Directions" with focused
discussion of assessment validation, performance tradeoffs, energy measurement gaps,
and accessibility constraints.

This 3-section structure provides clearer organization:
1. What we deliberately excluded (scope boundaries)
2. What we learned about spiral reinforcement (pedagogical observations)
3. What needs improvement (honest limitations)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 09:56:17 -05:00
Vijay Janapa Reddi
c3b8598d5d Remove Design Insights subsection from Discussion
After review, determined that Design Insights section was repetitive and didn't
add genuine value beyond what's already covered in:
- Section 2: Related Work (positioning and comparison)
- Sections 3-5: Pedagogical patterns (progressive disclosure, systems-first, etc.)
- Section 7: Deployment models

Discussion section now consists solely of:
- Limitations and Scope Boundaries (organized by categories)

This cleaner structure avoids repetition and keeps the Discussion focused on
acknowledging scope boundaries through trade-off framing.

Paper compiles successfully (23 pages, down from 24).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 09:52:43 -05:00
Vijay Janapa Reddi
3e38929e34 Restructure Discussion and strengthen Conclusion per research feedback
Major improvements to Discussion and Future Work sections based on comprehensive
research team feedback:

DISCUSSION SECTION (Section 8):
- Added new 'Design Insights' subsection opening with positive framing:
  * Progressive disclosure effectiveness through gradual feature activation
  * Systems-first integration preventing 'algorithms without costs' learning
  * Historical milestones as pedagogical checkpoints with validation
  * Build-Use-Reflect cycle enabling immediate application

- Consolidated 'Scope' and 'Limitations' into unified section with trade-off framing:
  * Production Systems Beyond Scope (GPU, distributed, deployment)
  * Infrastructure Maturity Gaps (NBGrader validation, performance, energy)
  * Accessibility Constraints (language, type hints, advanced concepts)
  * Connected limitations to deliberate pedagogical choices

FUTURE DIRECTIONS (Section 9, renamed from 'Future Work'):
- Reorganized with clear structure prioritizing empirical validation first
- Made tool mentions more concept-focused (e.g., 'distributed training simulation'
  vs 'ASTRA-sim for distributed training simulation')
- Removed duplicate sections and consolidated curriculum extensions
- Maintained detailed empirical validation roadmap (3-phase plan)

CONCLUSION (Section 10):
- Complete rewrite with strong vision statement and call to action
- Opens with fundamental choice: use frameworks vs understand frameworks
- Expanded practitioner value proposition with concrete debugging scenarios
- Added memorable closing: 'The difference between engineers who know what ML
  systems do and engineers who understand why they work'
- Transformed from passive ('one approach') to confident and inspiring

STRUCTURAL IMPROVEMENTS:
- Discussion now opens positively (Design Insights) before limitations
- Future Directions organized by audience (researchers, educators, community)
- Conclusion ends with vision + call to action instead of apologetic tone
- Fixed undefined reference (subsec:future-work -> sec:future-work)

Paper compiles successfully with no LaTeX errors or undefined references.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 09:08:13 -05:00
Vijay Janapa Reddi
e54ec0faa6 Restore corrupted references.bib entries
The references.bib file had several corrupted entries where bibliography
data was overwritten with incorrect content:
- perkins1992transfer was showing a Nature epidemiology paper
- bruner1960process had wrong data
- Other entries were malformed

Restored from previous commit to fix all corruption issues.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 08:46:50 -05:00
Vijay Janapa Reddi
f31865560e Add enumitem package to fix itemize formatting
The itemize environment parameters [leftmargin=*, itemsep=1pt, parsep=0pt]
were appearing as visible text in the PDF because the enumitem package
wasn't loaded. This fix adds \usepackage{enumitem} to the preamble.

All itemized lists now format correctly with proper spacing and margins.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-19 08:43:41 -05:00
Vijay Janapa Reddi
31548e88fe Add missing citations from research review
Added three citations for bibliography entries that existed but weren't cited in the text:

1. meadows2008thinking - Added at line 586 for systems thinking discussion
2. vygotsky1978mind - Added at line 906 for NBGrader scaffolding discussion
3. thompson2008bloom - Added at line 914 for automated assessment framework

Note: aho2006compilers already cited at line 308 (compiler course model)
Note: MLPerf date already correct at line 618 (says 2018, not 2024)

All citations verified in references.bib and paper compiles successfully.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 21:26:14 -05:00
Vijay Janapa Reddi
8f1188c78b Clean up temporary review and analysis files
Remove temporary files from repository:
- COMPREHENSIVE_MODULE_REVIEW.md - Module review (temporary)
- paper/CITATIONS_TO_ADD.md - Citation recommendations (temporary)
- paper/CLAIM_EVIDENCE_MATRIX.md - Evidence validation (temporary)
- paper/EVIDENCE_INVENTORY.md - Evidence tracking (temporary)
- paper/LITERATURE_REVIEW_ASSESSMENT.md - Literature review (temporary)
- paper/PYTHON_DEVELOPER_TECHNICAL_REVIEW.md - Code review (temporary)
- paper/NEW_CITATIONS.bib - Temporary citations (content in references.bib)
- paper/proposed_figures.tex - Figure proposals (temporary)

Update .gitignore to prevent tracking these file types:
- Add patterns for *_REVIEW*, *_MATRIX, *_INVENTORY, *_ASSESSMENT
- Add NEW_CITATIONS.bib and proposed_figures.tex patterns
- These files are AI-generated temporary analysis artifacts

Update paper.pdf with latest compilation including caption styling.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 20:51:32 -05:00
Vijay Janapa Reddi
fda66004b1 Clean up LaTeX build artifacts and add to gitignore
- Add LaTeX build artifacts to .gitignore (aux, bbl, blg, out, etc.)
- Remove tracked build artifacts: paper.aux, paper.bbl, paper.blg, paper.out
- Remove empty benchmark_results.txt file

These files are regenerated on each compilation and should not be tracked.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 19:29:35 -05:00
Vijay Janapa Reddi
27e1dd1495 Add consistent caption styling and enhance table captions
Caption Styling:
- Add bold labels (Figure/Table/Listing numbers) for visual hierarchy
- Use small font size with proper spacing (8pt skip)
- Period separator after labels for professional appearance
- Justified text alignment for clean presentation
- Position tables captions at top, figures at bottom (academic standard)

Enhanced Table Captions:
- Table 1: Explain TinyTorch's bridging role between educational and production frameworks
- Table 2: Clarify dual-concept pedagogy (ML algorithms + systems implications)

All captions now follow consistent pedagogical structure:
1. Opening statement of what element shows
2. Key components and their significance
3. Educational rationale and learning benefits

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 19:28:16 -05:00
Vijay Janapa Reddi
dfe9b4ef6d Align progressive disclosure feature boxes precisely at Module 05 boundary
Fixed visual alignment issue where dormant and active feature boxes were
floating separately instead of meeting at the activation point.

Key improvements:
1. Feature boxes now use anchor=east (dormant) and anchor=west (active)
2. Both positioned at exactly x=6 (Module 05 vertical line)
3. Dormant boxes END at the red line, active boxes START at the red line
4. Made gray dotted module boundary lines darker (gray!60 instead of gray!40)
5. Increased box width to 2.0cm for better visual balance

Visual logic now perfectly clear:
- Gray boxes extend left from M05 = features exist but dormant
- Orange boxes extend right from M05 = features now active
- Red vertical line at M05 = exact moment of activation
- Boxes meet precisely at the boundary with no gap or overlap

This addresses user feedback: 'why aren't the .backward() and so forth really
aligned exactly at that point?' Now they ARE precisely aligned, making the
discrete activation event visually obvious.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 19:18:40 -05:00
Vijay Janapa Reddi
d2839ec79a Redesign Figure 3 with vertical module boundaries instead of horizontal lines
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>
2025-11-18 19:15:37 -05:00
Vijay Janapa Reddi
7d298c0dc8 Add missing reference to Figure 3 (progressive disclosure timeline)
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>
2025-11-18 19:14:00 -05:00