QUICKSTART.md

"""
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! 🚀")