| """ | |
| QUICK START GUIDE - How to Run the Improved MNIST Classifier | |
| =============================================================== | |
| Follow these steps to get started quickly! | |
| """ | |
| # STEP 1: INSTALLATION | |
| # ==================== | |
| """ | |
| 1. Make sure you have Python 3.8+ installed | |
| Check with: python --version or python3 --version | |
| 2. Create a new folder for your project and put all the files there: | |
| - improved_mnist_classifier.py | |
| - config.yaml | |
| - requirements.txt | |
| - inference.py | |
| 3. Open terminal/command prompt in that folder | |
| """ | |
| # Windows: | |
| # cd C:\path\to\your\folder | |
| # Mac/Linux: | |
| # cd /path/to/your/folder | |
| """ | |
| 4. Install required packages: | |
| """ | |
| # OPTION A - Using pip directly (recommended): | |
| pip install torch torchvision numpy matplotlib seaborn tqdm scikit-learn tensorboard PyYAML Pillow | |
| # OPTION B - Using requirements.txt: | |
| pip install -r requirements.txt | |
| # If you get permission errors, try: | |
| pip install --user -r requirements.txt | |
| # STEP 2: BASIC TRAINING (SIMPLEST WAY) | |
| # ====================================== | |
| """ | |
| Run this command to start training with default settings: | |
| """ | |
| # CPU only (slower, works everywhere): | |
| python improved_mnist_classifier.py | |
| # GPU (if you have NVIDIA GPU with CUDA): | |
| python improved_mnist_classifier.py --use-gpu | |
| # GPU with mixed precision (fastest): | |
| python improved_mnist_classifier.py --use-gpu --use-amp | |
| # STEP 3: MONITOR TRAINING (OPTIONAL) | |
| # ==================================== | |
| """ | |
| While training is running, open a NEW terminal window and run: | |
| """ | |
| tensorboard --logdir=./runs | |
| """ | |
| Then open your web browser and go to: | |
| http://localhost:6006 | |
| You'll see real-time graphs of training progress! | |
| """ | |
| # STEP 4: CUSTOMIZED TRAINING | |
| # ============================ | |
| """ | |
| You can customize many settings: | |
| """ | |
| # Train for 30 epochs instead of 20: | |
| python improved_mnist_classifier.py --epochs 30 --use-gpu | |
| # Use larger batch size (faster but needs more memory): | |
| python improved_mnist_classifier.py --batch-size 256 --use-gpu | |
| # Try fully connected network instead of CNN: | |
| python improved_mnist_classifier.py --model-type fc --use-gpu | |
| # Change learning rate: | |
| python improved_mnist_classifier.py --lr 0.0005 --use-gpu | |
| # Combine multiple options: | |
| python improved_mnist_classifier.py --epochs 25 --batch-size 256 --lr 0.001 --use-gpu --use-amp | |
| # STEP 5: AFTER TRAINING COMPLETES | |
| # ================================= | |
| """ | |
| Training will create several folders and files: | |
| checkpoints/ | |
| ├── best_model.pth ← Your trained model | |
| ├── training.log ← Training logs | |
| ├── training_history.json ← Loss and accuracy data | |
| ├── classification_report.txt ← Detailed metrics | |
| ├── training_curves.png ← Training graphs | |
| ├── confusion_matrix.png ← Error analysis | |
| └── predictions.png ← Sample predictions | |
| runs/ ← TensorBoard logs | |
| data/ ← MNIST dataset (auto-downloaded) | |
| """ | |
| # STEP 6: MAKE PREDICTIONS ON YOUR OWN IMAGES | |
| # ============================================ | |
| """ | |
| Once training is done, use your model to recognize digits! | |
| 1. Create a 28x28 grayscale image of a digit (or any size, it will be resized) | |
| 2. Run the inference script: | |
| """ | |
| # Predict a single image: | |
| python inference.py --model-path checkpoints/best_model.pth --image-path my_digit.png --use-gpu | |
| # This will show: | |
| # - The predicted digit | |
| # - Confidence score | |
| # - Probability for all 10 digits | |
| # - A visualization saved as prediction_visualization.png | |
| # FULL EXAMPLE SESSION | |
| # ===================== | |
| """ | |
| Here's a complete workflow from start to finish: | |
| """ | |
| # 1. Install packages | |
| pip install torch torchvision numpy matplotlib seaborn tqdm scikit-learn tensorboard PyYAML Pillow | |
| # 2. Train the model (this will take 5-10 minutes) | |
| python improved_mnist_classifier.py --use-gpu --epochs 20 | |
| # 3. Look at the results | |
| # - Open checkpoints/training_curves.png to see training progress | |
| # - Open checkpoints/confusion_matrix.png to see which digits are confused | |
| # - Open checkpoints/predictions.png to see sample predictions | |
| # - Read checkpoints/classification_report.txt for detailed metrics | |
| # 4. Make predictions on new images | |
| python inference.py --model-path checkpoints/best_model.pth --image-path my_digit.png | |
| # TROUBLESHOOTING COMMON ISSUES | |
| # ============================== | |
| """ | |
| Problem 1: "No module named 'torch'" | |
| Solution: Install PyTorch first | |
| """ | |
| pip install torch torchvision | |
| """ | |
| Problem 2: "CUDA out of memory" | |
| Solution: Reduce batch size | |
| """ | |
| python improved_mnist_classifier.py --batch-size 64 --use-gpu | |
| """ | |
| Problem 3: Slow on Windows with multiprocessing | |
| Solution: Set num_workers to 0 | |
| """ | |
| python improved_mnist_classifier.py --num-workers 0 | |
| """ | |
| Problem 4: "RuntimeError: DataLoader worker" | |
| Solution: Run without multiprocessing | |
| """ | |
| python improved_mnist_classifier.py --num-workers 0 | |
| """ | |
| Problem 5: Can't see TensorBoard | |
| Solution: Make sure you installed it and the port is not blocked | |
| """ | |
| pip install tensorboard | |
| tensorboard --logdir=./runs --port 6007 # Try different port | |
| """ | |
| Problem 6: Import errors | |
| Solution: Make sure all files are in the same folder | |
| """ | |
| # Put these files together: | |
| # - improved_mnist_classifier.py | |
| # - inference.py | |
| # - config.yaml | |
| # - requirements.txt | |
| # WHAT TO EXPECT | |
| # =============== | |
| """ | |
| Training output will look like this: | |
| Epoch 1/20 [Train]: 100%|████| 469/469 [00:15<00:00, Loss: 0.1234, Acc: 95.67%] | |
| [Val]: 100%|████████████████| 79/79 [00:02<00:00, Loss: 0.0987, Acc: 97.23%] | |
| Epoch 1/20 | LR: 0.001000 | |
| Train Loss: 0.1234, Acc: 95.67% | |
| Val Loss: 0.0987, Acc: 97.23% | |
| ✓ New best model saved! Val Acc: 97.23% | |
| ---------------------------------------------------------------------- | |
| ... (continues for all epochs) ... | |
| Training complete! Time: 0:05:23 | |
| Best Val Acc: 99.34% | |
| Final Test Accuracy: 99.28% | |
| Files created: | |
| - checkpoints/best_model.pth | |
| - checkpoints/training_curves.png | |
| - checkpoints/confusion_matrix.png | |
| - checkpoints/predictions.png | |
| """ | |
| # COMPLETE COMMAND REFERENCE | |
| # =========================== | |
| """ | |
| All available options: | |
| --model-type {cnn,fc} # Model architecture (default: cnn) | |
| --dropout-rate FLOAT # Dropout rate (default: 0.3) | |
| --epochs INT # Number of training epochs (default: 20) | |
| --batch-size INT # Batch size (default: 128) | |
| --lr FLOAT # Learning rate (default: 0.001) | |
| --optimizer {adam,sgd,adamw} # Optimizer (default: adamw) | |
| --weight-decay FLOAT # Weight decay (default: 0.0001) | |
| --scheduler {cosine,onecycle,step} # LR scheduler (default: onecycle) | |
| --warmup-epochs INT # Warmup epochs (default: 2) | |
| --data-dir PATH # Data directory (default: ./data) | |
| --val-split FLOAT # Validation split (default: 0.1) | |
| --num-workers INT # Data loading workers (default: 4) | |
| --early-stop-patience INT # Early stopping patience (default: 7) | |
| --use-amp # Use mixed precision training | |
| --save-dir PATH # Save directory (default: ./checkpoints) | |
| --log-dir PATH # TensorBoard logs (default: ./runs) | |
| --save-freq INT # Save checkpoint frequency (default: 5) | |
| --seed INT # Random seed (default: 42) | |
| --use-gpu # Use GPU if available | |
| """ | |
| # EXAMPLES FOR DIFFERENT SCENARIOS | |
| # ================================= | |
| # Example 1: I just want to see if it works (fastest test) | |
| python improved_mnist_classifier.py --epochs 5 | |
| # Example 2: I want the best accuracy (recommended) | |
| python improved_mnist_classifier.py --model-type cnn --epochs 20 --use-gpu | |
| # Example 3: I want it as fast as possible | |
| python improved_mnist_classifier.py --use-gpu --use-amp --batch-size 256 | |
| # Example 4: I have limited GPU memory | |
| python improved_mnist_classifier.py --use-gpu --batch-size 64 | |
| # Example 5: I only have CPU (will be slower) | |
| python improved_mnist_classifier.py --epochs 10 --num-workers 0 | |
| # Example 6: I want to experiment with different settings | |
| python improved_mnist_classifier.py --model-type fc --lr 0.01 --optimizer sgd --epochs 15 | |
| # NEXT STEPS | |
| # ========== | |
| """ | |
| After you successfully run training: | |
| 1. Compare your original model with the new CNN model | |
| 2. Try different hyperparameters (learning rate, batch size, epochs) | |
| 3. Create your own digit images and test the inference script | |
| 4. Look at the confusion matrix to see which digits are hardest | |
| 5. Check TensorBoard to understand training dynamics | |
| 6. Read COMPARISON.md to understand all the improvements | |
| 7. Modify the code to add your own ideas! | |
| """ | |
| # GETTING HELP | |
| # ============ | |
| """ | |
| If you run into issues: | |
| 1. Check the error message carefully | |
| 2. Make sure all required packages are installed | |
| 3. Try running with --num-workers 0 first | |
| 4. Check that all files are in the same directory | |
| 5. Read the README.md for detailed documentation | |
| 6. Read COMPARISON.md to understand the differences | |
| Common first-time issues: | |
| - Missing packages → pip install -r requirements.txt | |
| - CUDA errors → Don't use --use-gpu, train on CPU first | |
| - Multiprocessing errors → Add --num-workers 0 | |
| - Import errors → Check all files are in same folder | |
| """ | |
| print("Good luck with your training! 🚀") |