From 770d27c21bc21d35161493b07a4185794f1e0dcc Mon Sep 17 00:00:00 2001 From: Vijay Janapa Reddi Date: Tue, 11 Nov 2025 21:31:38 -0500 Subject: [PATCH] Add canonical student workflow documentation Created new student-workflow.md as the single source of truth for the TinyTorch development cycle. Updated quickstart-guide.md, tito-essentials.md, and intro.md to emphasize the simple workflow and reference the canonical guide. Key changes: - **New file**: site/student-workflow.md - Complete workflow guide - **quickstart-guide.md**: Added workflow context and step-by-step examples - **tito-essentials.md**: Simplified to focus on essential commands, marked checkpoint system as optional - **intro.md**: Added workflow section early, simplified getting started, marked instructor features as "coming soon" The actual workflow: 1. Edit modules in modules/source/ 2. Export with `tito module complete N` 3. Validate by running milestone scripts Checkpoint system and instructor features are documented as optional/coming soon, not primary workflow. --- site/intro.md | 36 +++++- site/quickstart-guide.md | 84 +++++++++----- site/student-workflow.md | 153 ++++++++++++++++++++++++++ site/tito-essentials.md | 230 +++++++++++++-------------------------- 4 files changed, 319 insertions(+), 184 deletions(-) create mode 100644 site/student-workflow.md diff --git a/site/intro.md b/site/intro.md index 5afbbf1d..45bded68 100644 --- a/site/intro.md +++ b/site/intro.md @@ -31,6 +31,18 @@ TinyTorch is an educational ML systems course where you **build complete neural **Core Learning Approach**: Build β†’ Profile β†’ Optimize. You'll implement each system component, measure its performance characteristics, and understand the engineering trade-offs that shape production ML systems. +## The Simple Workflow + +TinyTorch follows a three-step cycle: + +``` +1. Edit modules β†’ 2. Export to package β†’ 3. Validate with milestones +``` + +You work on module source files (`modules/source/`), export them to the TinyTorch package (`tito module complete N`), and prove they work by running historical milestone scripts. That's it. + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete development cycle. + ## Three-Tier Learning Pathway TinyTorch organizes learning through **three pedagogically-motivated tiers** that follow ML history: @@ -221,7 +233,7 @@ You master modern LLM optimizations

πŸŽ“ Instructors

-

Classroom-ready β€’ NBGrader integration β€’ Automated grading

+

Classroom-ready β€’ NBGrader integration (coming soon)

Teaching Guide β†’
@@ -235,11 +247,23 @@ You master modern LLM optimizations ## Getting Started -Whether you're just exploring or ready to dive in, here are helpful resources: **πŸ“– See [Essential Commands](tito-essentials.html)** for complete setup and command reference, or **πŸ“– See [Three-Tier Learning Structure](chapters/00-introduction.html#three-tier-learning-pathway-build-complete-ml-systems)** for detailed tier breakdown and learning outcomes. +Ready to build ML systems from scratch? Here's how to start: -**Additional Resources**: -- **[Progress Tracking](learning-progress.html)** - Monitor your learning journey with 21 capability checkpoints -- **[Testing Framework](testing-framework.html)** - Understand our comprehensive validation system -- **[Documentation & Guides](resources.html)** - Complete technical documentation and tutorials +**Quick Setup** (15 minutes): +1. Clone the repository +2. Run `./setup-environment.sh` +3. Start with Module 01 (Tensors) +4. Export with `tito module complete 01` +5. Validate by running milestone scripts + +**πŸ“– See [Quick Start Guide](quickstart-guide.html)** for detailed setup instructions. + +**Understanding the Workflow**: +- **πŸ“– See [Student Workflow](student-workflow.html)** - The essential edit β†’ export β†’ validate cycle +- **πŸ“– See [Essential Commands](tito-essentials.html)** - Complete TITO command reference +- **πŸ“– See [Three-Tier Learning Structure](chapters/00-introduction.html)** - Detailed course structure + +**Optional Progress Tracking**: +- **[Progress Tracking](learning-progress.html)** - Monitor your journey with capability checkpoints (optional) TinyTorch is more than a courseβ€”it's a community of learners building together. Join thousands exploring ML systems from the ground up. \ No newline at end of file diff --git a/site/quickstart-guide.md b/site/quickstart-guide.md index 401ee671..74a14863 100644 --- a/site/quickstart-guide.md +++ b/site/quickstart-guide.md @@ -52,7 +52,13 @@ You should see all green checkmarks! This confirms your environment is ready for ## πŸ—οΈ 15-Minute First Module Walkthrough -Let's build your first neural network component and unlock your first capability: +Let's build your first neural network component following the **TinyTorch workflow**: + +``` +1. Edit modules β†’ 2. Export to package β†’ 3. Validate with milestones +``` + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete development cycle. ### Module 01: Tensor Foundations @@ -65,9 +71,9 @@ Let's build your first neural network component and unlock your first capability **πŸ’» Action:** Start with Module 01 to build tensor operations from scratch. ```bash -# Navigate to the tensor module -cd modules/01_tensor -jupyter lab tensor_dev.py +# Step 1: Edit the module source +cd modules/source/01_tensor +jupyter lab 01_tensor_dev.py ``` You'll implement core tensor operations: @@ -78,7 +84,14 @@ You'll implement core tensor operations: **Key Implementation:** Build the `Tensor` class that forms the foundation of all neural networks -**πŸ“– See [Essential Commands](tito-essentials.html)** for module workflow commands. +```bash +# Step 2: Export to package when ready +tito module complete 01 +``` + +This makes your implementation importable: `from tinytorch import Tensor` + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete edit β†’ export β†’ validate cycle. **βœ… Achievement Unlocked:** Foundation capability - "Can I create and manipulate the building blocks of ML?" @@ -94,6 +107,12 @@ You'll implement core tensor operations: **πŸ’» Action:** Continue with Module 02 to add activation functions. +```bash +# Step 1: Edit the module +cd modules/source/02_activations +jupyter lab 02_activations_dev.py +``` + You'll implement essential activation functions: - ReLU (Rectified Linear Unit) - the workhorse of deep learning - Softmax - for probability distributions @@ -102,7 +121,12 @@ You'll implement essential activation functions: **Key Implementation:** Build activation functions that allow neural networks to learn complex patterns -**πŸ“– See [Essential Commands](tito-essentials.html)** for module development workflow. +```bash +# Step 2: Export when ready +tito module complete 02 +``` + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete edit β†’ export β†’ validate cycle. **βœ… Achievement Unlocked:** Intelligence capability - "Can I add nonlinearity to enable learning?" @@ -114,28 +138,38 @@ After completing your first modules:
-**Check your new capabilities:** Track your progress through the 21-checkpoint system to see your growing ML systems expertise. +**Check your new capabilities:** Use the optional checkpoint system to track your progress: -**πŸ“– See [Track Your Progress](learning-progress.html)** for detailed capability tracking and [Essential Commands](tito-essentials.html)** for progress monitoring commands. +```bash +tito checkpoint status # View your completion tracking +``` + +This is helpful for self-assessment but not required for the core workflow. + +**πŸ“– See [Student Workflow](student-workflow.html)** for the essential edit β†’ export β†’ validate cycle, and [Track Your Progress](learning-progress.html)** for detailed capability tracking.
-## πŸ† Unlock Historical Milestones +## πŸ† Validate with Historical Milestones -As you progress, **prove what you've built** by recreating history's greatest ML breakthroughs: +After exporting your modules, **prove what you've built** by running milestone scripts:
-**After Module 04**: Build **Rosenblatt's 1957 Perceptron** - the first trainable neural network -**After Module 06**: Solve the **1969 XOR Crisis** with multi-layer networks -**After Module 08**: Achieve **95%+ accuracy on MNIST** with 1986 backpropagation -**After Module 09**: Hit **75%+ on CIFAR-10** with 1998 CNNs - your North Star goal! 🎯 +**After Module 07**: Build **Rosenblatt's 1957 Perceptron** - the first trainable neural network +**After Module 07**: Solve the **1969 XOR Crisis** with multi-layer networks +**After Module 08**: Achieve **95%+ accuracy on MNIST** with 1986 backpropagation +**After Module 09**: Hit **75%+ on CIFAR-10** with 1998 CNNs +**After Module 13**: Generate text with **2017 Transformers** +**After Module 18**: Optimize for production with **2018 MLPerf** **πŸ“– See [Journey Through ML History](chapters/milestones.html)** for complete milestone demonstrations.
-**Why Milestones Matter**: These aren't toy demos - they're historically significant achievements proving YOUR implementations work at production scale! +**The Workflow**: Edit modules β†’ Export with `tito module complete N` β†’ Run milestone scripts to validate + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete cycle. ## 🎯 What You Just Accomplished @@ -166,14 +200,15 @@ In 15 minutes, you've: ### Immediate Next Actions (Choose One): -**πŸ”₯ Continue Building (Recommended):** Begin Module 03 to add intelligence to your network with nonlinear activation functions. +**πŸ”₯ Continue Building (Recommended):** Begin Module 03 to add layers to your network. -**πŸ“š Learn the Workflow:** -- **πŸ“– See [Essential Commands](tito-essentials.html)** for complete TITO command guide +**πŸ“š Master the Workflow:** +- **πŸ“– See [Student Workflow](student-workflow.html)** for the complete edit β†’ export β†’ validate cycle +- **πŸ“– See [Essential Commands](tito-essentials.html)** for complete TITO command reference - **πŸ“– See [Track Your Progress](learning-progress.html)** for the full learning path **πŸŽ“ For Instructors:** -- **πŸ“– See [Classroom Setup Guide](usage-paths/classroom-use.html)** for NBGrader integration and grading workflow +- **πŸ“– See [Classroom Setup Guide](usage-paths/classroom-use.html)** for NBGrader integration (coming soon) @@ -181,13 +216,12 @@ In 15 minutes, you've:
-**Essential Development Practices:** -- Always verify your environment before starting -- Track your progress through capability checkpoints -- Follow the standard module development workflow -- Use diagnostic commands when debugging issues +**The TinyTorch Development Cycle:** +1. Edit module sources in `modules/source/` +2. Export with `tito module complete N` +3. Validate by running milestone scripts -**πŸ“– See [Essential Commands](tito-essentials.html)** for complete workflow commands and troubleshooting guide. +**πŸ“– See [Student Workflow](student-workflow.html)** for detailed workflow guide and best practices.
diff --git a/site/student-workflow.md b/site/student-workflow.md new file mode 100644 index 00000000..35c23272 --- /dev/null +++ b/site/student-workflow.md @@ -0,0 +1,153 @@ +# Student Workflow + +This guide explains the actual day-to-day workflow for building your ML framework with TinyTorch. + +## The Core Workflow + +TinyTorch follows a simple three-step cycle: + +``` +1. Edit modules β†’ 2. Export to package β†’ 3. Validate with milestones +``` + +### Step 1: Edit Modules + +Work on module source files in `modules/source/`: + +```bash +# Example: Working on Module 03 (Layers) +cd modules/source/03_layers +# Edit the *_dev.py files with your implementation +``` + +Each module is a Jupyter notebook in Python format (`.py` files with cell markers). You'll: +- Implement the required functionality +- Add docstrings and comments +- Include tests within the module + +### Step 2: Export to Package + +Once your module implementation is complete, export it to the main TinyTorch package: + +```bash +tito module complete MODULE_NUMBER +``` + +This command: +- Converts your source files to the `tinytorch/` package +- Validates NBGrader metadata +- Makes your implementation available for import + +**Example:** +```bash +tito module complete 03 # Export Module 03 (Layers) +``` + +After export, your code is importable: +```python +from tinytorch.layers import Linear # YOUR implementation! +``` + +### Step 3: Validate with Milestones + +Run milestone scripts to prove your implementation works: + +```bash +cd milestones/01_1957_perceptron +python 01_rosenblatt_forward.py # Uses YOUR Tensor (M01) +python 02_rosenblatt_trained.py # Uses YOUR layers (M01-M07) +``` + +Each milestone has a README explaining: +- Required modules +- Historical context +- Expected results +- What you're learning + +See [Milestones Guide](chapters/milestones.md) for the full progression. + +## Module Progression + +TinyTorch has 18 modules organized in three tiers: + +### πŸ—οΈ Foundation (Modules 01-07) +Core ML infrastructure - tensors, autograd, training loops + +**Milestones unlocked:** +- M01: Perceptron (after Module 07) +- M02: XOR Crisis (after Module 07) + +### πŸ›οΈ Architecture (Modules 08-13) +Neural network architectures - data loading, CNNs, transformers + +**Milestones unlocked:** +- M03: MLPs (after Module 08) +- M04: CNNs (after Module 09) +- M05: Transformers (after Module 13) + +### ⚑ Optimization (Modules 14-18) +Production optimization - profiling, quantization, acceleration + +**Milestones unlocked:** +- M06: MLPerf (after Module 18) + +## Typical Development Session + +Here's what a typical session looks like: + +```bash +# 1. Work on a module +cd modules/source/05_autograd +# Edit 05_autograd_dev.py with your implementation + +# 2. Export when ready +tito module complete 05 + +# 3. Validate with existing milestones +cd ../../milestones/01_1957_perceptron +python 01_rosenblatt_forward.py # Should still work! + +# 4. Continue to next module or milestone +``` + +## TITO Commands Reference + +The most important commands you'll use: + +```bash +# Export module to package +tito module complete MODULE_NUMBER + +# Check module status (optional capability tracking) +tito checkpoint status + +# System information +tito system info +``` + +For complete command documentation, see [TITO Essentials](tito-essentials.md). + +## Checkpoint System (Optional) + +TinyTorch includes an optional checkpoint system for tracking progress: + +```bash +tito checkpoint status # View completion tracking +``` + +This is helpful for self-assessment but **not required** for the core workflow. The essential cycle remains: edit β†’ export β†’ validate. + +## Instructor Integration (Coming Soon) + +TinyTorch supports NBGrader for classroom use. Documentation for instructors using the autograding features will be available in future releases. + +For now, focus on the student workflow: building your implementations and validating them with milestones. + +## What's Next? + +1. **Start with Module 01**: See [Getting Started](intro.md) +2. **Follow the progression**: Each module builds on previous ones +3. **Run milestones**: Prove your implementations work +4. **Build intuition**: Understand ML systems from first principles + +The goal isn't just to write code - it's to **understand** how modern ML frameworks work by building one yourself. diff --git a/site/tito-essentials.md b/site/tito-essentials.md index c41a0783..09708f0a 100644 --- a/site/tito-essentials.md +++ b/site/tito-essentials.md @@ -7,9 +7,23 @@ **Purpose**: Complete command reference for the TITO CLI. Master the essential commands for development workflow, progress tracking, and system management. -## πŸš€ First 4 Commands (Start Here) +## The Core Workflow -Every TinyTorch journey begins with these essential commands: +TinyTorch follows a simple three-step cycle: + +``` +1. Edit modules β†’ 2. Export to package β†’ 3. Validate with milestones +``` + +**The essential command**: `tito module complete MODULE_NUMBER` - exports your code to the TinyTorch package. + +**πŸ“– See [Student Workflow](student-workflow.html)** for the complete development cycle guide. + +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:
@@ -19,67 +33,55 @@ Every TinyTorch journey begins with these essential commands:

Verify your setup is ready for development

-
-

🎯 Track Your Progress

-tito checkpoint status -

See which capabilities you've mastered

-
-
-

πŸ”¨ Work on a Module

-tito module work 02_tensor -

Open and start building tensor operations

+

πŸ”¨ Export Module to Package (Essential)

+tito module complete 01 +

Export your module to the TinyTorch package - use this after editing modules

-
-

βœ… Complete Your Work

-tito module complete 02_tensor -

Export your code and test your capabilities

+
+

🎯 Track Your Progress (Optional)

+tito checkpoint status +

See which capabilities you've mastered (optional capability tracking)

-## πŸ”„ Your Daily Learning Workflow +## πŸ”„ Typical Development Session -Follow this proven pattern for effective learning: +Here's what a typical session looks like:
-**Morning Start:** +**Edit modules:** ```bash -# 1. Check environment -tito system doctor - -# 2. See your progress -tito checkpoint status - -# 3. Start working on next module -tito module work 03_activations +cd modules/source/03_layers +jupyter lab 03_layers_dev.py +# Make your implementation... ``` -**During Development:** +**Export to package:** ```bash -# Test your understanding anytime -tito checkpoint test 02 - -# View your learning timeline -tito checkpoint timeline +# From repository root +tito module complete 03 ``` -**End of Session:** +**Validate with milestones:** ```bash -# Complete and export your work -tito module complete 03_activations - -# Celebrate your progress! -tito checkpoint status +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.html)** for complete development cycle details. +
-## πŸ’ͺ Most Important Commands (Top 10) - -Master these commands for maximum efficiency: +## πŸ“– Complete Command Reference ### πŸ₯ System & Health
@@ -90,124 +92,73 @@ tito system doctor ``` *Diagnose environment issues before they block you* -**Module Status** +**System Info** ```bash -tito module status +tito system info ``` -*See all available modules and your completion status* +*View configuration details*
-### πŸ“Š Progress Tracking +### πŸ”¨ Module Management +
+ +**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! +``` + +
+ +### πŸ“Š Progress Tracking (Optional)
**Capability Overview** ```bash tito checkpoint status ``` -*Quick view of your 16 core capabilities* +*Quick view of your capabilities (optional tracking)* **Detailed Progress** ```bash tito checkpoint status --detailed ``` -*Module-by-module breakdown with test status* +*Module-by-module breakdown* **Visual Timeline** ```bash tito checkpoint timeline ``` -*See your learning journey in beautiful visual format* - -
- -### πŸ”¨ Module Development -
- -**Start Working** -```bash -tito module work 05_dense -``` -*Open module and start building* - -**Export to Package** -```bash -tito module complete 05_dense -``` -*Export your code to the TinyTorch package + run capability test* - -**Quick Export (No Test)** -```bash -tito module export 05_dense -``` -*Export without running capability tests* - -
- -### πŸ§ͺ Testing & Validation -
+*See your learning journey in visual format* **Test Specific Capability** ```bash -tito checkpoint test 03 +tito checkpoint test CHECKPOINT_NUMBER ``` *Verify you've mastered a specific capability* -**Run Checkpoint with Details** -```bash -tito checkpoint run 03 --verbose -``` -*See detailed output of capability validation* -
-## πŸŽ“ Learning Stages & Commands - -### Stage 1: Foundation (Modules 1-4) -**Key Commands:** -- `tito module work 01_setup` β†’ `tito module complete 01_setup` -- `tito checkpoint test 00` (Environment) -- `tito checkpoint test 01` (Foundation) - -### Stage 2: Core Learning (Modules 5-8) -**Key Commands:** -- `tito checkpoint status` (Track your capabilities) -- `tito checkpoint timeline` (Visual progress) -- Complete modules 5-8 systematically - -### Stage 3: Advanced Systems (Modules 9+) -**Key Commands:** -- `tito checkpoint timeline --horizontal` (Linear view) -- Focus on systems optimization modules -- Use `tito checkpoint test XX` for validation - -## πŸ‘©β€πŸ« Instructor Commands (NBGrader) - -For instructors managing the course: +## πŸ‘©β€πŸ« Instructor Commands (Coming Soon)
-**Setup Course:** -```bash -tito nbgrader init # Initialize NBGrader environment -tito nbgrader status # Check assignment status -``` +TinyTorch includes NBGrader integration for classroom use. Full documentation for instructor workflows (assignment generation, autograding, etc.) will be available in future releases. -**Manage Assignments:** -```bash -tito nbgrader generate 01_setup # Create assignment from module -tito nbgrader release 01_setup # Release to students -tito nbgrader collect 01_setup # Collect submissions -tito nbgrader autograde 01_setup # Automatic grading -``` +**For now, focus on the student workflow**: edit modules β†’ export β†’ validate with milestones. -**Reports & Export:** -```bash -tito nbgrader report # Generate grade report -tito nbgrader export # Export grades to CSV -``` - -*For detailed instructor workflow, see [Instructor Guide](usage-paths/classroom-use.html)* +*For current instructor capabilities, see [Classroom Use Guide](usage-paths/classroom-use.html)*
@@ -223,13 +174,7 @@ tito system doctor # Diagnose problems tito system info # Show configuration details ``` -**Module Problems:** -```bash -tito module status # Check what's available -tito module info 02_tensor # Get specific module details -``` - -**Progress Confusion:** +**Progress Tracking (Optional):** ```bash tito checkpoint status --detailed # See exactly where you are tito checkpoint timeline # Visualize your progress @@ -237,27 +182,6 @@ tito checkpoint timeline # Visualize your progress -## 🎯 Pro Tips for Efficiency - -
- -
-

πŸ”₯ Hot Tip

-

Use tab completion! Type `tito mod` + TAB to auto-complete commands

-
- -
-

⚑ Speed Boost

-

Alias common commands: `alias ts='tito checkpoint status'`

-
- -
-

🎯 Focus

-

Always run `tito system doctor` first when starting a new session

-
- -
- ## πŸš€ Ready to Build?