README.md

# ViT Semantic Segmentation on ADE20K

A Vision Transformer built from first principles (patch embedding, multi-head
self-attention, MLP, transformer encoder blocks) adapted for semantic
segmentation on the ADE20K dataset (150 classes), with training, evaluation,
benchmarking against published ViT segmentation models, and an evolutionary
hyperparameter search.

## Contents

- `vit-ade20k-segmentation.ipynb` — the full notebook
- `config.json` — model/training/search configuration
- `checkpoints/vit_seg_best.pt` — best model checkpoint (created after training)

## Configuration

See [`config.json`](config.json) for the exact data, model, training, and
evolutionary-search settings used to produce the results below.

## Results

### Training curves

![Training curves](training_curves.png)

Train/val loss, validation mIoU, validation pixel & mean-class accuracy, and
the learning-rate schedule.

### Inference samples

![Inference samples](inference_samples.png)

Image / ground truth / prediction, side by side, for a few validation images.

## How to reproduce

1. Install dependencies (see the first cell of the notebook).
2. Run all cells top to bottom.
3. Images (`training_curves.png`, `inference_samples.png`,
   `benchmark_comparison.png`, `evolution_fitness.png`) and `config.json`
   are written to the working directory as you go.

## Notes

- Published benchmark numbers are commonly-cited approximations from the
  original papers — verify exact figures before citing them elsewhere.
- Demo defaults (small `embed_dim`/`depth`, few epochs) are set to run
  quickly; scale up for real training.