Skip to content

Detector sim 4/4: raw readouts, MC decoder, bad-channel list, validation tooling - #358

Draft
SFBayLaser wants to merge 22 commits into
feature/usher_detsim_truth_outputfrom
feature/usher_detsim_bad_channels
Draft

SFBayLaser wants to merge 22 commits into
feature/usher_detsim_truth_outputfrom
feature/usher_detsim_bad_channels

Conversation

@SFBayLaser

@SFBayLaser SFBayLaser commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Timing: this PR is for after the final tag of the upcoming production. It is not intended for that tag.
Stacked: PR 4 of 4 in a stack, tracked in #330. Base: the front-end/truth PR (#357). This is the top of the stack; the default-on flip is a separate, later PR.

Raw readouts and an MC decoder, a bad-channel list, and the validation tooling

  1. Raw readout and decoder. The electronics simulation ends by handing per-channel TMS_RawReadout records (channel, time stamp, charge, ToT, energies, truth hit id) to TMS_MCDecoder, which makes the TMS_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).
  2. Bad-channel list. [Decoder] BadChannelFile names a TOML list of channels (plane, bar, view) with status missing or dead; their readouts make no TMS_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. BadChannelsTest covers parsing and errors. Also DumpChannels and a random bad-channel list generator for scans.
  3. Validation tooling: DetSimStageScan, stage-by-stage plot-page scripts, a hit-level validation script, and TrueHitDx (true path length) in Truth_Info.

All of this applies only with Sim.DetSim.UseResponseElements=true.

Default behavior

Existing branches are unchanged; the only differences are new branches. Against main at 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

  • The bad-channel list is applied by the decoder, which only the response-element pipeline (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

@SFBayLaser
SFBayLaser added this pull request to stack #359 November 12, 2026 19:09
@SFBayLaser SFBayLaser changed the title feature/usher detsim bad channels Detector sim 4/4: raw readouts, MC decoder, bad-channel list, validation tooling Nov 12, 2026
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch 2 times, most recently from 9c2054b to 2dfaa95 Compare November 12, 2026 22:57
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 12, 2026 23:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
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

Comment thread app/BadChannelsTest.cpp Resolved
Comment thread app/CMakeLists.txt Resolved
Comment thread app/DetSimStageScan.cpp Resolved
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from 2dfaa95 to 3be3542 Compare November 13, 2026 03:07
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 03:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread app/DetSimStageScan.cpp Resolved
Comment thread src/TMS_Event.cpp Resolved
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from 3be3542 to d6f7370 Compare November 13, 2026 03:39
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 16:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread app/DetSimStageScan.cpp Resolved
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from bf856fd to a4ff404 Compare November 13, 2026 16:33
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 16:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from a4ff404 to f0647f3 Compare November 13, 2026 17:00
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 17:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch 2 times, most recently from f9c41e6 to f748f20 Compare November 13, 2026 19:25
@SFBayLaser

Copy link
Copy Markdown
Member Author

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).

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread app/DetSimStageScan.cpp Resolved
Comment thread app/DumpChannels.cpp Resolved
Comment on lines +181 to +182
o2 = np.lexsort((d["TrueHitT"][idx][order], grp))
t = d["TrueHitT"][idx][order][o2]

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because a disabled reference channel can produce an unusable, header-only CSV while the scan process and wrapper still report success.

1 open issue
4 resolved since last review

Review effort: Balanced

@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from 1fdebdb to e941ed5 Compare November 13, 2026 20:49
@SFBayLaser

Copy link
Copy Markdown
Member Author

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.

SFBayLaser and others added 22 commits November 13, 2026 19:23
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>
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_bad_channels branch from e941ed5 to 7d37d47 Compare November 14, 2026 03:38
@SFBayLaser

Copy link
Copy Markdown
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants