Upgrade

.github/classroom/autograding.json

@@ -0,0 +1,54 @@
+{
+  "tests": [
+    {
+      "name": "Task 4.1 - 1D Convolution",
+      "setup": "pip install -e .",
+      "run": "python -m pytest -m task4_1 --tb=no -q",
+      "input": "",
+      "output": "",
+      "comparison": "included",
+      "timeout": 15,
+      "points": 25
+    },
+    {
+      "name": "Task 4.2 - 2D Convolution", 
+      "setup": "",
+      "run": "python -m pytest -m task4_2 --tb=no -q",
+      "input": "",
+      "output": "",
+      "comparison": "included",
+      "timeout": 15,
+      "points": 25
+    },
+    {
+      "name": "Task 4.3 - Pooling Operations",
+      "setup": "",
+      "run": "python -m pytest -m task4_3 --tb=no -q",
+      "input": "",
+      "output": "",
+      "comparison": "included", 
+      "timeout": 15,
+      "points": 25
+    },
+    {
+      "name": "Task 4.4 - Advanced NN Functions",
+      "setup": "",
+      "run": "python -m pytest -m task4_4 --tb=no -q",
+      "input": "",
+      "output": "",
+      "comparison": "included",
+      "timeout": 15,
+      "points": 15
+    },
+    {
+      "name": "Style Check",
+      "setup": "",
+      "run": "python -m ruff check . && python -m pyright",
+      "input": "",
+      "output": "",
+      "comparison": "included",
+      "timeout": 10,
+      "points": 10
+    }
+  ]
+}

.github/workflows/classroom.yaml

@@ -0,0 +1,78 @@
+name: Autograding Tests
+'on':
+- push
+- repository_dispatch
+permissions:
+  checks: write
+  actions: read
+  contents: read
+jobs:
+  run-autograding-tests:
+    runs-on: ubuntu-latest
+    if: github.actor != 'github-classroom[bot]'
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+    - name: Install dependencies and package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev,extra]"
+    - name: Task 4.1 - 1D Convolution
+      id: task-4-1-1d-convolution
+      uses: classroom-resources/autograding-command-grader@v1
+      with:
+        test-name: Task 4.1 - 1D Convolution
+        setup-command: ''
+        command: python -m pytest -m task4_1 --tb=no -q
+        timeout: 15
+        max-score: 25
+    - name: Task 4.2 - 2D Convolution
+      id: task-4-2-2d-convolution
+      uses: classroom-resources/autograding-command-grader@v1
+      with:
+        test-name: Task 4.2 - 2D Convolution
+        setup-command: ''
+        command: python -m pytest -m task4_2 --tb=no -q
+        timeout: 15
+        max-score: 25
+    - name: Task 4.3 - Pooling Operations
+      id: task-4-3-pooling-operations
+      uses: classroom-resources/autograding-command-grader@v1
+      with:
+        test-name: Task 4.3 - Pooling Operations
+        setup-command: ''
+        command: python -m pytest -m task4_3 --tb=no -q
+        timeout: 15
+        max-score: 25
+    - name: Task 4.4 - Advanced NN Functions
+      id: task-4-4-advanced-nn-functions
+      uses: classroom-resources/autograding-command-grader@v1
+      with:
+        test-name: Task 4.4 - Advanced NN Functions
+        setup-command: ''
+        command: python -m pytest -m task4_4 --tb=no -q
+        timeout: 15
+        max-score: 15
+    - name: Style Check
+      id: style-check
+      uses: classroom-resources/autograding-command-grader@v1
+      with:
+        test-name: Style Check
+        setup-command: ''
+        command: python -m ruff check . && python -m pyright
+        timeout: 10
+        max-score: 10
+    - name: Autograding Reporter
+      uses: classroom-resources/autograding-grading-reporter@v1
+      env:
+        TASK-4-1-1D-CONVOLUTION_RESULTS: "${{steps.task-4-1-1d-convolution.outputs.result}}"
+        TASK-4-2-2D-CONVOLUTION_RESULTS: "${{steps.task-4-2-2d-convolution.outputs.result}}"
+        TASK-4-3-POOLING-OPERATIONS_RESULTS: "${{steps.task-4-3-pooling-operations.outputs.result}}"
+        TASK-4-4-ADVANCED-NN-FUNCTIONS_RESULTS: "${{steps.task-4-4-advanced-nn-functions.outputs.result}}"
+        STYLE-CHECK_RESULTS: "${{steps.style-check.outputs.result}}"
+      with:
+        runners: task-4-1-1d-convolution,task-4-2-2d-convolution,task-4-3-pooling-operations,task-4-4-advanced-nn-functions,style-check

.pre-commit-config.yaml

@@ -1,44 +1,15 @@
-# To use:
-#
-#     pre-commit run -a
-#
-# Or:
-#
-#     pre-commit install  # (runs every time you commit in git)
-#
-# To update this file:
-#
-#     pre-commit autoupdate
-#
-# See https://github.com/pre-commit/pre-commit
-
 repos:
-# Standard hooks
-- repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.3.0
-  hooks:
-  - id: check-added-large-files
-  - id: check-case-conflict
-  - id: check-docstring-first
-  - id: check-merge-conflict
-  - id: check-symlinks
-  - id: check-toml
-  - id: debug-statements
-  - id: mixed-line-ending
-  - id: requirements-txt-fixer
-  - id: trailing-whitespace
-
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
-  rev: v0.6.1
-  hooks:
-    # Run the linter.
-    - id: ruff
-      args: [ --fix ]
-    # Run the formatter.
-    - id: ruff-format
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.8.4
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format
 
-- repo: https://github.com/RobertCraigie/pyright-python
-  rev: v1.1.376
-  hooks:
-    - id: pyright
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.390
+    hooks:
+      - id: pyright

README.md

@@ -1,36 +1,139 @@
-# MiniTorch Module 4
+# MiniTorch Module 4: Neural Networks and Convolutions
 
 <img src="https://minitorch.github.io/minitorch.svg" width="50%">
 
+[![CI](https://github.com/minitorch/minitorch/workflows/CI/badge.svg)](https://github.com/minitorch/minitorch/actions)
+
 * Docs: https://minitorch.github.io/
 
 * Overview: https://minitorch.github.io/module4.html
 
-This module requires `fast_ops.py`, `cuda_ops.py`, `scalar.py`, `tensor_functions.py`, `tensor_data.py`, `tensor_ops.py`, `operators.py`, `module.py`, and `autodiff.py` from Module 3.
+Module 4 extends MiniTorch with convolutional neural network operations to build an image recognition system. You'll implement a version of LeNet on MNIST for digit recognition and 1D convolution for NLP sentiment classification:
 
+- **1D and 2D convolution** for feature extraction and image processing
+- **Pooling operations** for spatial down-sampling and dimension reduction
+- **Advanced NN functions** including softmax, dropout, and max operations
+- **MNIST digit classification** and **SST2 sentiment analysis** with CNNs
 
-Additionally you will need to install and download the MNist library.
+## Quick Start
 
-(On Mac, this may require installing the `wget` command)
+```bash
+# Install dependencies
+pip install -e ".[dev,extra]"
 
-```
+# Set up MNIST dataset
 pip install python-mnist
 mnist_get_data.sh
+
+# Sync files from Module 3
+python sync_previous_module.py ../Module-3 .
+
+# Run Module 4 tests
+pytest -m task4_1
+pytest -m task4_2
+pytest -m task4_3
+pytest -m task4_4
+
+# Train CNN models
+python project/run_mnist_multiclass.py  # MNIST digits
+python project/run_sentiment.py         # SST2 sentiment
+
+# Run style checks
+pre-commit run --all-files
 ```
 
+## Tasks Overview
+
+### Task 4.1: 1D Convolution
+**File**: `minitorch/fast_conv.py`
+- Implement `_tensor_conv1d()` function
+- Support forward and backward convolution with parallel processing
+
+### Task 4.2: 2D Convolution
+**File**: `minitorch/fast_conv.py`
+- Implement `_tensor_conv2d()` function
+- Optimize for image processing with efficient memory access
+
+### Task 4.3: Pooling Operations
+**File**: `minitorch/nn.py`
+- Implement `tile()` tensor reshaping function
+- Implement `avgpool2d()` for average pooling
+
+### Task 4.4: Advanced Neural Network Functions
+**File**: `minitorch/nn.py`
+- Implement `max()`, `softmax()`, `logsoftmax()`, and `dropout()`
+- Implement `maxpool2d()` for max pooling operations
+- Add property tests and ensure gradient computation correctness
+
+### Task 4.4b: Extra Credit (CUDA Convolution)
+**File**: `minitorch/cuda_conv.py`
+- Implement `conv1d` and `conv2d` on CUDA for efficient GPU processing
+- Critical for large-scale image recognition performance
+- Show output on Google Colab
+
+### Task 4.5: Training an Image Classifier
+**Files**: `project/run_sentiment.py` and `project/run_mnist_multiclass.py`
+- Implement Conv1D, Conv2D, and Network for both sentiment and image classification
+- Train models on SST2 sentiment data and MNIST digit classification
+- Use Streamlit visualization to view hidden states of your model
 
-* Tests:
+**Training Requirements:**
+- Train a model on Sentiment (SST2), add training logs as `sentiment.txt` showing train loss, train accuracy and validation accuracy (should achieve >70% best validation accuracy)
+- Train a model on Digit classification (MNIST), add logs as `mnist.txt` showing train loss and validation accuracy
+- Implement Conv1D, Conv2D, and Network classes for both training files
 
+## Testing
+
+**Module 4 Tasks:**
+```bash
+pytest -m task4_1  # 1D convolution
+pytest -m task4_2  # 2D convolution
+pytest -m task4_3  # Pooling operations
+pytest -m task4_4  # Advanced NN functions
 ```
-python run_tests.py
+
+**CNN Training:**
+```bash
+python project/run_mnist_multiclass.py  # MNIST digit classification
+python project/run_sentiment.py         # SST2 sentiment analysis
+```
+
+**Style Checks:**
+```bash
+pre-commit run --all-files
+ruff check . && pyright
 ```
 
-This assignment requires the following files from the previous assignments. You can get these by running
+## CNN Applications
+
+**MNIST digit classification with CNNs:**
+- Convolutional feature extraction
+- Spatial pooling for dimension reduction
+- Performance comparison with fully-connected networks
+
+**Expected improvements over fully-connected:**
+- Fewer parameters through weight sharing
+- Translation invariance for image recognition
+- Hierarchical feature learning
+
+## Module Requirements
+
+This module requires files from previous assignments, so make sure to pull them over to your new repo. We recommend getting familiar with `tensor.py`, since you might find some of those functions useful for implementing this module.
+
+Get the required files by running:
 
 ```bash
-python sync_previous_module.py previous-module-dir current-module-dir
+python sync_previous_module.py <path-to-module-3> <path-to-current-module>
 ```
 
-The files that will be synced are:
+**Required files from Module 3:**
+- All tensor system files and fast operations
+- Module framework and autodifferentiation
+- Training scripts and datasets
+
+## Resources
 
-        minitorch/tensor_data.py minitorch/tensor_functions.py minitorch/tensor_ops.py minitorch/operators.py minitorch/scalar.py minitorch/scalar_functions.py minitorch/module.py minitorch/autodiff.py minitorch/module.py project/run_manual.py project/run_scalar.py project/run_tensor.py minitorch/operators.py minitorch/module.py minitorch/autodiff.py minitorch/tensor.py minitorch/datasets.py minitorch/testing.py minitorch/optim.py minitorch/tensor_ops.py minitorch/fast_ops.py minitorch/cuda_ops.py project/parallel_check.py tests/test_tensor_general.py
+- **[Installation Guide](installation.md)**: Setup instructions with MNIST
+- **[Testing Guide](testing.md)**: CNN testing strategies
+- **MiniTorch Docs**: https://minitorch.github.io/
+- **Module 4 Overview**: https://minitorch.github.io/module4.html