Add SCECorrection IPCTransform with pluggable ISCEField (SBND)

[abhatfnal]

Summary

Adds an SBND-ready 3D SCE correction to the toolkit as an IPCTransform composed from a new ISCEField interface. T0 correction is built in; the SCE backward displacements (X, optionally Y / Z) are delegated to whichever ISCEField implementation is wired in via configuration. This PR ships one such implementation, SCEFieldTH3, backed by per-TPC TH3F histograms loaded from a ROOT file (e.g. the SBND dualmap SCEoffsets_SBND_E500_dualmap_CV_voxelTH3.root model).

Validation evidence: WireCell/wcp-porting-validation#9 (Stage 1, merged) and WireCell/wcp-porting-validation#12 (Stage 3a, transverse).

Architecture

• iface/inc/WireCellIface/ISCEField.h — pure-virtual IComponent<ISCEField> with displacement_x(int apa, double x, double y, double z) const (required) plus optional displacement_y / displacement_z (default no-op, so maps without transverse components are unaffected). WCT-internal mm in, mm out.
• root/inc/WireCellRoot/SCEFieldTH3.{h,cxx} — ROOT-backed ISCEField + IConfigurable. Loads up to six TH3Fs (X / Y / Z × East / West) from a single ROOT file via a shared interp() helper; transverse histograms soft-load (skipped without error if absent). Handles cm ↔ mm axis units, sign convention, and TH3::Interpolate's open-interval edge clamping.
• clus/inc/WireCellClus/SCECorrection.h + clus/src/PCTransforms.cxx — SCECorrection does T0 (per-APA drift_speed from DetectorVolumes metadata) plus the optional 3D SCE displacement via an injected ISCEField::pointer. PCTransformSet::configure looks up the field by TypeName from the DetectorVolumes metadata key sce_field via Factory::find_tn. If sce_field is absent, SCECorrection runs as T0-only.

The interface lives in iface/, the ROOT-backed implementation in root/, the transform in clus/. clus/wscript_build is untouched — clus/ remains ROOT-free.

Behavior change (intentional): SCECorrection's output_scope is {x_sce, y_sce, z_sce}; stored_array_names likewise. Downstream configs that cluster on the SCE scope therefore cluster in fully-corrected 3D.

Validation

50 SBND crossing-muon DETSIM events, 226 721 / 228 762 points paired by charge (99.1 %; 0.9 % dropped on ambiguous q), comparing the reco output to the input TH3 backward map at the corrected (x_sce, y_sce, z_sce) coordinates:

quantity	East	West
Δx rms (cm)	1.83 × 10⁻⁴	2.23 × 10⁻⁴
Δy rms (cm)	2.63 × 10⁻⁴	1.65 × 10⁻⁴
Δz rms (cm)	3.35 × 10⁻⁴	2.99 × 10⁻⁴
max residual any (cm)	9.91 × 10⁻⁴	9.91 × 10⁻⁴
pooled mean|Δx| (cm)	0.4026	0.5340

Pooled W / E |Δx| = 1.326 — consistent with the map volume-average (1.276) and the patched 0.33-era reco (1.271). The implementation reproduces the TH3 backward map to interpolation precision (≈ 2 µm) in all three components.

Configuration

Minimal jsonnet wiring for the SBND dualmap (3D):

local sce_field = {
  type: "SCEFieldTH3",
  name: "sbnd_dualmap",
  data: {
    sce_map_file: "/cvmfs/.../SCEoffsets_SBND_E500_dualmap_CV_voxelTH3.root",
    th3_name_E:   "TrueBkwd_Displacement_X_E",
    th3_name_W:   "TrueBkwd_Displacement_X_W",
    th3_name_E_y: "TrueBkwd_Displacement_Y_E",  // optional
    th3_name_W_y: "TrueBkwd_Displacement_Y_W",  // optional
    th3_name_E_z: "TrueBkwd_Displacement_Z_E",  // optional
    th3_name_W_z: "TrueBkwd_Displacement_Z_W",  // optional
    axis_unit_mm: false,  // SBND TH3 axes are in cm
    sign:         -1,     // backward map
  },
};
// in the DetectorVolumes face metadata:
//   { ..., sce_field: wc.tn(sce_field) }
// and add sce_field to the PCTransformSet's `uses` list.

Files

5 files, +466 / 0 across 3 commits:

file	status
iface/inc/WireCellIface/ISCEField.h	new
root/inc/WireCellRoot/SCEFieldTH3.h	new
root/src/SCEFieldTH3.cxx	new
clus/inc/WireCellClus/SCECorrection.h	new
clus/src/PCTransforms.cxx	modified

cc @HaiwangYu

[HaiwangYu]

Review: SCE correction (SCECorrection / ISCEField / SCEFieldTH3)

Adds SBND Space-Charge-Effect correction: a new ISCEField interface (iface), a ROOT-backed SCEFieldTH3 implementation (root), and an SCECorrection IPCTransform (clus) wired into PCTransformSet. Reviewed against two criteria: new functionality compiles, and the change does not affect existing functionality.

✅ Compilation — passes

Verified against a full build log of this branch:

• root/src/SCEFieldTH3.cxx and clus/src/PCTransforms.cxx both compile.
• Full build finishes successfully (all targets linked).
• root/src/*.cxx is auto-globbed by smplpkg, so no wscript change is needed.
• Dependency direction is clean (root → clus → iface). ISCEField.h is header-only in iface, so clus stays ROOT-free and resolves the field at runtime via Factory::find_tn. Good separation.

✅ No impact on existing functionality

• Transforms are selected by name via pc_transform(name). This PR only adds a "SCECorrection" map entry; the existing "T0Correction" path is untouched.
• The sce_field discovery loop is a correct no-op when the metadata key is absent: sce_field stays null and SCECorrection falls back to T0-only. Merely building/merging this PR changes nothing for current configs.
• ISCEField and SCEFieldTH3 are new symbols; nothing else references them.

Test segfaults in the build log — pre-existing, not from this PR

The test run shows 2 doctest crashes (SIGSEGV):

• wcdoctest-sigproc (l1sp_kernel) — sigproc is not touched by this PR, so this is environmental/pre-existing (log also shows HDF5, libtorch/CUDA, and missing-data-file errors).
• wcdoctest-clus crashes in doctest_clustering_prototype.cxx:301 ("clustering prototype pca") — a clustering-PCA test that does not exercise PCTransforms/SCECorrection. No test files are modified by this PR.

Recommend confirming both also fail on master in the same environment to fully close the loop, but the evidence indicates they are not introduced here.

Non-blocking notes (relevant when the feature is enabled)

1. backward() is an approximate inverse of forward() when an SCE field is active — it evaluates the displacement at the corrected position rather than solving the inverse (documented as "Approximate"). Forward→backward round-trips will not be exact with the field on. The T0-only path (null field) is still exact.
2. Downstream scope must match. Unlike T0Correction (stores only x_t0cor), SCECorrection declares all three {x_sce, y_sce, z_sce} in output_scope()/stored_array_names(). Any consumer (e.g. ClusteringRetile) must be configured with the matching scope when the feature is enabled.
3. Single shared sce_field assumption. The discovery loop breaks at the first APA carrying the sce_field key, so all APAs share one field TypeName. Correct for SBND (E/W routing lives inside the field), but a latent assumption if reused elsewhere.
4. Minor: detached TH3F histograms (SetDirectory(nullptr)) are never explicitly deleted — a negligible program-lifetime leak. Missing drift_speed metadata yields 0 and silently disables T0, but this matches existing T0Correction behavior (not a regression).

Verdict

Both requirements are met: the PR compiles cleanly and is additive / name-gated, so it cannot affect existing behavior unless explicitly enabled via metadata + jsonnet. The two test segfaults are unrelated/pre-existing. The notes above are quality considerations for when the feature is turned on, not blockers.

[brettviren]

@calcuttj perhaps interesting for you to note given your presentation yesterday about the VD non-uniform drift field issue.

[HaiwangYu]

The match branch PR479 is targeting is obsolete.
Now I am cherry-picking PR479 commits into master

848de71
0b16a47
a33e2c6