Skip to content

Detector sim 1/4: fix segmentation-dependent hit-time bias (flag off by default) - #355

Draft
SFBayLaser wants to merge 4 commits into
mainfrom
feature/usher_detsim_passages
Draft

SFBayLaser wants to merge 4 commits into
mainfrom
feature/usher_detsim_passages

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 1 of 4 in a stack, tracked in #330. Base: main. Above it: the per-channel readout, front-end/truth, and decoder/bad-channel PRs.

Fix the segmentation-dependent hit-time bias (flag off by default)

On release 1.1.0 the reconstructed hit time depends on how many Geant4 steps a crossing was split into: each fragment becomes its own TMS_Hit with its own random PE and timing draw, and the later merge keeps the earliest time. In the ArtificialResegmentationTest harness the same 9 mm muon crossing gives dt = t_reco - t_true of 12.04 ns as 1 step but -0.10 ns as 20 steps.

With Sim.DetSim.UseResponseElements=true, ProcessTG4Event() now merges coincident same-bar fragments on the vertex's own deterministic true times before any random draw. Harness result with the flag on: dt is flat within ~0.1 ns across 1-20 steps (12.02-12.09 ns), exactly 1.0 hits, PE and survival unchanged, all four scenarios. Also adds TMS_Passage (BuildPassages, Resegment), unit-tested in PassageUtilsTest (15 checks); later PRs in the stack use it.

Known limitations (superseded by the next PR in the stack)

The pre-response merge combines all same-bar fragments of one vertex within the readout window, and the merged hit and truth time is the minimum of the fragment midpoints. For a crossing that lasts many nanoseconds (slow particles), or passages far apart in time within one bar, the merged hit has one timing draw at the earlier time. For muons (about 0.05 ns per bar) this is negligible, which is why the harness result is flat. #356 replaces it with per-deposit photon arrival times.

Default behavior

Unchanged. Verified against main at 60f2edf with the default config on 4 real spills (1, 4, 6, 7): every pre-existing branch of every tree is identical (2636 branches, 0 differences).

🤖 Generated with Claude Code

…fore simulation

On release 1.1.0 the reconstructed hit time depends on how many Geant4 steps a
crossing was split into. Each fragment becomes its own TMS_Hit and gets its own
random PE and timing draw, and the post-simulation merge then keeps the earliest
time. In the ArtificialResegmentationTest harness the same physical 9 mm muon
crossing gives dt = t_reco - t_true of 12.04 ns as 1 step but -0.10 ns as 20
steps (~12 ns swing), with 6% of 20-step throws ending up with extra final hits.
The pre-simulation coincident-hit merge (873c1af, PR #317) never reached main:
#318 brought over the timing fix and #319 the RNG seeding, not this. #318's
timing loop is not the cause (putting bf46891's Poisson photon count on 1.1.0
left the bias in place).

With Sim.DetSim.UseResponseElements=true, ProcessTG4Event() now runs
MergeCoincidentHits() on the vertex's own deterministic true times before any
random draw and before overlay, as 873c1af did. Harness result, flag on: dt is
flat within ~0.1 ns across 1-20 steps (12.02-12.09 ns), exactly 1.0 hits, PE and
survival unchanged, for all four scenarios. Default (false) is unchanged. The
"not yet implemented" throw for the flag is removed. Numbers and baseline:
reports/2026-09-13_segmentation_timing_benchmark/phase2_baseline/BASELINE.md.

Also adds TMS_Passage (BuildPassages, Resegment): plain-data helpers that stitch
raw steps into per-bar passages and re-slice a passage onto a fixed spatial scale
by geometric overlap (E_ij = E_j * L_ij / L_j), conserving energy and giving the
same bins however the deposit was split. Unit-tested in PassageUtilsTest (15
checks). Not yet used by the simulation; later phases consume it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@SFBayLaser
SFBayLaser added this pull request to stack #359 November 12, 2026 19:09
@SFBayLaser SFBayLaser changed the title feature/usher detsim passages Detector sim 1/4: fix segmentation-dependent hit-time bias (flag off by default) Nov 12, 2026
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 12, 2026 19:14

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

Pre-response merging can sum uninitialized visible energy and combine physically separate passages, corrupting energy values and advancing pulse timing.

5 open issues
What changed in this PR

This PR adds an opt-in pre-response hit merge to address segmentation-dependent timing in the detector simulation, plus passage utilities for later response-model stages. The default configuration remains off.

Changes:

  • Merge same-channel fragments before optical and timing simulation when enabled.
  • Add passage grouping and fixed-scale resegmentation helpers with a standalone validation executable.
  • Update flag documentation and register the validation executable with CMake.
File Description
src/​TMS_Readout_Manager.h Updates comments describing the response-pipeline flag.
src/​TMS_Passage.h Defines segment, passage, and optical-deposit interfaces.
src/​TMS_Passage.cpp Implements passage grouping and energy-preserving resegmentation.
src/​TMS_Event.cpp Adds the gated pre-response merge and removes the unimplemented-pipeline exception.
config/​TMS_Readout_Default_Config.toml Documents enabled behavior while retaining the false default.
app/​PassageUtilsTest.cpp Adds checks for grouping, energy conservation, interpolation, and split invariance.
app/​CMakeLists.txt Builds, links, and installs PassageUtilsTest.

Review effort: Balanced

Comment thread src/TMS_Event.cpp Resolved
Comment thread src/TMS_Event.cpp Resolved
Comment thread app/CMakeLists.txt Resolved
Comment thread src/TMS_Event.cpp Resolved
Comment thread src/TMS_Passage.cpp Resolved
…file build, snap bin count

- TMS_Hit: EnergyDepositVisible was never initialized by the edep-sim constructor, so the
  pre-response merge (TMS_Hit::MergeWith) summed uninitialized values. It is set later by the
  optical model, but initialize it to 0 so the merge is defined.
- Makefile build (the one CI uses): add TMS_Passage.o to the library and a PassageUtilsTest
  target to app/Makefile, as CMake already had.
- TMS_Passage::Resegment: the summed path length depends on how many steps it is built from
  (a 6-8-10 crossing sums to 10 for one step and 10.000000000000002 for ten), which made the
  bin count 10 vs 11. Ratios within 1e-9 of an integer are snapped before the ceiling. New
  PassageUtilsTest check for the tilted crossing; it fails without the fix.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

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

The new passage-binning helper lacks bin-length and bin-count guards, allowing zero or tiny bin lengths to trigger undefined behavior through an out-of-range double-to-int conversion.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Validate bin length and count before casting or allocation

src/​TMS_Passage.cpp:75

For a nonempty 10 mm passage, max_bin_length_mm = 0 makes the requested bin count infinite, while 1e-12 requests 10^13 bins. Both reach an out-of-range double-to-int conversion here, which is undefined behavior. The new public helper has no argument or count guard. Reject nonpositive/nonfinite bin lengths and check that the computed count fits the index/allocation limits before casting and resizing.

5 resolved since last review

Review effort: Balanced

…n lengths

A bin length of 0 made the bin count infinite and 1e-12 asked for 1e13 bins, both reaching an
out-of-range double-to-int conversion (undefined behavior) before the allocation. Reject a
nonpositive or non-finite bin length (std::invalid_argument) and a count above 1e6
(std::length_error) before casting. PassageUtilsTest checks 0, -1, 1e-12, inf and nan.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@SFBayLaser

Copy link
Copy Markdown
Member Author

Addressed the bin-length finding from the second review in 378cd6a: TMS_Passage::Resegment now throws std::invalid_argument for a zero, negative or non-finite max_bin_length_mm, and std::length_error if the bin count would exceed 1e6, both before the double-to-int conversion and the allocation. PassageUtilsTest checks 0, -1, 1e-12, inf and nan.

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

Equal-start-time deposits can be grouped differently depending on input order because ties are not broken by stop time.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Break equal-start-time ties by stop time to ensure consistent grouping

src/​TMS_Passage.cpp:37

With equal start times, input order can change passage grouping: a same-bar, same-trajectory point deposit at z=0, t=0 followed by a step from z=0 to z=3 mm over 0–0.01 ns forms one passage with a 0.5 mm gap limit, but reversing the entries forms two. The gap check then compares the outgoing step's endpoint with the point deposit, making identical deposits produce different groups. Break start-time ties by stop time so the point deposit precedes the outgoing step.

Review effort: Balanced

Steps with the same start time (a point deposit and the step that leaves from it) were left in
input order by the stable sort, so the gap check could group them differently when the input was
reversed: with a 0.5 mm gap limit, a point at z = 0 and a 0 - 3 mm step over 0 - 0.01 ns were
one passage in one order and two in the other. Order by start time, then stop time, then
position. PassageUtilsTest checks both orders; it fails without the fix.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@SFBayLaser

Copy link
Copy Markdown
Member Author

Addressed the tie-break finding in 800118f: BuildPassages now orders steps by start time, then stop time, then position, so the grouping does not depend on input order. PassageUtilsTest has the point-deposit-plus-step case in both orders; it fails on the previous code.

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.

🟢 Approval recommended

No active review issues are recorded for the opt-in pre-response hit merge and passage utilities.

No open issues 🎉

Review effort: Balanced

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