TinyTorch/book/instructor-guide.md

👨‍🏫 Instructor Guide: NBGrader + TinyTorch

Complete workflow for instructors and TAs using TinyTorch with automated grading

---

🎯 The Complete Instructor Journey

This guide walks you through everything you need to know to successfully run a TinyTorch course with automated grading, from initial setup to semester completion.

---

📋 Prerequisites

Before you begin, ensure you have:

• Python 3.8+ installed on your system
• Git for version control
• Terminal/Command Line access
• Basic familiarity with Jupyter notebooks

Time Investment: ~30 minutes for initial setup, then 5-10 minutes per assignment

---

🚀 Phase 1: Initial Setup (One-Time)

Step 1: Clone and Setup Repository

# Clone the TinyTorch repository
git clone https://github.com/your-org/TinyTorch.git
cd TinyTorch

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install all dependencies
pip install -r requirements.txt
pip install nbgrader jupyter jupytext rich

Step 2: Verify Installation

# Test that everything is working
./bin/tito system doctor

# Expected output:
# ✅ Python 3.x.x
# ✅ Virtual environment active
# ✅ All dependencies installed
# ✅ TinyTorch CLI ready

Step 3: Initialize NBGrader Environment

# Initialize the grading infrastructure
./bin/tito nbgrader init

# Expected output:
# ✅ NBGrader version: 0.9.5
# 📁 Created directory: assignments
# ✅ NBGrader database initialized
# 🎉 NBGrader environment initialized successfully!

Step 4: Verify Complete Setup

# Check system status
./bin/tito module status --comprehensive

# Should show:
# 🐍 Environment Health: All ✅ green
# 📊 Module Status: Overview of 17 modules
# 🎯 Priority Actions: Any setup issues to fix

---

🎓 Phase 2: Course Preparation

Understanding the TinyTorch Module Structure

TinyTorch has 17 progressive modules:

Foundation (Modules 00-02):

• 00_introduction - Visual system overview and dependencies
• 01_setup - Development environment and CLI workflow
• 02_tensor - Multi-dimensional arrays and operations

Building Blocks (Modules 03-07):

• 03_activations - Mathematical functions and nonlinearity
• 04_layers - Neural network layer abstractions
• 05_dense - Fully connected layers and matrix operations
• 06_spatial - Convolutional operations and computer vision
• 07_attention - Self-attention and transformer mechanisms

Training Systems (Modules 08-11):

• 08_dataloader - Data pipeline and CIFAR-10 integration
• 09_autograd - Automatic differentiation engine
• 10_optimizers - SGD, Adam, and learning rate scheduling
• 11_training - Training loops, loss functions, and metrics

Production & Performance (Modules 12-16):

• 12_compression - Model pruning and quantization
• 13_kernels - Custom operations and hardware optimization
• 14_benchmarking - MLPerf-style evaluation and profiling
• 15_mlops - Production deployment and monitoring
• 16_capstone - Final integration project

Course Planning Recommendations

📅 Semester Planning (14-16 weeks):

Week 1: 00_introduction + 01_setup
Week 2: 02_tensor  
Week 3: 03_activations
Week 4: 04_layers
Week 5: 05_dense
Week 6: 06_spatial
Week 7: 07_attention
Week 8: Midterm / Review
Week 9: 08_dataloader
Week 10: 09_autograd
Week 11: 10_optimizers  
Week 12: 11_training
Week 13: 12_compression + 13_kernels
Week 14: 14_benchmarking + 15_mlops
Week 15: 16_capstone
Week 16: Final presentations

---

📝 Phase 3: Assignment Management

Creating Student Assignments

For Individual Modules:

# Generate assignment from TinyTorch module
./bin/tito nbgrader generate 01_setup

# This creates:
# assignments/source/01_setup/01_setup.ipynb (instructor version)

For Multiple Modules:

# Generate first 4 modules
./bin/tito nbgrader generate --range 01-04

# Or generate all modules at once (start of semester)
./bin/tito nbgrader generate --all

What happens during generation:

1. Reads the module's .py file from modules/source/XX_module/
2. Converts to Jupyter notebook using jupytext
3. Processes with NBGrader to create student version
4. Removes instructor solutions, adds # YOUR CODE HERE stubs
5. Creates assignments in assignments/source/XX_module/

Releasing Assignments to Students

# Release individual assignment
./bin/tito nbgrader release 01_setup

# Release multiple assignments
./bin/tito nbgrader release --range 01-04

# This creates:
# assignments/release/01_setup/01_setup.ipynb (student version)

Distribution to Students:

• Upload assignments/release/XX_module/XX_module.ipynb to your LMS
• Or provide direct access to the assignments/release/ directory
• Students download and work on their local copies

Monitoring Assignment Status

# Check what assignments exist
./bin/tito nbgrader status

# Example output:
# 📚 Source assignments: 4
#   - 01_setup, 02_tensor, 03_activations, 04_layers
# 🚀 Released assignments: 2  
#   - 01_setup, 02_tensor
# 📥 Submitted assignments: 1
#   - 01_setup
# 🎯 Graded assignments: 0

---

📊 Phase 4: Grading Workflow

Collecting Student Submissions

Manual Collection (Most Common):

# Students submit via LMS, you download to:
mkdir -p assignments/submitted/01_setup/student_name/
# Place student notebooks in: assignments/submitted/01_setup/student_name/01_setup.ipynb

NBGrader Exchange (If Using Shared Server):

# Collect all submissions for an assignment
./bin/tito nbgrader collect 01_setup

Auto-Grading Process

# Auto-grade specific assignment
./bin/tito nbgrader autograde 01_setup

# Auto-grade all collected assignments
./bin/tito nbgrader autograde --all

# What happens:
# - Executes all student code
# - Runs hidden test cells  
# - Checks assert statements
# - Records pass/fail for each test
# - Creates detailed grading reports

Generating Student Feedback

# Generate feedback for specific assignment
./bin/tito nbgrader feedback 01_setup

# Generate feedback for all assignments
./bin/tito nbgrader feedback --all

# Creates:
# assignments/feedback/01_setup/student_name/01_setup.html

Exporting Grades

# Export grades to CSV
./bin/tito nbgrader report --format csv

# Creates: grades.csv with all student scores

---

🔧 Phase 5: Common Workflows

Weekly Assignment Routine

# Monday: Generate and release new assignment
./bin/tito nbgrader generate 03_activations
./bin/tito nbgrader release 03_activations

# Upload assignments/release/03_activations/03_activations.ipynb to LMS
# Announce assignment to students

# Friday: Collect submissions and grade
# (Download student submissions from LMS to assignments/submitted/)
./bin/tito nbgrader autograde 03_activations
./bin/tito nbgrader feedback 03_activations

# Monday: Return graded assignments and feedback to students

Mid-Semester Status Check

# Comprehensive system status
./bin/tito module status --comprehensive

# Assignment analytics
./bin/tito nbgrader analytics 03_activations

# Export current gradebook
./bin/tito nbgrader report --format csv

End-of-Semester Workflow

# Generate final gradebook
./bin/tito nbgrader report --format csv

# Archive all assignments and submissions
tar -czf course_archive_fall2024.tar.gz assignments/ gradebook.db

# Clean up for next semester
./bin/tito clean
./bin/tito nbgrader init  # Fresh start

---

🛠️ Phase 6: Troubleshooting & Tips

Common Issues

"Module not found" when generating:

# Check available modules
ls modules/source/

# Use exact directory name
./bin/tito nbgrader generate 02_tensor  # Not just "tensor"

"NBGrader validation failed":

# This is expected for student notebooks (they have unimplemented functions)
# Validation failure = students need to implement the code

Environment issues:

# Always activate virtual environment first
source .venv/bin/activate

# Check environment health
./bin/tito system doctor

Best Practices

📋 Assignment Preparation:

• Generate all assignments at start of semester
• Test each assignment yourself before releasing
• Provide clear due dates and submission instructions

⏰ Grading Efficiency:

• Set up consistent folder structure for submissions
• Use batch grading commands (--all flags)
• Review auto-graded results before finalizing

💡 Student Support:

• Share ./bin/tito module status command with students
• Encourage testing with provided test functions
• Provide clear error message interpretation

Advanced Configuration

Customize point values in nbgrader_config.py:

# Adjust timeout for long-running assignments
c.ExecutePreprocessor.timeout = 300  # 5 minutes per cell

# Customize solution stubs
c.ClearSolutions.code_stub = {
    "python": "# YOUR IMPLEMENTATION HERE\nraise NotImplementedError()"
}

---

📚 Phase 7: Student Guidance

What to Tell Your Students

Setup Instructions for Students:

# Students should run:
git clone [your-course-repo]
cd TinyTorch
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Test their setup:
./bin/tito system doctor

Working on Assignments:

1. Download the assignment notebook from [LMS]
2. Open in Jupyter: `jupyter lab assignment.ipynb`
3. Look for `# YOUR CODE HERE` markers
4. Implement the required functions
5. Test your work with provided test cells
6. Submit the completed notebook

Debugging Help:

# Students can check their module status
./bin/tito module status

# Get help with specific modules
./bin/tito module info 02_tensor

---

🎯 Quick Reference Commands

Essential Daily Commands

# Check overall system status
./bin/tito module status --comprehensive

# Assignment lifecycle
./bin/tito nbgrader generate MODULE_NAME
./bin/tito nbgrader release MODULE_NAME  
./bin/tito nbgrader autograde MODULE_NAME
./bin/tito nbgrader feedback MODULE_NAME

# Monitor progress
./bin/tito nbgrader status
./bin/tito nbgrader analytics MODULE_NAME

Batch Operations

# Work with multiple modules
./bin/tito nbgrader generate --range 01-04
./bin/tito nbgrader release --all
./bin/tito nbgrader autograde --all
./bin/tito nbgrader feedback --all

System Maintenance

# Environment health
./bin/tito system doctor

# Clean temporary files  
./bin/tito clean

# Export final grades
./bin/tito nbgrader report --format csv

---

📞 Getting Help

If you encounter issues:

1. Check system status: ./bin/tito system doctor
2. Review logs: Check output messages for specific errors
3. Consult documentation: This guide covers 95% of common scenarios
4. Community support: GitHub Issues

For urgent instructor support:

• Create detailed issue with error messages
• Include output of ./bin/tito module status --comprehensive
• Specify which assignment and step is failing

---

🎉 Success Metrics

You'll know you're successful when:

• ✅ Students can download and run assignments without setup issues
• ✅ Auto-grading provides consistent, fair evaluation
• ✅ Weekly assignment workflow takes <10 minutes
• ✅ Students build a complete ML framework by semester end
• ✅ You have detailed analytics on student progress and common issues

Ready to run the most comprehensive ML systems course your students will ever take! 🚀

---

This guide covers the complete instructor journey from setup to course completion. For specific technical details, see the individual command documentation with ./bin/tito --help.