From c058ab941968ee6e2493c448ae2280f3a39891b7 Mon Sep 17 00:00:00 2001 From: Vijay Janapa Reddi Date: Fri, 28 Nov 2025 05:01:44 +0100 Subject: [PATCH] =?UTF-8?q?Fix=20documentation=20links=20after=20site=20?= =?UTF-8?q?=E2=86=92=20docs=20reorganization?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace all .html β†’ .md in markdown source files (43 instances) - Fix broken links: tito-essentials.md β†’ tito/overview.md - Remove broken links to non-existent leaderboard/olympics-rules pages - Fix PDF_BUILD_GUIDE reference in website-README.md Website rebuilt successfully with 46 warnings. Changes: - All markdown files now use .md extension for internal links - Removed references to missing/planned files - Website builds cleanly and all links are functional --- {site => docs}/chapters/00-introduction.md | 2 +- {site => docs}/chapters/learning-journey.md | 0 {site => docs}/chapters/milestones.md | 0 {site => docs}/checkpoint-system.md | 6 +- {site => docs}/community.md | 2 +- {site => docs}/credits.md | 0 {site => docs}/datasets.md | 0 {site => docs}/faq.md | 6 +- docs/for-instructors.md | 443 ++++++ {site => docs}/getting-started.md | 10 +- {site => docs}/instructor-guide.md | 0 {site => docs}/intro.md | 0 {site => docs}/learning-journey-visual.md | 0 {site => docs}/learning-progress.md | 2 +- {site => docs}/prerequisites.md | 14 +- {site => docs}/quickstart-guide.md | 2 +- {site => docs}/resources.md | 0 {site => docs}/student-workflow.md | 4 +- {site => docs}/tiers/architecture.md | 0 {site => docs}/tiers/foundation.md | 0 {site => docs}/tiers/olympics.md | 2 +- {site => docs}/tiers/optimization.md | 0 {site => docs}/tito/data.md | 0 {site => docs}/tito/milestones.md | 0 {site => docs}/tito/modules.md | 0 {site => docs}/tito/overview.md | 24 +- docs/tito/quick-reference.md | 217 +++ {site => docs}/tito/troubleshooting.md | 0 {site => docs}/usage-paths/classroom-use.md | 4 +- {site => docs}/usage-paths/ta-guide.md | 0 {site => docs}/usage-paths/team-onboarding.md | 0 site/README.md => docs/website-README.md | 4 +- site/.nojekyll | 2 - site/Makefile | 61 - site/_config.yml | 104 -- site/_toc.yml | 117 -- site/build.sh | 70 - site/build_pdf.sh | 73 - site/build_pdf_simple.sh | 70 - site/chapters/docs/README.md | 73 - site/chapters/modules/02_tensor.ipynb | 1269 ----------------- site/conf.py | 39 - site/modules/01_tensor_ABOUT.md | 1 - site/modules/02_activations_ABOUT.md | 1 - site/modules/03_layers_ABOUT.md | 1 - site/modules/04_losses_ABOUT.md | 1 - site/modules/05_autograd_ABOUT.md | 1 - site/modules/06_optimizers_ABOUT.md | 1 - site/modules/07_training_ABOUT.md | 1 - site/modules/08_dataloader_ABOUT.md | 1 - site/modules/09_spatial_ABOUT.md | 1 - site/modules/10_tokenization_ABOUT.md | 1 - site/modules/11_embeddings_ABOUT.md | 1 - site/modules/12_attention_ABOUT.md | 1 - site/modules/13_transformers_ABOUT.md | 1 - site/modules/14_profiling_ABOUT.md | 1 - site/modules/15_quantization_ABOUT.md | 1 - site/modules/16_compression_ABOUT.md | 1 - site/modules/17_memoization_ABOUT.md | 1 - site/modules/18_acceleration_ABOUT.md | 1 - site/modules/19_benchmarking_ABOUT.md | 1 - site/modules/20_capstone_ABOUT.md | 1 - site/prepare_notebooks.sh | 77 - site/references.bib | 0 site/requirements.txt | 36 - 65 files changed, 701 insertions(+), 2052 deletions(-) rename {site => docs}/chapters/00-introduction.md (99%) rename {site => docs}/chapters/learning-journey.md (100%) rename {site => docs}/chapters/milestones.md (100%) rename {site => docs}/checkpoint-system.md (97%) rename {site => docs}/community.md (98%) rename {site => docs}/credits.md (100%) rename {site => docs}/datasets.md (100%) rename {site => docs}/faq.md (98%) create mode 100644 docs/for-instructors.md rename {site => docs}/getting-started.md (98%) rename {site => docs}/instructor-guide.md (100%) rename {site => docs}/intro.md (100%) rename {site => docs}/learning-journey-visual.md (100%) rename {site => docs}/learning-progress.md (98%) rename {site => docs}/prerequisites.md (90%) rename {site => docs}/quickstart-guide.md (99%) rename {site => docs}/resources.md (100%) rename {site => docs}/student-workflow.md (97%) rename {site => docs}/tiers/architecture.md (100%) rename {site => docs}/tiers/foundation.md (100%) rename {site => docs}/tiers/olympics.md (98%) rename {site => docs}/tiers/optimization.md (100%) rename {site => docs}/tito/data.md (100%) rename {site => docs}/tito/milestones.md (100%) rename {site => docs}/tito/modules.md (100%) rename {site => docs}/tito/overview.md (94%) create mode 100644 docs/tito/quick-reference.md rename {site => docs}/tito/troubleshooting.md (100%) rename {site => docs}/usage-paths/classroom-use.md (98%) rename {site => docs}/usage-paths/ta-guide.md (100%) rename {site => docs}/usage-paths/team-onboarding.md (100%) rename site/README.md => docs/website-README.md (97%) delete mode 100644 site/.nojekyll delete mode 100644 site/Makefile delete mode 100644 site/_config.yml delete mode 100644 site/_toc.yml delete mode 100755 site/build.sh delete mode 100755 site/build_pdf.sh delete mode 100755 site/build_pdf_simple.sh delete mode 100644 site/chapters/docs/README.md delete mode 100644 site/chapters/modules/02_tensor.ipynb delete mode 100644 site/conf.py delete mode 120000 site/modules/01_tensor_ABOUT.md delete mode 120000 site/modules/02_activations_ABOUT.md delete mode 120000 site/modules/03_layers_ABOUT.md delete mode 120000 site/modules/04_losses_ABOUT.md delete mode 120000 site/modules/05_autograd_ABOUT.md delete mode 120000 site/modules/06_optimizers_ABOUT.md delete mode 120000 site/modules/07_training_ABOUT.md delete mode 120000 site/modules/08_dataloader_ABOUT.md delete mode 120000 site/modules/09_spatial_ABOUT.md delete mode 120000 site/modules/10_tokenization_ABOUT.md delete mode 120000 site/modules/11_embeddings_ABOUT.md delete mode 120000 site/modules/12_attention_ABOUT.md delete mode 120000 site/modules/13_transformers_ABOUT.md delete mode 120000 site/modules/14_profiling_ABOUT.md delete mode 120000 site/modules/15_quantization_ABOUT.md delete mode 120000 site/modules/16_compression_ABOUT.md delete mode 120000 site/modules/17_memoization_ABOUT.md delete mode 120000 site/modules/18_acceleration_ABOUT.md delete mode 120000 site/modules/19_benchmarking_ABOUT.md delete mode 120000 site/modules/20_capstone_ABOUT.md delete mode 100755 site/prepare_notebooks.sh delete mode 100644 site/references.bib delete mode 100644 site/requirements.txt diff --git a/site/chapters/00-introduction.md b/docs/chapters/00-introduction.md similarity index 99% rename from site/chapters/00-introduction.md rename to docs/chapters/00-introduction.md index 8a2bf067..92ca2b03 100644 --- a/site/chapters/00-introduction.md +++ b/docs/chapters/00-introduction.md @@ -289,7 +289,7 @@ After each tier, you become the team member who: **Next Steps**: - **New to TinyTorch**: Start with [Quick Start Guide](../quickstart-guide.md) for immediate hands-on experience -- **Ready to Commit**: Begin [Module 01: Tensor](../modules/01_tensor_ABOUT.html) to start building +- **Ready to Commit**: Begin [Module 01: Tensor](../modules/01_tensor_ABOUT.md) to start building - **Teaching a Course**: Review [Getting Started Guide - For Instructors](../getting-started.html#instructors) for classroom integration ```{admonition} Your Three-Tier Journey Awaits diff --git a/site/chapters/learning-journey.md b/docs/chapters/learning-journey.md similarity index 100% rename from site/chapters/learning-journey.md rename to docs/chapters/learning-journey.md diff --git a/site/chapters/milestones.md b/docs/chapters/milestones.md similarity index 100% rename from site/chapters/milestones.md rename to docs/chapters/milestones.md diff --git a/site/checkpoint-system.md b/docs/checkpoint-system.md similarity index 97% rename from site/checkpoint-system.md rename to docs/checkpoint-system.md index 8920c7f8..d3aee28b 100644 --- a/site/checkpoint-system.md +++ b/docs/checkpoint-system.md @@ -152,7 +152,7 @@ Every checkpoint completion unlocks a concrete capability: The checkpoint system provides comprehensive progress tracking and capability validation through automated testing infrastructure. -**πŸ“– See [Essential Commands](tito-essentials.md)** for complete command reference and usage examples. +**πŸ“– See [Essential Commands](tito/overview.md)** for complete command reference and usage examples. ### Integration with Development The checkpoint system connects directly to your actual development work: @@ -248,7 +248,7 @@ The checkpoint progression **Foundation β†’ Architecture β†’ Training β†’ Infere - **Problem**: Modules don't work together due to missing dependencies - **Solution**: Verify prerequisite capabilities before testing advanced features -**πŸ“– See [Essential Commands](tito-essentials.md)** for complete debugging command reference. +**πŸ“– See [Essential Commands](tito/overview.md)** for complete debugging command reference. ### Checkpoint Test Structure @@ -299,4 +299,4 @@ print("πŸ† Foundation checkpoint PASSED") - Analyze memory usage during testing - Identify bottlenecks in capability validation -**πŸ“– See [Essential Commands](tito-essentials.md)** for complete command reference and advanced usage examples. \ No newline at end of file +**πŸ“– See [Essential Commands](tito/overview.md)** for complete command reference and advanced usage examples. \ No newline at end of file diff --git a/site/community.md b/docs/community.md similarity index 98% rename from site/community.md rename to docs/community.md index 16658468..7d2bf1f3 100644 --- a/site/community.md +++ b/docs/community.md @@ -117,7 +117,7 @@ tito benchmark capstone **Submission:** After benchmarks complete, you'll be prompted to submit results (optional). Submissions are saved locally and can be shared with the community. -See [TITO CLI Reference](tito/overview.html) for complete command documentation. +See [TITO CLI Reference](tito/overview.md) for complete command documentation. --- diff --git a/site/credits.md b/docs/credits.md similarity index 100% rename from site/credits.md rename to docs/credits.md diff --git a/site/datasets.md b/docs/datasets.md similarity index 100% rename from site/datasets.md rename to docs/datasets.md diff --git a/site/faq.md b/docs/faq.md similarity index 98% rename from site/faq.md rename to docs/faq.md index c09daa13..84a21b39 100644 --- a/site/faq.md +++ b/docs/faq.md @@ -228,7 +228,7 @@ Each milestone proves your framework works by running actual ML experiments. - Helpful for self-assessment - Use `tito checkpoint status` to view progress -**πŸ“– See [Module Workflow](tito/modules.html)** for the core development cycle. +**πŸ“– See [Module Workflow](tito/modules.md)** for the core development cycle. --- @@ -255,7 +255,7 @@ cd modules/01_tensor jupyter lab tensor_dev.py ``` -**πŸ“– See [Getting Started Guide](getting-started.html)** for detailed setup. +**πŸ“– See [Getting Started Guide](getting-started.md)** for detailed setup. ### What's the typical workflow? @@ -272,7 +272,7 @@ cd ../../milestones/01_1957_perceptron python rosenblatt_forward.py # Uses YOUR implementation! ``` -**πŸ“– See [Module Workflow](tito/modules.html)** for complete details. +**πŸ“– See [Module Workflow](tito/modules.md)** for complete details. ### Can I use this in my classroom? diff --git a/docs/for-instructors.md b/docs/for-instructors.md new file mode 100644 index 00000000..bb6e3875 --- /dev/null +++ b/docs/for-instructors.md @@ -0,0 +1,443 @@ +# πŸ‘₯ For Instructors & TAs + +**Complete guide for teaching ML Systems Engineering with TinyTorch** + +
+

πŸ“‹ Quick Course Assessment

+

+Duration: 14-16 weeks (flexible pacing)
+Prerequisites: Python + basic linear algebra
+Student Outcome: Complete ML framework supporting vision AND language models
+Grading: 70% auto-graded (NBGrader), 30% manual (systems thinking) +

+
+ +## For Instructors: Course Setup + +### 30-Minute Initial Setup + +**Step 1: Environment Setup (10 minutes)** +```bash +# Clone repository +git clone https://github.com/mlsysbook/TinyTorch.git +cd TinyTorch + +# Create virtual environment +python -m venv .venv +source .venv/bin/activate # or `.venv\Scripts\activate` on Windows + +# Install dependencies +pip install -r requirements.txt +pip install nbgrader + +# Verify installation +tito system doctor +``` + +**Step 2: Initialize Grading (10 minutes)** +```bash +# Setup NBGrader integration +tito grade setup + +# Verify grading commands +tito grade --help +``` + +**Step 3: Prepare First Assignment (10 minutes)** +```bash +# Generate instructor version (with solutions) +tito grade generate 01_tensor + +# Create student version (solutions removed) +tito grade release 01_tensor + +# Student assignments ready in: release/01_tensor/ +``` + +### Assignment Workflow + +TinyTorch wraps NBGrader behind simple `tito grade` commands: + +**1. Prepare Assignments** +```bash +# Generate instructor version with solutions +tito grade generate MODULE_NAME + +# Create student version (auto-removes solutions) +tito grade release MODULE_NAME +``` + +**2. Distribute to Students** +- **Option A: GitHub Classroom** (recommended) + - Create assignment repository from TinyTorch template + - Students clone and work in their repos + - Automatic submission via GitHub + +- **Option B: Direct Distribution** + - Share `release/` directory contents + - Students download and submit via LMS + +**3. Collect Submissions** +```bash +# Collect all students +tito grade collect MODULE_NAME + +# Or specific student +tito grade collect MODULE_NAME --student student_id +``` + +**4. Auto-Grade** +```bash +# Grade all submissions +tito grade autograde MODULE_NAME + +# Grade specific student +tito grade autograde MODULE_NAME --student student_id +``` + +**5. Manual Review** +```bash +# Open browser-based grading interface +tito grade manual MODULE_NAME +``` + +**6. Generate Feedback** +```bash +# Create feedback files for students +tito grade feedback MODULE_NAME +``` + +**7. Export Grades** +```bash +# Export all grades to CSV +tito grade export + +# Or specific module +tito grade export --module MODULE_NAME --output grades.csv +``` + +### Grading Components + +**Auto-Graded (70%)** +- Code implementation correctness +- Test passing +- Function signatures +- Output validation +- Edge case handling + +**Manually Graded (30%)** +- ML Systems Thinking questions (3 per module) +- Each question: 10 points +- Focus on understanding, not perfection + +### Grading Rubric for Systems Thinking Questions + +| Points | Criteria | +|--------|----------| +| 9-10 | Deep understanding, specific code references, discusses systems implications (memory, scaling, trade-offs) | +| 7-8 | Good understanding, some code references, basic systems thinking | +| 5-6 | Surface understanding, generic response, limited systems perspective | +| 3-4 | Attempted but misses key concepts | +| 0-2 | No attempt or completely off-topic | + +**What to Look For:** +- References to actual implemented code +- Memory/performance analysis +- Scaling considerations +- Production system comparisons (PyTorch, TensorFlow) +- Understanding of trade-offs + +### Sample 16-Week Schedule + +| Week | Module | Focus | Teaching Notes | +|------|--------|-------|----------------| +| 1 | 01 Tensor | Data Structures, Memory | Demo: memory profiling, copying behavior | +| 2 | 02 Activations | Non-linearity, Stability | Demo: gradient vanishing/exploding | +| 3 | 03 Layers | Neural Components | Demo: forward/backward passes | +| 4 | 04 Losses | Optimization Objectives | Demo: loss landscapes | +| 5 | 05 Autograd | Auto Differentiation | ⚠️ Most challenging - allocate extra TA hours | +| 6 | 06 Optimizers | Training Algorithms | Demo: optimizer comparisons | +| 7 | 07 Training | Complete Training Loop | Milestone: Train first network! | +| 8 | **Midterm Project** | Build and Train Network | Assessment: End-to-end system | +| 9 | 08 DataLoader | Data Pipeline | Demo: batching, shuffling | +| 10 | 09 Spatial | Convolutions, CNNs | ⚠️ High demand - O(NΒ²) complexity | +| 11 | 10 Tokenization | Text Processing | Demo: vocabulary building | +| 12 | 11 Embeddings | Word Representations | Demo: embedding similarity | +| 13 | 12 Attention | Attention Mechanisms | ⚠️ Moderate-high demand | +| 14 | 13 Transformers | Transformer Architecture | Milestone: Text generation! | +| 15 | 14-19 Optimization | Profiling, Quantization | Focus on production trade-offs | +| 16 | 20 Capstone | **Torch Olympics** | Final Competition | + +### Critical Modules (Extra TA Support Needed) + +1. **Module 05: Autograd** - Most conceptually challenging + - Pre-record debugging walkthroughs + - Create FAQ document + - Schedule additional office hours + +2. **Module 09: Spatial (CNNs)** - Complex nested loops + - Focus on memory profiling + - Loop optimization strategies + - Padding/stride calculations + +3. **Module 12: Attention** - Attention mechanisms + - Scaling factor importance + - Numerical stability + - Positional encoding issues + +### Module-Specific Teaching Notes + +**Module 01: Tensor** +- **Key Concept:** Memory layout is crucial for ML performance +- **Demo:** Show `memory_footprint()`, compare copying vs views +- **Watch For:** Students hardcoding float32 instead of using `dtype` + +**Module 05: Autograd** +- **Key Concept:** Computational graphs enable deep learning +- **Demo:** Visualize computational graphs, show gradient flow +- **Watch For:** Gradient shape mismatches, disconnected graphs + +**Module 09: Spatial (CNNs)** +- **Key Concept:** O(NΒ²) operations become bottlenecks +- **Demo:** Profile convolution memory usage +- **Watch For:** Index out of bounds, missing padding + +**Module 12: Attention** +- **Key Concept:** Attention is compute-intensive but powerful +- **Demo:** Profile attention with different sequence lengths +- **Watch For:** Missing scaling factor (1/√d_k), softmax errors + +**Module 20: Capstone** +- **Key Concept:** Production requires optimization across ALL components +- **Project:** Torch Olympics Competition (4 tracks: Speed, Compression, Accuracy, Efficiency) + +### Assessment Strategy + +**Continuous Assessment (70%)** +- Module completion: 4% each Γ— 16 modules = 64% +- Checkpoint achievements: 6% + +**Projects (30%)** +- Midterm: Build and train CNN on CIFAR-10 (15%) +- Final: Torch Olympics Competition (15%) + +### Tracking Student Progress + +```bash +# Check specific student +tito checkpoint status --student student_id + +# Export class progress +tito checkpoint export --output class_progress.csv + +# View module completion rates +tito module status --comprehensive +``` + +**Identify Struggling Students:** +- Missing checkpoint achievements +- Low scores on systems thinking questions +- Incomplete module submissions +- Late milestone completions + +--- + +## For Teaching Assistants: Student Support + +### TA Preparation + +**Develop Deep Familiarity With:** +1. **Module 05: Autograd** - Most student questions +2. **Module 09: CNNs** - Complex implementation +3. **Module 13: Transformers** - Advanced concepts + +**Preparation Process:** +1. Complete all three critical modules yourself +2. Introduce bugs intentionally +3. Practice debugging scenarios +4. Review past student submissions + +### Common Student Errors + +#### Module 05: Autograd + +**Error 1: Gradient Shape Mismatches** +- Symptom: `ValueError: shapes don't match for gradient` +- Cause: Incorrect gradient accumulation +- Debug: Check gradient shapes match parameter shapes + +**Error 2: Disconnected Computational Graph** +- Symptom: Gradients are None or zero +- Cause: Operations not tracked +- Debug: Verify `requires_grad=True`, check graph construction + +**Error 3: Broadcasting Failures** +- Symptom: Shape errors during backward pass +- Cause: Incorrect handling of broadcasted operations +- Debug: Check gradient accumulation for broadcasted dims + +#### Module 09: CNNs (Spatial) + +**Error 1: Index Out of Bounds** +- Symptom: `IndexError` in convolution loops +- Cause: Incorrect padding/stride calculations +- Debug: Verify output shape calculations + +**Error 2: Memory Issues** +- Symptom: Out of memory errors +- Cause: Creating unnecessary intermediate arrays +- Debug: Profile memory, look for unnecessary copies + +#### Module 13: Transformers + +**Error 1: Attention Scaling Issues** +- Symptom: Attention weights don't sum to 1 +- Cause: Missing softmax or incorrect scaling +- Debug: Verify softmax, check scaling factor (1/√d_k) + +**Error 2: Positional Encoding Errors** +- Symptom: Model doesn't learn positional information +- Cause: Incorrect implementation +- Debug: Verify sinusoidal patterns + +### Debugging Strategy + +**Guide students with questions, not answers:** + +1. "What error message are you seeing?" - Read full traceback +2. "What did you expect to happen?" - Clarify mental model +3. "What actually happened?" - Compare expected vs actual +4. "What have you tried?" - Avoid repeating failed approaches +5. "Can you test with a simpler case?" - Reduce complexity + +### Productive vs Unproductive Struggle + +**Productive Struggle (encourage):** +- Trying different approaches +- Making incremental progress +- Understanding error messages +- Passing more tests over time + +**Unproductive Frustration (intervene):** +- Repeated identical errors +- Random code changes +- Unable to articulate the problem +- No progress after 30+ minutes + +### Office Hour Patterns + +**Expected Demand Spikes:** + +- **Weeks 5-6 (Module 05: Autograd)**: Highest demand + - Schedule 2Γ— TA capacity + - Pre-record debugging walkthroughs + - Create FAQ document + +- **Week 10 (Module 09: CNNs)**: High demand + - Focus on memory profiling + - Loop optimization + - Padding/stride help + +- **Week 13 (Module 13: Transformers)**: Moderate-high + - Attention debugging + - Scaling problems + - Architecture questions + +### Manual Review Focus + +While auto-grading handles 70%, focus manual review on: + +1. **Code Quality** + - Readability + - Design choices + - Documentation + +2. **Edge Case Handling** + - Appropriate checks + - Error handling + - Boundary conditions + +3. **Systems Thinking** + - Memory analysis + - Performance understanding + - Scaling awareness + +### Teaching Tips + +1. **Encourage Exploration** - Let students try different approaches +2. **Connect to Production** - Reference PyTorch equivalents +3. **Make Systems Visible** - Profile memory, analyze complexity together +4. **Build Confidence** - Acknowledge progress and validate understanding + +--- + +## Troubleshooting Common Issues + +### Environment Problems +```bash +# Student fix: +tito system doctor +tito system reset +``` + +### Module Import Errors +```bash +# Rebuild package +tito module complete N +``` + +### Test Failures +```bash +# Detailed test output +tito module test N --verbose +``` + +### NBGrader Issues + +**Database Locked** +```bash +# Clear and reinitialize +rm gradebook.db +tito grade setup +``` + +**Missing Submissions** +```bash +# Check submission directory +ls submitted/*/MODULE/ +``` + +--- + +## Additional Resources + +- **[Complete Course Structure](chapters/00-introduction.md)** - Full curriculum overview +- **[Student Getting Started](getting-started.md)** - Send this to students +- **[CLI Documentation](tito/overview.md)** - Detailed command reference +- **[Troubleshooting Guide](tito/troubleshooting.md)** - Common issues and solutions +- **[GitHub Discussions](https://github.com/mlsysbook/TinyTorch/discussions)** - Community support +- **[Issue Tracker](https://github.com/mlsysbook/TinyTorch/issues)** - Report bugs + +--- + +## Contact & Support + +**Need help?** +- Open an issue on GitHub +- Join discussions forum +- Email: support@mlsysbook.ai (if available) + +**Contributing:** +- Sample solutions welcome +- Teaching material improvements +- Bug fixes and enhancements + +--- + +
+

βœ… You're Ready to Teach!

+

+With NBGrader integration, automated grading, and comprehensive teaching materials, you have everything needed to run a successful ML systems course. +

+
+ diff --git a/site/getting-started.md b/docs/getting-started.md similarity index 98% rename from site/getting-started.md rename to docs/getting-started.md index 439f19c6..34e1810e 100644 --- a/site/getting-started.md +++ b/docs/getting-started.md @@ -71,7 +71,7 @@ tito community join tito benchmark baseline ``` -All community data is stored locally in `.tinytorch/` directory. See **[Community Guide](community.html)** for complete features. +All community data is stored locally in `.tinytorch/` directory. See **[Community Guide](community.md)** for complete features. ### The TinyTorch Build Cycle @@ -136,7 +136,7 @@ Each milestone has a README explaining: - Expected results - What you're learning -**πŸ“– See [Historical Milestones](chapters/milestones.html)** for the complete progression through ML history. +**πŸ“– See [Historical Milestones](chapters/milestones.md)** for the complete progression through ML history. ### Your First Module (15 Minutes) @@ -170,7 +170,7 @@ TinyTorch has 20 modules organized in progressive tiers: - **Optimization (14-19)**: Production optimization - profiling, quantization, benchmarking - **Capstone (20)**: Torch Olympics Competition -**πŸ“– See [Complete Course Structure](chapters/00-introduction.html)** for detailed module descriptions. +**πŸ“– See [Complete Course Structure](chapters/00-introduction.md)** for detailed module descriptions. ### Essential Commands Reference @@ -191,7 +191,7 @@ tito community join tito benchmark baseline ``` -**πŸ“– See [TITO CLI Reference](tito/overview.html)** for complete command documentation. +**πŸ“– See [TITO CLI Reference](tito/overview.md)** for complete command documentation. ### Notebook Platform Options @@ -416,7 +416,7 @@ tito grade export --module 01_tensor --output grades_module01.csv - **System health monitoring** (`tito module status --comprehensive`) - **Community support** via GitHub Issues -**πŸ“– See [Complete Course Structure](chapters/00-introduction.html)** for full curriculum overview. +**πŸ“– See [Complete Course Structure](chapters/00-introduction.md)** for full curriculum overview. --- diff --git a/site/instructor-guide.md b/docs/instructor-guide.md similarity index 100% rename from site/instructor-guide.md rename to docs/instructor-guide.md diff --git a/site/intro.md b/docs/intro.md similarity index 100% rename from site/intro.md rename to docs/intro.md diff --git a/site/learning-journey-visual.md b/docs/learning-journey-visual.md similarity index 100% rename from site/learning-journey-visual.md rename to docs/learning-journey-visual.md diff --git a/site/learning-progress.md b/docs/learning-progress.md similarity index 98% rename from site/learning-progress.md rename to docs/learning-progress.md index 44ad090c..4e586382 100644 --- a/site/learning-progress.md +++ b/docs/learning-progress.md @@ -82,7 +82,7 @@ tito checkpoint status # View your progress This provides 21 capability checkpoints corresponding to modules and validates your understanding. Helpful for self-assessment but **not required** for the core workflow. -**πŸ“– See [Essential Commands](tito-essentials.md)** for checkpoint commands. +**πŸ“– See [Essential Commands](tito/overview.md)** for checkpoint commands. --- diff --git a/site/prerequisites.md b/docs/prerequisites.md similarity index 90% rename from site/prerequisites.md rename to docs/prerequisites.md index 7e5f2218..11c36a9a 100644 --- a/site/prerequisites.md +++ b/docs/prerequisites.md @@ -99,7 +99,7 @@ You need TWO things to start building: ### Python & NumPy -**[NumPy Quickstart Tutorial](https://numpy.org/doc/stable/user/quickstart.html)** +**[NumPy Quickstart Tutorial](https://numpy.org/doc/stable/user/quickstart.md)** - Essential NumPy operations and array manipulation - **Review before Module 01** if NumPy is unfamiliar @@ -121,14 +121,14 @@ You need TWO things to start building: ## Next Steps **Ready to Build:** -- See [Quick Start Guide](quickstart-guide.html) for hands-on experience -- See [Student Workflow](student-workflow.html) for development process -- See [Course Structure](chapters/00-introduction.html) for full curriculum +- See [Quick Start Guide](quickstart-guide.md) for hands-on experience +- See [Student Workflow](student-workflow.md) for development process +- See [Course Structure](chapters/00-introduction.md) for full curriculum **Need More Context:** -- See [Additional Resources](resources.html) for broader ML learning materials -- See [FAQ](faq.html) for common questions about TinyTorch -- See [Community](community.html) to connect with other learners +- See [Additional Resources](resources.md) for broader ML learning materials +- See [FAQ](faq.md) for common questions about TinyTorch +- See [Community](community.md) to connect with other learners --- diff --git a/site/quickstart-guide.md b/docs/quickstart-guide.md similarity index 99% rename from site/quickstart-guide.md rename to docs/quickstart-guide.md index b5831b76..905bd0b9 100644 --- a/site/quickstart-guide.md +++ b/docs/quickstart-guide.md @@ -74,7 +74,7 @@ tito benchmark baseline - Your "Hello World" moment! - Generates score and saves results locally -See [Community Guide](community.html) for complete features. +See [Community Guide](community.md) for complete features. diff --git a/site/resources.md b/docs/resources.md similarity index 100% rename from site/resources.md rename to docs/resources.md diff --git a/site/student-workflow.md b/docs/student-workflow.md similarity index 97% rename from site/student-workflow.md rename to docs/student-workflow.md index d09da6f1..c85503a2 100644 --- a/site/student-workflow.md +++ b/docs/student-workflow.md @@ -208,7 +208,7 @@ tito community profile tito community update ``` -**Privacy:** All information is optional. Data is stored locally in `.tinytorch/` directory. See [Community Guide](community.html) for details. +**Privacy:** All information is optional. Data is stored locally in `.tinytorch/` directory. See [Community Guide](community.md) for details. ### Benchmark Your Progress @@ -226,7 +226,7 @@ tito benchmark capstone --track all **Capstone Benchmark:** Full performance evaluation across speed, compression, accuracy, and efficiency tracks. -See [Community Guide](community.html) for complete community and benchmarking features. +See [Community Guide](community.md) for complete community and benchmarking features. ## Instructor Integration diff --git a/site/tiers/architecture.md b/docs/tiers/architecture.md similarity index 100% rename from site/tiers/architecture.md rename to docs/tiers/architecture.md diff --git a/site/tiers/foundation.md b/docs/tiers/foundation.md similarity index 100% rename from site/tiers/foundation.md rename to docs/tiers/foundation.md diff --git a/site/tiers/olympics.md b/docs/tiers/olympics.md similarity index 98% rename from site/tiers/olympics.md rename to docs/tiers/olympics.md index e0e29b21..46f3bc3c 100644 --- a/site/tiers/olympics.md +++ b/docs/tiers/olympics.md @@ -382,4 +382,4 @@ tito olympics leaderboard --- -**[← Back to Home](../intro)** β€’ **[View Leaderboard](../leaderboard)** β€’ **[Competition Rules](../olympics-rules)** +**[← Back to Home](../intro)** diff --git a/site/tiers/optimization.md b/docs/tiers/optimization.md similarity index 100% rename from site/tiers/optimization.md rename to docs/tiers/optimization.md diff --git a/site/tito/data.md b/docs/tito/data.md similarity index 100% rename from site/tito/data.md rename to docs/tito/data.md diff --git a/site/tito/milestones.md b/docs/tito/milestones.md similarity index 100% rename from site/tito/milestones.md rename to docs/tito/milestones.md diff --git a/site/tito/modules.md b/docs/tito/modules.md similarity index 100% rename from site/tito/modules.md rename to docs/tito/modules.md diff --git a/site/tito/overview.md b/docs/tito/overview.md similarity index 94% rename from site/tito/overview.md rename to docs/tito/overview.md index 496ccf36..1c66ecb7 100644 --- a/site/tito/overview.md +++ b/docs/tito/overview.md @@ -187,13 +187,13 @@ tito milestone run 03 | Command | Description | Guide | |---------|-------------|-------| -| `tito community join` | Join the community (optional info) | [Community Guide](../community.html) | -| `tito community update` | Update your community profile | [Community Guide](../community.html) | -| `tito community profile` | View your community profile | [Community Guide](../community.html) | -| `tito community stats` | View community statistics | [Community Guide](../community.html) | -| `tito community leave` | Remove your community profile | [Community Guide](../community.html) | +| `tito community join` | Join the community (optional info) | [Community Guide](../community.md) | +| `tito community update` | Update your community profile | [Community Guide](../community.md) | +| `tito community profile` | View your community profile | [Community Guide](../community.md) | +| `tito community stats` | View community statistics | [Community Guide](../community.md) | +| `tito community leave` | Remove your community profile | [Community Guide](../community.md) | -**See**: [Community Guide](../community.html) for complete details +**See**: [Community Guide](../community.md) for complete details ### Benchmark Commands @@ -201,10 +201,10 @@ tito milestone run 03 | Command | Description | Guide | |---------|-------------|-------| -| `tito benchmark baseline` | Quick setup validation ("Hello World") | [Community Guide](../community.html) | -| `tito benchmark capstone` | Full Module 20 performance evaluation | [Community Guide](../community.html) | +| `tito benchmark baseline` | Quick setup validation ("Hello World") | [Community Guide](../community.md) | +| `tito benchmark capstone` | Full Module 20 performance evaluation | [Community Guide](../community.md) | -**See**: [Community Guide](../community.html) for complete details +**See**: [Community Guide](../community.md) for complete details ### Developer Commands @@ -370,9 +370,9 @@ tito milestone run --help ## Related Resources -- **[Getting Started Guide](../getting-started.html)** - Complete setup and first steps -- **[Module Workflow](modules.html)** - Day-to-day development cycle -- **[Datasets Guide](../datasets.html)** - Understanding TinyTorch datasets +- **[Getting Started Guide](../getting-started.md)** - Complete setup and first steps +- **[Module Workflow](modules.md)** - Day-to-day development cycle +- **[Datasets Guide](../datasets.md)** - Understanding TinyTorch datasets --- diff --git a/docs/tito/quick-reference.md b/docs/tito/quick-reference.md new file mode 100644 index 00000000..4df1cde9 --- /dev/null +++ b/docs/tito/quick-reference.md @@ -0,0 +1,217 @@ +# ⚑ Quick Reference + +**One-page cheatsheet for experienced developers** + +## Essential Commands + +### Setup & Verification +```bash +# Initial setup +git clone https://github.com/mlsysbook/TinyTorch.git +cd TinyTorch +./setup-environment.sh +source activate.sh + +# Verify installation +tito system doctor + +# System information +tito system info +``` + +### Core Workflow +```bash +# 1. Edit module in Jupyter +cd modules/NN_name +jupyter lab NN_name.ipynb + +# 2. Export to package +tito module complete N + +# 3. Validate (run milestone scripts) +cd milestones/MM_YYYY_name +python script.py +``` + +### Module Management +```bash +# Export specific module +tito module complete 01 + +# Check module status +tito checkpoint status + +# System reset (if needed) +tito system reset +``` + +### Community & Benchmarking +```bash +# Join community (optional) +tito community join + +# Run baseline benchmark +tito benchmark baseline + +# View profile +tito community profile +``` + +## Module Dependencies + +### Foundation (Required for All) +**Modules 01-07**: Tensor, Activations, Layers, Losses, Autograd, Optimizers, Training + +**Unlocks:** +- Milestone 01: Perceptron (1957) +- Milestone 02: XOR Crisis (1969) +- Milestone 03: MLP (1986) + +### Architecture (Vision + Language) +**Modules 08-13**: DataLoader, Convolutions, Tokenization, Embeddings, Attention, Transformers + +**Unlocks:** +- Milestone 04: CNN (1998) - requires M01-09 +- Milestone 05: Transformer (2017) - requires M01-13 + +### Optimization (Production) +**Modules 14-19**: Profiling, Quantization, Compression, Memoization, Acceleration, Benchmarking + +**Unlocks:** +- Milestone 06: Torch Olympics (2018) - requires M01-19 + +### Capstone +**Module 20**: Torch Olympics Competition + +## Common Workflows + +### Starting a New Module +```bash +# Navigate to module directory +cd modules/05_autograd + +# Open in Jupyter +jupyter lab 05_autograd.ipynb + +# Implement required functions +# Run inline tests +# Add docstrings + +# Export when complete +cd ../.. +tito module complete 05 +``` + +### Debugging Module Errors +```bash +# Check system health +tito system doctor + +# View detailed error logs +tito module complete N --verbose + +# Reset if corrupted +tito system reset + +# Reimport in Python +python +>>> from tinytorch import * +>>> # Test your implementation +``` + +### Running Milestones +```bash +# After completing Foundation (M01-07) +cd milestones/01_1957_perceptron +python 01_rosenblatt_forward.py + +# After completing Architecture (M01-09) +cd milestones/04_1998_cnn +python 01_lenet_inference.py +python 02_lenet_training.py + +# After completing Optimization (M01-19) +cd milestones/06_2018_mlperf +python benchmark.py +``` + +## File Structure + +``` +TinyTorch/ +β”œβ”€β”€ modules/ # Source notebooks (edit these) +β”‚ β”œβ”€β”€ 01_tensor/ +β”‚ β”‚ └── 01_tensor.ipynb +β”‚ └── ... +β”œβ”€β”€ tinytorch/ # Exported package (auto-generated) +β”‚ β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ nn/ +β”‚ └── ... +β”œβ”€β”€ milestones/ # Validation scripts (run these) +β”‚ β”œβ”€β”€ 01_1957_perceptron/ +β”‚ β”œβ”€β”€ 02_1969_xor/ +β”‚ └── ... +└── tito/ # CLI tool +``` + +## Import Patterns + +```python +# After exporting modules +from tinytorch.core.tensor import Tensor # M01 +from tinytorch.nn.activations import ReLU, Softmax # M02 +from tinytorch.nn.layers import Linear # M03 +from tinytorch.nn.losses import CrossEntropyLoss # M04 +from tinytorch.autograd import backward # M05 +from tinytorch.optim import SGD, Adam # M06 +from tinytorch.training import Trainer # M07 +``` + +## Troubleshooting Quick Fixes + +| Issue | Quick Fix | +|-------|-----------| +| `ModuleNotFoundError: tinytorch` | Run `tito module complete N` to export | +| `tito: command not found` | Run `source activate.sh` | +| Import works in notebook, fails in Python | Restart Python kernel after export | +| Tests pass in notebook, fail in milestone | Check module dependencies (M01-07 required) | +| OOM errors | Profile memory usage, check for unnecessary copies | +| NaN losses | Check gradient flow, activation stability | + +## Performance Expectations + +### Baseline Benchmarks (Your Hardware May Vary) +- **M01-07**: Perceptron trains in <1 second +- **M01-09**: CIFAR-10 CNN trains in 10-30 minutes (CPU) +- **M01-13**: Small transformer inference in 1-5 seconds +- **M01-19**: Optimized models run 10-40Γ— faster + +### Memory Usage +- **M01**: Tensor operations ~100 MB +- **M01-09**: CNN training ~1-2 GB +- **M01-13**: Transformer training ~2-4 GB +- **M01-19**: Optimized models use 50-90% less memory + +## NBGrader (For Students in Courses) + +```bash +# If using NBGrader in classroom setting +# Submit your completed notebook +# Do NOT submit the exported package + +# Grading components: +# - 70% Auto-graded (tests) +# - 30% Manual (systems thinking questions) +``` + +## Next Steps + +- **New to TinyTorch?** Start with [Getting Started](../getting-started.md) +- **Stuck on a module?** Check [Troubleshooting](troubleshooting.md) +- **Need detailed docs?** See [CLI Documentation](overview.md) +- **Teaching a course?** See [For Instructors & TAs](../for-instructors.md) + +--- + +**πŸ’‘ Pro Tip**: Bookmark this page for quick command reference while building! + diff --git a/site/tito/troubleshooting.md b/docs/tito/troubleshooting.md similarity index 100% rename from site/tito/troubleshooting.md rename to docs/tito/troubleshooting.md diff --git a/site/usage-paths/classroom-use.md b/docs/usage-paths/classroom-use.md similarity index 98% rename from site/usage-paths/classroom-use.md rename to docs/usage-paths/classroom-use.md index 24b7e807..f0b5ea4b 100644 --- a/site/usage-paths/classroom-use.md +++ b/docs/usage-paths/classroom-use.md @@ -34,7 +34,7 @@