Add PDHD/PDVD DNNROI and L1SP TorchScript models with READMEs (20260615)

DNNROI (dnn-roi/<exp>/20260615/):
- pdhd: pipe_distill_transformer_6ch.ts
- pdvd: pipe_distill_transformer_6ch.ts (from WireCell/wire-cell-data)

L1SP (l1sp/<exp>/20260615/):
- pdhd: l1sp_dnn_pdhd_v1.ts
- pdvd: l1sp_dnn_pdvd_v1.ts

Each model accompanied by its upstream README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dnn-roi/pdhd/20260615/README.pipe_distill_transformer_6ch.md

@@ -0,0 +1,65 @@
+# `pipe_distill_transformer_6ch.ts` — PDHD DNN-ROI (FP32, KD-Transformer)
+
+Single-file companion to the directory-level [`README.md`](README.md), which is
+the authoritative source for the full PDHD DNN-ROI model set, input layout,
+normalization, and tick-padding rules. This note documents only this one file.
+
+| field | value |
+|---|---|
+| file | `dnnroi/pdhd/pipe_distill_transformer_6ch.ts` |
+| size | 21,410,681 bytes (≈20.4 MB) |
+| architecture | MobileNetV3-large UNet |
+| precision | FP32 |
+| input channels | 6 |
+| output | per-pixel `sigmoid` probability in `[0, 1]` (no extra sigmoid in Wire-Cell) |
+| TorchScript mode | `torch.jit.trace` |
+| role | pipeline-reproduced FP32 distillation model |
+
+## What it is
+
+The FP32 knowledge-distillation **Transformer-teacher** student for PDHD — the
+"best distillation" leg of the end-to-end run documented in
+`DNN_ROI_SP/docs/full_pipeline.md`. Trained 6-channel on the same corpus and
+split as its sibling baseline (`pipe_base_mbv3_6ch.ts`) and its QAT INT8 model
+(`pipe_qat_transformer_6ch_int8.ts`).
+
+| metric (held-out test) | value |
+|---|---|
+| Dice / ROI-eff | 0.9107 / 0.7454 |
+| run-id | `pipe_distill_transformer_6ch` |
+| training | Transformer teacher + bottleneck-feature KD |
+
+Passes the toolkit-vs-standalone replay validation (max abs diff < 1.4e-6) —
+see `full_pipeline.md` §4.3.
+
+## Input / output
+
+C++ tensor order `(batch=1, ntags=6, nchannels, nticks)`. `nchannels = 800`
+per-plane (`pp` mode) or `1600` (U+V stacked, `mp` mode); the traced UNet is
+fully convolutional and runs at both heights. `nticks = 1500` (PDHD raw 6000
+after `tick_per_slice=4`). The 6 trace tags, in order:
+
+```
+loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss
+```
+
+All six tags come from the standard PDHD `OmnibusSigProc` chain (debug +
+multi-plane-protection mode) — no SP-config change needed. Per-channel z-scale
+normalization is **baked into the `.ts`**; run with `input_scale = 1.0`. Tick
+padding for PDHD only requires `nticks % 4 == 0`. Full details in the directory
+[`README.md`](README.md).
+
+## Run with
+
+```
+run_nf_sp_dnnroi_evt.sh -n 6
+```
+
+(then `-M dnnroi/pdhd/pipe_distill_transformer_6ch.ts` to select this `.ts`).
+Wired by `cfg/pgrapher/experiment/pdhd/dnnroi_pp.jsonnet`; loaded by the toolkit
+C++ node `DNNROIFinding`.
+
+## Limitations
+
+Trained on **APA0 only** — inference on APAs 1–3 is out-of-domain. The W plane
+is not processed (routed through a `PlaneSelector` passthrough).

dnn-roi/pdhd/20260615/pipe_distill_transformer_6ch.ts

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

dnn-roi/pdvd/20260615/README.pipe_distill_transformer_6ch.md

@@ -0,0 +1,58 @@
+# `pipe_distill_transformer_6ch.ts` — PDVD DNN-ROI (FP32, KD-Transformer)
+
+Single-file companion to the directory-level [`README.md`](README.md), which is
+the authoritative source for the full PDVD DNN-ROI model set, input layout,
+normalization, and tick-padding rules. This note documents only this one file.
+
+| field | value |
+|---|---|
+| file | `dnnroi/pdvd/pipe_distill_transformer_6ch.ts` |
+| size | 21,407,103 bytes (≈20.4 MB) |
+| architecture | MobileNetV3-large UNet |
+| precision | FP32 |
+| input channels | 6 |
+| output | per-pixel `sigmoid` probability in `[0, 1]` (no extra sigmoid in Wire-Cell) |
+| TorchScript mode | `torch.jit.trace` (re-traced 2026-05-23 at per-plane shape) |
+| role | **staged / diagnostic — not wired by default** |
+
+## What it is
+
+The FP32 knowledge-distillation **Transformer-teacher** student for PDVD,
+exported from DAGMan cluster 287 (SDCC, 2026-05-20/21). It is the
+same-architecture FP32 reference used in the §11 / §12.4 INT8-vs-FP32
+comparisons against the Transformer INT8 candidate
+(`pipe_qat_transformer_6ch_ep3_int8.ts`). It is **not** the shipped FP32
+deployable — that is `pipe_distill_nestedunet_6ch.ts` (NestedUNet teacher,
+stronger on held-out test). See the directory README's *Staged / diagnostic*
+and *Provenance* sections.
+
+| metric (400-event held-out test) | value |
+|---|---|
+| Dice | 0.7680 |
+| run-id | `pdvd_distill_transformer_6ch` |
+| checkpoint | `CP99.pth` (best-val ep 99) |
+
+## Input / output
+
+C++ tensor order `(batch=1, ntags=6, nchannels=476, nticks=1600)`, processed
+per-plane (U then V) by `DNNROIFinding`. The 6 trace tags, in order:
+
+```
+loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss
+```
+
+Per-channel z-scale normalization is **baked into the `.ts`**; run with
+`input_scale = 1.0`. Tick padding must use a multiple of
+`tick_per_slice·32 = 128`. Full details (the 5-level stride-2 cascade, the
+cross-anode-mean z-scales, the 2026-05-23 per-plane re-trace) are in the
+directory [`README.md`](README.md).
+
+## Run with
+
+```
+run_nf_sp_dnnroi_evt.sh -M dnnroi/pdvd/pipe_distill_transformer_6ch.ts
+```
+
+Wired (when selected) by
+`cfg/pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet`. Loaded by the toolkit
+C++ node `DNNROIFinding`.

dnn-roi/pdvd/20260615/pipe_distill_transformer_6ch.ts

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

l1sp/pdhd/20260615/README.md

@@ -0,0 +1,69 @@
+# `l1sp_dnn_pdhd_v1.ts` — PDHD L1SP DNN ROI tagger
+
+TorchScript (`.ts`) model loaded by the wire-cell-toolkit L1SP deep-learning
+ROI tagger for ProtoDUNE-HD. It is a **per-ROI binary classifier** (not a
+per-pixel segmentation U-Net like the `dnnroi/` models): for each candidate ROI
+it consumes a short waveform window plus 29 hand-engineered scalar features and
+emits a single `sigmoid` score in `[0, 1]`, which is cut at a default threshold
+to keep or drop the ROI.
+
+Full machine-readable spec: [`l1sp_dnn_pdhd_v1.meta.json`](l1sp_dnn_pdhd_v1.meta.json).
+
+| field | value |
+|---|---|
+| file | `l1sp/pdhd/l1sp_dnn_pdhd_v1.ts` |
+| size | 917,502 bytes (≈896 KB) |
+| task | per-ROI binary classification (keep / drop) |
+| output | `score` = `sigmoid` in `[0, 1]`, cut at `default_threshold` |
+| **default threshold** | **0.9945** |
+| precision | FP32 |
+
+## Inputs
+
+The model `forward` takes **two** tensors (C++ `Pytorch::from_itensor` 4-D
+convention, batch `B`):
+
+| input | shape | dtype | contents |
+|---|---|---|---|
+| `waveform` | `(B, 1, 2, 256)` | float32 | channel 0 = `raw/scale`, channel 1 = `decon/scale`, where `scale = max(|raw|.max, |decon|.max, 1.0)`. Window = full ROI right-padded to 256, **or** ±128 ticks centered on `argmax(|decon|)` clamped to ROI bounds. The dim-1 axis is a dummy to satisfy WCT's 4-D requirement. |
+| `scalars` | `(B, 1, 1, 29)` | float32 | the 29 scalar features in `scalar_feature_order` (see meta JSON) |
+
+`nbin = 256`, `amp_floor = 1.0`.
+
+### Scalar feature order (29)
+
+```
+nbin_fit, temp_sum, temp1_sum, temp2_sum, max_val, min_val, prev_gap, next_gap,
+flag, ratio, temp_sum_pos, temp_sum_neg, n_above_pos, n_above_neg, argmax_tick,
+argmin_tick, sig_peak, sig_integral, gmax, gauss_fill, gauss_fwhm_frac,
+roi_energy_frac, raw_asym_wide, core_lo, core_hi, core_length, core_fill,
+core_fwhm_frac, core_raw_asym_wide
+```
+
+The 30th feature (`vae_kl`, `kl_index = 29`) appears in the full
+`feature_order` but is **not** part of the model's scalar input — it is the KL
+term from the stage-B VAE (`model_n16.pt`, `vae_n_lat = 16`) used in training,
+not consumed at inference.
+
+## Output
+
+`score` of shape `(B, 1, 1, 1)`, a `sigmoid` probability in `[0, 1]`. An ROI is
+kept when `score ≥ default_threshold = 0.9945`. The threshold convention is the
+p99.9 of the data-corpus score distribution from the training run; see the
+experiment dir's `notes.md` for the promoted value.
+
+## Provenance
+
+| field | value |
+|---|---|
+| experiment dir | `/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_a_pu_round4` |
+| VAE checkpoint | `…/experiments/stage_b_vae/model_n16.pt` (`vae_n_lat = 16`) |
+| git sha | `708b942b199e2cc7395e9e3468b926b8146e171b` |
+
+## Note on the PDVD sibling
+
+`l1sp/pdvd/l1sp_dnn_pdvd_v1.ts` is the same architecture and I/O layout. The
+differences are the training corpus / detector (PDVD `stage_a_pu_round2_pdvd`)
+and a much lower `default_threshold` (**0.16** vs 0.9945 here) — the two are
+**not** interchangeable; always use the model matching the detector and its
+own threshold.

l1sp/pdhd/20260615/l1sp_dnn_pdhd_v1.ts

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

l1sp/pdvd/20260615/README.md

@@ -0,0 +1,69 @@
+# `l1sp_dnn_pdvd_v1.ts` — PDVD L1SP DNN ROI tagger
+
+TorchScript (`.ts`) model loaded by the wire-cell-toolkit L1SP deep-learning
+ROI tagger for ProtoDUNE Vertical Drift. It is a **per-ROI binary classifier**
+(not a per-pixel segmentation U-Net like the `dnnroi/` models): for each
+candidate ROI it consumes a short waveform window plus 29 hand-engineered scalar
+features and emits a single `sigmoid` score in `[0, 1]`, which is cut at a
+default threshold to keep or drop the ROI.
+
+Full machine-readable spec: [`l1sp_dnn_pdvd_v1.meta.json`](l1sp_dnn_pdvd_v1.meta.json).
+
+| field | value |
+|---|---|
+| file | `l1sp/pdvd/l1sp_dnn_pdvd_v1.ts` |
+| size | 917,502 bytes (≈896 KB) |
+| task | per-ROI binary classification (keep / drop) |
+| output | `score` = `sigmoid` in `[0, 1]`, cut at `default_threshold` |
+| **default threshold** | **0.16** |
+| precision | FP32 |
+
+## Inputs
+
+The model `forward` takes **two** tensors (C++ `Pytorch::from_itensor` 4-D
+convention, batch `B`):
+
+| input | shape | dtype | contents |
+|---|---|---|---|
+| `waveform` | `(B, 1, 2, 256)` | float32 | channel 0 = `raw/scale`, channel 1 = `decon/scale`, where `scale = max(|raw|.max, |decon|.max, 1.0)`. Window = full ROI right-padded to 256, **or** ±128 ticks centered on `argmax(|decon|)` clamped to ROI bounds. The dim-1 axis is a dummy to satisfy WCT's 4-D requirement. |
+| `scalars` | `(B, 1, 1, 29)` | float32 | the 29 scalar features in `scalar_feature_order` (see meta JSON) |
+
+`nbin = 256`, `amp_floor = 1.0`.
+
+### Scalar feature order (29)
+
+```
+nbin_fit, temp_sum, temp1_sum, temp2_sum, max_val, min_val, prev_gap, next_gap,
+flag, ratio, temp_sum_pos, temp_sum_neg, n_above_pos, n_above_neg, argmax_tick,
+argmin_tick, sig_peak, sig_integral, gmax, gauss_fill, gauss_fwhm_frac,
+roi_energy_frac, raw_asym_wide, core_lo, core_hi, core_length, core_fill,
+core_fwhm_frac, core_raw_asym_wide
+```
+
+The 30th feature (`vae_kl`, `kl_index = 29`) appears in the full
+`feature_order` but is **not** part of the model's scalar input — it is the KL
+term from the stage-B VAE (`model_n16.pt`, `vae_n_lat = 16`) used in training,
+not consumed at inference.
+
+## Output
+
+`score` of shape `(B, 1, 1, 1)`, a `sigmoid` probability in `[0, 1]`. An ROI is
+kept when `score ≥ default_threshold = 0.16`. The threshold convention is the
+p99.9 of the data-corpus score distribution from the training run; see the
+experiment dir's `notes.md` for the promoted value.
+
+## Provenance
+
+| field | value |
+|---|---|
+| experiment dir | `/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_a_pu_round2_pdvd` |
+| VAE checkpoint | `…/experiments/stage_b_vae/model_n16.pt` (`vae_n_lat = 16`) |
+| git sha | `cd038ae0da106fd215a54a061824daa835f05fc6` |
+
+## Note on the PDHD sibling
+
+`l1sp/pdhd/l1sp_dnn_pdhd_v1.ts` is the same architecture and I/O layout. The
+differences are the training corpus / detector (PDHD `stage_a_pu_round4`) and a
+much higher `default_threshold` (**0.9945** vs 0.16 here) — the two are **not**
+interchangeable; always use the model matching the detector and its own
+threshold.

l1sp/pdvd/20260615/l1sp_dnn_pdvd_v1.ts

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