This repository demonstrates deep learning techniques for image classification using the CIFAR-10 benchmark dataset. Through a series of progressively more sophisticated models, it shows how different neural network architectures and training techniques improve classification performance.

The tools developed for this project are available via PyPI for use in your own projects.

• PyPi package: image-classification-tools
• Documentation: gperdrizet.github.io/CIFAR10
• Models: Pre-trained models are available on HuggingFace

CIFAR-10 consists of 60,000 32×32 color images across 10 classes:

• Training set: 50,000 images (40,000 for training, 10,000 for validation)
• Test set: 10,000 images
• Classes: airplane, automobile, bird, cat, deer, dog, frog, horse, ship, truck

1. 01-DNN.ipynb - Baseline fully-connected deep neural network on grayscale images
2. 02-CNN.ipynb - Convolutional neural network to exploit spatial relationships
3. 03-RGB-CNN.ipynb - CNN modified to process full RGB color information
4. 04-architecture_optimization.ipynb - Optuna optimization of CNN architecture (conv blocks, filters, dropout)
5. 05-training-optimization.ipynb - Optuna optimization of training hyperparameters (optimizer, learning rate, weight decay)
6. 06-augmented-CNN.ipynb - Optimized architecture + training with data augmentation
7. 07-resnet50.ipynb - Transfer learning with pre-trained ResNet50
8. 08-results.ipynb - Model comparison and performance analysis

• Docker
• Visual Studio Code
• Dev Containers extension
• Optional: NVIDIA GPU with drivers ≥545 (for GPU configuration)

1. Clone this repository:

git clone https://github.com/gperdrizet/CIFAR10.git

2. Open the repository directory in VS Code

3. When prompted, choose your configuration:

   • DeepLearning GPU: For Linux/WSL2 with NVIDIA GPU (recommended for training)
   • DeepLearning CPU: For Mac or machines without GPU (suitable for code development and testing)

4. Click "Reopen in Container" or use the command palette (Ctrl+Shift+P / Cmd+Shift+P) and select "Dev Containers: Reopen in Container"

5. Wait for the container to build and initialize (first time only). The devcontainer will:

   • Set up the Python environment
   • Install all dependencies (GPU or CPU version of PyTorch)
   • Download the CIFAR-10 dataset

Note: The CPU configuration works on any machine but training will be significantly slower (10-50x). It's perfect for following along with the material without a GPU. See .devcontainer/README.md for more details.

Once the container environment loads, you can start running the notebooks!

Training control: Each notebook has parameters to control whether to train or load existing models:

• retrain_model = True (default): Train a new model
• retrain_model = False: Load an existing model (from local disk or Hugging Face Hub)
• model_source = 'local' or 'huggingface': Choose where to load from

Note: Run notebooks in order - some depend on output generated by earlier notebooks.

Each notebook includes optional Hugging Face Hub integration to share your trained models:

1. Copy .env.template to .env and add your repository details
2. Create a Hugging Face account at huggingface.co
3. Run huggingface-cli login in the terminal and enter your access token
4. Set upload_to_hf = True in the upload cells

Note: Students can download pre-trained models from the default repository (gperdrizet/CIFAR10) without any setup by setting retrain_model=False and model_source='huggingface'.

See HUGGINGFACE.md for detailed setup instructions.

This project uses Dev Containers with two configurations to support both GPU and CPU-only machines:

GPU Configuration (recommended for training):

• Based on deeplearning-GPU template
• Pre-installed PyTorch with CUDA 12.6 support
• Works with any NVIDIA GPU from GTX 1050 to RTX 5090 (Pascal architecture and newer)
• Requires: Linux/WSL2, NVIDIA drivers ≥545, Docker with GPU support

CPU Configuration (for Mac and non-GPU machines):

• Based on Microsoft's Python 3.10 devcontainer
• PyTorch CPU-only (auto-installed)
• Works on any machine (Mac, Windows, Linux)
• Good for code development, testing, and learning without GPU

Why use this setup?

• Zero configuration: CUDA, cuDNN, and ML frameworks are pre-installed
• Cross-platform: Identical environment across different machines
• Reproducible: Everyone gets the exact same dependencies
• Flexible: Choose GPU or CPU based on your hardware

The code automatically detects your hardware, so both configurations work seamlessly. Training on CPU will be slower but still functional.

Core requirements:

• python ≥3.10, <3.13
• torch ≥2.0
• torchvision ≥0.15
• numpy ≥1.24, <2.0
• matplotlib ≥3.7
• optuna ≥3.0
• scikit-learn ≥1.3

If you find this project helpful for your learning or work, feel free to reference it:

@software{cifar10_tutorial,
  author = {Perdrizet, George},
  title = {CIFAR-10 Image Classification Tutorial},
  year = {2024},
  url = {https://github.com/gperdrizet/CIFAR10}
}

This project is licensed under the GPLv3 License - see the LICENSE file for details.