""" QUICK START GUIDE - How to Run the Improved MNIST Classifier
Follow these steps to get started quickly! """
STEP 1: INSTALLATION
====================
"""
Make sure you have Python 3.8+ installed Check with: python --version or python3 --version
Create a new folder for your project and put all the files there:
- improved_mnist_classifier.py
- config.yaml
- requirements.txt
- inference.py
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!
- Create a 28x28 grayscale image of a digit (or any size, it will be resized)
- 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:
- Compare your original model with the new CNN model
- Try different hyperparameters (learning rate, batch size, epochs)
- Create your own digit images and test the inference script
- Look at the confusion matrix to see which digits are hardest
- Check TensorBoard to understand training dynamics
- Read COMPARISON.md to understand all the improvements
- Modify the code to add your own ideas! """
GETTING HELP
============
""" If you run into issues:
- Check the error message carefully
- Make sure all required packages are installed
- Try running with --num-workers 0 first
- Check that all files are in the same directory
- Read the README.md for detailed documentation
- 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! 🚀")