mirror of
https://github.com/MLSysBook/TinyTorch.git
synced 2026-04-30 02:17:31 -05:00
Improve SIGCSE paper with reviewer feedback and clean up repository
Paper improvements: - Add differentiated time estimates (60-80h experienced, 100-120h typical, 140-180h struggling) - Moderate cognitive load claims with hedging language and empirical validation notes - Add ML Systems Research subsection with citations (Baydin AD survey, Chen gradient checkpointing, TVM, FlashAttention) - Add comprehensive Threats to Validity section (selection bias, single institution, demand characteristics, no control group, maturation, assessment validity) - Define jargon (monkey-patching) at first use with clear explanation Documentation updates: - Restructure TITO CLI docs into dedicated section (overview, modules, milestones, data, troubleshooting) - Update student workflow guide and quickstart guide - Remove deprecated files (testing-framework.md, tito-essentials.md) - Update module template and testing architecture docs Repository cleanup: - Remove temporary review files (ADDITIONAL_REVIEWS.md, EDTECH_OPENSOURCE_REVIEWS.md, TA_STRUGGLING_STUDENT_REVIEWS.md, etc.) - Remove temporary development planning docs - Update demo GIFs and configurations
This commit is contained in:
Vijay Janapa Reddi
Binary file not shown.
@@ -6,7 +6,7 @@ root: intro
|
||||
title: "TinyTorch Course"
|
||||
|
||||
parts:
|
||||
- caption: Getting Started
|
||||
- caption: 🚀 Getting Started
|
||||
chapters:
|
||||
- file: quickstart-guide
|
||||
title: "Quick Start Guide"
|
||||
@@ -77,7 +77,7 @@ parts:
|
||||
- file: modules/20_capstone_ABOUT
|
||||
title: "20. Torch Olympics"
|
||||
|
||||
- caption: Course Orientation
|
||||
- caption: 🧭 Course Orientation
|
||||
chapters:
|
||||
- file: chapters/00-introduction
|
||||
title: "Course Structure"
|
||||
@@ -90,16 +90,22 @@ parts:
|
||||
- file: faq
|
||||
title: "FAQ"
|
||||
|
||||
- caption: Using TinyTorch
|
||||
- caption: 🛠️ TITO CLI Reference
|
||||
chapters:
|
||||
- file: tito-essentials
|
||||
title: "Essential Commands"
|
||||
- file: tito/overview
|
||||
title: "Command Overview"
|
||||
- file: tito/modules
|
||||
title: "Module Workflow"
|
||||
- file: tito/milestones
|
||||
title: "Milestone System"
|
||||
- file: tito/data
|
||||
title: "Progress & Data"
|
||||
- file: tito/troubleshooting
|
||||
title: "Troubleshooting"
|
||||
- file: datasets
|
||||
title: "Datasets Guide"
|
||||
- file: testing-framework
|
||||
title: "Testing Guide"
|
||||
|
||||
- caption: Community
|
||||
- caption: 🤝 Community
|
||||
chapters:
|
||||
- file: community
|
||||
title: "Ecosystem"
|
||||
|
||||
@@ -32,7 +32,7 @@ source activate.sh
|
||||
- Configures TinyTorch in development mode
|
||||
- Verifies installation
|
||||
|
||||
See [Essential Commands](tito-essentials.md) for detailed workflow and troubleshooting.
|
||||
See [TITO CLI Reference](tito/overview.md) for detailed workflow and troubleshooting.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -46,7 +46,7 @@ tito system doctor
|
||||
|
||||
You should see all green checkmarks. This confirms your environment is ready for hands-on ML systems building.
|
||||
|
||||
See [Essential Commands](tito-essentials.md) for verification commands and troubleshooting.
|
||||
See [Module Workflow](tito/modules.md) for detailed commands and [Troubleshooting](tito/troubleshooting.md) if needed.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -214,8 +214,7 @@ In 15 minutes, you've:
|
||||
|
||||
**Master the Workflow:**
|
||||
- See [Student Workflow](student-workflow.md) for the complete edit → export → validate cycle
|
||||
- See [Essential Commands](tito-essentials.md) for complete TITO command reference
|
||||
- See [Student Workflow](student-workflow.md) for the complete development cycle
|
||||
- See [TITO CLI Reference](tito/overview.md) for complete command reference
|
||||
|
||||
**For Instructors:**
|
||||
- See [Classroom Setup Guide](usage-paths/classroom-use.md) for [NBGrader](https://nbgrader.readthedocs.io/) integration (coming soon)
|
||||
@@ -241,7 +240,7 @@ See [Student Workflow](student-workflow.md) for detailed workflow guide and best
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Ready to Build Production ML Systems</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">You've proven you can build ML components from scratch. Time to keep going!</p>
|
||||
<a href="chapters/03-activations.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">Continue Building →</a>
|
||||
<a href="tito-essentials.html" style="display: inline-block; background: #28a745; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Master Commands →</a>
|
||||
<a href="tito/overview.html" style="display: inline-block; background: #28a745; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">TITO CLI Reference →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
@@ -137,7 +137,7 @@ tito checkpoint status
|
||||
tito system info
|
||||
```
|
||||
|
||||
For complete command documentation, see [TITO Essentials](tito-essentials.md).
|
||||
For complete command documentation, see [TITO CLI Reference](tito/overview.md).
|
||||
|
||||
## Checkpoint System (Optional)
|
||||
|
||||
|
||||
@@ -1,383 +0,0 @@
|
||||
# Testing Framework
|
||||
|
||||
```{admonition} Test-Driven ML Engineering
|
||||
:class: tip
|
||||
TinyTorch's testing framework ensures your implementations are not just educational, but production-ready and reliable.
|
||||
```
|
||||
|
||||
## Testing Philosophy: Verify Understanding Through Implementation
|
||||
|
||||
TinyTorch testing goes beyond checking syntax - it validates that you understand ML systems engineering through working implementations.
|
||||
|
||||
## Quick Start: Validate Your Implementation
|
||||
|
||||
### Run Everything (Recommended)
|
||||
```bash
|
||||
# Complete validation suite
|
||||
tito test --comprehensive
|
||||
|
||||
# Expected output:
|
||||
# 🧪 Running 16 module tests...
|
||||
# 🔗 Running integration tests...
|
||||
# 📊 Running performance benchmarks...
|
||||
# ✅ Overall TinyTorch Health: 100.0%
|
||||
```
|
||||
|
||||
### Target-Specific Testing
|
||||
```bash
|
||||
# Test what you just built
|
||||
tito module complete 02_tensor && tito checkpoint test 01
|
||||
|
||||
# Quick module check
|
||||
tito test --module attention --verbose
|
||||
|
||||
# Performance validation
|
||||
tito test --performance --module training
|
||||
```
|
||||
|
||||
## Testing Levels: From Components to Systems
|
||||
|
||||
### 1. Module-Level Testing
|
||||
**Goal**: Verify individual components work correctly in isolation
|
||||
|
||||
```bash
|
||||
# Test what you just implemented
|
||||
tito test --module tensor --verbose
|
||||
tito test --module attention --detailed
|
||||
|
||||
# Quick health check for specific module
|
||||
tito module validate spatial
|
||||
|
||||
# Debug failing module
|
||||
tito test --module autograd --debug
|
||||
```
|
||||
|
||||
**What Gets Tested:**
|
||||
- ✅ Core functionality (forward pass, backward pass)
|
||||
- ✅ Memory usage patterns and leaks
|
||||
- ✅ Mathematical correctness vs reference implementations
|
||||
- ✅ Edge cases and error handling
|
||||
|
||||
### 2. 🔗 Integration Testing
|
||||
**Goal**: Ensure modules work together seamlessly
|
||||
|
||||
```bash
|
||||
# Test module dependencies
|
||||
tito test --integration --focus training
|
||||
|
||||
# Validate export/import chain
|
||||
tito test --exports --all-modules
|
||||
|
||||
# Full pipeline validation
|
||||
tito test --pipeline --from tensor --to training
|
||||
```
|
||||
|
||||
**Integration Scenarios:**
|
||||
- **Tensor → Autograd**: Gradient flow works correctly
|
||||
- **Spatial → Training**: CNN training pipeline functions end-to-end
|
||||
- **Attention → TinyGPT**: Transformer components integrate properly
|
||||
- **All Modules**: Complete framework functionality
|
||||
|
||||
### 3. 🏆 Checkpoint Testing
|
||||
**Goal**: Validate you've achieved specific learning capabilities
|
||||
|
||||
```bash
|
||||
# Test your current capabilities
|
||||
tito checkpoint test 01 # "Can I create and manipulate tensors?"
|
||||
tito checkpoint test 08 # "Can I train neural networks end-to-end?"
|
||||
tito checkpoint test 13 # "Can I build attention mechanisms?"
|
||||
|
||||
# Progressive capability validation
|
||||
tito checkpoint validate --from 00 --to 15
|
||||
```
|
||||
|
||||
See [Student Workflow](student-workflow.md) for the complete development cycle and testing integration.
|
||||
|
||||
**Key Capability Categories:**
|
||||
- **Foundation (00-03)**: Building blocks of neural networks
|
||||
- **Training (04-08)**: End-to-end learning systems
|
||||
- **Architecture (09-14)**: Advanced model architectures
|
||||
- **Optimization (15+)**: Production-ready systems
|
||||
|
||||
### 4. 📊 Performance & Systems Testing
|
||||
**Goal**: Verify your implementation meets performance expectations
|
||||
|
||||
```bash
|
||||
# Memory usage analysis
|
||||
tito test --memory --module training --profile
|
||||
|
||||
# Speed benchmarking
|
||||
tito test --speed --compare-baseline
|
||||
|
||||
# Scaling behavior validation
|
||||
tito test --scaling --model-sizes 1M,5M,10M
|
||||
```
|
||||
|
||||
**Performance Metrics:**
|
||||
- **Memory efficiency**: Peak usage, gradient memory, batch scaling
|
||||
- **Training speed**: Convergence time, throughput (samples/sec)
|
||||
- **Inference latency**: Forward pass time, batch processing efficiency
|
||||
- **Scaling behavior**: Performance vs model size, memory vs accuracy trade-offs
|
||||
|
||||
### 5. 🌍 Real-World Example Validation
|
||||
**Goal**: Demonstrate production-ready functionality
|
||||
|
||||
```bash
|
||||
# Train actual models
|
||||
tito example train-mnist-mlp # 95%+ accuracy target
|
||||
tito example train-cifar-cnn # 75%+ accuracy target
|
||||
tito example generate-text # TinyGPT coherent generation
|
||||
|
||||
# Production scenarios
|
||||
tito example benchmark-inference # Speed/memory competitive analysis
|
||||
tito example deploy-edge # Resource-constrained deployment
|
||||
```
|
||||
|
||||
## 🏗️ Test Architecture: Systems Engineering Approach
|
||||
|
||||
### 📋 Progressive Testing Pattern
|
||||
Every TinyTorch module follows consistent testing standards:
|
||||
|
||||
```python
|
||||
# Module testing template (every module follows this pattern)
|
||||
class ModuleTest:
|
||||
def test_core_functionality(self): # Basic operations work
|
||||
def test_mathematical_correctness(self): # Matches reference implementations
|
||||
def test_memory_usage(self): # No memory leaks, efficient usage
|
||||
def test_integration_ready(self): # Exports correctly for other modules
|
||||
def test_real_world_usage(self): # Works in actual ML pipelines
|
||||
```
|
||||
|
||||
### 📁 Test Organization Structure
|
||||
```bash
|
||||
tests/
|
||||
├── checkpoints/ # 16 capability validation tests
|
||||
│ ├── checkpoint_00_environment.py # Development setup working
|
||||
│ ├── checkpoint_01_foundation.py # Tensor operations mastered
|
||||
│ └── checkpoint_15_capstone.py # Complete ML systems expertise
|
||||
├── integration/ # Cross-module compatibility
|
||||
│ ├── test_training_pipeline.py # End-to-end training works
|
||||
│ └── test_module_exports.py # All modules export correctly
|
||||
├── performance/ # Systems performance validation
|
||||
│ ├── memory_profiling.py # Memory usage analysis
|
||||
│ └── speed_benchmarks.py # Computational performance
|
||||
└── examples/ # Real-world usage validation
|
||||
├── test_mnist_training.py # Actual MNIST training works
|
||||
└── test_cifar_cnn.py # CNN achieves 75%+ on CIFAR-10
|
||||
```
|
||||
|
||||
## 📊 Understanding Test Results
|
||||
|
||||
### 🎯 Health Status Interpretation
|
||||
| Score | Status | Action Required |
|
||||
|-------|--------|----------------|
|
||||
| **100%** | 🟢 Excellent | All systems operational, ready for production |
|
||||
| **95-99%** | 🟡 Good | Minor issues, investigate warnings |
|
||||
| **90-94%** | 🟠 Caution | Some failing tests, address specific modules |
|
||||
| **<90%** | 🔴 Issues | Significant problems, requires immediate attention |
|
||||
|
||||
### 🚦 Module Status Indicators
|
||||
- ✅ **Passing**: Module implemented correctly, all tests green
|
||||
- ⚠️ **Warning**: Minor issues detected, functionality mostly intact
|
||||
- ❌ **Failing**: Critical errors, module needs debugging
|
||||
- 🚧 **In Progress**: Module under development, tests expected to fail
|
||||
- 🎯 **Checkpoint Ready**: Module ready for capability testing
|
||||
|
||||
## 💡 Best Practices: Test-Driven ML Engineering
|
||||
|
||||
### 🔄 During Active Development
|
||||
```bash
|
||||
# Continuous validation workflow
|
||||
tito test --module tensor # After implementing core functionality
|
||||
tito test --integration tensor # After module completion
|
||||
tito checkpoint test 01 # After achieving milestone
|
||||
```
|
||||
|
||||
**Development Testing Pattern:**
|
||||
1. **Write minimal test first**: Define expected behavior before implementation
|
||||
2. **Test each component**: Validate individual functions as you build them
|
||||
3. **Integration early**: Test module interactions frequently, not just at the end
|
||||
4. **Performance check**: Monitor memory and speed throughout development
|
||||
|
||||
### ✅ Before Code Commits
|
||||
```bash
|
||||
# Pre-commit validation checklist
|
||||
tito test --comprehensive # Full test suite passes
|
||||
tito system doctor # Environment is healthy
|
||||
tito checkpoint status # All achieved capabilities still work
|
||||
```
|
||||
|
||||
**Commit Readiness Criteria:**
|
||||
- ✅ All tests pass (100% health status)
|
||||
- ✅ No memory leaks detected in performance tests
|
||||
- ✅ Integration tests confirm module exports work
|
||||
- ✅ Checkpoint tests validate learning objectives met
|
||||
|
||||
### 🎯 Before Module Completion
|
||||
```bash
|
||||
# Module completion validation
|
||||
tito test --module mymodule --comprehensive
|
||||
tito test --integration --focus mymodule
|
||||
tito module validate mymodule
|
||||
tito module complete mymodule # Only after all tests pass
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting Guide
|
||||
|
||||
### 🚨 Common Test Failures & Solutions
|
||||
|
||||
#### Module Import Errors
|
||||
```bash
|
||||
# Problem: Module won't import
|
||||
❌ ModuleNotFoundError: No module named 'tinytorch.core.tensor'
|
||||
|
||||
# Solution: Check module export
|
||||
tito module complete tensor # Ensure module is properly exported
|
||||
tito system doctor # Verify Python path and virtual environment
|
||||
```
|
||||
|
||||
#### Mathematical Correctness Failures
|
||||
```bash
|
||||
# Problem: Your implementation doesn't match reference
|
||||
❌ AssertionError: Expected 0.5, got 0.48 (tolerance: 0.01)
|
||||
|
||||
# Debug process:
|
||||
tito test --module tensor --debug # Get detailed failure info
|
||||
python -c "import tinytorch; help(tinytorch.tensor)" # Check implementation
|
||||
```
|
||||
|
||||
#### Memory Usage Issues
|
||||
```bash
|
||||
# Problem: Memory tests failing
|
||||
❌ Memory usage: 150MB (expected: <100MB)
|
||||
|
||||
# Investigation:
|
||||
tito test --memory --profile tensor # Get memory profile
|
||||
tito test --scaling --module tensor # Check scaling behavior
|
||||
```
|
||||
|
||||
#### Integration Test Failures
|
||||
```bash
|
||||
# Problem: Modules don't work together
|
||||
❌ Integration test: tensor→autograd failed
|
||||
|
||||
# Debugging approach:
|
||||
tito test --integration --focus autograd --verbose
|
||||
tito test --exports tensor # Check tensor exports correctly
|
||||
tito test --imports autograd # Check autograd imports correctly
|
||||
```
|
||||
|
||||
### 🔍 Advanced Debugging Techniques
|
||||
|
||||
#### Verbose Test Output
|
||||
```bash
|
||||
# Get detailed test information
|
||||
tito test --module attention --verbose --debug
|
||||
|
||||
# See exact error locations
|
||||
tito test --traceback --module training
|
||||
```
|
||||
|
||||
#### Performance Profiling
|
||||
```bash
|
||||
# Memory usage analysis
|
||||
tito test --memory --profile --module spatial
|
||||
|
||||
# Speed profiling
|
||||
tito test --speed --profile --module training --iterations 100
|
||||
```
|
||||
|
||||
#### Environment Validation
|
||||
```bash
|
||||
# Complete environment check
|
||||
tito system doctor --comprehensive
|
||||
|
||||
# Specific dependency verification
|
||||
tito system check-dependencies --module autograd
|
||||
```
|
||||
|
||||
### 📋 Test Failure Decision Tree
|
||||
|
||||
```
|
||||
Test Failed?
|
||||
├── Import Error?
|
||||
│ ├── Run `tito system doctor`
|
||||
│ └── Check virtual environment activation
|
||||
├── Mathematical Error?
|
||||
│ ├── Compare with reference implementation
|
||||
│ └── Check tensor shapes and dtypes
|
||||
├── Memory Error?
|
||||
│ ├── Profile memory usage patterns
|
||||
│ └── Check for memory leaks in loops
|
||||
├── Integration Error?
|
||||
│ ├── Test modules individually first
|
||||
│ └── Verify export/import chain
|
||||
└── Performance Error?
|
||||
├── Profile bottlenecks
|
||||
└── Check algorithmic complexity
|
||||
```
|
||||
|
||||
## 🎯 Testing Philosophy: Building Reliable ML Systems
|
||||
|
||||
The TinyTorch testing framework embodies professional ML engineering principles:
|
||||
|
||||
### 🧩 KISS Principle in Testing
|
||||
- **Consistent patterns**: Every module follows identical testing structure - learn once, apply everywhere
|
||||
- **Actionable feedback**: Tests provide specific error messages with exact fix suggestions
|
||||
- **Essential focus**: Tests validate critical functionality without unnecessary complexity
|
||||
|
||||
### 🔗 Systems Engineering Mindset
|
||||
- **Integration-first**: Tests verify components work together, not just in isolation
|
||||
- **Real-world validation**: Examples prove your code works on actual datasets (CIFAR-10, MNIST)
|
||||
- **Performance consciousness**: All tests include memory and speed awareness
|
||||
|
||||
### 📚 Educational Excellence
|
||||
- **Understanding verification**: Tests confirm you grasp concepts, not just syntax
|
||||
- **Progressive mastery**: Capabilities build systematically through checkpoint validation
|
||||
- **Immediate feedback**: Know instantly if your implementation meets professional standards
|
||||
|
||||
### 🚀 Production Readiness
|
||||
- **Professional standards**: Tests match industry-level validation practices
|
||||
- **Scalability validation**: Ensure your code works at realistic data sizes
|
||||
- **Reliability assurance**: Comprehensive testing prevents production failures
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Success Metrics
|
||||
|
||||
```{admonition} Testing Success
|
||||
:class: tip
|
||||
A well-tested TinyTorch implementation should achieve:
|
||||
- **100% test suite passing** - All functionality works correctly
|
||||
- **>95% memory efficiency** - Comparable to reference implementations
|
||||
- **Real dataset success** - MNIST 95%+, CIFAR-10 75%+ accuracy targets
|
||||
- **Clean integration** - All modules work together seamlessly
|
||||
```
|
||||
|
||||
**Remember**: TinyTorch testing doesn't just verify your code works - it confirms you understand ML systems engineering well enough to build production-ready implementations.
|
||||
|
||||
Your testing discipline here translates directly to building reliable ML systems in industry settings!
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
**Ready to start testing your implementations?**
|
||||
|
||||
```bash
|
||||
# Begin with comprehensive health check
|
||||
tito test --comprehensive
|
||||
|
||||
# Start building and testing your first module
|
||||
tito module complete 01_setup
|
||||
|
||||
# Track your testing progress
|
||||
tito checkpoint status
|
||||
```
|
||||
|
||||
**Testing Integration with Your Learning Path:**
|
||||
- See [Student Workflow](student-workflow.md) for how testing fits into the development cycle
|
||||
- **📖 See [Historical Milestones](chapters/milestones.md)** for how testing validates achievements
|
||||
|
||||
<div style="background: #e3f2fd; border: 2px solid #1976d2; padding: 1.5rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h4 style="margin: 0 0 1rem 0; color: #1565c0;">🎯 Testing Excellence = ML Systems Mastery</h4>
|
||||
<p style="margin: 0; color: #1976d2;">Every test you write and run builds the discipline needed for production ML engineering</p>
|
||||
</div>
|
||||
@@ -1,192 +0,0 @@
|
||||
# Essential TITO Commands
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: #495057;">Master the TinyTorch CLI in Minutes</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; color: #6c757d;">Everything you need to build ML systems efficiently</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: Complete command reference for the TITO CLI. Master the essential commands for development workflow, progress tracking, and system management.
|
||||
|
||||
## The Core Workflow
|
||||
|
||||
TinyTorch follows a simple three-step cycle: **Edit modules → Export to package → Validate with milestones**
|
||||
|
||||
**The essential command**: `tito module complete MODULE_NUMBER` - exports your code to the TinyTorch package.
|
||||
|
||||
See [Student Workflow](student-workflow.md) for the complete development cycle, best practices, and troubleshooting.
|
||||
|
||||
This page documents all available TITO commands. The checkpoint system (`tito checkpoint status`) is optional for progress tracking.
|
||||
|
||||
## Most Important Commands
|
||||
|
||||
The commands you'll use most often:
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr; gap: 1rem; margin: 2rem 0;">
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #1976d2;">Check Your Environment</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito system doctor</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Verify your setup is ready for development</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #d97706;">Export Module to Package (Essential)</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module complete 01</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Export your module to the TinyTorch package - use this after editing modules</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #15803d;">Track Your Progress (Optional)</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito checkpoint status</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">See which capabilities you've mastered (optional capability tracking)</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## Typical Development Session
|
||||
|
||||
Here's what a typical session looks like:
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**Edit modules:**
|
||||
```bash
|
||||
cd modules/source/03_layers
|
||||
jupyter lab 03_layers_dev.py
|
||||
# Make your implementation...
|
||||
```
|
||||
|
||||
**Export to package:**
|
||||
```bash
|
||||
# From repository root
|
||||
tito module complete 03
|
||||
```
|
||||
|
||||
**Validate with milestones:**
|
||||
```bash
|
||||
cd milestones/01_1957_perceptron
|
||||
python 01_rosenblatt_forward.py # Uses YOUR implementation!
|
||||
```
|
||||
|
||||
**Optional progress tracking:**
|
||||
```bash
|
||||
tito checkpoint status # See what you've completed
|
||||
```
|
||||
|
||||
See [Student Workflow](student-workflow.md) for complete development cycle details.
|
||||
|
||||
</div>
|
||||
|
||||
## Complete Command Reference
|
||||
|
||||
### System & Health
|
||||
<div style="background: #f8f9fa; padding: 1rem; border-radius: 0.25rem; margin: 1rem 0;">
|
||||
|
||||
**System Check**
|
||||
```bash
|
||||
tito system doctor
|
||||
```
|
||||
*Diagnose environment issues before they block you*
|
||||
|
||||
**System Info**
|
||||
```bash
|
||||
tito system info
|
||||
```
|
||||
*View configuration details*
|
||||
|
||||
</div>
|
||||
|
||||
### Module Management
|
||||
<div style="background: #f8f9fa; padding: 1rem; border-radius: 0.25rem; margin: 1rem 0;">
|
||||
|
||||
**Export Module to Package (Essential)**
|
||||
```bash
|
||||
tito module complete MODULE_NUMBER
|
||||
```
|
||||
*Export your implementation to the TinyTorch package - the key command in the workflow*
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
tito module complete 05 # Export Module 05 (Autograd)
|
||||
```
|
||||
|
||||
After exporting, your code is importable:
|
||||
```python
|
||||
from tinytorch.autograd import backward # YOUR implementation!
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Progress Tracking (Optional)
|
||||
<div style="background: #f8f9fa; padding: 1rem; border-radius: 0.25rem; margin: 1rem 0;">
|
||||
|
||||
**Capability Overview**
|
||||
```bash
|
||||
tito checkpoint status
|
||||
```
|
||||
*Quick view of your capabilities (optional tracking)*
|
||||
|
||||
**Detailed Progress**
|
||||
```bash
|
||||
tito checkpoint status --detailed
|
||||
```
|
||||
*Module-by-module breakdown*
|
||||
|
||||
**Visual Timeline**
|
||||
```bash
|
||||
tito checkpoint timeline
|
||||
```
|
||||
*See your learning journey in visual format*
|
||||
|
||||
**Test Specific Capability**
|
||||
```bash
|
||||
tito checkpoint test CHECKPOINT_NUMBER
|
||||
```
|
||||
*Verify you've mastered a specific capability*
|
||||
|
||||
</div>
|
||||
|
||||
## Instructor Commands (Coming Soon)
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1rem; border-radius: 0.25rem; margin: 1rem 0;">
|
||||
|
||||
TinyTorch includes NBGrader integration for classroom use. Full documentation for instructor workflows (assignment generation, autograding, etc.) will be available in future releases.
|
||||
|
||||
**For now, focus on the student workflow**: edit modules → export → validate with milestones.
|
||||
|
||||
*For current instructor capabilities, see [Classroom Use Guide](usage-paths/classroom-use.md)*
|
||||
|
||||
</div>
|
||||
|
||||
## Troubleshooting Commands
|
||||
|
||||
When things go wrong, these commands help:
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border: 1px solid #fed7d7; border-radius: 0.5rem; margin: 1rem 0;">
|
||||
|
||||
**Environment Issues:**
|
||||
```bash
|
||||
tito system doctor # Diagnose problems
|
||||
tito system info # Show configuration details
|
||||
```
|
||||
|
||||
**Progress Tracking (Optional):**
|
||||
```bash
|
||||
tito checkpoint status --detailed # See exactly where you are
|
||||
tito checkpoint timeline # Visualize your progress
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Ready to Build?
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Start Your TinyTorch Journey</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">Follow the 2-minute setup and begin building ML systems from scratch</p>
|
||||
<a href="quickstart-guide.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">2-Minute Setup →</a>
|
||||
<a href="student-workflow.html" style="display: inline-block; background: #28a745; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Student Workflow →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
*Master these commands and you'll build ML systems with confidence. Every command is designed to accelerate your learning and keep you focused on what matters: building production-quality ML frameworks from scratch.*
|
||||
581
site/tito/data.md
Normal file
581
site/tito/data.md
Normal file
@@ -0,0 +1,581 @@
|
||||
# Progress & Data Management
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: #495057;">Track Your Journey</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; color: #6c757d;">Understanding progress tracking, data management, and reset commands</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: Learn how TinyTorch tracks your progress, where your data lives, and how to manage it effectively.
|
||||
|
||||
## Your Learning Journey: Two Tracking Systems
|
||||
|
||||
TinyTorch uses a clean, simple approach to track your ML systems engineering journey:
|
||||
|
||||
```{mermaid}
|
||||
graph LR
|
||||
A[Build Modules] --> B[Complete 01-20]
|
||||
B --> C[Export to Package]
|
||||
C --> D[Unlock Milestones]
|
||||
D --> E[Achieve 1957-2018]
|
||||
E --> F[Track Progress]
|
||||
|
||||
style A fill:#e3f2fd
|
||||
style B fill:#fffbeb
|
||||
style C fill:#f0fdf4
|
||||
style D fill:#fef3c7
|
||||
style E fill:#f3e5f5
|
||||
style F fill:#e8eaf6
|
||||
```
|
||||
|
||||
### The Two Systems
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; margin: 2rem 0;">
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #1976d2;">📦 Module Progress</h4>
|
||||
<p style="margin: 0.5rem 0; font-size: 0.95rem; color: #37474f;">What you BUILD (01-20)</p>
|
||||
<ul style="margin: 0.5rem 0 0 0; padding-left: 1.5rem; font-size: 0.9rem; color: #546e7a;">
|
||||
<li>Tensor, Autograd, Optimizers</li>
|
||||
<li>Layers, Training, DataLoader</li>
|
||||
<li>Convolutions, Transformers</li>
|
||||
<li>Your complete ML framework</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #7b1fa2;">🏆 Milestone Achievements</h4>
|
||||
<p style="margin: 0.5rem 0; font-size: 0.95rem; color: #37474f;">What you ACHIEVE (01-06)</p>
|
||||
<ul style="margin: 0.5rem 0 0 0; padding-left: 1.5rem; font-size: 0.9rem; color: #546e7a;">
|
||||
<li>Perceptron (1957)</li>
|
||||
<li>MLP Revival (1986)</li>
|
||||
<li>CNN Revolution (1998)</li>
|
||||
<li>AlexNet Era (2012)</li>
|
||||
<li>Transformer Era (2017)</li>
|
||||
<li>MLPerf (2018)</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
**Simple relationship**:
|
||||
- Complete modules → Unlock milestones → Achieve historical ML recreations
|
||||
- Build capabilities → Validate with history → Track achievements
|
||||
|
||||
---
|
||||
|
||||
## Where Your Data Lives
|
||||
|
||||
All your progress is stored in the `.tito/` folder:
|
||||
|
||||
```
|
||||
TinyTorch/
|
||||
├── .tito/ ← Your progress data
|
||||
│ ├── config.json ← User preferences
|
||||
│ ├── progress.json ← Module completion (01-20)
|
||||
│ ├── milestones.json ← Milestone achievements (01-06)
|
||||
│ └── backups/ ← Automatic safety backups
|
||||
│ ├── 01_tensor_YYYYMMDD_HHMMSS.py
|
||||
│ ├── 02_activations_YYYYMMDD_HHMMSS.py
|
||||
│ └── ...
|
||||
├── modules/ ← Where you edit
|
||||
├── tinytorch/ ← Where code exports
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Understanding Each File
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**`config.json`** - User Preferences
|
||||
```json
|
||||
{
|
||||
"logo_theme": "standard"
|
||||
}
|
||||
```
|
||||
- UI preferences
|
||||
- Display settings
|
||||
- Personal configuration
|
||||
|
||||
**`progress.json`** - Module Completion
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"completed_modules": [1, 2, 3, 4, 5, 6, 7],
|
||||
"completion_dates": {
|
||||
"1": "2025-11-16T10:00:00",
|
||||
"2": "2025-11-16T11:00:00",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
- Tracks which modules (01-20) you've completed
|
||||
- Records when you completed each
|
||||
- Updated by `tito module complete XX`
|
||||
|
||||
**`milestones.json`** - Milestone Achievements
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"completed_milestones": ["03"],
|
||||
"completion_dates": {
|
||||
"03": "2025-11-16T15:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Tracks which milestones (01-06) you've achieved
|
||||
- Records when you achieved each
|
||||
- Updated by `tito milestone run XX`
|
||||
|
||||
**`backups/`** - Module Backups
|
||||
- Automatic backups before operations
|
||||
- Timestamped copies of your work
|
||||
- Safety net for module development
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Unified Progress View
|
||||
|
||||
### See Everything: `tito status`
|
||||
|
||||
<div style="background: #e8eaf6; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #5e35b1; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito status
|
||||
```
|
||||
|
||||
**Shows your complete learning journey in one view**:
|
||||
|
||||
```
|
||||
╭─────────────── 📊 TinyTorch Progress ────────────────╮
|
||||
│ │
|
||||
│ 📦 Modules Completed: 7/20 (35%) │
|
||||
│ 🏆 Milestones Achieved: 1/6 (17%) │
|
||||
│ 📍 Last Activity: Module 07 (2 hours ago) │
|
||||
│ │
|
||||
│ Next Steps: │
|
||||
│ • Complete modules 08-09 to unlock Milestone 04 │
|
||||
│ │
|
||||
╰──────────────────────────────────────────────────────╯
|
||||
|
||||
Module Progress:
|
||||
✅ 01 Tensor
|
||||
✅ 02 Activations
|
||||
✅ 03 Layers
|
||||
✅ 04 Losses
|
||||
✅ 05 Autograd
|
||||
✅ 06 Optimizers
|
||||
✅ 07 Training
|
||||
🔒 08 DataLoader
|
||||
🔒 09 Convolutions
|
||||
🔒 10 Normalization
|
||||
...
|
||||
|
||||
Milestone Achievements:
|
||||
✅ 03 - MLP Revival (1986)
|
||||
🎯 04 - CNN Revolution (1998) [Ready after modules 08-09]
|
||||
🔒 05 - Transformer Era (2017)
|
||||
🔒 06 - MLPerf (2018)
|
||||
```
|
||||
|
||||
**Use this to**:
|
||||
- Check overall progress
|
||||
- See next recommended steps
|
||||
- Understand milestone prerequisites
|
||||
- Track your learning journey
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Data Management Commands
|
||||
|
||||
### Reset Your Progress
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Starting fresh?** Reset commands let you start over cleanly.
|
||||
|
||||
#### Reset Everything
|
||||
|
||||
```bash
|
||||
tito reset all
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Clears all module completion
|
||||
- Clears all milestone achievements
|
||||
- Resets configuration to defaults
|
||||
- Keeps your code in `modules/` safe
|
||||
- Asks for confirmation before proceeding
|
||||
|
||||
**Example output**:
|
||||
```
|
||||
⚠️ Warning: This will reset ALL progress
|
||||
|
||||
This will clear:
|
||||
• Module completion (7 modules)
|
||||
• Milestone achievements (1 milestone)
|
||||
• Configuration settings
|
||||
|
||||
Your code in modules/ will NOT be deleted.
|
||||
|
||||
Continue? [y/N]: y
|
||||
|
||||
✅ Creating backup at .tito_backup_20251116_143000/
|
||||
✅ Clearing module progress
|
||||
✅ Clearing milestone achievements
|
||||
✅ Resetting configuration
|
||||
|
||||
🔄 Reset Complete!
|
||||
|
||||
You're ready to start fresh.
|
||||
Run: tito module start 01
|
||||
```
|
||||
|
||||
#### Reset Module Progress Only
|
||||
|
||||
```bash
|
||||
tito reset progress
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Clears module completion tracking only
|
||||
- Keeps milestone achievements
|
||||
- Keeps configuration
|
||||
- Useful for re-doing module workflow
|
||||
|
||||
#### Reset Milestone Achievements Only
|
||||
|
||||
```bash
|
||||
tito reset milestones
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Clears milestone achievements only
|
||||
- Keeps module completion
|
||||
- Keeps configuration
|
||||
- Useful for re-running historical recreations
|
||||
|
||||
#### Safety: Automatic Backups
|
||||
|
||||
```bash
|
||||
# Create backup before reset
|
||||
tito reset all --backup
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Creates timestamped backup: `.tito_backup_YYYYMMDD_HHMMSS/`
|
||||
- Contains complete copy of `.tito/` folder
|
||||
- Allows manual restore if needed
|
||||
- Automatic before any destructive operation
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Data Safety & Recovery
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
TinyTorch automatically backs up your work:
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e; margin: 1.5rem 0;">
|
||||
|
||||
**When backups happen**:
|
||||
1. **Before module start**: Backs up existing work
|
||||
2. **Before reset**: Creates full `.tito/` backup
|
||||
3. **Before module reset**: Saves current implementation
|
||||
|
||||
**Where backups go**:
|
||||
```
|
||||
.tito/backups/
|
||||
├── 01_tensor_20251116_100000.py
|
||||
├── 01_tensor_20251116_143000.py
|
||||
├── 03_layers_20251115_180000.py
|
||||
└── ...
|
||||
```
|
||||
|
||||
**How to use backups**:
|
||||
```bash
|
||||
# Backups are timestamped - find the one you need
|
||||
ls -la .tito/backups/
|
||||
|
||||
# Manually restore if needed
|
||||
cp .tito/backups/03_layers_20251115_180000.py modules/03_layers/layers_dev.py
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### What If .tito/ Is Deleted?
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
**No problem!** TinyTorch recovers gracefully:
|
||||
|
||||
```bash
|
||||
# If .tito/ is deleted, next command recreates it
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. TinyTorch detects missing `.tito/` folder
|
||||
2. Creates fresh folder structure
|
||||
3. Initializes empty progress tracking
|
||||
4. Your code in `modules/` and `tinytorch/` is safe
|
||||
5. You can continue from where you left off
|
||||
|
||||
**Important**: Your actual code (in `modules/` and `tinytorch/`) is separate from progress tracking (in `.tito/`). Deleting `.tito/` only resets progress tracking, not your implementations.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Data Health Checks
|
||||
|
||||
### Verify Data Integrity
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
**Now includes data health checks**:
|
||||
|
||||
```
|
||||
╭────────── 🔍 TinyTorch System Check ──────────╮
|
||||
│ │
|
||||
│ ✅ Environment setup │
|
||||
│ ✅ Dependencies installed │
|
||||
│ ✅ TinyTorch in development mode │
|
||||
│ ✅ Data files intact │
|
||||
│ ✓ .tito/progress.json valid │
|
||||
│ ✓ .tito/milestones.json valid │
|
||||
│ ✓ .tito/config.json valid │
|
||||
│ ✅ Backups directory exists │
|
||||
│ │
|
||||
╰───────────────────────────────────────────────╯
|
||||
|
||||
All systems ready! 🚀
|
||||
```
|
||||
|
||||
**If data is corrupted**:
|
||||
```
|
||||
❌ Data files corrupted
|
||||
✗ .tito/progress.json is malformed
|
||||
|
||||
Fix:
|
||||
tito reset progress
|
||||
|
||||
Or restore from backup:
|
||||
cp .tito_backup_YYYYMMDD/.tito/progress.json .tito/
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Progress Checks
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**Good habits**:
|
||||
|
||||
1. **Check status regularly**:
|
||||
```bash
|
||||
tito status
|
||||
```
|
||||
See where you are, what's next
|
||||
|
||||
2. **Verify environment before work**:
|
||||
```bash
|
||||
tito system doctor
|
||||
```
|
||||
Catch issues early
|
||||
|
||||
3. **Let automatic backups work**:
|
||||
- Don't disable them
|
||||
- They're your safety net
|
||||
- Cleanup happens automatically
|
||||
|
||||
4. **Backup before experiments**:
|
||||
```bash
|
||||
tito reset all --backup # If trying something risky
|
||||
```
|
||||
|
||||
5. **Version control for code**:
|
||||
```bash
|
||||
git commit -m "Completed Module 05: Autograd"
|
||||
```
|
||||
`.tito/` is gitignored - use git for code versions
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Understanding What Gets Tracked
|
||||
|
||||
### Modules (Build Progress)
|
||||
|
||||
**Tracked when**: You run `tito module complete XX`
|
||||
|
||||
**What's recorded**:
|
||||
- Module number (1-20)
|
||||
- Completion timestamp
|
||||
- Test results (passed/failed)
|
||||
|
||||
**Visible in**:
|
||||
- `tito module status`
|
||||
- `tito status`
|
||||
- `.tito/progress.json`
|
||||
|
||||
### Milestones (Achievement Progress)
|
||||
|
||||
**Tracked when**: You run `tito milestone run XX`
|
||||
|
||||
**What's recorded**:
|
||||
- Milestone ID (01-06)
|
||||
- Achievement timestamp
|
||||
- Number of attempts (if multiple runs)
|
||||
|
||||
**Visible in**:
|
||||
- `tito milestone status`
|
||||
- `tito status`
|
||||
- `.tito/milestones.json`
|
||||
|
||||
### What's NOT Tracked
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
**TinyTorch does NOT track**:
|
||||
- Your actual code implementations (those live in `modules/` and `tinytorch/`)
|
||||
- How long you spent on each module
|
||||
- How many times you edited files
|
||||
- Your test scores or grades
|
||||
- Personal information
|
||||
- Usage analytics
|
||||
|
||||
**Why**: TinyTorch is a local, offline learning tool. Your privacy is protected. All data stays on your machine.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Common Data Scenarios
|
||||
|
||||
### Scenario 1: "I want to start completely fresh"
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
# Create backup first (recommended)
|
||||
tito reset all --backup
|
||||
|
||||
# Or just reset
|
||||
tito reset all
|
||||
|
||||
# Start from Module 01
|
||||
tito module start 01
|
||||
```
|
||||
|
||||
**Result**: Clean slate, progress tracking reset, code in `modules/` untouched
|
||||
|
||||
</div>
|
||||
|
||||
### Scenario 2: "I want to re-run milestones but keep module progress"
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
# Reset only milestone achievements
|
||||
tito reset milestones
|
||||
|
||||
# Re-run historical recreations
|
||||
tito milestone run 03
|
||||
tito milestone run 04
|
||||
```
|
||||
|
||||
**Result**: Module completion preserved, milestone achievements reset
|
||||
|
||||
</div>
|
||||
|
||||
### Scenario 3: "I accidentally deleted .tito/"
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
# Just run any tito command
|
||||
tito system doctor
|
||||
|
||||
# OR
|
||||
|
||||
# If you have a backup
|
||||
cp -r .tito_backup_YYYYMMDD/ .tito/
|
||||
```
|
||||
|
||||
**Result**: `.tito/` folder recreated, either fresh or from backup
|
||||
|
||||
</div>
|
||||
|
||||
### Scenario 4: "I want to share my progress with a friend"
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
# Create backup with timestamp
|
||||
tito reset all --backup # (then cancel when prompted)
|
||||
|
||||
# Share the backup folder
|
||||
cp -r .tito_backup_YYYYMMDD/ ~/Desktop/my-tinytorch-progress/
|
||||
```
|
||||
|
||||
**Result**: Friend can see your progress by copying to their `.tito/` folder
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Will resetting delete my code?
|
||||
|
||||
**A**: No! Reset commands only affect progress tracking in `.tito/`. Your implementations in `modules/` and exported code in `tinytorch/` are never touched.
|
||||
|
||||
### Q: Can I manually edit progress.json?
|
||||
|
||||
**A**: Yes, but not recommended. Use `tito` commands instead. Manual edits might break validation.
|
||||
|
||||
### Q: What if I want to re-export a module?
|
||||
|
||||
**A**: Just run `tito module complete XX` again. It will re-run tests and re-export. Progress tracking remains unchanged.
|
||||
|
||||
### Q: How do I see my completion dates?
|
||||
|
||||
**A**: Run `tito status` for a formatted view, or check `.tito/progress.json` and `.tito/milestones.json` directly.
|
||||
|
||||
### Q: Can I delete backups?
|
||||
|
||||
**A**: Yes, backups in `.tito/backups/` can be deleted manually. They're safety nets, not requirements.
|
||||
|
||||
### Q: Is my data shared anywhere?
|
||||
|
||||
**A**: No. TinyTorch is completely local. No data leaves your machine. No tracking, no analytics, no cloud sync.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Keep Building!</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">Now that you understand data management, focus on what matters: building ML systems</p>
|
||||
<a href="modules.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">Module Workflow →</a>
|
||||
<a href="milestones.html" style="display: inline-block; background: #9c27b0; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Milestone System →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
*Your progress is tracked, your data is safe, and your journey is yours. TinyTorch keeps track of what you've built and achieved - you focus on learning ML systems engineering.*
|
||||
449
site/tito/milestones.md
Normal file
449
site/tito/milestones.md
Normal file
@@ -0,0 +1,449 @@
|
||||
# Milestone System
|
||||
|
||||
<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center; color: white;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: white;">Recreate ML History with YOUR Code</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; opacity: 0.95;">Run the algorithms that changed the world using the TinyTorch you built from scratch</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: The milestone system lets you run famous ML algorithms (1957-2018) using YOUR implementations. Every milestone validates that your code can recreate a historical breakthrough.
|
||||
|
||||
See [Historical Milestones](chapters/milestones.md) for the full historical context and significance of each milestone.
|
||||
|
||||
## What Are Milestones?
|
||||
|
||||
Milestones are **runnable recreations of historical ML papers** that use YOUR TinyTorch implementations:
|
||||
|
||||
- **1957 - Rosenblatt's Perceptron**: The first trainable neural network
|
||||
- **1969 - XOR Solution**: Solving the problem that stalled AI
|
||||
- **1986 - Backpropagation**: The MLP revival (Rumelhart, Hinton & Williams)
|
||||
- **1998 - LeNet**: Yann LeCun's CNN breakthrough
|
||||
- **2017 - Transformer**: "Attention is All You Need" (Vaswani et al.)
|
||||
- **2018 - MLPerf**: Production ML benchmarks
|
||||
|
||||
Each milestone script imports **YOUR code** from the TinyTorch package you built.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**Typical workflow:**
|
||||
|
||||
```bash
|
||||
# 1. Build the required modules (e.g., Foundation Tier for Milestone 03)
|
||||
tito module complete 01 # Tensor
|
||||
tito module complete 02 # Activations
|
||||
tito module complete 03 # Layers
|
||||
tito module complete 04 # Losses
|
||||
tito module complete 05 # Autograd
|
||||
tito module complete 06 # Optimizers
|
||||
tito module complete 07 # Training
|
||||
|
||||
# 2. See what milestones you can run
|
||||
tito milestone list
|
||||
|
||||
# 3. Get details about a specific milestone
|
||||
tito milestone info 03
|
||||
|
||||
# 4. Run it!
|
||||
tito milestone run 03
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Discover Milestones
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1rem 0;">
|
||||
|
||||
**List All Milestones**
|
||||
```bash
|
||||
tito milestone list
|
||||
```
|
||||
|
||||
Shows all 6 historical milestones with status:
|
||||
- 🔒 **LOCKED** - Need to complete required modules first
|
||||
- 🎯 **READY TO RUN** - All prerequisites met!
|
||||
- ✅ **COMPLETE** - You've already achieved this
|
||||
|
||||
**Simple View** (compact list):
|
||||
```bash
|
||||
tito milestone list --simple
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Learn About Milestones
|
||||
|
||||
<div style="background: #fff3e0; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #ff9800; margin: 1rem 0;">
|
||||
|
||||
**Get Detailed Information**
|
||||
```bash
|
||||
tito milestone info 03
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Historical context (year, researchers, significance)
|
||||
- Description of what you'll recreate
|
||||
- Required modules with ✓/✗ status
|
||||
- Whether you're ready to run it
|
||||
|
||||
</div>
|
||||
|
||||
### Run Milestones
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0; margin: 1rem 0;">
|
||||
|
||||
**Run a Milestone**
|
||||
```bash
|
||||
tito milestone run 03
|
||||
```
|
||||
|
||||
What happens:
|
||||
1. **Checks prerequisites** - Validates required modules are complete
|
||||
2. **Tests imports** - Ensures YOUR implementations work
|
||||
3. **Shows context** - Historical background and what you'll recreate
|
||||
4. **Runs the script** - Executes the milestone using YOUR code
|
||||
5. **Tracks achievement** - Records your completion
|
||||
6. **Celebrates!** - Shows achievement message 🏆
|
||||
|
||||
**Skip prerequisite checks** (not recommended):
|
||||
```bash
|
||||
tito milestone run 03 --skip-checks
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Track Progress
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e; margin: 1rem 0;">
|
||||
|
||||
**View Milestone Progress**
|
||||
```bash
|
||||
tito milestone status
|
||||
```
|
||||
|
||||
Shows:
|
||||
- How many milestones you've completed
|
||||
- Your overall progress (%)
|
||||
- Unlocked capabilities
|
||||
- Next milestone ready to run
|
||||
|
||||
**Visual Timeline**
|
||||
```bash
|
||||
tito milestone timeline
|
||||
```
|
||||
|
||||
See your journey through ML history in a visual tree format.
|
||||
|
||||
</div>
|
||||
|
||||
## The 6 Milestones
|
||||
|
||||
### Milestone 01: Perceptron (1957) 🧠
|
||||
|
||||
**What**: Frank Rosenblatt's first trainable neural network
|
||||
|
||||
**Requires**: Module 01 (Tensor)
|
||||
|
||||
**What you'll do**: Implement and train the perceptron that proved machines could learn
|
||||
|
||||
**Historical significance**: First demonstration of machine learning
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 01
|
||||
tito milestone run 01
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Milestone 02: XOR Crisis (1969) 🔀
|
||||
|
||||
**What**: Solving the problem that stalled AI research
|
||||
|
||||
**Requires**: Modules 01-02 (Tensor, Activations)
|
||||
|
||||
**What you'll do**: Use multi-layer networks to solve XOR - impossible for single-layer perceptrons
|
||||
|
||||
**Historical significance**: Minsky & Papert showed perceptron limitations; this shows how to overcome them
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 02
|
||||
tito milestone run 02
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Milestone 03: MLP Revival (1986) 🎓
|
||||
|
||||
**What**: Backpropagation breakthrough - train deep networks on MNIST
|
||||
|
||||
**Requires**: Modules 01-07 (Complete Foundation Tier)
|
||||
|
||||
**What you'll do**: Train a multi-layer perceptron to recognize handwritten digits (95%+ accuracy)
|
||||
|
||||
**Historical significance**: Rumelhart, Hinton & Williams (Nature, 1986) - the paper that reignited neural network research
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 03
|
||||
tito milestone run 03
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Milestone 04: CNN Revolution (1998) 👁️
|
||||
|
||||
**What**: LeNet - Computer Vision Breakthrough
|
||||
|
||||
**Requires**: Modules 01-09 (Foundation + Spatial/Convolutions)
|
||||
|
||||
**What you'll do**: Build LeNet for digit recognition using convolutional layers
|
||||
|
||||
**Historical significance**: Yann LeCun's breakthrough that enabled modern computer vision
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 04
|
||||
tito milestone run 04
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Milestone 05: Transformer Era (2017) 🤖
|
||||
|
||||
**What**: "Attention is All You Need"
|
||||
|
||||
**Requires**: Modules 01-13 (Foundation + Architecture Tiers)
|
||||
|
||||
**What you'll do**: Implement transformer architecture with self-attention mechanism
|
||||
|
||||
**Historical significance**: Vaswani et al. revolutionized NLP and enabled GPT/BERT/modern LLMs
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 05
|
||||
tito milestone run 05
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Milestone 06: MLPerf Benchmarks (2018) 🏆
|
||||
|
||||
**What**: Production ML Systems
|
||||
|
||||
**Requires**: Modules 01-19 (Foundation + Architecture + Optimization Tiers)
|
||||
|
||||
**What you'll do**: Optimize for production deployment with quantization, compression, and benchmarking
|
||||
|
||||
**Historical significance**: MLPerf standardized ML system benchmarks for real-world deployment
|
||||
|
||||
**Run it**:
|
||||
```bash
|
||||
tito milestone info 06
|
||||
tito milestone run 06
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites and Validation
|
||||
|
||||
### How Prerequisites Work
|
||||
|
||||
Each milestone requires specific modules to be complete. The `run` command automatically validates:
|
||||
|
||||
**Module Completion Check**:
|
||||
```bash
|
||||
tito milestone run 03
|
||||
|
||||
🔍 Checking prerequisites for Milestone 03...
|
||||
✓ Module 01 - complete
|
||||
✓ Module 02 - complete
|
||||
✓ Module 03 - complete
|
||||
✓ Module 04 - complete
|
||||
✓ Module 05 - complete
|
||||
✓ Module 06 - complete
|
||||
✓ Module 07 - complete
|
||||
|
||||
✅ All prerequisites met!
|
||||
```
|
||||
|
||||
**Import Validation**:
|
||||
```bash
|
||||
🧪 Testing YOUR implementations...
|
||||
✓ Tensor import successful
|
||||
✓ Activations import successful
|
||||
✓ Layers import successful
|
||||
|
||||
✅ YOUR TinyTorch is ready!
|
||||
```
|
||||
|
||||
### If Prerequisites Are Missing
|
||||
|
||||
You'll see a helpful error:
|
||||
|
||||
```bash
|
||||
❌ Missing Required Modules
|
||||
|
||||
Milestone 03 requires modules: 01, 02, 03, 04, 05, 06, 07
|
||||
Missing: 05, 06, 07
|
||||
|
||||
Complete the missing modules first:
|
||||
tito module start 05
|
||||
tito module start 06
|
||||
tito module start 07
|
||||
```
|
||||
|
||||
## Achievement Celebration
|
||||
|
||||
When you successfully complete a milestone, you'll see:
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════════════╗
|
||||
║ 🎓 Milestone 03: MLP Revival (1986) ║
|
||||
║ Backpropagation Breakthrough ║
|
||||
╚════════════════════════════════════════════════╝
|
||||
|
||||
🏆 MILESTONE ACHIEVED!
|
||||
|
||||
You completed Milestone 03: MLP Revival (1986)
|
||||
Backpropagation Breakthrough
|
||||
|
||||
What makes this special:
|
||||
• Every line of code: YOUR implementations
|
||||
• Every tensor operation: YOUR Tensor class
|
||||
• Every gradient: YOUR autograd
|
||||
|
||||
Achievement saved to your progress!
|
||||
|
||||
🎯 What's Next:
|
||||
Milestone 04: CNN Revolution (1998)
|
||||
Unlock by completing modules: 08, 09
|
||||
```
|
||||
|
||||
## Understanding Your Progress
|
||||
|
||||
### Three Tracking Systems
|
||||
|
||||
TinyTorch tracks progress in three ways (all are related but distinct):
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border-radius: 0.5rem; margin: 1rem 0;">
|
||||
|
||||
**1. Module Completion** (`tito module status`)
|
||||
- Which modules (01-20) you've implemented
|
||||
- Tracked in `.tito/progress.json`
|
||||
- **Required** for running milestones
|
||||
|
||||
**2. Milestone Achievements** (`tito milestone status`)
|
||||
- Which historical papers you've recreated
|
||||
- Tracked in `.tito/milestones.json`
|
||||
- Unlocked by completing modules + running milestones
|
||||
|
||||
**3. Capability Checkpoints** (`tito checkpoint status`) - OPTIONAL
|
||||
- Gamified capability tracking
|
||||
- Tracked in `.tito/checkpoints.json`
|
||||
- Purely motivational; can be disabled
|
||||
|
||||
</div>
|
||||
|
||||
### Relationship Between Systems
|
||||
|
||||
```
|
||||
Complete Modules (01-07)
|
||||
↓
|
||||
Unlock Milestone 03
|
||||
↓
|
||||
Run: tito milestone run 03
|
||||
↓
|
||||
Achievement Recorded
|
||||
↓
|
||||
Capability Unlocked (optional checkpoint system)
|
||||
```
|
||||
|
||||
## Tips for Success
|
||||
|
||||
### 1. Complete Modules in Order
|
||||
|
||||
While you can technically skip around, the tier structure is designed for progressive learning:
|
||||
|
||||
- **Foundation Tier (01-07)**: Required for first milestone
|
||||
- **Architecture Tier (08-13)**: Build on Foundation
|
||||
- **Optimization Tier (14-19)**: Build on Architecture
|
||||
|
||||
### 2. Test as You Go
|
||||
|
||||
Before running a milestone, make sure your modules work:
|
||||
|
||||
```bash
|
||||
# After completing a module
|
||||
tito module complete 05
|
||||
|
||||
# Test it works
|
||||
python -c "from tinytorch import Tensor; print(Tensor([[1,2]]))"
|
||||
```
|
||||
|
||||
### 3. Use Info Before Run
|
||||
|
||||
Learn what you're about to do:
|
||||
|
||||
```bash
|
||||
tito milestone info 03 # Read the context first
|
||||
tito milestone run 03 # Then run it
|
||||
```
|
||||
|
||||
### 4. Celebrate Achievements
|
||||
|
||||
Share your milestones! Each one represents recreating a breakthrough that shaped modern AI.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Import Error" when running milestone
|
||||
|
||||
**Problem**: Module not exported or import failing
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Re-export the module
|
||||
tito module complete XX
|
||||
|
||||
# Test import manually
|
||||
python -c "from tinytorch import Tensor"
|
||||
```
|
||||
|
||||
### "Prerequisites Not Met" but I completed modules
|
||||
|
||||
**Problem**: Progress not tracked correctly
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check module status
|
||||
tito module status
|
||||
|
||||
# If modules show incomplete, re-run complete
|
||||
tito module complete XX
|
||||
```
|
||||
|
||||
### Milestone script fails during execution
|
||||
|
||||
**Problem**: Bug in your implementation
|
||||
|
||||
**Solution**:
|
||||
1. Check error message for which module failed
|
||||
2. Edit `modules/source/XX_name/` (NOT `tinytorch/`)
|
||||
3. Re-export: `tito module complete XX`
|
||||
4. Run milestone again
|
||||
|
||||
## Next Steps
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Ready to Recreate ML History?</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">Start with the Foundation Tier and work toward your first milestone</p>
|
||||
<a href="tiers/foundation.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">Foundation Tier →</a>
|
||||
<a href="chapters/milestones.html" style="display: inline-block; background: #6f42c1; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Historical Context →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
*Every milestone uses YOUR code. Every achievement is proof you understand ML systems deeply. Build from scratch, recreate history, master the fundamentals.*
|
||||
461
site/tito/modules.md
Normal file
461
site/tito/modules.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# Module Workflow
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: #495057;">Build ML Systems from Scratch</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; color: #6c757d;">The core workflow for implementing and exporting TinyTorch modules</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: Master the module development workflow - the heart of TinyTorch. Learn how to implement modules, export them to your package, and validate with tests.
|
||||
|
||||
## The Core Workflow
|
||||
|
||||
TinyTorch follows a simple build-export-validate cycle:
|
||||
|
||||
```{mermaid}
|
||||
graph LR
|
||||
A[Start/Resume Module] --> B[Edit in Jupyter]
|
||||
B --> C[Complete & Export]
|
||||
C --> D[Test Import]
|
||||
D --> E[Next Module]
|
||||
|
||||
style A fill:#e3f2fd
|
||||
style B fill:#fffbeb
|
||||
style C fill:#f0fdf4
|
||||
style D fill:#fef3c7
|
||||
style E fill:#f3e5f5
|
||||
```
|
||||
|
||||
**The essential command**: `tito module complete XX` - exports your code to the TinyTorch package
|
||||
|
||||
See [Student Workflow](../student-workflow.md) for the complete development cycle and best practices.
|
||||
|
||||
---
|
||||
|
||||
## Essential Commands
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr; gap: 1rem; margin: 2rem 0;">
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #1976d2;">Check Environment</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito system doctor</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Verify your setup is ready before starting</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #d97706;">Start a Module (First Time)</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module start 01</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Opens Jupyter Lab for Module 01 (Tensor)</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #7b1fa2;">Resume Work (Continue Later)</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module resume 01</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Continue working on Module 01 where you left off</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #15803d;">Export & Complete (Essential)</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module complete 01</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Export Module 01 to TinyTorch package - THE key command</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #fef3c7; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #d97706;">Check Progress</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module status</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">See which modules you've completed</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Typical Development Session
|
||||
|
||||
Here's what a complete session looks like:
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**1. Start Session**
|
||||
```bash
|
||||
cd TinyTorch
|
||||
source activate.sh
|
||||
tito system doctor # Verify environment
|
||||
```
|
||||
|
||||
**2. Start or Resume Module**
|
||||
```bash
|
||||
# First time working on Module 03
|
||||
tito module start 03
|
||||
|
||||
# OR: Continue from where you left off
|
||||
tito module resume 03
|
||||
```
|
||||
|
||||
This opens Jupyter Lab with the module notebook.
|
||||
|
||||
**3. Edit in Jupyter Lab**
|
||||
```python
|
||||
# In modules/03_layers/layers_dev.py
|
||||
class Linear:
|
||||
def __init__(self, in_features, out_features):
|
||||
# YOUR implementation here
|
||||
...
|
||||
```
|
||||
|
||||
Work interactively:
|
||||
- Implement the required functionality
|
||||
- Add docstrings and comments
|
||||
- Run and test your code inline
|
||||
- See immediate feedback
|
||||
|
||||
**4. Export to Package**
|
||||
```bash
|
||||
# From repository root
|
||||
tito module complete 03
|
||||
```
|
||||
|
||||
This command:
|
||||
- Runs tests on your implementation
|
||||
- Exports code to `tinytorch/nn/layers.py`
|
||||
- Makes your code importable
|
||||
- Tracks completion
|
||||
|
||||
**5. Test Your Implementation**
|
||||
```bash
|
||||
# Your code is now in the package!
|
||||
python -c "from tinytorch import Linear; print(Linear(10, 5))"
|
||||
```
|
||||
|
||||
**6. Check Progress**
|
||||
```bash
|
||||
tito module status
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## System Commands
|
||||
|
||||
### Environment Health
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1.5rem 0;">
|
||||
|
||||
**Check Setup (Run This First)**
|
||||
```bash
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
Verifies:
|
||||
- Virtual environment activated
|
||||
- Dependencies installed (NumPy, Jupyter, Rich)
|
||||
- TinyTorch in development mode
|
||||
- All systems ready
|
||||
|
||||
**Output**:
|
||||
```
|
||||
✅ Environment validation passed
|
||||
• Virtual environment: Active
|
||||
• Dependencies: NumPy, Jupyter, Rich installed
|
||||
• TinyTorch: Development mode
|
||||
```
|
||||
|
||||
**System Information**
|
||||
```bash
|
||||
tito system info
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Python version
|
||||
- Environment paths
|
||||
- Package versions
|
||||
- Configuration settings
|
||||
|
||||
**Start Jupyter Lab**
|
||||
```bash
|
||||
tito system jupyter
|
||||
```
|
||||
|
||||
Convenience command to launch Jupyter Lab from the correct directory.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Module Lifecycle Commands
|
||||
|
||||
### Start a Module (First Time)
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito module start 01
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
1. Opens Jupyter Lab for Module 01 (Tensor)
|
||||
2. Shows module README and learning objectives
|
||||
3. Provides clean starting point
|
||||
4. Creates backup of any existing work
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
tito module start 05 # Start Module 05 (Autograd)
|
||||
```
|
||||
|
||||
Jupyter Lab opens with `modules/05_autograd/autograd_dev.py`
|
||||
|
||||
</div>
|
||||
|
||||
### Resume Work (Continue Later)
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito module resume 01
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
1. Opens Jupyter Lab with your previous work
|
||||
2. Preserves all your changes
|
||||
3. Shows where you left off
|
||||
4. No backup created (you're continuing)
|
||||
|
||||
**Use this when**: Coming back to a module you started earlier
|
||||
|
||||
</div>
|
||||
|
||||
### Complete & Export (Essential)
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito module complete 01
|
||||
```
|
||||
|
||||
**THE KEY COMMAND** - This is what makes your code real!
|
||||
|
||||
**What this does**:
|
||||
1. **Tests** your implementation (inline tests)
|
||||
2. **Exports** to `tinytorch/` package
|
||||
3. **Tracks** completion in `.tito/progress.json`
|
||||
4. **Validates** NBGrader metadata
|
||||
5. **Makes read-only** exported files (protection)
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
tito module complete 05 # Export Module 05 (Autograd)
|
||||
```
|
||||
|
||||
**After exporting**:
|
||||
```python
|
||||
# YOUR code is now importable!
|
||||
from tinytorch.autograd import backward
|
||||
from tinytorch import Tensor
|
||||
|
||||
# Use YOUR implementations
|
||||
x = Tensor([[1.0, 2.0]], requires_grad=True)
|
||||
y = x * 2
|
||||
y.backward()
|
||||
print(x.grad) # Uses YOUR autograd!
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### View Progress
|
||||
|
||||
<div style="background: #fef3c7; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito module status
|
||||
```
|
||||
|
||||
**Shows**:
|
||||
- Which modules (01-20) you've completed
|
||||
- Completion dates
|
||||
- Next recommended module
|
||||
|
||||
**Example Output**:
|
||||
```
|
||||
📦 Module Progress
|
||||
|
||||
✅ Module 01: Tensor (completed 2025-11-16)
|
||||
✅ Module 02: Activations (completed 2025-11-16)
|
||||
✅ Module 03: Layers (completed 2025-11-16)
|
||||
🔒 Module 04: Losses (not started)
|
||||
🔒 Module 05: Autograd (not started)
|
||||
|
||||
Progress: 3/20 modules (15%)
|
||||
|
||||
Next: Complete Module 04 to continue Foundation Tier
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Reset Module (Advanced)
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
```bash
|
||||
tito module reset 01
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
1. Creates backup of current work
|
||||
2. Unexports from `tinytorch/` package
|
||||
3. Restores module to clean state
|
||||
4. Removes from completion tracking
|
||||
|
||||
**Use this when**: You want to start a module completely fresh
|
||||
|
||||
⚠️ **Warning**: This removes your implementation. Use with caution!
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Understanding the Export Process
|
||||
|
||||
When you run `tito module complete XX`, here's what happens:
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**Step 1: Validation**
|
||||
```
|
||||
✓ Checking NBGrader metadata
|
||||
✓ Validating Python syntax
|
||||
✓ Running inline tests
|
||||
```
|
||||
|
||||
**Step 2: Export**
|
||||
```
|
||||
✓ Converting modules/XX_name/name_dev.py
|
||||
→ tinytorch/path/name.py
|
||||
✓ Adding "DO NOT EDIT" warning
|
||||
✓ Making file read-only
|
||||
```
|
||||
|
||||
**Step 3: Tracking**
|
||||
```
|
||||
✓ Recording completion in .tito/progress.json
|
||||
✓ Updating module status
|
||||
```
|
||||
|
||||
**Step 4: Success**
|
||||
```
|
||||
🎉 Module XX complete!
|
||||
Your code is now part of TinyTorch!
|
||||
|
||||
Import with: from tinytorch import YourClass
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
|
||||
### Where You Edit
|
||||
|
||||
```
|
||||
modules/
|
||||
├── 01_tensor/
|
||||
│ └── tensor_dev.py ← YOU EDIT THIS
|
||||
├── 02_activations/
|
||||
│ └── activations_dev.py ← YOU EDIT THIS
|
||||
└── 03_layers/
|
||||
└── layers_dev.py ← YOU EDIT THIS
|
||||
```
|
||||
|
||||
### Where Code Exports
|
||||
|
||||
```
|
||||
tinytorch/
|
||||
├── core/
|
||||
│ └── tensor.py ← AUTO-GENERATED (DO NOT EDIT)
|
||||
├── nn/
|
||||
│ ├── activations.py ← AUTO-GENERATED (DO NOT EDIT)
|
||||
│ └── layers.py ← AUTO-GENERATED (DO NOT EDIT)
|
||||
└── ...
|
||||
```
|
||||
|
||||
**IMPORTANT**: Never edit files in `tinytorch/` directly!
|
||||
- They have "DO NOT EDIT" warnings
|
||||
- They're auto-generated from `modules/`
|
||||
- Changes will be lost on re-export
|
||||
- Always edit in `modules/` instead
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Environment Not Ready
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border: 1px solid #fed7d7; border-radius: 0.5rem; margin: 1rem 0;">
|
||||
|
||||
**Problem**: `tito system doctor` shows errors
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Re-run setup
|
||||
./setup-environment.sh
|
||||
source activate.sh
|
||||
|
||||
# Verify
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Export Fails
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border: 1px solid #fed7d7; border-radius: 0.5rem; margin: 1rem 0;">
|
||||
|
||||
**Problem**: `tito module complete XX` fails
|
||||
|
||||
**Common causes**:
|
||||
1. Syntax errors in your code
|
||||
2. Failing tests
|
||||
3. Missing required functions
|
||||
|
||||
**Solution**:
|
||||
1. Check error message for details
|
||||
2. Fix issues in `modules/XX_name/`
|
||||
3. Test in Jupyter Lab first
|
||||
4. Re-run `tito module complete XX`
|
||||
|
||||
</div>
|
||||
|
||||
### Import Errors
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border: 1px solid #fed7d7; border-radius: 0.5rem; margin: 1rem 0;">
|
||||
|
||||
**Problem**: `from tinytorch import X` fails
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Re-export the module
|
||||
tito module complete XX
|
||||
|
||||
# Test import
|
||||
python -c "from tinytorch import Tensor"
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
See [Troubleshooting Guide](troubleshooting.md) for more issues and solutions.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Ready to Build Your First Module?</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">Start with Module 01 (Tensor) and build the foundation of neural networks</p>
|
||||
<a href="../tiers/foundation.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">Foundation Tier →</a>
|
||||
<a href="milestones.html" style="display: inline-block; background: #9c27b0; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Milestone System →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
*The module workflow is the heart of TinyTorch. Master these commands and you'll build ML systems with confidence. Every line of code you write becomes part of a real, working framework.*
|
||||
223
site/tito/overview.md
Normal file
223
site/tito/overview.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# TITO Command Reference
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: #495057;">Master the TinyTorch CLI</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; color: #6c757d;">Complete command reference for building ML systems efficiently</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: Quick reference for all TITO commands. Find the right command for every task in your ML systems engineering journey.
|
||||
|
||||
## Quick Start: Three Commands You Need
|
||||
|
||||
<div style="display: grid; grid-template-columns: 1fr; gap: 1rem; margin: 2rem 0;">
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #1976d2;">1. Check Your Environment</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito system doctor</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Verify your setup is ready for development</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #d97706;">2. Build & Export Modules</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito module complete 01</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Export your module to the TinyTorch package</p>
|
||||
</div>
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0;">
|
||||
<h4 style="margin: 0 0 0.5rem 0; color: #7b1fa2;">3. Run Historical Milestones</h4>
|
||||
<code style="background: #263238; color: #ffffff; padding: 0.5rem; border-radius: 0.25rem; display: block; margin: 0.5rem 0;">tito milestone run 03</code>
|
||||
<p style="margin: 0.5rem 0 0 0; font-size: 0.9rem; color: #64748b;">Recreate ML history with YOUR code</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Complete Command Reference
|
||||
|
||||
### System Commands
|
||||
|
||||
**Purpose**: Environment health and configuration
|
||||
|
||||
| Command | Description | Guide |
|
||||
|---------|-------------|-------|
|
||||
| `tito system doctor` | Diagnose environment issues | [Module Workflow](modules.md) |
|
||||
| `tito system info` | Show system configuration | [Module Workflow](modules.md) |
|
||||
| `tito system jupyter` | Start Jupyter Lab server | [Module Workflow](modules.md) |
|
||||
|
||||
### Module Commands
|
||||
|
||||
**Purpose**: Build-from-scratch workflow (your main development cycle)
|
||||
|
||||
| Command | Description | Guide |
|
||||
|---------|-------------|-------|
|
||||
| `tito module start XX` | Begin working on a module (first time) | [Module Workflow](modules.md) |
|
||||
| `tito module resume XX` | Continue working on a module | [Module Workflow](modules.md) |
|
||||
| `tito module complete XX` | Test, export, and track module completion | [Module Workflow](modules.md) |
|
||||
| `tito module status` | View module completion progress | [Module Workflow](modules.md) |
|
||||
| `tito module reset XX` | Reset module to clean state | [Module Workflow](modules.md) |
|
||||
|
||||
**See**: [Module Workflow Guide](modules.md) for complete details
|
||||
|
||||
### Milestone Commands
|
||||
|
||||
**Purpose**: Run historical ML recreations with YOUR implementations
|
||||
|
||||
| Command | Description | Guide |
|
||||
|---------|-------------|-------|
|
||||
| `tito milestone list` | Show all 6 historical milestones (1957-2018) | [Milestone System](milestones.md) |
|
||||
| `tito milestone run XX` | Run milestone with prerequisite checking | [Milestone System](milestones.md) |
|
||||
| `tito milestone info XX` | Get detailed milestone information | [Milestone System](milestones.md) |
|
||||
| `tito milestone status` | View milestone progress and achievements | [Milestone System](milestones.md) |
|
||||
| `tito milestone timeline` | Visual timeline of your journey | [Milestone System](milestones.md) |
|
||||
|
||||
**See**: [Milestone System Guide](milestones.md) for complete details
|
||||
|
||||
### Progress & Data Commands
|
||||
|
||||
**Purpose**: Track progress and manage user data
|
||||
|
||||
| Command | Description | Guide |
|
||||
|---------|-------------|-------|
|
||||
| `tito status` | View all progress (modules + milestones) | [Progress & Data](data.md) |
|
||||
| `tito reset all` | Reset all progress and start fresh | [Progress & Data](data.md) |
|
||||
| `tito reset progress` | Reset module completion only | [Progress & Data](data.md) |
|
||||
| `tito reset milestones` | Reset milestone achievements only | [Progress & Data](data.md) |
|
||||
|
||||
**See**: [Progress & Data Management](data.md) for complete details
|
||||
|
||||
---
|
||||
|
||||
## Command Groups by Task
|
||||
|
||||
### First-Time Setup
|
||||
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone https://github.com/mlsysbook/TinyTorch.git
|
||||
cd TinyTorch
|
||||
./setup-environment.sh
|
||||
source activate.sh
|
||||
|
||||
# Verify environment
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
### Daily Development Workflow
|
||||
|
||||
```bash
|
||||
# Start or continue a module
|
||||
tito module start 01 # First time
|
||||
tito module resume 01 # Continue later
|
||||
|
||||
# Export when complete
|
||||
tito module complete 01
|
||||
|
||||
# Check progress
|
||||
tito module status
|
||||
```
|
||||
|
||||
### Achievement & Validation
|
||||
|
||||
```bash
|
||||
# See available milestones
|
||||
tito milestone list
|
||||
|
||||
# Get details
|
||||
tito milestone info 03
|
||||
|
||||
# Run milestone
|
||||
tito milestone run 03
|
||||
|
||||
# View achievements
|
||||
tito milestone status
|
||||
```
|
||||
|
||||
### Progress Management
|
||||
|
||||
```bash
|
||||
# View all progress
|
||||
tito status
|
||||
|
||||
# Reset if needed
|
||||
tito reset all --backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Typical Session Flow
|
||||
|
||||
Here's what a typical TinyTorch session looks like:
|
||||
|
||||
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">
|
||||
|
||||
**1. Start Session**
|
||||
```bash
|
||||
cd TinyTorch
|
||||
source activate.sh
|
||||
tito system doctor # Verify environment
|
||||
```
|
||||
|
||||
**2. Work on Module**
|
||||
```bash
|
||||
tito module start 03 # Or: tito module resume 03
|
||||
# Edit in Jupyter Lab...
|
||||
```
|
||||
|
||||
**3. Export & Test**
|
||||
```bash
|
||||
tito module complete 03
|
||||
```
|
||||
|
||||
**4. Run Milestone (when prerequisites met)**
|
||||
```bash
|
||||
tito milestone list # Check if ready
|
||||
tito milestone run 03 # Run with YOUR code
|
||||
```
|
||||
|
||||
**5. Track Progress**
|
||||
```bash
|
||||
tito status # See everything
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Command Help
|
||||
|
||||
Every command has detailed help text:
|
||||
|
||||
```bash
|
||||
# Top-level help
|
||||
tito --help
|
||||
|
||||
# Command group help
|
||||
tito module --help
|
||||
tito milestone --help
|
||||
|
||||
# Specific command help
|
||||
tito module complete --help
|
||||
tito milestone run --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Detailed Guides
|
||||
|
||||
- **[Module Workflow](modules.md)** - Complete guide to building and exporting modules
|
||||
- **[Milestone System](milestones.md)** - Running historical ML recreations
|
||||
- **[Progress & Data](data.md)** - Managing your learning journey
|
||||
- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **[Quick Start Guide](../quickstart-guide.md)** - 15-minute setup walkthrough
|
||||
- **[Student Workflow](../student-workflow.md)** - Day-to-day development cycle
|
||||
- **[Datasets Guide](../datasets.md)** - Understanding TinyTorch datasets
|
||||
|
||||
---
|
||||
|
||||
*Master these commands and you'll build ML systems with confidence. Every command is designed to accelerate your learning and keep you focused on what matters: building production-quality ML frameworks from scratch.*
|
||||
882
site/tito/troubleshooting.md
Normal file
882
site/tito/troubleshooting.md
Normal file
@@ -0,0 +1,882 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h2 style="margin: 0 0 1rem 0; color: #495057;">Common Issues & Solutions</h2>
|
||||
<p style="margin: 0; font-size: 1.1rem; color: #6c757d;">Quick fixes for the most common TinyTorch problems</p>
|
||||
</div>
|
||||
|
||||
**Purpose**: Fast solutions to common issues. Get unstuck and back to building ML systems quickly.
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnostic: Start Here
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1.5rem 0;">
|
||||
|
||||
**First step for ANY issue**:
|
||||
|
||||
```bash
|
||||
cd TinyTorch
|
||||
source activate.sh
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
This checks:
|
||||
- ✅ Virtual environment activated
|
||||
- ✅ Dependencies installed (NumPy, Jupyter, Rich)
|
||||
- ✅ TinyTorch in development mode
|
||||
- ✅ Data files intact
|
||||
- ✅ All systems ready
|
||||
|
||||
**If doctor shows errors**: Follow the specific fixes below.
|
||||
|
||||
**If doctor shows all green**: Your environment is fine - issue is elsewhere.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Environment Issues
|
||||
|
||||
### Problem: "tito: command not found"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module start 01
|
||||
-bash: tito: command not found
|
||||
```
|
||||
|
||||
**Cause**: Virtual environment not activated or TinyTorch not installed in development mode.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# 1. Activate environment
|
||||
cd TinyTorch
|
||||
source activate.sh
|
||||
|
||||
# 2. Verify activation
|
||||
which python # Should show TinyTorch/venv/bin/python
|
||||
|
||||
# 3. Re-install TinyTorch in development mode
|
||||
pip install -e .
|
||||
|
||||
# 4. Test
|
||||
tito --help
|
||||
```
|
||||
|
||||
**Prevention**: Always run `source activate.sh` before working.
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "No module named 'tinytorch'"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```python
|
||||
>>> from tinytorch import Tensor
|
||||
ModuleNotFoundError: No module named 'tinytorch'
|
||||
```
|
||||
|
||||
**Cause**: TinyTorch not installed in development mode, or wrong Python interpreter.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# 1. Verify you're in the right directory
|
||||
pwd # Should end with /TinyTorch
|
||||
|
||||
# 2. Activate environment
|
||||
source activate.sh
|
||||
|
||||
# 3. Install in development mode
|
||||
pip install -e .
|
||||
|
||||
# 4. Verify installation
|
||||
pip show tinytorch
|
||||
python -c "import tinytorch; print(tinytorch.__file__)"
|
||||
```
|
||||
|
||||
**Expected output**:
|
||||
```
|
||||
/Users/YourName/TinyTorch/tinytorch/__init__.py
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Virtual environment issues after setup"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ source activate.sh
|
||||
# No (venv) prefix appears, or wrong Python version
|
||||
```
|
||||
|
||||
**Cause**: Virtual environment not created properly or corrupted.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# 1. Remove old virtual environment
|
||||
rm -rf venv/
|
||||
|
||||
# 2. Re-run setup
|
||||
./setup-environment.sh
|
||||
|
||||
# 3. Activate
|
||||
source activate.sh
|
||||
|
||||
# 4. Verify
|
||||
python --version # Should be 3.8+
|
||||
which pip # Should show TinyTorch/venv/bin/pip
|
||||
```
|
||||
|
||||
**Expected**: `(venv)` prefix appears in terminal prompt.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Module Issues
|
||||
|
||||
### Problem: "Module export fails"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module complete 03
|
||||
❌ Export failed: SyntaxError in modules/03_layers/layers_dev.py
|
||||
```
|
||||
|
||||
**Causes**:
|
||||
1. Python syntax errors in your code
|
||||
2. Missing required functions
|
||||
3. NBGrader metadata issues
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Check syntax**:
|
||||
```bash
|
||||
# Test Python syntax directly
|
||||
python -m py_compile modules/03_layers/layers_dev.py
|
||||
```
|
||||
|
||||
**Step 2: Open in Jupyter and test**:
|
||||
```bash
|
||||
tito module resume 03
|
||||
# In Jupyter: Run all cells, check for errors
|
||||
```
|
||||
|
||||
**Step 3: Fix errors shown in output**
|
||||
|
||||
**Step 4: Re-export**:
|
||||
```bash
|
||||
tito module complete 03
|
||||
```
|
||||
|
||||
**Common syntax errors**:
|
||||
- Missing `:` after function/class definitions
|
||||
- Incorrect indentation (use 4 spaces, not tabs)
|
||||
- Unclosed parentheses or brackets
|
||||
- Missing `return` statements
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Tests fail during export"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module complete 05
|
||||
Running tests...
|
||||
❌ Test failed: test_backward_simple
|
||||
```
|
||||
|
||||
**Cause**: Your implementation doesn't match expected behavior.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: See test details**:
|
||||
```bash
|
||||
# Tests are in the module file - look for cells marked "TEST"
|
||||
tito module resume 05
|
||||
# In Jupyter: Find test cells, run them individually
|
||||
```
|
||||
|
||||
**Step 2: Debug your implementation**:
|
||||
```python
|
||||
# Add print statements to see what's happening
|
||||
def backward(self):
|
||||
print(f"Debug: self.grad = {self.grad}")
|
||||
# ... your implementation
|
||||
```
|
||||
|
||||
**Step 3: Compare with expected behavior**:
|
||||
- Read test assertions carefully
|
||||
- Check edge cases (empty tensors, zero values)
|
||||
- Verify shapes and types
|
||||
|
||||
**Step 4: Fix and re-export**:
|
||||
```bash
|
||||
tito module complete 05
|
||||
```
|
||||
|
||||
**Tip**: Run tests interactively in Jupyter before exporting.
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Jupyter Lab won't start"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module start 01
|
||||
# Jupyter Lab fails to launch or shows errors
|
||||
```
|
||||
|
||||
**Cause**: Jupyter not installed or port already in use.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Verify Jupyter installation**:
|
||||
```bash
|
||||
pip install jupyter jupyterlab jupytext
|
||||
```
|
||||
|
||||
**Step 2: Check for port conflicts**:
|
||||
```bash
|
||||
# Kill any existing Jupyter instances
|
||||
pkill -f jupyter
|
||||
|
||||
# Or try a different port
|
||||
jupyter lab --port=8889 modules/01_tensor/
|
||||
```
|
||||
|
||||
**Step 3: Clear Jupyter cache**:
|
||||
```bash
|
||||
jupyter lab clean
|
||||
```
|
||||
|
||||
**Step 4: Restart**:
|
||||
```bash
|
||||
tito module start 01
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Changes in Jupyter don't save"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**: Edit in Jupyter Lab, but `modules/XX_name/name_dev.py` doesn't change.
|
||||
|
||||
**Cause**: Jupytext sync issues or file permissions.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Manual save**:
|
||||
```
|
||||
In Jupyter Lab:
|
||||
File → Save File (or Cmd/Ctrl + S)
|
||||
```
|
||||
|
||||
**Step 2: Check file permissions**:
|
||||
```bash
|
||||
ls -la modules/01_tensor/tensor_dev.py
|
||||
# Should be writable (not read-only)
|
||||
```
|
||||
|
||||
**Step 3: If read-only, fix permissions**:
|
||||
```bash
|
||||
chmod u+w modules/01_tensor/tensor_dev.py
|
||||
```
|
||||
|
||||
**Step 4: Verify changes**:
|
||||
```bash
|
||||
cat modules/01_tensor/tensor_dev.py | head -20
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Import Issues
|
||||
|
||||
### Problem: "Cannot import from tinytorch after export"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```python
|
||||
>>> from tinytorch import Linear
|
||||
ImportError: cannot import name 'Linear' from 'tinytorch'
|
||||
```
|
||||
|
||||
**Cause**: Module not exported yet, or export didn't update `__init__.py`.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Verify module completed**:
|
||||
```bash
|
||||
tito module status
|
||||
# Check if module shows as ✅ completed
|
||||
```
|
||||
|
||||
**Step 2: Check exported file exists**:
|
||||
```bash
|
||||
ls -la tinytorch/nn/layers.py
|
||||
# File should exist and have recent timestamp
|
||||
```
|
||||
|
||||
**Step 3: Re-export**:
|
||||
```bash
|
||||
tito module complete 03
|
||||
```
|
||||
|
||||
**Step 4: Test import**:
|
||||
```python
|
||||
python -c "from tinytorch.nn import Linear; print(Linear)"
|
||||
```
|
||||
|
||||
**Note**: Use full import path initially, then check if `from tinytorch import Linear` works (requires `__init__.py` update).
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Circular import errors"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```python
|
||||
>>> from tinytorch import Tensor
|
||||
ImportError: cannot import name 'Tensor' from partially initialized module 'tinytorch'
|
||||
```
|
||||
|
||||
**Cause**: Circular dependency in your imports.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Check your import structure**:
|
||||
```python
|
||||
# In modules/XX_name/name_dev.py
|
||||
# DON'T import from tinytorch in module development files
|
||||
# DO import from dependencies only
|
||||
```
|
||||
|
||||
**Step 2: Use local imports if needed**:
|
||||
```python
|
||||
# Inside functions, not at module level
|
||||
def some_function():
|
||||
from tinytorch.core import Tensor # Local import
|
||||
...
|
||||
```
|
||||
|
||||
**Step 3: Re-export**:
|
||||
```bash
|
||||
tito module complete XX
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Milestone Issues
|
||||
|
||||
### Problem: "Milestone says prerequisites not met"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito milestone run 04
|
||||
❌ Prerequisites not met
|
||||
Missing modules: 08, 09
|
||||
```
|
||||
|
||||
**Cause**: You haven't completed required modules yet.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Check requirements**:
|
||||
```bash
|
||||
tito milestone info 04
|
||||
# Shows which modules are required
|
||||
```
|
||||
|
||||
**Step 2: Complete required modules**:
|
||||
```bash
|
||||
tito module status # See what's completed
|
||||
tito module start 08 # Complete missing modules
|
||||
# ... implement and export
|
||||
tito module complete 08
|
||||
```
|
||||
|
||||
**Step 3: Try milestone again**:
|
||||
```bash
|
||||
tito milestone run 04
|
||||
```
|
||||
|
||||
**Tip**: Milestones unlock progressively. Complete modules in order (01 → 20) for best experience.
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Milestone fails with import errors"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito milestone run 03
|
||||
Running: MLP Revival (1986)
|
||||
ImportError: cannot import name 'ReLU' from 'tinytorch'
|
||||
```
|
||||
|
||||
**Cause**: Required module not exported properly.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Check which import failed**:
|
||||
```
|
||||
# Error message shows: 'ReLU' from 'tinytorch'
|
||||
# This is from Module 02 (Activations)
|
||||
```
|
||||
|
||||
**Step 2: Re-export that module**:
|
||||
```bash
|
||||
tito module complete 02
|
||||
```
|
||||
|
||||
**Step 3: Test import manually**:
|
||||
```python
|
||||
python -c "from tinytorch import ReLU; print(ReLU)"
|
||||
```
|
||||
|
||||
**Step 4: Run milestone again**:
|
||||
```bash
|
||||
tito milestone run 03
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Milestone runs but shows errors"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito milestone run 03
|
||||
Running: MLP Revival (1986)
|
||||
# Script runs but shows runtime errors or wrong output
|
||||
```
|
||||
|
||||
**Cause**: Your implementation has bugs (not syntax errors, but logic errors).
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Run milestone script manually**:
|
||||
```bash
|
||||
python milestones/03_1986_mlp/03_mlp_mnist_train.py
|
||||
# See full error output
|
||||
```
|
||||
|
||||
**Step 2: Debug the specific module**:
|
||||
```bash
|
||||
# If error is in ReLU, for example
|
||||
tito module resume 02
|
||||
# Fix implementation in Jupyter
|
||||
```
|
||||
|
||||
**Step 3: Re-export**:
|
||||
```bash
|
||||
tito module complete 02
|
||||
```
|
||||
|
||||
**Step 4: Test milestone again**:
|
||||
```bash
|
||||
tito milestone run 03
|
||||
```
|
||||
|
||||
**Tip**: Milestones test your implementations in realistic scenarios. They help find edge cases you might have missed.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Data & Progress Issues
|
||||
|
||||
### Problem: ".tito folder deleted or corrupted"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module status
|
||||
Error: .tito/progress.json not found
|
||||
```
|
||||
|
||||
**Cause**: `.tito/` folder deleted or progress file corrupted.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Option 1: Let TinyTorch recreate it (fresh start)**:
|
||||
```bash
|
||||
tito system doctor
|
||||
# Recreates .tito/ structure with empty progress
|
||||
```
|
||||
|
||||
**Option 2: Restore from backup (if you have one)**:
|
||||
```bash
|
||||
# Check for backups
|
||||
ls -la .tito_backup_*/
|
||||
|
||||
# Restore from latest backup
|
||||
cp -r .tito_backup_20251116_143000/ .tito/
|
||||
```
|
||||
|
||||
**Option 3: Manual recreation**:
|
||||
```bash
|
||||
mkdir -p .tito/backups
|
||||
echo '{"version":"1.0","completed_modules":[],"completion_dates":{}}' > .tito/progress.json
|
||||
echo '{"version":"1.0","completed_milestones":[],"completion_dates":{}}' > .tito/milestones.json
|
||||
echo '{"logo_theme":"standard"}' > .tito/config.json
|
||||
```
|
||||
|
||||
**Important**: Your code in `modules/` and `tinytorch/` is safe. Only progress tracking is affected.
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Progress shows wrong modules completed"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ tito module status
|
||||
Shows modules as completed that you haven't done
|
||||
```
|
||||
|
||||
**Cause**: Accidentally ran `tito module complete XX` without implementing, or manual `.tito/progress.json` edit.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Option 1: Reset specific module**:
|
||||
```bash
|
||||
tito module reset 05
|
||||
# Clears completion for Module 05 only
|
||||
```
|
||||
|
||||
**Option 2: Reset all progress**:
|
||||
```bash
|
||||
tito reset progress
|
||||
# Clears all module completion
|
||||
```
|
||||
|
||||
**Option 3: Manually edit `.tito/progress.json`**:
|
||||
```bash
|
||||
# Open in editor
|
||||
nano .tito/progress.json
|
||||
|
||||
# Remove the module number from "completed_modules" array
|
||||
# Remove the entry from "completion_dates" object
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Dependency Issues
|
||||
|
||||
### Problem: "NumPy import errors"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```python
|
||||
>>> import numpy as np
|
||||
ImportError: No module named 'numpy'
|
||||
```
|
||||
|
||||
**Cause**: Dependencies not installed in virtual environment.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Activate environment
|
||||
source activate.sh
|
||||
|
||||
# Install dependencies
|
||||
pip install numpy jupyter jupyterlab jupytext rich
|
||||
|
||||
# Verify
|
||||
python -c "import numpy; print(numpy.__version__)"
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Rich formatting doesn't work"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**: TITO output is plain text instead of colorful panels.
|
||||
|
||||
**Cause**: Rich library not installed or terminal doesn't support colors.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**Step 1: Install Rich**:
|
||||
```bash
|
||||
pip install rich
|
||||
```
|
||||
|
||||
**Step 2: Use color-capable terminal**:
|
||||
- macOS: Terminal.app, iTerm2
|
||||
- Linux: GNOME Terminal, Konsole
|
||||
- Windows: Windows Terminal, PowerShell
|
||||
|
||||
**Step 3: Test**:
|
||||
```bash
|
||||
python -c "from rich import print; print('[bold green]Test[/bold green]')"
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Problem: "Jupyter Lab is slow"
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
**Solutions**:
|
||||
|
||||
**1. Close unused notebooks**:
|
||||
```
|
||||
In Jupyter Lab:
|
||||
Right-click notebook tab → Close
|
||||
File → Shut Down All Kernels
|
||||
```
|
||||
|
||||
**2. Clear output cells**:
|
||||
```
|
||||
In Jupyter Lab:
|
||||
Edit → Clear All Outputs
|
||||
```
|
||||
|
||||
**3. Restart kernel**:
|
||||
```
|
||||
Kernel → Restart Kernel
|
||||
```
|
||||
|
||||
**4. Increase memory** (if working with large datasets):
|
||||
```bash
|
||||
# Check memory usage
|
||||
top
|
||||
# Close other applications if needed
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Problem: "Export takes a long time"
|
||||
|
||||
<div style="background: #fffbeb; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #f59e0b; margin: 1.5rem 0;">
|
||||
|
||||
**Cause**: Tests running on large data or complex operations.
|
||||
|
||||
**Solution**:
|
||||
|
||||
**This is normal for**:
|
||||
- Modules with extensive tests
|
||||
- Operations involving training loops
|
||||
- Large tensor operations
|
||||
|
||||
**If export hangs**:
|
||||
```bash
|
||||
# Cancel with Ctrl+C
|
||||
# Check for infinite loops in your code
|
||||
# Simplify tests temporarily, then re-export
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Issues
|
||||
|
||||
### macOS: "Permission denied"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Symptom**:
|
||||
```bash
|
||||
$ ./setup-environment.sh
|
||||
Permission denied
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
chmod +x setup-environment.sh activate.sh
|
||||
./setup-environment.sh
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Windows: "activate.sh not working"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Solution**: Use Windows-specific activation:
|
||||
```bash
|
||||
# PowerShell
|
||||
.\venv\Scripts\Activate.ps1
|
||||
|
||||
# Command Prompt
|
||||
.\venv\Scripts\activate.bat
|
||||
|
||||
# Git Bash
|
||||
source venv/Scripts/activate
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Linux: "Python version issues"
|
||||
|
||||
<div style="background: #fff5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #e74c3c; margin: 1.5rem 0;">
|
||||
|
||||
**Solution**: Specify Python 3.8+ explicitly:
|
||||
```bash
|
||||
python3.8 -m venv venv
|
||||
source activate.sh
|
||||
python --version # Verify
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Getting More Help
|
||||
|
||||
### Debug Mode
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1.5rem 0;">
|
||||
|
||||
**Run commands with verbose output**:
|
||||
```bash
|
||||
# Most TITO commands support --verbose
|
||||
tito module complete 03 --verbose
|
||||
|
||||
# See detailed error traces
|
||||
python -m pdb milestones/03_1986_mlp/03_mlp_mnist_train.py
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Check Logs
|
||||
|
||||
<div style="background: #e3f2fd; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #2196f3; margin: 1.5rem 0;">
|
||||
|
||||
**Jupyter Lab logs**:
|
||||
```bash
|
||||
# Check Jupyter output in terminal where you ran tito module start
|
||||
# Look for error messages, warnings
|
||||
```
|
||||
|
||||
**Python traceback**:
|
||||
```bash
|
||||
# Full error context
|
||||
python -c "from tinytorch import Tensor" 2>&1 | less
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Community Support
|
||||
|
||||
<div style="background: #f3e5f5; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #9c27b0; margin: 1.5rem 0;">
|
||||
|
||||
**GitHub Issues**: Report bugs or ask questions
|
||||
- Repository: [mlsysbook/TinyTorch](https://github.com/mlsysbook/TinyTorch)
|
||||
- Search existing issues first
|
||||
- Include error messages and OS details
|
||||
|
||||
**Documentation**: Check other guides
|
||||
- [Module Workflow](modules.md)
|
||||
- [Milestone System](milestones.md)
|
||||
- [Progress & Data](data.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Prevention: Best Practices
|
||||
|
||||
<div style="background: #f0fdf4; padding: 1.5rem; border-radius: 0.5rem; border-left: 4px solid #22c55e; margin: 1.5rem 0;">
|
||||
|
||||
**Avoid issues before they happen**:
|
||||
|
||||
1. **Always activate environment first**:
|
||||
```bash
|
||||
source activate.sh
|
||||
```
|
||||
|
||||
2. **Run `tito system doctor` regularly**:
|
||||
```bash
|
||||
tito system doctor
|
||||
```
|
||||
|
||||
3. **Test in Jupyter before exporting**:
|
||||
```bash
|
||||
# Run all cells, verify output
|
||||
# THEN run tito module complete
|
||||
```
|
||||
|
||||
4. **Keep backups** (automatic):
|
||||
```bash
|
||||
# Backups happen automatically
|
||||
# Don't delete .tito/backups/ unless needed
|
||||
```
|
||||
|
||||
5. **Use git for your code**:
|
||||
```bash
|
||||
git commit -m "Working Module 05 implementation"
|
||||
```
|
||||
|
||||
6. **Read error messages carefully**:
|
||||
- They usually tell you exactly what's wrong
|
||||
- Pay attention to file paths and line numbers
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Fixing Common Errors
|
||||
|
||||
| Error Message | Quick Fix |
|
||||
|--------------|-----------|
|
||||
| `tito: command not found` | `source activate.sh` |
|
||||
| `ModuleNotFoundError: tinytorch` | `pip install -e .` |
|
||||
| `SyntaxError` in export | Fix Python syntax, test in Jupyter first |
|
||||
| `ImportError` in milestone | Re-export required modules |
|
||||
| `.tito/progress.json not found` | `tito system doctor` to recreate |
|
||||
| `Jupyter Lab won't start` | `pkill -f jupyter && tito module start XX` |
|
||||
| `Permission denied` | `chmod +x setup-environment.sh activate.sh` |
|
||||
| `Tests fail` during export | Debug in Jupyter, check test assertions |
|
||||
| `Prerequisites not met` | `tito milestone info XX` to see requirements |
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
<div style="background: #f8f9fa; padding: 2rem; border-radius: 0.5rem; margin: 2rem 0; text-align: center;">
|
||||
<h3 style="margin: 0 0 1rem 0; color: #495057;">Need More Help?</h3>
|
||||
<p style="margin: 0 0 1.5rem 0; color: #6c757d;">Try these resources for additional support</p>
|
||||
<a href="https://github.com/mlsysbook/TinyTorch/issues" style="display: inline-block; background: #28a745; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500; margin-right: 1rem;">Report Issue →</a>
|
||||
<a href="overview.html" style="display: inline-block; background: #007bff; color: white; padding: 0.75rem 1.5rem; border-radius: 0.25rem; text-decoration: none; font-weight: 500;">Command Reference →</a>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
*Most issues have simple fixes. Start with `tito system doctor`, read error messages carefully, and remember: your code is always safe in `modules/` - only progress tracking can be reset.*
|
||||
Reference in New Issue
Block a user