tidy up dnn-roi description; add .json for l1sp

dnn-roi/pdhd/20260615/README.md

@@ -1,120 +0,0 @@
-# PDHD DNN-ROI TorchScript models
-
-TorchScript (`.ts`) models loaded by the wire-cell-toolkit DNN-ROI nodes
-(`DNNROIFinding` / `DNNROIFindingMultiPlane`). All are exported with
-`DNN_ROI_SP/scripts/to_torchscript.py` and output `sigmoid` probabilities
-in `[0, 1]` (no extra sigmoid needed in Wire-Cell).
-
-| file | input ch | precision | size | run with |
-|---|---|---|---|---|
-| `CP43.ts` | 3 | FP32 | 20.4 MB | `run_nf_sp_dnnroi_evt.sh -n 3` (default) |
-| `kd_mbv3_transformer_bnKD_6ch.ts` | 6 | FP32 | 20.4 MB | `run_nf_sp_dnnroi_evt.sh -n 6` |
-| `qat_mbv3_transformer_bnKD_6ch_int8.ts` | 6 | INT8 (QAT) | 10.8 MB | `run_nf_sp_dnnroi_evt.sh -n 6 -D cpu` |
-| `pipe_base_mbv3_6ch.ts` | 6 | FP32 | 20.4 MB | `run_nf_sp_dnnroi_evt.sh -n 6` |
-| `pipe_distill_transformer_6ch.ts` | 6 | FP32 | 20.4 MB | `run_nf_sp_dnnroi_evt.sh -n 6` |
-| `pipe_qat_transformer_6ch_int8.ts` | 6 | INT8 (QAT) | 10.8 MB | `run_nf_sp_dnnroi_evt.sh -n 6 -D cpu` |
-
-## Provenance
-
-| field | `CP43.ts` | `kd_..._6ch.ts` | `qat_..._6ch_int8.ts` |
-|---|---|---|---|
-| Architecture | MobileNetV3-large UNet | MobileNetV3-large UNet | QuantizableMobileNetV3-UNet, INT8 |
-| Source repo | `DNN_ROI_SP/` | `DNN_ROI_SP/` | `DNN_ROI_SP/` |
-| Run-id | `bs1_20260511-210525` | `distill_mbv3_transformer_bnKD_6ch_th150_ep100_l40s_ddp2` | `qat_distill_mbv3_transformer_bnKD_6ch_th150_ep20_l40s_ddp2` |
-| Checkpoint | `CP43.pth` | `CP70.pth` | `qat_int8_state.pth` |
-| Training | 3-ch baseline | Transformer teacher + bottleneck-feature KD | QAT-KD-C, warm-started from `CP70.pth` |
-| TorchScript mode | trace | trace | trace |
-| Held-out test Dice / ROI-eff | — | 0.9118 / 0.7609 | 0.8932 / 0.7274 |
-
-`to_torchscript.py` falls back to `torch.jit.trace` because `torch.jit.script`
-hits the `break` in the encoder loop; the INT8 quantized graph also cannot be
-scripted. The traced UNets are fully convolutional and run at both the
-per-plane (`800`) and stacked (`1600`) channel heights.
-
-### Pipeline-reproduced models (2026-05-16)
-
-`pipe_base_mbv3_6ch.ts`, `pipe_distill_transformer_6ch.ts`, and
-`pipe_qat_transformer_6ch_int8.ts` are the three models deployed by the
-end-to-end run documented in `DNN_ROI_SP/docs/full_pipeline.md` — a baseline,
-the best distillation, and its QAT INT8 model, all 6-channel and trained on the
-same corpus and split.
-
-| field | `pipe_base_mbv3_6ch.ts` | `pipe_distill_transformer_6ch.ts` | `pipe_qat_transformer_6ch_int8.ts` |
-|---|---|---|---|
-| Architecture | MobileNetV3-large UNet | MobileNetV3-large UNet | QuantizableMobileNetV3-UNet, INT8 |
-| Run-id | `pipe_base_mbv3_6ch` | `pipe_distill_transformer_6ch` | `pipe_qat_transformer_6ch` |
-| Training | 6-ch baseline, no KD | Transformer teacher + bottleneck-feature KD | QAT-KD, warm-started from the distillation |
-| Held-out test Dice / ROI-eff | 0.9120 / 0.7474 | 0.9107 / 0.7454 | 0.8900 / 0.7305 |
-
-All three pass the toolkit-vs-standalone replay validation (max abs diff
-< 1.4e-6; the INT8 model bit-exact) — see `full_pipeline.md` §4.3.
-
-## Input layout
-
-C++ tensor order is `(batch=1, ntags, nchannels, nticks)`:
-
-- `nchannels` = `800` per plane in per-plane (`pp`) mode, or `1600`
-  (U+V stacked) in stacked (`mp`) mode. The W collection plane is not consumed.
-- `nticks` = `1500`, from PDHD's raw `6000` after `tick_per_slice=4`
-  downsampling inside the C++ node.
-
-**3-channel model** (`CP43.ts`) — `ntags=3`, in order:
-
-```
-loose_lf{APA}, mp2_roi{APA}, mp3_roi{APA}
-```
-
-**6-channel models** — `ntags=6`, in order:
-
-```
-loose_lf{APA}, mp2_roi{APA}, mp3_roi{APA}, tight_lf{APA}, decon_charge{APA}, gauss{APA}
-```
-
-All six tags are emitted by the standard PDHD `OmnibusSigProc` chain
-(debug + multi-plane-protection mode) and require no SP-config change.
-
-## Per-channel normalization (6-ch models)
-
-The 6-ch models are trained on inputs divided by **per-channel** z-scales:
-
-```
-[944.6256, 4000.0, 4000.0, 803.7348, 1927.6997, 530.75]
-```
-
-Wire-Cell's `DNNROIFinding` can only apply one **scalar** `input_scale` to all
-channels, so the per-channel division is **baked into the `.ts` module** as a
-fixed normalization layer. Consequently the 6-ch models must run with
-`input_scale = 1.0` — the `run_nf_sp_dnnroi_evt.sh -n 6` path sets this
-automatically (`dnnroi_pp.jsonnet`). `CP43.ts` keeps the C++ default
-`input_scale = 1/4000`.
-
-## Tick padding
-
-The C++ node rebins the time axis by `tick_per_slice=4` before inference and
-needs the input tick count to be a multiple of the model's stride alignment.
-For the PDHD MobileNetV3-large UNet (no deep stride-2 cascade in the tick
-axis: post-rebin width 1500 = 4·375 is not divisible by 8 or higher powers
-of 2), the alignment requirement is just `nticks % tick_per_slice == 0`,
-i.e. **`nticks` must be a multiple of 4**. PDHD's standard `nticks=6000`
-satisfies this with no padding.
-
-The `dnnroi_pp.jsonnet` for PDHD leaves `tick_pad_multiple` unset (defaults
-to `tick_per_slice=4`). The C++ node pads to the next 4-multiple before
-inference, then crops back to `input_ticks` — a no-op for any
-`nticks % 4 == 0` (including 6000, 6400, 8000).
-
-## Consumer
-
-Loaded by the toolkit C++ node `DNNROIFinding` (per-plane sequential: U
-and V each run their own forward call sharing one TorchService). Wired by
-`cfg/pgrapher/experiment/pdhd/dnnroi_pp.jsonnet`; driven by
-`wcp-porting-img/pdhd/run_nf_sp_dnnroi_evt.sh` (`-n 3|6` selects the
-input-channel set, `-M <model>` selects the `.ts`).
-
-## Limitations
-
-- Trained on **APA0 only**. Inference on APAs 1–3 is out-of-domain.
-- W plane is not processed; downstream jsonnet routes it through a
-  `PlaneSelector` passthrough.
-- The INT8 QAT model runs on **CPU only** (x86/fbgemm quantized backend);
-  it cannot be placed on a GPU device.

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

@@ -1,65 +0,0 @@
-# `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.md

@@ -0,0 +1,123 @@
+# PDHD DNN-ROI — `pipe_distill_transformer_6ch.ts`
+
+TorchScript (`.ts`) DNN-ROI model for ProtoDUNE-HD (PDHD), loaded by the
+wire-cell-toolkit DNN-ROI node `DNNROIFinding`. It produces a per-pixel
+region-of-interest (ROI) probability map used to gate signal-processing output.
+
+| field | value |
+|---|---|
+| file | `dnnroi/pdhd/pipe_distill_transformer_6ch.ts` |
+| architecture | MobileNetV3-large UNet |
+| precision | FP32 |
+| input channels (tags) | 6 |
+| output | per-pixel `sigmoid` probability in `[0, 1]` (no extra sigmoid needed in Wire-Cell) |
+| TorchScript mode | `torch.jit.trace` |
+| size | ≈20.4 MB (21,410,681 bytes) |
+
+## 1. How the model was trained
+
+- **Architecture:** MobileNetV3-large UNet, exported to TorchScript with
+  `torch.jit.trace`. (`torch.jit.script` is not used because the encoder loop
+  contains a `break` that the scripter cannot handle.) The traced network is
+  fully convolutional and runs at both the per-plane (`800`) and stacked
+  (`1600`) channel heights.
+- **Method:** knowledge distillation from a **Transformer teacher** using
+  bottleneck-feature KD. This is the "best distillation" leg of a matched
+  three-model set (a plain 6-ch baseline, this distilled model, and a QAT INT8
+  version), all 6-channel and trained on the same corpus and split.
+- **Training data:** PDHD signal-processing frames, **APA0 only** (see
+  Limitations).
+- **Held-out test metrics:** Dice **0.9107** / ROI-efficiency **0.7454**.
+- **Validation:** passes toolkit-vs-standalone replay validation
+  (max absolute difference < 1.4e-6).
+- **Hyperparameters** (epochs, thresholds, optimizer, dataset size/split
+  details): _W.I.P._
+
+## 2. Input / output
+
+### Input tensor
+
+C++ tensor order `(batch=1, ntags=6, nchannels, nticks)`:
+
+- **`ntags = 6`** — the 6 input trace tags, in this exact order:
+
+  ```
+  loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss
+  ```
+
+  All six tags are emitted by the standard PDHD `OmnibusSigProc` chain
+  (debug + multi-plane-protection mode) and require no signal-processing
+  config change.
+
+- **`nchannels`** — `800` per plane in per-plane (`pp`) mode, or `1600`
+  (U+V stacked) in stacked (`mp`) mode. The W (collection) plane is not
+  consumed.
+
+- **`nticks`** — `1500`, obtained from PDHD's raw `6000` ticks after
+  `tick_per_slice = 4` downsampling inside the C++ node.
+
+### Normalization (baked in)
+
+The model was trained on inputs divided by **per-channel** z-scales:
+
+```
+[944.6256, 4000.0, 4000.0, 803.7348, 1927.6997, 530.75]
+```
+
+Because `DNNROIFinding` can apply only a single **scalar** `input_scale` to all
+channels, this per-channel division is **baked into the `.ts` module** as a
+fixed normalization layer. Therefore run this model with **`input_scale = 1.0`**.
+
+### Tick padding
+
+The C++ node rebins the time axis by `tick_per_slice = 4` before inference and
+requires the tick count to be a multiple of the model's stride alignment. For
+this network the requirement is simply **`nticks % 4 == 0`**. PDHD's standard
+`nticks = 6000` satisfies this with no padding (`tick_pad_multiple` may be left
+unset, defaulting to `tick_per_slice = 4`). The node pads to the next
+4-multiple, runs inference, then crops back to `input_ticks` — a no-op for any
+`nticks % 4 == 0` (e.g. 6000, 6400, 8000).
+
+### Output tensor
+
+Per-pixel ROI probability in `[0, 1]` (`sigmoid` already applied inside the
+model). No additional sigmoid should be applied in Wire-Cell.
+
+## 3. How to use
+
+The model is loaded via a `TorchService` and consumed by the `DNNROIFinding`
+node. Example wiring (from
+[`dunereco/.../pdhd/wcls-rawdigit-dnnsp.jsonnet`](https://github.com/DUNE/dunereco/blob/25641a94aca58900c5e87f8e592f3d3aba166e6a/dunereco/DUNEWireCell/pdhd/wcls-rawdigit-dnnsp.jsonnet#L284)):
+
+```jsonnet
+// TorchService pointing at this model
+local ts = {
+  type: "TorchService",
+  name: "dnnroi",
+  data: {
+    model: "dnnroi/pdhd/pipe_distill_transformer_6ch.ts",
+    device: "cpu",       // or "gpu"
+    concurrency: 1,
+  },
+};
+
+// DNN-ROI node, wired per anode; input_scale=1.0 because normalization
+// is baked into the .ts (see §2). The dnnroi helper is imported from
+// pgrapher/experiment/pdhd/dnnroi_pp.jsonnet.
+local dnnroi = import 'pgrapher/experiment/pdhd/dnnroi_pp.jsonnet';
+
+dnnroi(tools.anodes[n], ts, output_scale=1.0,
+       nticks=params.daq.nticks, nchunks=1),
+```
+
+Notes:
+- Run with **`input_scale = 1.0`** (normalization is baked in — see §2).
+- Loaded by the toolkit C++ node `DNNROIFinding`, which processes U and V
+  planes sequentially (each plane runs its own forward call, sharing one
+  `TorchService`).
+
+## 4. Limitations
+
+- Trained on **APA0 only** — inference on APAs 1–3 is out-of-domain.
+- The **W (collection) plane is not processed**; downstream jsonnet routes it
+  through a `PlaneSelector` passthrough.

dnn-roi/pdvd/20260615/README.md

@@ -1,214 +0,0 @@
-# PDVD DNN-ROI TorchScript models
-
-TorchScript (`.ts`) models loaded by the wire-cell-toolkit DNN-ROI node
-`DNNROIFinding` (single-plane, per-plane sequential) for ProtoDUNE Vertical
-Drift. All are exported with `DNN_ROI_SP/scripts/to_torchscript.py` from the
-full-corpus 6-channel SDCC training campaign (DAGMan 287, 2026-05-20/21) and
-output `sigmoid` probabilities in `[0, 1]` (no extra sigmoid needed in
-Wire-Cell).
-
-> **2026-05-23 retrace.** The shipped `.ts` files were originally traced at
-> the stacked-plane shape `(1, 6, 952, 1600)` and crashed when fed the
-> per-plane shape `(1, 6, 476, 1600)` that the deployed `DNNROIFinding`
-> chain actually produces (119-vs-120 cat mismatch in `mobilenetv3_unet`'s
-> decoder skip at H=476). All five `.ts` files have been re-traced from
-> the same canonical checkpoints at the per-plane input shape; the trace
-> now records the model's runtime `F.interpolate` size-fixup at the
-> failing decoder layer (an aligned 120→119 bilinear, identity on
-> matched layers). Standalone replay through the re-traced
-> `pipe_distill_nestedunet_6ch.ts` reproduces the toolkit output to
-> max-abs `~5×10⁻⁷` on all 8 anodes × 2 induction planes for run 039324
-> evt 0 (`DNN_ROI_SP/scripts/verify_wirecell_dnn.py`).
-
-## Production deployables
-
-The three files actively wired by the toolkit. The current default in
-`simulation/toolkit/pdvd/wct-nf-sp-dnnroi.jsonnet` is the INT8 primary
-(`pipe_qat_nestedunet_6ch_ep0_int8.ts`); flip `dnnroi_model` to a different
-row to swap.
-
-| file | input ch | precision | size | role | run with |
-|---|---|---|---|---|---|
-| `pipe_base_mbv3_6ch.ts`              | 6 | FP32       | 20.4 MB | FP32 baseline (no KD)         | `run_nf_sp_dnnroi_evt.sh -M dnnroi/pdvd/pipe_base_mbv3_6ch.ts` |
-| `pipe_distill_nestedunet_6ch.ts`     | 6 | FP32       | 20.4 MB | FP32 best KD                  | `run_nf_sp_dnnroi_evt.sh -M dnnroi/pdvd/pipe_distill_nestedunet_6ch.ts` |
-| `pipe_qat_nestedunet_6ch_ep0_int8.ts`| 6 | INT8 (QAT) | 10.8 MB | **INT8 primary (default)**    | `run_nf_sp_dnnroi_evt.sh -D cpu -M dnnroi/pdvd/pipe_qat_nestedunet_6ch_ep0_int8.ts` |
-
-## Staged / diagnostic
-
-Not wired by default; kept so the user can re-run the §11 / §12.4
-comparisons without re-exporting from checkpoints. Both originate from the
-Transformer-teacher chain of DAGMan 287 — kept as a reference companion to
-the production NestedUNet-teacher chain above.
-
-| file | input ch | precision | size | role |
-|---|---|---|---|---|
-| `pipe_distill_transformer_6ch.ts`        | 6 | FP32       | 20.4 MB | FP32 KD-Tx, used in §11 as a same-architecture FP32 reference for INT8-Tx |
-| `pipe_qat_transformer_6ch_ep3_int8.ts`   | 6 | INT8 (QAT) | 10.8 MB | Tx INT8 candidate at epoch 3; narrows the §11 top-CRP regression but did not clear the strict §12.4 ≤10 % nzpx gate (an5 12.57 %). Held back from production pending an explicit decision; not the canonical Tx INT8. |
-
-(The previous canonical Tx INT8, `pipe_qat_transformer_6ch_int8.ts`, was
-derived from epoch 19 — the last-epoch fakequant that the un-patched
-`scripts/qat_kd_finetune.py` shipped by default. Per
-`DNN_ROI_SP/docs/qat_deployable_diagnostic_2026-05-21.md`, that ep19 ckpt
-was strictly dominated by ep3 on labeled Dice (0.7550 vs 0.7772) **and** on
-top-CRP over-emission. The ep19 `.ts` was removed in the 2026-05-21
-cleanup; if the user ever wants it back for a controlled comparison,
-re-export from `checkpoints/pdvd_qat_transformer_6ch/qat_int8_state.pth.ep19`
-on wcgpu1.)
-
-## Provenance
-
-All exports trace back to DAGMan cluster **287** on SDCC
-(`sgpu0004`, 2× L40S, 2026-05-20 22:12 → 2026-05-21 06:51 EDT,
-~8 h 40 min wall total). The training corpus is the 6-channel PDVD
-mix (1 000 train + 200 val + 400 held-out test, 125/25/50 events per
-anode × 8 anodes, `pdvd_anode{0..7}_6ch_th150_pad3.h5`).
-
-### Production deployables
-
-| field | `pipe_base_mbv3_6ch` | `pipe_distill_nestedunet_6ch` | `pipe_qat_nestedunet_6ch_ep0_int8` |
-|---|---|---|---|
-| Architecture | MobileNetV3-large UNet | MobileNetV3-large UNet | QuantizableMobileNetV3-UNet, INT8 |
-| Run-id | `pdvd_mobilenetv3_all_6ch` | `pdvd_distill_nestedunet_6ch` | `pdvd_qat_nestedunet_6ch` |
-| Checkpoint | `CP97.pth` (best-val ep 97) | `CP35.pth` (best-val ep 35) | `qat_int8_state.pth.ep0` (best-by-post-convert) |
-| Training | 6-ch baseline, no KD, 100 ep | NestedUNet teacher + feature-map KD, 100 ep | QAT-KD INT8, 20 ep, warm-started from KD-NU (`pdvd_distill_nestedunet_6ch`) |
-| TorchScript mode | trace | trace | trace |
-| Held-out test (400 ev) Dice | 0.7538 | **0.7816** | 0.7797 |
-| Held-out test eff_roi / pur_roi | 0.7135 / 0.8594 | 0.7520 / 0.8537 | 0.7533 / 0.8490 |
-
-The KD-NestedUNet student (`pdvd_distill_nestedunet_6ch`) is the strongest
-FP32 model on test (Dice 0.7816, eff_roi 0.7520 — both #1 of the 5 FP32
-runs). The INT8 primary (`pdvd_qat_nestedunet_6ch` epoch 0) keeps 99.7 % of
-that FP32 Dice (0.7797 = −0.27 % vs FP32 KD parent) and clears the toolkit
-§12.4 ≤10 % nzpx gate on all 8 anodes (worst case 9.34 % on anode 5). The
-direct-MBV3 baseline is shipped as the no-KD reference.
-
-The INT8 primary's epoch choice (ep 0) is governed by post-convert dice
-peaking early in QAT, not the trainer's fakequant `val_dice`. See
-`DNN_ROI_SP/docs/qat_deployable_diagnostic_2026-05-21.md` for the full
-diagnostic and `DNN_ROI_SP/scripts/qat_kd_finetune.py`'s
-best-by-post-convert tracking that lands canonically going forward.
-
-### Staged / diagnostic
-
-| field | `pipe_distill_transformer_6ch` | `pipe_qat_transformer_6ch_ep3_int8` |
-|---|---|---|
-| Architecture | MobileNetV3-large UNet | QuantizableMobileNetV3-UNet, INT8 |
-| Run-id | `pdvd_distill_transformer_6ch` | `pdvd_qat_transformer_6ch` |
-| Checkpoint | `CP99.pth` (best-val ep 99) | `qat_int8_state.pth.ep3` |
-| Held-out test Dice | 0.7680 | 0.7772 |
-| Notes | Diagnostic FP32 anchor for §11 / §12.4 same-arch INT8 comparison. Not the shipped FP32 deployable. | Tx-chain INT8 candidate. +1.20 % vs FP32 KD-Tx parent on labeled test Dice. Narrows the §11 top-CRP regression (an4 11.27 %→7.60 %, an5 17.63 %→12.57 %) but an5 still exceeds the §12.4 10 % strict gate; ep19 was deleted as superseded but no Tx INT8 .ts is wired as canonical until the residual is resolved (see `DNN_ROI_SP/memory/pdvd_int8_top_crp_oversegmentation.md`). |
-
-`to_torchscript.py` falls back to `torch.jit.trace` (the encoder `break`
-and the INT8 graph cannot be scripted); each export is verified by an
-eager-vs-TorchScript `allclose` (max abs diff 0.00e+00 for all five files).
-
-## Input layout
-
-C++ tensor order is `(batch=1, ntags, nchannels, nticks)`:
-
-- `ntags` = **6**.
-- `nchannels` = **476** per plane. The two induction planes U and V are
-  processed sequentially by two `DNNROIFinding` nodes per anode (sharing a
-  single TorchService); the W collection plane is not consumed (passed
-  through from standard SP gauss). See
-  `cfg/pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet`.
-- `nticks` = **1600**, from PDVD's raw `6400` ticks after `tick_per_slice=4`
-  downsampling inside the C++ node.
-
-The toolkit input per call is `(1, 6, 476, 1600)`. The PDVD students were
-trained on **stacked U+V at (1, 6, 952, 1600)**; per-plane deployment is
-structurally compatible (MobileNetV3-large is fully convolutional on the
-channel axis), and the re-traced `.ts` files include the runtime
-size-fixup the U-Net needs at this shape (see top-of-file note).
-
-**6-channel input** — `ntags=6`, trace tags in order:
-
-```
-loose_lf{A}, mp2_roi{A}, mp3_roi{A}, tight_lf{A}, decon_charge{A}, gauss{A}
-```
-
-The two new tags relative to the previous 4-ch deployment (`tight_lf` and
-`decon_charge`) must be emitted by PDVD's `OmnibusSigProc` chain in debug +
-multi-plane-protection mode — the same way PDHD 6-ch deployment works. The
-order matches the PDHD 6-ch sibling exactly.
-
-## Per-channel normalization
-
-The 6-ch models are trained on inputs divided by **per-channel** z-scales.
-Wire-Cell's `DNNROIFinding` applies one scalar `input_scale`, so the
-per-channel division is baked into each `.ts` as a fixed normalization layer;
-the models run with `input_scale = 1.0` (set by
-`protodunevd/dnnroi_pp.jsonnet`).
-
-A single set is baked into all `.ts` files — the **cross-anode mean**:
-
-```
-[766.1332, 4000.0, 4000.0, 762.4834, 1679.252, 11827.907]
-        (loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss)
-```
-
-The per-anode z-scales differ — z[0] runs ~50 % higher on the top CRP
-(anodes 4-7) than the bottom CRP (anodes 0-3). The cross-anode mean is an
-approximation; the unified vs split study
-(`DNN_ROI_SP/docs/pdvd_unified_vs_split_study.md`) shows one mixed model
-matches the per-half specialists, so a single set is shipped.
-
-## Tick padding
-
-The C++ node rebins the time axis by `tick_per_slice=4` before inference;
-the PDVD MobileNetV3-large UNet was trained at post-rebin width
-**1600** (= `6400/4`), and 1600 = 64·25 has five spare factors of 2, so
-the deployed `.ts` has **5 stride-2 down/up levels** in the tick axis
-post-rebin. To survive that cascade the post-rebin width must be
-divisible by 2⁵ = 32, i.e. the input `nticks` must be a multiple of
-`tick_per_slice · 32 = 4·32 = 128`.
-
-`cfg/pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet` sets
-`tick_pad_multiple=128` by default; the C++ `DNNROIFinding` node then
-pads the input ticks up to the next 128-multiple before inference and
-crops the output back to the original `input_ticks`.
-
-| input `nticks` | padded `model_ticks` | output cropped to |
-|---|---|---|
-| 6000 | 6016 (= 47·128) | 6000 |
-| 6400 | 6400 (already 50·128) | 6400 |
-| 8000 | 8064 (= 63·128) | 8000 |
-
-A mismatch surfaces as a tensor-shape error inside the model at runtime,
-not as a toolkit-side check, so do not lower `tick_pad_multiple` for
-these models.
-
-## Consumer
-
-Loaded by the toolkit C++ node `DNNROIFinding` (per-plane sequential:
-U and V each run their own forward call sharing one TorchService —
-analogous to the PDHD pp wiring). Wired by
-`cfg/pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet`; driven by
-`toolkit/pdvd/run_nf_sp_dnnroi_evt.sh` and
-`wcp-porting-img/pdvd/run_nf_sp_dnnroi_evt.sh` (`-M <model>` selects the
-`.ts`).
-
-The C++ `DNNROIFinding` node honors `debugfile` (set via the chain's
-`-X <basename>` flag) and writes one `{basename}_anode{N}_{plane}_call0.pt`
-per call containing `(input, output, meta)` — loadable with
-`DNN_ROI_SP/scripts/verify_wirecell_dnn.py` for offline 1:1 replay
-against the same `.ts`.
-
-## Limitations
-
-- Trained on **all 8 PDVD anodes** (bottom CRP = anodes 0-3, top CRP =
-  anodes 4-7) — the previous 4-channel deployment's "anodes 4-7
-  out-of-domain" caveat no longer applies. See
-  `DNN_ROI_SP/docs/pdvd_unified_vs_split_study.md` for evidence one model
-  handles both halves.
-- The W collection plane is not processed; the toolkit jsonnet routes it
-  through a `PlaneSelector` passthrough of standard SP gauss.
-- INT8 QAT models run on **CPU only** (x86 quantized backend); they cannot
-  be placed on a GPU device.
-- The INT8 primary (NU ep0) is the result of a deployable-selection patch
-  (best-by-post-convert dice). For runs that pre-date the patch, the
-  trainer's last-epoch `qat_int8_state.pth` should not be assumed to be
-  the best post-convert deployable — see the §12.6 follow-up in
-  `DNN_ROI_SP/docs/sdcc_full_training_campaign.md` for details.
-- Cross-anode-mean z-scales are an approximation — see
-  *Per-channel normalization* above.

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

@@ -1,58 +0,0 @@
-# `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.md

@@ -0,0 +1,157 @@
+# PDVD DNN-ROI — `pipe_distill_transformer_6ch.ts`
+
+TorchScript (`.ts`) DNN-ROI model for ProtoDUNE Vertical Drift (PDVD), loaded
+by the wire-cell-toolkit DNN-ROI node `DNNROIFinding`. It produces a per-pixel
+region-of-interest (ROI) probability map used to gate signal-processing output.
+
+| field | value |
+|---|---|
+| file | `dnnroi/pdvd/pipe_distill_transformer_6ch.ts` |
+| architecture | MobileNetV3-large UNet |
+| precision | FP32 |
+| input channels (tags) | 6 |
+| output | per-pixel `sigmoid` probability in `[0, 1]` (no extra sigmoid needed in Wire-Cell) |
+| TorchScript mode | `torch.jit.trace` (traced at the per-plane input shape) |
+| size | ≈20.4 MB (21,407,103 bytes) |
+| role | **diagnostic / reference — not the default production FP32 model** |
+
+> **Which FP32 model should I use?** For production PDVD signal processing the
+> recommended FP32 model is the NestedUNet-teacher student
+> (`pipe_distill_nestedunet_6ch.ts`), which scores higher on the held-out test.
+> This Transformer-teacher model is kept as a same-architecture FP32 reference
+> for INT8-vs-FP32 comparisons.
+
+## 1. How the model was trained
+
+- **Architecture:** MobileNetV3-large UNet, exported to TorchScript with
+  `torch.jit.trace`. (`torch.jit.script` is not used because the encoder loop
+  contains a `break` that the scripter cannot handle.) MobileNetV3-large is
+  fully convolutional on the channel axis; the model was trained on **stacked
+  U+V** input `(1, 6, 952, 1600)` but is deployed **per-plane** at
+  `(1, 6, 476, 1600)`. The traced `.ts` records the U-Net's runtime
+  size-fixup (an aligned bilinear interpolate at the decoder skip that would
+  otherwise mismatch at H=476), so it runs correctly at the per-plane shape.
+- **Method:** knowledge distillation from a **Transformer teacher**.
+- **Training data:** 6-channel PDVD corpus — 1,000 train + 200 val + 400
+  held-out test events (125/25/50 events per anode across **all 8 anodes**),
+  from the SDCC full-corpus 6-channel training campaign.
+- **Checkpoint:** `CP99.pth` (best-val, epoch 99); run-id
+  `pdvd_distill_transformer_6ch`.
+- **Held-out test metric:** Dice **0.7680** (400-event test set).
+- **Validation:** standalone replay reproduces the toolkit output to
+  max absolute difference ≈ 5×10⁻⁷ (eager-vs-TorchScript `allclose` max abs
+  diff 0.00 at export).
+- **Hyperparameters** (optimizer, learning rate, exact epoch count/schedule):
+  _W.I.P._
+
+## 2. Input / output
+
+### Input tensor
+
+C++ tensor order `(batch=1, ntags=6, nchannels=476, nticks=1600)`, processed
+per-plane (U then V):
+
+- **`ntags = 6`** — the 6 input trace tags, in this exact order:
+
+  ```
+  loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss
+  ```
+
+  All six tags are emitted by PDVD's `OmnibusSigProc` chain (debug +
+  multi-plane-protection mode). Relative to the older 4-channel deployment,
+  the two additional tags are `tight_lf` and `decon_charge`; the order matches
+  the PDHD 6-channel model exactly.
+
+- **`nchannels = 476`** per plane. The two induction planes U and V are
+  processed sequentially by two `DNNROIFinding` nodes per anode (sharing one
+  `TorchService`). The W (collection) plane is not consumed.
+
+- **`nticks = 1600`**, from PDVD's raw `6400` ticks after `tick_per_slice = 4`
+  downsampling inside the C++ node.
+
+### Normalization (baked in)
+
+The model was trained on inputs divided by **per-channel** z-scales. Because
+`DNNROIFinding` can apply only a single **scalar** `input_scale`, the
+per-channel division is **baked into the `.ts` module** as a fixed
+normalization layer. Therefore run this model with **`input_scale = 1.0`**.
+
+The baked-in z-scales are the **cross-anode mean**:
+
+```
+[766.1332, 4000.0, 4000.0, 762.4834, 1679.252, 11827.907]
+ (loose_lf, mp2_roi, mp3_roi, tight_lf, decon_charge, gauss)
+```
+
+Per-anode z-scales differ (channel 0 runs ~50% higher on the top CRP,
+anodes 4–7, than the bottom CRP, anodes 0–3); a single cross-anode-mean set is
+shipped as an approximation validated to match per-half specialists.
+
+### Tick padding
+
+The C++ node rebins the time axis by `tick_per_slice = 4` before inference.
+This network has **5 stride-2 down/up levels** in the (post-rebin) tick axis,
+so the post-rebin width must be divisible by 2⁵ = 32 — i.e. the input
+`nticks` must be a **multiple of `tick_per_slice · 32 = 128`**. Set
+`tick_pad_multiple = 128`; the node pads up to the next 128-multiple before
+inference and crops the output back to the original `input_ticks`:
+
+| input `nticks` | padded `model_ticks` | output cropped to |
+|---|---|---|
+| 6000 | 6016 (= 47·128) | 6000 |
+| 6400 | 6400 (already 50·128) | 6400 |
+| 8000 | 8064 (= 63·128) | 8000 |
+
+Do **not** lower `tick_pad_multiple` for this model — a mismatch surfaces as a
+tensor-shape error inside the model at runtime, not as a toolkit-side check.
+
+### Output tensor
+
+Per-pixel ROI probability in `[0, 1]` (`sigmoid` already applied inside the
+model). No additional sigmoid should be applied in Wire-Cell.
+
+## 3. How to use
+
+The model is loaded via a `TorchService` and consumed by the `DNNROIFinding`
+node. Example wiring (analogous to the PDHD
+[`wcls-rawdigit-dnnsp.jsonnet`](https://github.com/DUNE/dunereco/blob/25641a94aca58900c5e87f8e592f3d3aba166e6a/dunereco/DUNEWireCell/pdhd/wcls-rawdigit-dnnsp.jsonnet#L284)
+pattern):
+
+```jsonnet
+// TorchService pointing at this model
+local ts = {
+  type: "TorchService",
+  name: "dnnroi",
+  data: {
+    model: "dnnroi/pdvd/pipe_distill_transformer_6ch.ts",
+    device: "cpu",       // or "gpu"
+    concurrency: 1,
+  },
+};
+
+// DNN-ROI node, wired per anode; input_scale=1.0 because normalization
+// is baked into the .ts (see §2), and tick_pad_multiple=128 (see §2).
+// The dnnroi helper is imported from
+// pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet.
+local dnnroi = import 'pgrapher/experiment/protodunevd/dnnroi_pp.jsonnet';
+
+dnnroi(tools.anodes[n], ts, output_scale=1.0,
+       nticks=params.daq.nticks, nchunks=1),
+```
+
+Notes:
+- Run with **`input_scale = 1.0`** and **`tick_pad_multiple = 128`**
+  (both set by `protodunevd/dnnroi_pp.jsonnet`).
+- Loaded by the toolkit C++ node `DNNROIFinding`, which processes the U and V
+  induction planes sequentially (each plane runs its own forward call, sharing
+  one `TorchService`). The W plane is routed through a `PlaneSelector`
+  passthrough of standard SP gauss.
+
+## 4. Limitations
+
+- The **W (collection) plane is not processed**; downstream jsonnet routes it
+  through a `PlaneSelector` passthrough.
+- The baked-in cross-anode-mean z-scales are an approximation (per-anode
+  z-scales differ, especially top vs bottom CRP — see §2).
+- This is a **diagnostic / reference** model, not the recommended production
+  FP32 deployable (see the note at the top).

l1sp/pdhd/20260615/l1sp_dnn_pdhd_v1.meta.json

@@ -0,0 +1,112 @@
+{
+  "experiment_dir": "/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_a_pu_round4",
+  "vae_ckpt": "/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_b_vae/model_n16.pt",
+  "vae_n_lat": 16,
+  "git_sha": "708b942b199e2cc7395e9e3468b926b8146e171b",
+  "nbin": 256,
+  "amp_floor": 1.0,
+  "n_features": 30,
+  "feature_order": [
+    "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",
+    "vae_kl"
+  ],
+  "scalar_feature_order": [
+    "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"
+  ],
+  "kl_index": 29,
+  "default_threshold": 0.9945,
+  "threshold_notes": "default_threshold=0.9945 \u2014 set by --default-threshold at export time. Convention is to use the p99.9 of the data-corpus score distribution from the training run; see the experiment dir's notes.md for the value that was promoted.",
+  "model_io": {
+    "forward.inputs": [
+      {
+        "name": "waveform",
+        "shape": [
+          "B",
+          1,
+          2,
+          256
+        ],
+        "dtype": "float32",
+        "notes": "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 \u00b1128 ticks centered on argmax(|decon|) clamped to ROI bounds. The dim-1 axis is a dummy to satisfy WCT's Pytorch::from_itensor 4-D requirement."
+      },
+      {
+        "name": "scalars",
+        "shape": [
+          "B",
+          1,
+          1,
+          29
+        ],
+        "dtype": "float32",
+        "notes": "29 scalars in scalar_feature_order"
+      }
+    ],
+    "forward.output": {
+      "name": "score",
+      "shape": [
+        "B",
+        1,
+        1,
+        1
+      ],
+      "dtype": "float32",
+      "notes": "sigmoid in [0, 1]; cut at default_threshold"
+    }
+  }
+}

l1sp/pdvd/20260615/l1sp_dnn_pdvd_v1.meta.json

@@ -0,0 +1,112 @@
+{
+  "experiment_dir": "/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_a_pu_round2_pdvd",
+  "vae_ckpt": "/nfs/data/1/xqian/toolkit-dev/l1sp_dl_tagger/experiments/stage_b_vae/model_n16.pt",
+  "vae_n_lat": 16,
+  "git_sha": "cd038ae0da106fd215a54a061824daa835f05fc6",
+  "nbin": 256,
+  "amp_floor": 1.0,
+  "n_features": 30,
+  "feature_order": [
+    "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",
+    "vae_kl"
+  ],
+  "scalar_feature_order": [
+    "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"
+  ],
+  "kl_index": 29,
+  "default_threshold": 0.16,
+  "threshold_notes": "default_threshold=0.16 \u2014 set by --default-threshold at export time. Convention is to use the p99.9 of the data-corpus score distribution from the training run; see the experiment dir's notes.md for the value that was promoted.",
+  "model_io": {
+    "forward.inputs": [
+      {
+        "name": "waveform",
+        "shape": [
+          "B",
+          1,
+          2,
+          256
+        ],
+        "dtype": "float32",
+        "notes": "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 \u00b1128 ticks centered on argmax(|decon|) clamped to ROI bounds. The dim-1 axis is a dummy to satisfy WCT's Pytorch::from_itensor 4-D requirement."
+      },
+      {
+        "name": "scalars",
+        "shape": [
+          "B",
+          1,
+          1,
+          29
+        ],
+        "dtype": "float32",
+        "notes": "29 scalars in scalar_feature_order"
+      }
+    ],
+    "forward.output": {
+      "name": "score",
+      "shape": [
+        "B",
+        1,
+        1,
+        1
+      ],
+      "dtype": "float32",
+      "notes": "sigmoid in [0, 1]; cut at default_threshold"
+    }
+  }
+}