add trained checkpoints, results and model card

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+results/pet_samples.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,148 @@
+---
+license: mit
+library_name: timm
+pipeline_tag: image-classification
+base_model: timm/vit_base_patch16_224.augreg_in21k_ft_in1k
+datasets:
+  - timm/oxford-iiit-pet
+tags:
+  - lora
+  - parameter-efficient-fine-tuning
+  - vision-transformer
+  - pytorch
+metrics:
+  - accuracy
+---
+
+# LoRA Fine-Tuning of ViT-B/16 on Oxford-IIIT Pets
+
+Trained checkpoints for [github.com/headless-start/peft-lora-vit](https://github.com/headless-start/peft-lora-vit),
+a hand-written LoRA implementation on a frozen ViT-B/16 (`vit_base_patch16_224`, timm).
+LoRA matrices are added to the attention query and value projections
+(`alpha = 2r`, `B` initialised to zero) and only they and the classification
+head are trained.
+
+The repository holds every checkpoint behind the results in the GitHub README:
+the headline run, the linear-probe / LoRA / full fine-tuning comparison, the
+placement study and the rank study. Code, training scripts and figures live on GitHub.
+
+![Dataset samples](results/pet_samples.png)
+
+## Results
+
+Top-1 accuracy on the Oxford-IIIT Pets test split (3,669 images, 37 breeds).
+
+**Headline run** (LoRA rank 8 on q and v, 25 epochs): **95.2%** with 323K trainable
+parameters out of 86.1M (0.38%). File: `checkpoints/best.pt`.
+
+### Baselines
+
+| Method | Accuracy | Trainable parameters | Checkpoint file | Size |
+|---|---|---|---|---|
+| Linear probe | 93.5% | 28K (0.03%) | `checkpoints/best_head.pt` | 0.1 MB |
+| LoRA r=8, q+v | **94.9%** | 323K (0.38%) | `checkpoints/best_lora.pt` | 1.3 MB |
+| Full fine-tuning | 93.9% | 85.8M (100%) | `checkpoints/best_full.pt` | 343 MB |
+
+![Baselines](results/baselines.png)
+
+### Placement study (rank 8)
+
+| Placement | Accuracy | Trainable parameters | Checkpoint file |
+|---|---|---|---|
+| q | 94.3% | 176K | `checkpoints/best_r8_q.pt` |
+| k | 94.1% | 176K | `checkpoints/best_r8_k.pt` |
+| v | 94.7% | 176K | `checkpoints/best_r8_v.pt` |
+| q + k | 94.3% | 323K | `checkpoints/best_r8_qk.pt` |
+| q + v | **94.9%** | 323K | `checkpoints/best_r8_qv.pt` |
+| q + k + v | 94.7% | 471K | `checkpoints/best_r8_qkv.pt` |
+
+![Placement study](results/placement.png)
+
+### Rank study (q + v)
+
+| Rank | Accuracy | Trainable parameters | Checkpoint file |
+|---|---|---|---|
+| 4 | 94.8% | 176K | `checkpoints/best_r4_qv.pt` |
+| 8 | 94.9% | 323K | `checkpoints/best_r8_qv.pt` |
+| 16 | 94.6% | 618K | `checkpoints/best_r16_qv.pt` |
+| 32 | 94.9% | 1.21M | `checkpoints/best_r32_qv.pt` |
+
+![Rank study](results/ablation.png)
+
+### Notes on the numbers
+
+- `best_lora.pt` and `best_r8_qv.pt` are the same weights; the same run appears in
+  the baseline, placement and rank tables.
+- `best.pt` (95.2%) is a separate run of the same configuration. The 0.3-point gap
+  to 94.9% is the run-to-run variation described in the GitHub README.
+- Every number is a single run with seed 42. Each checkpoint is the epoch with the
+  highest accuracy on the test split, which is also the split reported here, so
+  the figures are best-epoch results rather than estimates from a held-out validation set.
+- All checkpoints were re-evaluated on the test split before upload and reproduce the stored accuracies.
+
+## Files
+
+```text
+checkpoints/
+  best.pt              headline run, LoRA r=8 on q+v
+  best_head.pt         linear probe (classification head only)
+  best_lora.pt         LoRA r=8 on q+v, as used in the comparison tables
+  best_full.pt         full fine-tuning (all weights)
+  best_r8_<placement>.pt   placement study
+  best_r<rank>_qv.pt       rank study
+results/               the JSON results and figures from the GitHub repository
+```
+
+The LoRA and linear-probe checkpoints store only the trained tensors (LoRA
+matrices and head); the frozen backbone comes from the public timm weights.
+`best_full.pt` stores the whole network. Every file is a PyTorch dictionary
+with the keys `model`, `epoch` and `val_acc`.
+
+## Usage
+
+Clone the code, download a checkpoint and run the prediction script:
+
+```bash
+git clone https://github.com/headless-start/peft-lora-vit.git
+cd peft-lora-vit
+pip install -r requirements.txt
+
+hf download headless-start/peft-lora-vit checkpoints/best.pt --local-dir .
+python predict.py path/to/pet.jpg --ckpt checkpoints/best.pt
+```
+
+For another LoRA checkpoint pass its rank and placement, for example
+`--ckpt checkpoints/best_r16_qv.pt --lora-r 16` or
+`--ckpt checkpoints/best_r8_k.pt --placement k`.
+
+In Python:
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from predict import load_model
+
+path = hf_hub_download("headless-start/peft-lora-vit", "checkpoints/best.pt")
+model = load_model(path, "vit_base_patch16_224", r=8, alpha_factor=2,
+                   device=torch.device("cpu"), placement="qv")
+```
+
+Inputs are RGB images resized to 256, centre-cropped to 224 and normalised with
+ImageNet statistics (`build_transforms` in `src/data.py`).
+
+## Training setup
+
+| Setting | Value |
+|---|---|
+| Backbone | `vit_base_patch16_224` (timm, ImageNet pretrained), frozen for LoRA and the linear probe |
+| Data | Oxford-IIIT Pets, `trainval` split for training, `test` split for evaluation |
+| Epochs | 25 |
+| Optimiser | AdamW, learning rate 3e-4 (3e-5 for full fine-tuning), weight decay 0.05 |
+| Schedule | 2 warmup epochs, then cosine decay to 1e-7 |
+| Batch size | 64 (16 for full fine-tuning) |
+| Other | mixed precision, drop-path 0.1, random resized crop and horizontal flip |
+
+## Licence
+
+Released under the MIT licence, as is the code. The pretrained backbone is
+Apache-2.0 and Oxford-IIIT Pets is CC BY-SA 4.0; their terms continue to apply.

checkpoints/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5bc0e71268fe7240473f7283cfb877bea169f3a465d915a9eef2c407ad95b779
+size 1309645

checkpoints/best_full.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37dfab4415663792f15786c71e259a6e9035a5fd44a08d88f1dbbe0568e993d4
+size 343356619

checkpoints/best_head.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e10e79b57066bca08495834431ab4d85e91be1c119233777be33b5ae7b0d6c6
+size 115765

checkpoints/best_lora.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:331f8b5eeb057ad726c84ec404d4e8606971f0e8cc7c90e6a62c4bff9b36654d
+size 1310333

checkpoints/best_r16_qv.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7c8616f8c3d987b1a392be0aa272f27a69bfb6552f4ca319e7522c3f15df0c70
+size 2490093

checkpoints/best_r32_qv.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f58a6dee8264d39944b06fe76fd057eed29ba0c629fa62137c78da7f37e6488a
+size 4849389

checkpoints/best_r4_qv.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af70ae6e7010db860e9cd3f3c254bbcc0acc658374e1f38e36a937be711eb671
+size 720565

checkpoints/best_r8_k.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5134da558f4c31785e0a914745e2bf70a28f8104868611203cc0b5c0f0811390
+size 712725

checkpoints/best_r8_q.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dfd69e142156e9f3ec7c6a4ae5dbbd94dc47a97a20bb8cc7df35f7e315b1f789
+size 712725

checkpoints/best_r8_qk.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d267261f6bb11b2de07e20de0e0e0b2cbb1256ab309deb4adb87be1314ba2cac
+size 1310389

checkpoints/best_r8_qkv.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9426fa4949649844f52db4daa4fcec143a7a0621661503f11801954dfc2b76c8
+size 1908101

checkpoints/best_r8_qv.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bce4374b5cb50af48a75e46a55b0420125c34982260c01f7b3d6687480fa5844
+size 1310389

checkpoints/best_r8_v.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8ebac657298058652deb78d68f41e7fbc1ca7b54ea0517afe67ce09ca4f97d89
+size 712725

results/ablation.json

@@ -0,0 +1,30 @@
+[
+  {
+    "r": 4,
+    "placement": "qv",
+    "top1_acc": 0.9479,
+    "trainable_params": 175909,
+    "trainable_pct": 0.205
+  },
+  {
+    "r": 8,
+    "placement": "qv",
+    "top1_acc": 0.9488,
+    "trainable_params": 323365,
+    "trainable_pct": 0.375
+  },
+  {
+    "r": 16,
+    "placement": "qv",
+    "top1_acc": 0.946,
+    "trainable_params": 618277,
+    "trainable_pct": 0.715
+  },
+  {
+    "r": 32,
+    "placement": "qv",
+    "top1_acc": 0.949,
+    "trainable_params": 1208101,
+    "trainable_pct": 1.389
+  }
+]

results/baselines.json

@@ -0,0 +1,29 @@
+[
+  {
+    "method": "head",
+    "top1_acc": 0.9351,
+    "trainable_params": 28453,
+    "trainable_pct": 0.033,
+    "ckpt_mb": 0.1,
+    "epoch_sec": 19.7,
+    "peak_vram_gb": 0.66
+  },
+  {
+    "method": "lora",
+    "top1_acc": 0.9488,
+    "trainable_params": 323365,
+    "trainable_pct": 0.375,
+    "ckpt_mb": 1.2,
+    "epoch_sec": 30.8,
+    "peak_vram_gb": 3.73
+  },
+  {
+    "method": "full",
+    "top1_acc": 0.9392,
+    "trainable_params": 85827109,
+    "trainable_pct": 100.0,
+    "ckpt_mb": 327.5,
+    "epoch_sec": 40.6,
+    "peak_vram_gb": 2.49
+  }
+]

results/metrics.json

@@ -0,0 +1,14 @@
+{
+  "backbone": "vit_base_patch16_224",
+  "dataset": "oxford_pets",
+  "epochs": 25,
+  "top1_acc": 0.9518,
+  "trainable_params": 323365,
+  "total_params": 86122021,
+  "trainable_pct": 0.375,
+  "lora": {
+    "r": 8,
+    "alpha_factor": 2,
+    "dropout": 0.0
+  }
+}

results/placement.json

@@ -0,0 +1,44 @@
+[
+  {
+    "r": 8,
+    "placement": "q",
+    "top1_acc": 0.943,
+    "trainable_params": 175909,
+    "trainable_pct": 0.205
+  },
+  {
+    "r": 8,
+    "placement": "k",
+    "top1_acc": 0.9411,
+    "trainable_params": 175909,
+    "trainable_pct": 0.205
+  },
+  {
+    "r": 8,
+    "placement": "v",
+    "top1_acc": 0.9471,
+    "trainable_params": 175909,
+    "trainable_pct": 0.205
+  },
+  {
+    "r": 8,
+    "placement": "qk",
+    "top1_acc": 0.943,
+    "trainable_params": 323365,
+    "trainable_pct": 0.375
+  },
+  {
+    "r": 8,
+    "placement": "qv",
+    "top1_acc": 0.9488,
+    "trainable_params": 323365,
+    "trainable_pct": 0.375
+  },
+  {
+    "r": 8,
+    "placement": "qkv",
+    "top1_acc": 0.9466,
+    "trainable_params": 470821,
+    "trainable_pct": 0.546
+  }
+]