# CS3317 AI Coursework — Code

## Setup

```bash
pip install -r requirements.txt
python setup_data.py
```

## Directory Structure

```
code/
├── requirements.txt
├── setup_data.py                  # Downloads FashionMNIST, saves as .npy
│
├── common/                        # Shared utilities (provided, do not modify)
│   ├── data_loader.py             # Data loading, batching, train/val split
│   ├── metrics.py                 # Accuracy, precision/recall/F1, confusion matrix
│   ├── visualization.py           # Training curves, confusion matrix, sample predictions
│   └── utils.py                   # Seed setting, timer, early stopping, result I/O
│
├── data/fashionmnist/             # Auto-generated by setup_data.py
│   ├── train_images.npy           # (60000, 784) float32, normalized [0,1]
│   ├── train_labels.npy           # (60000,) int64
│   ├── test_images.npy            # (10000, 784)
│   └── test_labels.npy            # (10000,)
│
├── cw2_logistic_regression/       # CW2: Logistic Regression (NumPy)
│   ├── model.py                   # ★ TODO: forward(), predict(), softmax()
│   ├── losses.py                  # ★ TODO: cross_entropy, hinge, exponential, squared
│   ├── optimizer.py               # ★ TODO: gradient descent
│   ├── trainer.py                 # Provided: training loop
│   ├── run.py                     # Provided: entry point
│   └── config.py                  # Provided: default hyperparameters
│
├── cw3_mlp/                       # CW3: MLP & Backpropagation (NumPy)
│   ├── layers.py                  # ★ TODO: Linear, ReLU, Sigmoid (forward + backward)
│   ├── model.py                   # ★ TODO: MLP assembly (forward + backward)
│   ├── losses.py                  # ★ TODO: CrossEntropyLoss (reuse CW2 logic)
│   ├── optimizer.py               # ★ TODO: SGD with momentum (extends CW2)
│   ├── trainer.py                 # Provided
│   ├── run.py                     # Provided
│   └── config.py                  # Provided
│
├── cw4_cnn/                       # CW4: CNN (PyTorch)
│   ├── model.py                   # ★ TODO: SimpleCNN, DeepCNN (nn.Module)
│   ├── dataset.py                 # Provided: PyTorch DataLoader
│   ├── trainer.py                 # Provided
│   ├── run.py                     # Provided
│   └── config.py                  # Provided
│
└── tests/                         # Sanity checks (provided)
    ├── test_cw2.py                # Numerical gradient checking for CW2 losses
    ├── test_cw3.py                # Gradient checking for CW3 layers & MLP
    └── test_cw4.py                # Shape checking for CW4 CNN
```

Files marked with ★ are what you need to implement. All other files are provided.

## Running Each Coursework

```bash
# CW2: Logistic Regression
cd cw2_logistic_regression
python run.py                          # Train with default settings
python run.py --quick                  # Fast debugging mode (10K samples)
python run.py --loss_type hinge        # Train with specific loss
python run.py --compare_all            # Compare all 4 loss functions

# CW3: MLP
cd cw3_mlp
python run.py                          # Train with default settings
python run.py --quick                  # Fast debugging mode
python run.py --hidden_dims 256 128    # Custom architecture
python run.py --sweep hidden_dim       # Hyperparameter sweep

# CW4: CNN
cd cw4_cnn
python run.py                          # Train SimpleCNN
python run.py --quick                  # Fast debugging mode
python run.py --use_augmentation       # With data augmentation
python run.py --model_type deep_cnn    # Train DeepCNN (bonus)
```

## Running Tests

Run from the `code/` directory:

```bash
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
```

## Output

Each run generates results in an `outputs/` folder within the coursework directory, including:
- `training_summary.png` — Loss and accuracy curves (include this in your report)
- `confusion_matrix.png` — Per-class prediction analysis
- `sample_predictions.png` — Example predictions with correct/incorrect labels
- `results.json` — Numerical results for further analysis
