<!-- examples/README-lw-detr.md -->

# LW-DETR mathematical reference

Run `python3 examples/lw_detr.py` from the repository root. No installation,
network, GPU, checkpoint or third-party package is required. The default
entrypoint is `lw_detr.py`; it prints JSON to stdout and creates no output file.
The dependency receipt is `requirements-lwDetr.txt`.

This authored deterministic reference calculates window-major permutations and
their inverse, structural local/global reach and ordered attention-pair counts,
projector output geometry, grouped-query budgets and IoU-aware BCE forward values.
It does not run attention, C2f, proposal ranking, Hungarian matching, training,
inference or TensorRT. All attention counts include diagonal pairs per head and
exclude projections, FFNs and memory movement. Exact divisible grids are required;
there is no implicit padding or claim that arbitrary shapes are upstream configs.

`windows`, `connectivity`, `projector`, `queries` and `loss` are the five excerpt
keys. The repository's sourceRegions parser requires `# region: NAME` and
`# endregion: NAME` (including the colon). The owning sync workflow generates
`src/data/lwDetrCode.mjs` with `lwDetrCode` and `lwDetrTokens`, and public downloads.
Do not hand-edit those generated files.

Run `node --test test/lwDetr*.test.mjs` for mathematical and Python parity checks.
Tiny uses 100 queries; other variants use 300. Training has 13 groups sharing
weights, inference one. Tiny/small/medium produce stride-16 features; large/xlarge
produce stride-8 and stride-32 features. Depth aggregation itself retains the
encoder grid. Loss arithmetic follows the paper's equations, without reproducing
implementation-specific detached targets, normalization, reductions or gradients.
Endpoints use extended-real BCE, with `0 log 0 = 0`.

Sources: [paper v1, §3 and Tables 1–3](https://arxiv.org/html/2406.03459v1),
[official implementation](https://github.com/Atten4Vis/LW-DETR), especially
`models/backbone/vit.py` and `models/lwdetr.py`. No pretrained output or new
latency/AP measurement is included. Published T4 FP16 TensorRT results must not
be inferred from these CPU calculations.
