From c1cdb8147bbfcd938822e70f4da26c65701e1a25 Mon Sep 17 00:00:00 2001 From: Vijay Janapa Reddi Date: Wed, 16 Jul 2025 07:45:31 -0400 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Restructure=20README:=20Lead=20with?= =?UTF-8?q?=20big=20picture=20and=20key=20differentiators?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move 'The Big Picture: Why Build from Scratch?' to the top - Add prominent 'What Makes TinyTorch Different' section highlighting unique value - Emphasize build-first philosophy vs traditional 'use' frameworks approach - Show concrete code comparison: traditional vs TinyTorch approach - Better highlight real production skills, progressive mastery, instant feedback - Reorganize content flow: vision β†’ differentiators β†’ practical details --- README.md | 155 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 100 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 8825b8b8..77281ef9 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,59 @@ [![Python](https://img.shields.io/badge/python-3.8+-green.svg)](https://python.org) [![Jupyter Book](https://img.shields.io/badge/docs-Jupyter_Book-orange.svg)](https://mlsysbook.github.io/TinyTorch/) -A hands-on [Machine Learning Systems](https://mlsysbook.ai) course companion where students don’t just learn ML β€” they build it. - -TinyπŸ”₯Torch is the minimalist, code-first companion to any machine learning systems course. It embraces a β€œstart small, go deep” philosophyβ€”starting with tensors and layers, and guiding learners through each system component, all the way to a complete MLOps pipelines built from scratch in their own codebaseβ€”albeit within a deliberately small-scale educational framework. - πŸ“š **[Read the Interactive Course β†’](https://mlsysbook.github.io/TinyTorch/)** --- +## πŸ—οΈ **The Big Picture: Why Build from Scratch?** + +**Most ML education teaches you to _use_ frameworks.** TinyTorch teaches you to _understand_ them. + +```python +Traditional ML Course: TinyTorch Approach: +β”œβ”€β”€ import torch β”œβ”€β”€ class Tensor: +β”œβ”€β”€ model = nn.Linear(10, 1) β”‚ def __add__(self, other): ... +β”œβ”€β”€ loss = nn.MSELoss() β”‚ def backward(self): ... +└── optimizer.step() β”œβ”€β”€ class Linear: + β”‚ def forward(self, x): + β”‚ return x @ self.weight + self.bias + β”œβ”€β”€ def mse_loss(pred, target): + β”‚ return ((pred - target) ** 2).mean() + β”œβ”€β”€ class SGD: + β”‚ def step(self): + └── param.data -= lr * param.grad + +Go from "How does this work?" 🀷 to "I implemented every line!" πŸ’ͺ +``` + +**Result:** You become the person others come to when they need to understand "how PyTorch actually works under the hood." + +--- + +## 🌟 **What Makes TinyTorch Different** + +### **πŸ”¬ Build-First Philosophy** +- **No black boxes**: Implement every component from scratch +- **Immediate ownership**: Use YOUR code in real neural networks +- **Deep understanding**: Know exactly how each piece works + +### **πŸš€ Real Production Skills** +- **Professional workflow**: Development with `tito` CLI, automated testing +- **Real datasets**: Train on CIFAR-10, not toy data +- **Production patterns**: MLOps, monitoring, optimization from day one + +### **🎯 Progressive Mastery** +- **Start simple**: Implement `hello_world()` function +- **Build systematically**: Each module enables the next +- **End powerful**: Deploy production ML systems with monitoring + +### **⚑ Instant Feedback** +- **Code works immediately**: No waiting to see results +- **Visual progress**: Success indicators and system integration +- **"Aha moments"**: Watch your `ReLU` power real neural networks + +--- + ## 🎯 What You'll Build * **Complete ML Framework** β€” Your own PyTorch-style toolkit, from tensors to MLOps @@ -79,6 +124,57 @@ tito nbdev build # Update package --- +## 🧠 Pedagogical Framework: Build β†’ Use β†’ Reflect + +### **Example: How You'll Master Activation Functions** + +**πŸ”§ Build:** Implement ReLU from scratch +```python +def relu(x): + # YOU implement this function + return ??? # What should this be? +``` + +**πŸš€ Use:** Immediately use your own code +```python +from tinytorch.core.activations import ReLU # YOUR implementation! +layer = ReLU() +output = layer.forward(input_tensor) # Your code working! +``` + +**πŸ’‘ Reflect:** See it working in real networks +```python +# Your ReLU is now part of a real neural network +model = Sequential([ + Dense(784, 128), + ReLU(), # <-- Your implementation + Dense(128, 10) +]) +``` + +**This pattern repeats for every component** β€” you build it, use it immediately, then see how it fits into larger systems. + +--- + +## πŸŽ“ Teaching Philosophy + +### **No Black Boxes** +* Build every component from scratch +* Understand performance trade-offs +* See how engineering decisions impact ML outcomes + +### **Production-Ready Thinking** +* Use real datasets (CIFAR-10, MNIST) +* Implement proper testing and benchmarking +* Learn MLOps and system design principles + +### **Iterative Mastery** +* Each module builds on previous work +* Immediate feedback through inline testing +* Progressive complexity with solid foundations + +--- + ## πŸ“– Documentation ### **Interactive Jupyter Book** @@ -126,57 +222,6 @@ git push origin main # Triggers documentation deployment --- -## 🧠 Pedagogical Framework: Build β†’ Use β†’ Reflect - -### **Real Engineering, Real Understanding** - -1. **Build** β€” Implement `ReLU()` activation function -2. **Use** β€” Apply it via `tinytorch.core.activations.ReLU()` -3. **Reflect** β€” Understand its role in neural network design -4. **Iterate** β€” Extend knowledge with each module - -### **Example Learning Cycle** - -```python -# Step 1: You implement this in tensor_dev.py -class Tensor: - def __init__(self, data): - self.data = np.array(data) - - def __add__(self, other): - return Tensor(self.data + other.data) - -# Step 2: Export and use in your framework -from tinytorch.core.tensor import Tensor -a = Tensor([1, 2, 3]) -b = Tensor([4, 5, 6]) -result = a + b # Your implementation at work! - -# Step 3: Apply to real problems -model = Sequential([Dense(784, 128), ReLU(), Dense(128, 10)]) -``` - ---- - -## πŸŽ“ Teaching Philosophy - -### **No Black Boxes** -* Build every component from scratch -* Understand performance trade-offs -* See how engineering decisions impact ML outcomes - -### **Production-Ready Thinking** -* Use real datasets (CIFAR-10, MNIST) -* Implement proper testing and benchmarking -* Learn MLOps and system design principles - -### **Iterative Mastery** -* Each module builds on previous work -* Immediate feedback through inline testing -* Progressive complexity with solid foundations - ---- - ## πŸ“ Project Structure ```