# CS3317 Artificial Intelligence — Coursework

This repository contains three progressive courseworks for implementing machine learning and deep learning algorithms on the **FashionMNIST** dataset.

| Coursework | Topic | Framework | Key Learning |
|---|---|---|---|
| **CW2** | Logistic Regression | NumPy | Loss functions, gradient descent |
| **CW3** | Multi-Layer Perceptron | NumPy | Backpropagation, chain rule |
| **CW4** | Convolutional Neural Network | PyTorch | CNN architectures, autograd |

## Project Structure

```
.
├── README.md
├── report_template/               # Unified report template
│   ├── report_template.tex        #   LaTeX version
│   └── report_template.docx       #   Word version
├── report_examples/               # Example reports (PDF)
│   ├── cw2_example_report.pdf
│   ├── cw3_example_report.pdf
│   └── cw4_example_report.pdf
│
└── code/                          # All source code
    ├── requirements.txt
    ├── setup_data.py              # Run first to download dataset
    ├── common/                    # Shared utilities (provided)
    ├── data/fashionmnist/         # Dataset (auto-generated)
    ├── cw2_logistic_regression/   # Coursework 2
    ├── cw3_mlp/                   # Coursework 3
    ├── cw4_cnn/                   # Coursework 4
    └── tests/                     # Gradient checking & sanity tests
```

## Setup

```bash
cd code

# Install dependencies
pip install -r requirements.txt

# Download and prepare the FashionMNIST dataset
python setup_data.py
```

## Quick Start

Each coursework has a `run.py` entry point. Use `--quick` mode for fast debugging:

```bash
cd code

# CW2
cd cw2_logistic_regression
python run.py --quick

# CW3
cd cw3_mlp
python run.py --quick

# CW4
cd cw4_cnn
python run.py --quick
```

## Dataset: FashionMNIST

10 classes of grayscale 28x28 clothing images:

| Label | Class | Label | Class |
|---|---|---|---|
| 0 | T-shirt/top | 5 | Sandal |
| 1 | Trouser | 6 | Shirt |
| 2 | Pullover | 7 | Sneaker |
| 3 | Dress | 8 | Bag |
| 4 | Coat | 9 | Ankle boot |

## Expected Performance

| Method | Test Accuracy |
|---|---|
| Logistic Regression (CW2) | ~84% |
| MLP [128, 64] (CW3) | ~88% |
| SimpleCNN (CW4) | ~91% |

## Running Tests

Gradient checking tests help verify your implementations:

```bash
# From code/ directory
python -m tests.test_cw2    # Check CW2 loss gradients
python -m tests.test_cw3    # Check CW3 layer gradients
python -m tests.test_cw4    # Check CW4 CNN shapes
```

## Estimated Running Times (CPU)

| Task | Quick Mode | Full Run |
|---|---|---|
| CW2: Single loss | < 1 min | ~5 min |
| CW3: Single config | ~2 min | ~20 min |
| CW4: SimpleCNN | ~3 min | ~15 min |

## Report

A **unified report template** is provided in `report_template/`. Choose either format:
- `report_template.tex` — LaTeX (recommended for typesetting)
- `report_template.docx` — Microsoft Word

The template contains sections for all three courseworks. Keep only the sections relevant to the CW you are submitting and delete the rest.

**Example reports** are in `report_examples/` — read them to understand the expected structure, depth, and quality:
- `cw2_example_report.pdf` — Logistic regression report example
- `cw3_example_report.pdf` — MLP & backpropagation report example
- `cw4_example_report.pdf` — CNN report example
