Repository navigation
Detector sim 4/4: raw readouts, MC decoder, bad-channel list, validation tooling - #358
SFBayLaser wants to merge 22 commits into
Conversation
9c2054b to
2dfaa95
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved defects can skew validation and provenance results, crash supported page-generation workflows, and leave new tools unavailable in plain Makefile builds.
9 open issues
Use absolute paths for test fixtures · New Add the new executables to the Makefile build · New Reset the minimum when the brightest readout changes · New Preserve fractional percentages in scan filenames · New Exclude pedestal-suppressed hits from timing statistics · New Match populated bins before computing efficiency differences · New Guard missing provenance_spills in the scans-only workflow · New Use distinct light-contributor counts for multi-particle metrics · New Handle metrics files without TrueHitDx · New
What changed in this PR
This PR separates electronics readouts from reconstructed hits in the opt-in detector-simulation pipeline and adds tools to validate that boundary. The default-on change remains deferred.
Changes:
- Adds raw-readout decoding with pedestal suppression and configurable bad-channel filtering.
- Extends truth output with path length and per-particle light contributions.
- Adds channel-list utilities, controlled simulation scans, and validation reports.
| File | Description |
|---|---|
src/TMS_TrueHit.h |
Stores and copies per-particle light contributions. |
src/TMS_TreeWriter.h |
Declares path-length and light-contribution branches. |
src/TMS_TreeWriter.cpp |
Registers and fills new truth branches. |
src/TMS_ReadoutTreeWriter.h |
Declares readout light-contribution branches. |
src/TMS_ReadoutTreeWriter.cpp |
Writes per-readout light contributions. |
src/TMS_RawReadout.h |
Defines simulated raw-readout records. |
src/TMS_Manager.h |
Exposes the bad-channel file setting. |
src/TMS_Manager.cpp |
Loads the optional decoder configuration. |
src/TMS_Hit.h |
Declares a decoder construction path. |
src/TMS_Hit.cpp |
Constructs hits from known bars. |
src/TMS_Event.h |
Adds raw-readout storage and decoding access. |
src/TMS_Event.cpp |
Integrates decoding and light-contribution collection. |
src/TMS_Decoder.h |
Defines the Monte Carlo decoder interface. |
src/TMS_Decoder.cpp |
Filters bad channels and applies pedestal suppression. |
src/TMS_BadChannels.h |
Defines channel status and lookup interfaces. |
src/TMS_BadChannels.cpp |
Parses and validates bad-channel lists. |
src/Makefile |
Links decoder and bad-channel objects. |
scripts/Validation/DetSim/stages/stage_page_data.py |
Reduces scans and spill metrics for visualization. |
scripts/Validation/DetSim/stages/run_stage_scans.sh |
Runs scans with pinned configurations. |
scripts/Validation/DetSim/stages/page_template.html |
Presents stage-level validation charts. |
scripts/Validation/DetSim/stages/build_stage_page.py |
Embeds scan data and notes into HTML. |
scripts/Validation/DetSim/README.md |
Documents validation workflows and metrics. |
scripts/Validation/DetSim/detsim_validation.py |
Compares hit-level outputs across simulation runs. |
scripts/BadChannels/make_bad_channel_lists.py |
Generates nested random bad-channel lists. |
config/TMS_Default_Config.toml |
Configures the decoder’s bad-channel file. |
config/TMS_BadChannels_Default.toml |
Supplies an empty default channel list. |
app/DumpChannels.cpp |
Exports geometry channel identifiers. |
app/DetSimStageScan.cpp |
Runs controlled crossing and readout scans. |
app/CMakeLists.txt |
Registers the new utilities and parser test. |
app/BadChannelsTest.cpp |
Checks bad-channel parsing and error handling. |
Review effort: Balanced
2dfaa95 to
3be3542
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved defects permit invalid bad-channel percentages, produce misleading merge and timing validation, lose simulated deadtime values, and confound arrival-order scans with changes in total energy.
8 open issues
Keep total energy constant when reversing crossing order · New Reject out-of-range channel-death percentages · New Align the full-crossing selection with detector thickness · New Exclude suppressed hits from readout-merge checks · New Use the minimum adjacent hit-time gap · New Preserve deadtime fields through readout conversion · New Use distinct light-contributor counts for multi-particle metrics Add the new executables to the Makefile build
7 resolved since last review
Handle metrics files without TrueHitDx Guard missing provenance_spills in the scans-only workflow Match populated bins before computing efficiency differences Exclude pedestal-suppressed hits from timing statistics Preserve fractional percentages in scan filenames Reset the minimum when the brightest readout changes Use absolute paths for test fixtures
Review effort: Balanced
3be3542 to
d6f7370
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved defects misattribute particle contributions and readout truth, while valid low-statistics scans can fail during data reduction or page rendering.
5 open issues
Energy-dominant ID comes from the full event, not the selected readout · New Merged-hit attribution drops energy from non-primary particles · New Null photon statistics crash tooltip construction · New Empty histogram crashes chart rendering for small samples · New Zero-light cells cause division by zero during path-scan reduction · New
8 resolved since last review
Preserve deadtime fields through readout conversion Use the minimum adjacent hit-time gap Exclude suppressed hits from readout-merge checks Align the full-crossing selection with detector thickness Reject out-of-range channel-death percentages Keep total energy constant when reversing crossing order Use distinct light-contributor counts for multi-particle metrics Add the new executables to the Makefile build
Review effort: Balanced
bf856fd to
a4ff404
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Null statistics can trigger .toFixed() errors that prevent charts and notes from rendering, and missing times require filtering and a fallback in timing range calculations.
2 open issues
4 resolved since last review
Review effort: Balanced
a4ff404 to
f0647f3
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unguarded percentile calculations on empty timing-cell or partial-fill samples can abort validation, preventing page_data.json or metrics.json from being written.
2 open issues
2 resolved since last review
Review effort: Balanced
f9c41e6 to
f748f20
Compare
|
Pushed f748f20 from a local review of the stack: bad-channel warning in the legacy path (the list only applies with UseResponseElements, now stated in the description), a shared TMS_LightContribColumns helper for both tree writers (output unchanged: flag off 2636 branches identical to main, flag on contribution branches identical to the previous tip), a config-keyed ToT table, and load-time validation of the response-element settings (#356, #357). |
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved issues can break report rendering for valid run labels, silently report failed CSV exports as successful, and misclassify legitimate charge-mode readouts as merge failures.
4 open issues
2 resolved since last review
Review effort: Balanced
| o2 = np.lexsort((d["TrueHitT"][idx][order], grp)) | ||
| t = d["TrueHitT"][idx][order][o2] |
There was a problem hiding this comment.
Agreed on the description. The gaps are between deposit times while the window opens at the first photon, so a pair inside the window can be split legitimately. In 1fdebdb the report and README describe this as a close-deposit diagnostic, not a pass/fail test, and point to ChannelReadoutTest as the correctness test of the window logic.
There was a problem hiding this comment.
🟡 Changes recommended
Electron/photon hits contaminate the reported muon statistics, while other active issues can falsely flag merge failures, crash charts for supported run labels, and report success despite missing CSV output.
5 open issues
Review effort: Balanced
1fdebdb to
e941ed5
Compare
|
Copilot's latest review (on 1fdebdb) flags a header-only CSV when the reference channel is disabled. Traced: if the reference bar makes no hit (for example it is a listed bad channel), BarAxis::Probe() fails and the path/position scans returned with only the CSV header and exit 0. e941ed5 makes DetSimStageScan exit 1 with a message in that case. Not tested end to end with a bad reference bar. |
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
DetSimStageScan runs the detector-simulation stages in isolation; the scripts under scripts/Validation/DetSim/stages build the stage-by-stage HTML page from its output. README section documents usage. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…out) Full-thickness MIP crossings of the reference bar at 13 distances along its readout axis, for checking the absolute light scale against the PDR light-yield expectation and the fiber propagation delay. Also widens the stage-page intro paragraph. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
PE (with the PDR initial/aged light-yield bands), full-crossing survival and hit time versus distance from the readout, from DetSimStageScan position. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…thickness The reference scintillator bar is 16 mm thick (z 12924.5-12940.5 mm), not the 10 mm assumed in a code comment, so the 9 mm "full crossing" was only 56% of a perpendicular crossing. Center the reference crossing on the bar, extend the path scan to 12 and 16 mm, make the position scan use the full 16 mm path, and take the timing-mode "full crossing" at 16 mm. The 9 mm results (resegmentation, pairs, path <= 9 mm) are unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d grid scans
Output: TMS_TrueHit keeps every (trajectory, vertex) that produced a detected photon of
its readout with the photon count (SetLightContributions, filled by FillLightProvenance,
copied in all three hand-written copy/move members). Truth_Info and the readout tree get
TrueHitNLightContrib / TrueHitLightContribOffset per hit and the flat vectors
TrueHitLightContrib{PrimaryId,VertexId,Photons,Share}. Additive; the top-particle branches
are unchanged.
DetSimStageScan: new pileup mode (2-4 particles in one channel, staggered times and
energies, with the light provenance), optional distance argument for path mode (far-end
timing), per-track trajectories in the synthetic events. run_stage_scans.sh adds the
0.5/2 mm deposit-bin runs, the far-end runs and the pileup runs; stage_page_data.py and
the page template add the matching panels.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…s for real hits Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The electronics simulation (SimulateChannelReadout + noise, or the A5202 timing mode) now ends by handing its per-channel readouts on as TMS_RawReadout records (channel, time stamp, charge, time over threshold, the simulation's energies, and the hit id of the truth), and TMS_MCDecoder::Decode() turns those into the TMS_Hits reconstruction uses. The pedestal threshold moves from the simulation (SimulatePedestalSubtraction) into the decoder, which is also where calibration will go; a decoder for real data can sit beside it once the raw format exists. First version, deliberately output-neutral: every raw readout still becomes a hit, and hits below Sim.Readout.PedestalSubtractionThreshold (charge mode), or whose channel never fired (timing mode), are kept and flagged as pedestal suppressed, as before. The electronics functions still use TMS_Hit as their working container, and the raw record carries a copy of the bar as a stand-in for a channel map. Only with Sim.DetSim.UseResponseElements; the legacy path is untouched. Verified: Reco and Readout output of ConvertToTMSTree on 3 real spill files (27 spills) in charge, timing and charge + deadtime/zombie modes is identical to the parent commit in all 6082 branches. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A channel known to be missing or dead (TMS_ChannelId: plane, bar, view; the two halves of a split X-bar are separate channels) makes no TMS_Hit. The list is a TOML file named by [Decoder] BadChannelFile in the main config (relative to $TMS_DIR or absolute; the key is optional and defaults to the shipped file). Each entry has a status, "missing" or "dead" for now, and an optional reason; other statuses, duplicates and missing keys are errors. The shipped list is empty, so output is unchanged until a list is supplied. The raw readout and the event's truth hit are kept; only the TMS_Hit is not made, so per-hit truth branches written from the hit loop have no row for it. BadChannelsTest covers parsing and the error cases. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
DumpChannels walks the geometry and writes every electronics channel (plane, bar, view) as the simulation numbers it: 15,744 channels (82 planes x 192 bars) for the MiniProdN5 geometry, all distinct. make_bad_channel_lists.py draws bad channel lists from that file: for each seed one random order, and the first f% of it for each fraction, so the lists of a seed are nested. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The CMake build already had them; the Makefile build (used by CI) did not, so ConvertToTMSTree failed to link with undefined references to the decoder. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- BadChannelsTest: write the fixtures under an absolute directory; TMS_BadChannels resolves a relative name under $TMS_DIR, so a relative directory made it read a different place. - app/Makefile: rules and 'all' entries for ChannelReadoutTest, BadChannelsTest, DumpChannels and DetSimStageScan, as CMake already had. - DetSimStageScan: reset the smallest light-contributor id when the brightest readout changes. - make_bad_channel_lists.py: keep fractional percentages in the file names (f05p1), integer names unchanged. - detsim_validation.py: timing statistics use surviving hits only; the survival difference panel matches bins by bounds; multi-particle provenance uses TrueHitNLightContrib (omitted for older output) instead of TrueNTrueParticles. - stage_page_data.py / page_template.html: the same distinct-particle selection; a metrics file without survival_vs_dx and a scans-only run without --spills no longer fail. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…le members ChannelReadoutTest and DetSimStageScan set TG4PrimaryParticle::TrackId/PDGCode/Momentum, which are private in the edep-sim that CI clones, so the Make build failed to compile them (CI on the previous commit). They stay in CMake, like ArtificialResegmentationTest, which is not in the Makefile either. BadChannelsTest and DumpChannels do not touch those members and stay. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- DetSimStageScan / stage_page_data.py: bright_first and bright_last of n particles are the first n entries of one sequence, reversed for bright_last, so the two patterns of an n have the same total energy and differ only in the order of arrival (they differed for n < 4). The pileup scans need rerunning (run_stage_scans.sh, about a minute). - make_bad_channel_lists.py: reject percentages outside 0-100 (a negative fraction selected order[:-k], i.e. nearly every channel as dead). - detsim_validation.py: the 'full crossing' band was 8-12 mm but the bar is 16 mm thick; it is now 12-20 mm (and 2.5-4 MeV without TrueHitDx), so the timing table no longer excludes full crossings. The merging check counts surviving hits only (a zero-photon deposit is not a readout) and uses the smallest adjacent time gap of a group instead of its total span, which let a late hit hide a close pair. Plane coverage still uses all muon deposits. - TMS_RawReadout / decoder: the readout carries the deadtime start and stop the electronics simulation recorded (RECORD_HIT_DEADTIME), and the decoder restores them, so RecoHitDeadtimeStart/ Stop in the readout file are no longer -999 in charge mode with a deadtime. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- DetSimStageScan: energy-dominant particle taken from the selected readout's truth - stage page: null photon statistics and empty histograms no longer abort rendering - stage_page_data: zero-light cells give undefined ratios instead of ZeroDivisionError Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… range Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…hen the bad-channel list is ignored; US spelling Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- DetSimStageScan and DumpChannels: fail when the CSV cannot be opened or written - stage page: comparison series built from the actual metrics labels - validation report: lepton-dominated (not muon) wording, merge check described as a diagnostic Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…y CSV) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…er never keeps a zero-charge readout, bad-channel list loaded at configuration Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
e941ed5 to
7d37d47
Compare
|
Pushed 7d37d47 after a final local review. Fixed: the stage scan always probes the reference bar and rejects nthrows < 1 (no header-only or all-zero CSV reported as success); the decoder never keeps a zero-charge readout whatever the pedestal threshold; the bad-channel list is read at configuration load when UseResponseElements is on, so a malformed list fails at startup. Reviewed and left as is: truth, photon arrivals and response segments of decoder-dropped hits stay in the event (documented design); no photon cap in the response path (a performance question, not measured as a problem on full spills); EVis is not rescaled by the readout noise (same as the legacy path); TMS_Hit::MergeWith does not merge ToT (timing mode never merges through it); Resegment's point lookup is quadratic in the segment count (small in practice). Flag off: 2636 branches identical to main. |


Raw readouts and an MC decoder, a bad-channel list, and the validation tooling
TMS_RawReadoutrecords (channel, time stamp, charge, ToT, energies, truth hit id) toTMS_MCDecoder, which makes theTMS_Hits reconstruction uses. The pedestal threshold moves into the decoder, where calibration will go; a data decoder can sit beside it once the raw format exists. Output-neutral: identical in all 6082 branches on 3 real spills x 3 modes (commit message).[Decoder] BadChannelFilenames a TOML list of channels (plane, bar, view) with statusmissingordead; their readouts make noTMS_Hit. The shipped list is empty, so output is unchanged. The raw readout and the event's truth hit are kept, so per-hit truth rows have no entry for a dropped hit.BadChannelsTestcovers parsing and errors. AlsoDumpChannelsand a random bad-channel list generator for scans.DetSimStageScan, stage-by-stage plot-page scripts, a hit-level validation script, andTrueHitDx(true path length) inTruth_Info.All of this applies only with
Sim.DetSim.UseResponseElements=true.Default behavior
Existing branches are unchanged; the only differences are new branches. Against
mainat 60f2edf, default config, 4 real spills (1, 4, 6, 7): 2636 pre-existing branches, 0 differences.Not in this stack: making the response-element simulation the default, which waits for reco-level validation.
Known limitations
Sim.DetSim.UseResponseElements = true) uses. The legacy detector simulation never reads it; a non-empty list there prints a one-time warning and the hits of the listed channels are kept.🤖 Generated with Claude Code