From 8df6974708ada7fb6a5fe997db74979f940a99ce Mon Sep 17 00:00:00 2001 From: Tracy Usher Date: Thu, 1 Oct 2026 15:38:25 -0700 Subject: [PATCH 01/22] Write each true hit's path length (TrueHitDx) to Truth_Info TMS_TrueHit already carries the true path length through the bar, summed over every Geant4 contribution merged into the hit (TMS_TrueHit::GetdX()), but it was never written out. Add it as TrueHitDx[NTrueHits], filled next to TrueHitE. For a hit with several contributing particles it is their total path length, not one particle's. The detector-simulation validation (hit survival, PE spread and hit-time bias vs path length) needs it; the 2026-09 segmentation benchmark used the same branch through a local instrumentation patch. Co-Authored-By: Claude Opus 5.5 --- src/TMS_TreeWriter.cpp | 2 ++ src/TMS_TreeWriter.h | 1 + 2 files changed, 3 insertions(+) diff --git a/src/TMS_TreeWriter.cpp b/src/TMS_TreeWriter.cpp index 11ac8dc8..dec971a0 100644 --- a/src/TMS_TreeWriter.cpp +++ b/src/TMS_TreeWriter.cpp @@ -681,6 +681,7 @@ void TMS_TreeWriter::MakeBranches() { Truth_Info->Branch("TrueHitT", &TrueHitT, "TrueHitT[NTrueHits]/F"); Truth_Info->Branch("TrueHitE", &TrueHitE, "TrueHitE[NTrueHits]/F"); Truth_Info->Branch("TrueHitPE", &TrueHitPE, "TrueHitPE[NTrueHits]/F"); + Truth_Info->Branch("TrueHitDx", &TrueHitDx, "TrueHitDx[NTrueHits]/F"); Truth_Info->Branch("TrueHitPEAfterFibers", &TrueHitPEAfterFibers, "TrueHitPEAfterFibers[NTrueHits]/F"); Truth_Info->Branch("TrueHitPEAfterFibersLongPath", &TrueHitPEAfterFibersLongPath, "TrueHitPEAfterFibersLongPath[NTrueHits]/F"); Truth_Info->Branch("TrueHitPEAfterFibersShortPath", &TrueHitPEAfterFibersShortPath, "TrueHitPEAfterFibersShortPath[NTrueHits]/F"); @@ -2026,6 +2027,7 @@ void TMS_TreeWriter::FillSlice(TMS_Event &event, const std::vector &t TrueHitT[index] = true_hit->GetT(); TrueHitE[index] = true_hit->GetE(); TrueHitPE[index] = true_hit->GetPE(); + TrueHitDx[index] = true_hit->GetdX(); TrueHitPEAfterFibers[index] = true_hit->GetPEAfterFibers(); TrueHitPEAfterFibersLongPath[index] = true_hit->GetPEAfterFibersLongPath(); TrueHitPEAfterFibersShortPath[index] = true_hit->GetPEAfterFibersShortPath(); diff --git a/src/TMS_TreeWriter.h b/src/TMS_TreeWriter.h index a0a7c92b..d0b8698f 100644 --- a/src/TMS_TreeWriter.h +++ b/src/TMS_TreeWriter.h @@ -605,6 +605,7 @@ class TMS_TreeWriter { MYVAR(TrueHitT); MYVAR(TrueHitE); MYVAR(TrueHitPE); + MYVAR(TrueHitDx); MYVAR(TrueHitPEAfterFibers); MYVAR(TrueHitPEAfterFibersLongPath); MYVAR(TrueHitPEAfterFibersShortPath); From cfca9ac69d111729b9fc9b8b488674ce70336bea Mon Sep 17 00:00:00 2001 From: Tracy Usher Date: Thu, 1 Oct 2026 19:36:59 -0700 Subject: [PATCH 02/22] Add hit-level detector-simulation validation script scripts/Validation/DetSim/detsim_validation.py compares two or more ConvertToTMSTree runs over the same input files and writes a Markdown report, a JSON file of all the numbers and six plots. It covers only the simulation, for muon-dominated hits: totals and light yield, hit survival vs true path length and deposited energy, reco PE spread near threshold, hit-time bias vs number of Geant4 contributions, coincident-hit merge failures by time gap, plane coverage, and (with UseResponseElements) light provenance. Path-length sections use TrueHitDx and fall back to deposited-energy bands without it. On the 100 MiniProdN5 files it runs in about a minute (7 GB of memory) with uproot, awkward, numpy and matplotlib. Co-Authored-By: Claude Opus 5.5 --- scripts/Validation/DetSim/README.md | 26 + .../Validation/DetSim/detsim_validation.py | 465 ++++++++++++++++++ 2 files changed, 491 insertions(+) create mode 100644 scripts/Validation/DetSim/README.md create mode 100755 scripts/Validation/DetSim/detsim_validation.py diff --git a/scripts/Validation/DetSim/README.md b/scripts/Validation/DetSim/README.md new file mode 100644 index 00000000..3413f631 --- /dev/null +++ b/scripts/Validation/DetSim/README.md @@ -0,0 +1,26 @@ +# Detector-simulation validation + +`detsim_validation.py` compares two or more `ConvertToTMSTree` runs over the same input files at the hit level (no +tracking or slicing) and writes `report.md`, `metrics.json` and six plots into an output directory. The first run is +the reference. + +``` +python3 detsim_validation.py --out [--files 1-15] off= on= +``` + +Each run directory holds `_RecoCandidates.root` and `_Readout.root` per file number. Needs uproot, +awkward, numpy and matplotlib (at FNAL: the CVMFS python v3_9_15 setup plus a user install of those packages). + +What it measures (muon-dominated hits: `TrueLeptonicEnergy / TrueHitE > 0.95`): + +| Section | Quantity | Plot | +|---|---|---| +| 1 | readout hits and PE above threshold per spill; PE after fibers per MeV for muon and hadronic hits | | +| 2 | hit survival vs true path length (`TrueHitDx`) and vs true deposited energy | `survival.png` | +| 3 | reco PE mean, relative spread and fraction below 3 PE per band; integer-PE fraction | `pe_partial_fill.png` | +| 4 | mean reco - true hit time vs number of Geant4 contributions, full crossings | `time_bias_vs_contributions.png` | +| 5 | one particle with more than one final hit in a bar and slice, by time gap (under the 120 ns window = merge failure) | `merge_gaps.png` | +| 6 | plane coverage: fraction of (particle, plane) deposits with a surviving hit, by deposited energy | `plane_coverage.png` | +| 7 | light provenance (`UseResponseElements = true` only): photon count vs PE, most-light vs most-energy particle | `light_share.png` | + +`TrueHitDx` is not written by default; without it, sections 2-4 use deposited-energy bands instead of path length. diff --git a/scripts/Validation/DetSim/detsim_validation.py b/scripts/Validation/DetSim/detsim_validation.py new file mode 100755 index 00000000..61eb5300 --- /dev/null +++ b/scripts/Validation/DetSim/detsim_validation.py @@ -0,0 +1,465 @@ +#!/usr/bin/env python3 +"""Detector-simulation validation: hit-level metrics and plots comparing ConvertToTMSTree outputs. + +Compares two or more runs over the same input files (the first is the reference) and writes a Markdown report, a +JSON file with every number in it, and a few plots. Only simulation-level quantities: no tracking or slicing. + +Sections (muon-dominated hits = TrueLeptonicEnergy / TrueHitE > 0.95, as in the 2026-09 segmentation benchmark): + 1. Totals: readout hits and PE above threshold per spill; light yield (PE after fibers per MeV) for muon- and + hadron-dominated hits. + 2. Hit survival (not pedestal-suppressed) vs true path length in the bar (TrueHitDx, if the run has it) and vs true + deposited energy. + 3. Photostatistics: reco PE mean and relative spread per path-length (or energy) band; PE distribution at partial fill. + 4. Timing: mean (reco - true) hit time vs the number of Geant4 contributions (TrueNTrueParticles) at full crossings. + 5. Coincident-hit merging: groups of more than one final true hit for one particle in one bar and slice, by time gap. + Within the readout window these are merge failures; beyond it, separate readouts by design. + 6. Plane coverage: per (particle, plane) with >= 0.5 MeV deposited by a muon-dominated particle, the fraction with a + surviving hit, by deposited energy. + 7. Light provenance (runs with Sim.DetSim.UseResponseElements = true): photon count vs detected PE, most-light vs + most-energy particle, first photon vs most-light particle. + +Inputs per run: a directory with _RecoCandidates.root (Truth_Info, Reco_Tree) and _Readout.root +(TMS tree) for each file number. + +Usage: + detsim_validation.py --out [--files 1-15]