# 👨‍🏫 Instructor Guide: NBGrader + TinyTorch — TinyTorch

Skip to main content
`Ctrl`+`K`

# 👨‍🏫 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`.