# Locked recipes and sensor research integration

`official_research_constrained` runs YOLO26, YOLOv8, the approximate CSPNeXt
variant and RF-DETR Small. This integrates locked upstream numerics with sensor
research overrides; it does not claim equivalence to official RGB training.
`official_default` remains gated. The CLI default is `project_adamw_pilot`.
No formal comparison study is established by integration smoke tests.

`get_recipe_spec` preserves complete package default snapshots, installed source
SHA256s and named overrides. Required versions: Ultralytics8.4.163, RF-DETR1.11.0.
Each constrained run writes `recipe_report.json` with source identity, named
parameter coverage, resolved optimizer, actual samples/epochs and warmup count.
Research training dependencies are pinned. The RF trainer's numerical helpers
are integrated into the project's own sensor loop rather than invoking Lightning.

| Recipe | Status |
| --- | --- |
| `official_default` | not_runnable |
| constrained YOLO | runnable_sensor_research_integration |
| constrained RF-DETR | runnable_sensor_research_integration |
| `project_adamw_pilot` | runnable_existing_train_py |

## Upstream numerical comparison

The installed `BaseTrainer.build_optimizer` is called unchanged. Auto selects
MuSGD(lr=.01,momentum=.9) iff `ceil(samples/max(batch,nbs))*epochs>10000`;
otherwise AdamW(lr=.002 for nc1,betas=.9/.999). Auto sets bias warmup LR zero.
Research nbs16 replaces upstream nbs64. Groups preserve official bias/norm
no-decay and weight decay policies. MuSGD preserves matrix/conv muon=.2,sgd=1
and cv3/one2one_cv3 3x LR. A parameter-preserving wrapper view exposes `.yolo`
through upstream `student_model` head access. Coverage rejects missing, duplicate
and foreign parameters. CUDA fused AdamW selection follows the official builder.

The epoch schedule is `max(1-epoch/epochs,0)*.99+.01`, stepped before each epoch
with epoch0 at full LR. Warmup iterations are `round(min(3,epochs-1)*num_batches)`;
group LRs interpolate zero to that epoch's scheduled initial LR. SGD/MuSGD
momentum interpolates .8 to trainer argument .937. Adam betas are not warmed.
YOLO26's end-to-end criterion advances once per epoch via official `update()`;
`hyp.epochs` is the run budget and resume reconstructs its update count.
Gradient clipping is10. CPU uses FP32; CUDA uses BF16 on capability8+, otherwise
scaled FP16. BF16 selection and absence of the upstream RGB AMP probe are named
runtime deviations.

## Constraints and accumulation

Requirements are size640, nominal effective16, physical batch dividing16,
1..300 epochs, patience50, mosaicFalse, warmup3, minimum LR ratio.01.
Accumulation stays fixed at `16/physical_batch` during warmup. Full windows
backpropagate upstream's raw batch-scaled YOLO loss without division by batch or
accumulation. Incomplete epoch tails multiply loss by `16/actual_window_examples`
and flush their step. This matches the loss scale of a full window but does not
create sixteen independent examples. Fixed accumulation and tail rescaling/flush
are deviations from upstream's accumulation ramp and cross-epoch pending grads.
No gradients remain at saved epoch boundaries. No distributed trainer is claimed.

## EMA, selection and resume

Installed `ModelEMA` uses decay.9999/tau2000 and updates only on successful
optimizer steps. Validation and best selection use EMA. `best.pt`'s `model` holds
EMA weights so existing evaluation/export loaders use the selected model;
`last.pt`'s `model` holds training weights. Checkpoints retain FP32 EMA/counter,
full optimizer/scaler/scheduler state, Python/NumPy/Torch/CUDA/loader RNG and
criterion update count. Pilot configuration fingerprints remain compatible.
Interruptions recover the last saved epoch and replay unfinished epochs from
saved RNG state; arbitrary mid-batch recovery is not promised.

Project original-coordinate AP50_95 selects strict improvements, with patience50.
Upstream fitness, equal-score best replacement, callbacks, OOM batch reduction
and compressed optimizer storage are not reproduced. The project's recoverable
best/last checkpoint digest publication remains in use.

## Sensor augmentation

A shared float grid transforms depth/intensity/validity and boxes with upstream
default scale[.5,1.5], translation±.1 and horizontal flip.5. Default rotation,
shear/perspective are zero. Boxes are clipped and use affine candidate thresholds
width/height>2, retained area>.1, aspect<100. Values use supported bilinear
interpolation, masks use nearest and padding is zero missing signal. This replaces
RGB114 padding, uint8/OpenCV interpolation and HSV. Sensor letterbox/normalization
and model adapters remain research components. Pilot modality/intensity/hole
perturbations are absent. `augmentation=False` disables spatial transforms.
Mosaic/mixup/cutmix/copy-paste/multi-scale remain off.

## RF-DETR integration

RF defaults are resolution512, batch4/accumulation1, epochs100, AdamW lr.0001,
encoder lr.00015, weight decay.0001, warmup0, epoch100 step decay, EMA.993/tau100
and disabled early stopping. The constrained run uses resolution640, nominal
effective16, maximum300 epochs and patience50. The installed `get_param_dict`
creates layer-decayed encoder, decoder and head groups; the sensor fusion adapter
gets a named base-lr/decay extension. Built-in AdamW uses fused kernels only on
BF16-capable CUDA, matching the upstream runtime gate. The installed managed
step scheduler advances after each successful optimizer step, with no warmup and
10x decay after 100 epochs. Full windows average per-microbatch detection losses
once, as Lightning automatic optimization does. Partial epoch tails use actual
example weighting instead of Lightning's fixed accumulation divisor. Per-image
box-count normalization remains inside the official criterion. Clip norm is .1;
precision is BF16 on supported CUDA, otherwise scaled FP16 or CPU FP32.

The installed `RFDETREMACallback` supplies the `AveragedModel` update formula,
buffer averaging and update counter. First update copies live weights, later
updates use `.993*(1-exp(-updates/100))`; only successful optimizer steps update
EMA. Checkpoints retain the callback state and counter. Validation and best/export
checkpoint selection use EMA through the common original-coordinate AP50_95
protocol. This differs from RF's two regular/EMA best tracks, optional smoothing,
skipped initial epochs and early-stopping min delta. The project's strict best
and patience50 semantics are explicit deviations.

Fixed sensor letterbox replaces RF's native direct square resize and random
resize/crop. Float depth/intensity/validity keep supported interpolation and
zero missing-signal padding; native horizontal flip probability .5 is applied
to all channels and boxes together. Scale jitter and multi-scale are disabled
for fixed640. RGB normalization, the sensor adapter and project AP evaluator
remain research components. The official RF trainer sets float32 matmul
precision `high`; the constrained loop does the same.

RF's CUDA deformable-attention backward is numerically nondeterministic here:
identical seeded first epochs produced weight differences about 1.6e-4 despite
identical RNG states, including with PyTorch deterministic algorithms requested.
The integrated resume restores exact RNG, optimizer, scheduler and EMA counters;
bit-exact GPU weights across independent runs cannot be promised. A tiny RF
interruption test confirms bit-exact state restoration where kernels permit it.
Real CUDA640 tests require final tensors within 5e-4 across independent runs.

Existing export loads the selected EMA checkpoint and can produce ONNX parity
below .003. For a random-init RF640 smoke, strict missing-mask probe parity also
failed once on four of 1200 query coordinates (maximum absolute difference .475)
after succeeding on another run. Such near-tied query order is an unresolved
ONNX inference limitation; individual export reports should be checked before
publication. This integration does not make ONNX parity a guaranteed RF property.

## Verification

Tests check source provenance/defaults, official optimizer groups, YOLO MuSGD
head boost, RF EMA/step schedule, gradient scaling, float mask/box alignment,
bit-exact toy resume and bounded real GPU resume. Real640 selected EMA checkpoint
loading and ONNX probes check mechanics, not detection quality; RF export probes
can fail strict parity as described above.

```bash
.venv/bin/python -m pytest -q tests/test_yolo_research_integration.py tests/test_rfdetr_research_integration.py tests/test_official_recipes.py tests/test_runtime_recovery.py tests/test_train_recipe_gate.py
```
