# QAT training source for the inblick YOLOv8n models

This is the source code that trained and exported the weights in this repository, published
under **AGPL-3.0** (see `LICENSE`) as the corresponding source of the AGPL-3.0 weights. It is a
snapshot of the training and export path of the inblick project's `cnnc` compiler (commit
`86f249d`).

## What is included

| Path | What |
|---|---|
| `cnnc/export/qat.py` | `QdqNet`: runs the PTQ `qdq.onnx` graph node by node in PyTorch with straight-through fake quantisation that matches the accelerator's int8 arithmetic; writes the trained values back into the QDQ graph |
| `cnnc/export/qat_train.py` | the CLI: `prep-coco`, `prep-crowd`, `crowd-init`, `fp32-train`, `train` (QAT), `export`, `eval` |
| `cnnc/export/yolov8n.py`, `quantize.py`, `coco.py`, `constraints.py`, `preprocess.py` | the YOLOv8n export (PyTorch → ONNX → int8 QDQ with onnxruntime static quantisation) and its constraint checks |
| `cnnc/frontend/qdq_graph.py`, `qdq_math.py` | QDQ ONNX graph reading and the quantisation maths |
| `cnnc/accuracy/coco_map.py`, `heads.py`, `ort_ref.py` | COCO mAP evaluation and the onnxruntime reference used for checkpoint selection |
| `cnnc/target/` | **a stub**: the export reads one value of the accelerator target, `activation_plane_channels = 16`. The full compiler derives it from the accelerator's own constants, which are not published here. |
| `requirements-train.txt` | the training environment (CUDA PyTorch for an RTX 5090, Ultralytics 8.4.164) |
| `doc/qat.md`, `doc/qat-design.md` | how to reproduce the training, and the int8 arithmetic mapping |

**Not included:** the rest of the inblick compiler (the hardware backend, scheduling and the golden
model of the accelerator). The functions in `cnnc/accuracy/heads.py` that compile a network and run it
on that golden model therefore don't work in this snapshot. They are only used for the bit-exact
verification gates, not for training, export or mAP evaluation.

## Running it

```sh
uv venv .venv-train --python 3.13
uv pip install --python .venv-train/bin/python -r requirements-train.txt
export PYTHONPATH=$PWD YOLO_AUTOINSTALL=False
.venv-train/bin/python -m cnnc.export.qat_train --help
```

The full recipe for both models (data preparation, the PTQ template export, QAT, export and
evaluation) is in `doc/qat.md`. The exact hyper-parameters and results are in each model folder's
`README.md` and `metrics.json`.

## Licence

This code is released under the GNU Affero General Public License v3.0 (`LICENSE`). It builds on
Ultralytics YOLOv8 (AGPL-3.0). The CrowdHuman-trained model is also subject to the CrowdHuman
dataset's non-commercial research terms: see `../LICENSE-NOTICE.md`.