sbnd: add sbnd_abhat SCE validation (WCT 0.36 migration)

Per-user subdir documenting and reproducing the SBND SCE-correction
migration from patched 0.33 to a clean WCT-native IPCTransform on 0.36.

Validated against the per-TPC TH3 displacement maps over 50 crossing-muon
events: per-point residual rms 1.8 / 2.2 µm (East/West), max 8.4 µm, and
pooled W/E = 1.327 (map vol-avg 1.276; 0.33-era reco 1.271).

Includes the new SCECorrection.h, patches for PCTransforms.cxx and
clus/wscript_build, the patched clus.jsonnet with diff, the BEE-pairing
analysis script, and the three validation figures.

Author: abhatfnal

sbnd/sbnd_abhat/PCTransforms.cxx.patch

@@ -0,0 +1,22 @@
+diff --git a/clus/src/PCTransforms.cxx b/clus/src/PCTransforms.cxx
+index 7af8e237..1b0bf8ef 100644
+--- a/clus/src/PCTransforms.cxx
++++ b/clus/src/PCTransforms.cxx
+@@ -6,6 +6,7 @@
+ //
+ 
+ #include "WireCellClus/IPCTransform.h"
++#include "WireCellClus/SCECorrection.h"
+ #include "WireCellIface/IDetectorVolumes.h"
+ 
+ #include "WireCellIface/IConfigurable.h"
+@@ -178,6 +179,9 @@ public:
+         std::string dvtn = get<std::string>(cfg, "detector_volumes", "DetectorVolumes");
+         auto dv = Factory::find_tn<WireCell::IDetectorVolumes>(dvtn);
+         m_pcts["T0Correction"] = std::make_shared<T0Correction>(dv);
++        // SBND SCE (Space Charge Effect) -- dualmap TH3 correction.
++        // No-op if sce_map_file not in DetectorVolumes metadata.
++        m_pcts["SCECorrection"] = std::make_shared<SCECorrection>(dv);
+         // ...
+     }
+ 

sbnd/sbnd_abhat/README.md

@@ -0,0 +1,82 @@
+# SBND SCE Correction — WCT 0.36 migration & validation
+
+Migration of the SBND Space-Charge-Effect (SCE) correction from the patched WCT 0.33
+pipeline (which used a `PCTransforms` reflection trick) into a clean, WCT-native
+`IPCTransform` for 0.36, validated against the per-TPC SCE TH3 displacement maps.
+
+## What
+
+- New class `WireCell::Clus::SCECorrection` — an `IPCTransform` that applies T0
+  and the per-TPC SCE displacement maps in one step:
+  `x_sce = x_t0 + sign * dx_map(x_t0, y, z)`, apa0 → East TH3, apa1 → West TH3.
+- Reads the SBND dualmap
+  (`SCEoffsets_SBND_E500_dualmap_CV_voxelTH3.root`, `TrueBkwd_Displacement_X_{E,W}`)
+  via DV metadata `sce_map_file` (axes in cm, sign default −1).
+- Wired through the existing `PCTransformSet` and `ClusteringSwitchScope`
+  (`correction_name="SCECorrection"`); merged-APA clustering uses
+  `common_sce_coords = ["x_sce","y","z"]`.
+- Toolkit code lives on branch `sbnd-sce-correction-036` off Haiwang's `match`.
+  Upstream PR to `WireCell/wire-cell-toolkit` is pending the `clus → root`
+  cleanup (the `TFile`/`TH3F` machinery belongs in the `root/` subpackage so
+  `clus` stays ROOT-free).
+
+## Result
+
+50 crossing-muon events (apacross 3 GeV detsim), 228 404 paired 3D points,
+per-point comparison of reco displacement against the TH3 map prediction:
+
+| Quantity                              | Value                |
+|---------------------------------------|----------------------|
+| residual (reco − map) rms             | E 1.8 µm,  W 2.2 µm  |
+| residual max                          | 8.4 µm               |
+| East mean|Δx|               | 0.4021 cm            |
+| West mean|Δx|               | 0.5338 cm            |
+| **pooled W/E**                        | **1.327**            |
+| reference (map volume-avg)            | 1.276                |
+| reference (0.33-era reco)             | 1.271                |
+
+The map application is exact to interpolation precision (sub-µm rms vs the
+~5000 µm signal). The track-sampled aggregate ratio is consistent with the
+volume-averaged map reference; the small offset (~4 %) is the crossing-muon
+trajectories preferentially sampling the high-displacement mid-drift region.
+
+Plots: `pics/01_residual.png` (headline, residual histogram),
+`pics/02_dx_vs_drift.png` (slide-style 2D Δx vs drift, per TPC),
+`pics/03_profile_ratio.png` (drift profile + W/E ratio panel).
+
+## Reproduce
+
+```bash
+# Env (FNAL SBND gpvm, SL7 container, our 0.36 + SCECorrection install)
+export SCE_TOP=/exp/sbnd/data/users/abhat/wct_sce
+source $SCE_TOP/restore_sce_env_036_sce.sh
+
+cd $SCE_TOP/sce_test
+export WIRECELL_PATH="$SCE_TOP/sce_test:$WIRECELL_PATH"
+export FHICL_FILE_PATH="$SCE_TOP/sce_test:$FHICL_FILE_PATH"
+lar -n 50 -c wcls-img-clus.fcl \
+    -s $SCE_TOP/validation_crossing_muons/chain_v3/apacross_3gev_detsim_50.root \
+    --no-output
+
+python3 make_validation_plots.py
+cat validation_plots/SUMMARY.txt
+```
+
+## Files
+
+- `SCECorrection.h` — the new `IPCTransform` (header-only v1).
+  Destination in WCT toolkit: `clus/inc/WireCellClus/SCECorrection.h`.
+- `PCTransforms.cxx.patch` — 4-line registration in `clus/src/PCTransforms.cxx`.
+- `wscript_build.patch` — adds `ROOTSYS` to clus link list (will move to `root/`
+  subpackage in the upstream PR).
+- `clus.jsonnet` — patched copy of canonical `../clus.jsonnet`; the SCE wiring
+  is: `common_sce_coords` local, `sce_map_file` in DV metadata, all-APA coords
+  set to `common_sce_coords`, `switch_scope(correction_name="SCECorrection")`,
+  an extra `bee_points_set` named `sce` (dumps `x_sce` for validation), and
+  `use_config_rse: false` so per-event folders survive multi-event runs.
+- `clus.jsonnet.patch` — diff against canonical `../clus.jsonnet`.
+- `wcls-img-clus.fcl` — symlink to canonical `../wcls-img-clus.fcl`.
+- `make_validation_plots.py` — pairs `img`/`sce` BEE points by `(y,z,q)`,
+  re-evaluates the TH3 maps per point, produces the three figures.
+- `pics/` — validation PNGs.
+- `SUMMARY.txt` — headline numbers.

sbnd/sbnd_abhat/SUMMARY.txt

@@ -0,0 +1,5 @@
+SBND WCT 0.36 SCECorrection validation -- 50 crossing-muon events
+points: 228404 (East 70503, West 157901)
+per-point residual reco-map: rms E=1.83e-04 W=2.23e-04 cm, max 8.42e-04 cm
+pooled mean|Dx|: East=0.4021 West=0.5338  W/E=1.327
+references: map vol-avg 1.276, 0.33-era reco 1.271