# PyTorch model programme

The complete execution plan, work packages and release gates are maintained in
`docs/PYTORCH_TRAINING_ROADMAP_BELGIUM.md`.

## Principle

PyTorch is the governed CUDA runtime for trainable image models. It is not a
replacement for authoritative GIS processing. Terrain, flood depth, land-use
classes, road length, water area and vector/raster change remain deterministic
source-derived analyses.

## Capability matrix

| Capability | Method | Current state | Promotion requirement |
|---|---|---|---|
| Building localisation | YOLO detection on orthophoto | Operational for `building`; validated only in Mol/Kempen | geographically independent Belgian train/validation/test portfolio, including Flanders, Wallonia and Brussels |
| Building footprint | official GRB/PICC/URBIS geometry | Operational where the governed source covers the AOI | no neural model; source coverage and freshness gates |
| Roads and water | official vectors and thematic rasters | Operational by provider zone | no detector unless a separately justified imagery use case and reviewed labels exist |
| Land use / vegetation | official classified rasters | Operational where source coverage exists | no neural model; preserve official class semantics |
| Terrain / flood / bathymetry | numeric raster analysis | Operational or explicit `not_configured` per source | no neural model; source and CRS validation |
| Solar panels or other imagery objects | dedicated detector | Unvalidated local asset only | task-specific labels, negative corpus, independent hold-outs and promotion report |
| Segmentation | dedicated YOLO-seg/SAM model | `not_configured` | reviewed polygon/mask corpus and segmentation QA; detection boxes are not valid mask labels |

## Training rules

1. One model contract per task and canonical class set.
2. Training, validation and test samples are separated geographically; an AOI
   or overlapping image tile may occur in only one split.
3. Reference labels identify authority, source, layer, observation/publication
   date, CRS and checksum.
4. Production training requires NVIDIA CUDA and fails closed when unavailable.
5. Every challenger is evaluated on positive AOIs, pure-empty negatives and
   difficult contextual negatives. Promotion is never based on training loss.
6. A model remains `not_configured` outside its independently proven geography
   and classes.

## Executable waves

1. **Building Belgium corpus:** prepare spatially disjoint samples from GRB
   (Flanders), PICC (Wallonia) and URBIS (Brussels) against temporally compatible
   orthophotos. Keep complete municipalities outside training as test areas.
2. **Building challenger:** train on Tower using PyTorch CUDA, compare against
   the active model at fixed thresholds and retain the current model unless all
   promotion gates pass.
3. **Additional imagery task intake:** admit solar panels or another class only
   after an explicit use case and reviewed labels exist. Never infer new classes
   from the building corpus.
4. **Segmentation intake:** build a polygon/mask corpus and independent QA before
   enabling YOLO-seg or SAM.

The tile exporter accepts explicit `--class-name`, `--reference-source` and
`--reference-layer` values and records them in dataset evidence. The production
training wrapper supports `TRAIN_REQUIRE_CUDA=true` and records CUDA and PyTorch
runtime evidence in every training summary.