Skip to content

Detector sim 2/4: light per optical deposit and per-channel readout (flag off by default) - #356

Draft
SFBayLaser wants to merge 9 commits into
feature/usher_detsim_passagesfrom
feature/usher_detsim_channel_readout
Draft

SFBayLaser wants to merge 9 commits into
feature/usher_detsim_passagesfrom
feature/usher_detsim_channel_readout

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 2 of 4 in a stack, tracked in #330. Base: the passages PR (#355). Above it: the front-end/truth PR and the decoder/bad-channel PR.

Light per optical deposit, and readout per electronics channel (flag off by default)

Three commits, each reviewable on its own; all act only with Sim.DetSim.UseResponseElements=true.

  1. Sim.Optical.PoissonAfterAttenuation (default false): apply the path efficiencies to the expected PE first, then Poisson-draw each fiber path. The current draw gives Fano factor ~0.31 (equal to the path efficiency) instead of 1. With the option on: Fano 1.00 +- 0.02, integer PE, same mean (chi2/ndf 14.4/20 across 20 cells).
  2. Light per optical deposit with explicit photon arrival times. Hits keep the raw edep-sim steps; the optical model stitches them into ~1 mm deposits and, per deposit, applies Birks suppression, computes fiber-path efficiencies at the deposit's position, Poisson-draws photons, and gives every photon an arrival time. The timing model takes the first photon plus electronic noise. New config: Sim.DetSim.DepositBinLength, PassageMaxGap, and a [Sim.Timing] section.
  3. Per-channel readout with a typed channel id. Adds TMS_ChannelId (plane, bar, view). The legacy (z, NotZ) key merges the two halves of a split X-bar: 2880 of 12864 distinct keys on MiniProdN5 files 1-15 cover two channels. SimulateChannelReadout() replaces the deadtime and post-simulation merge stages with one per-channel readout-window stage. New ChannelReadoutTest app.

Validation numbers are in each commit message.

Default behavior

Unchanged. Against main at 60f2edf, default config, 4 real spills (1, 4, 6, 7): 2636 pre-existing branches, 0 differences.

🤖 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 channel readout Detector sim 2/4: light per optical deposit and per-channel readout (flag off by default) Nov 12, 2026
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_channel_readout branch from 5fe325c to b5c5ec2 Compare November 12, 2026 21:46
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 12, 2026 22:56
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_channel_readout branch from b5c5ec2 to 8061024 Compare November 12, 2026 22:57

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 critical issues break previously valid readout configurations and make response-enabled readout counts and charge depend on Geant4 hit segmentation.

6 open issues
What changed in this PR

This PR extends the detector-response redesign from passage handling to deposit-level light simulation and channel-level readout, while keeping the response-element pipeline disabled by default.

Changes:

  • Adds per-deposit optical response, photon arrival times, and configurable optical and timing settings.
  • Introduces typed channel IDs and combined readout-window, deadtime, and merging logic.
  • Adds a validation harness for same-channel crossings and split X-bar channels.
File Description
src/​TMS_SignalProcessing.cpp Checks channel identity and maintains response segments during merges.
src/​TMS_Readout_Manager.h Exposes new optical, deposit, and timing settings.
src/​TMS_Readout_Manager.cpp Loads the new simulation settings.
src/​TMS_Hit.h Defines typed electronics-channel IDs.
src/​TMS_Event.h Adds per-hit storage for raw response segments.
src/​TMS_Event.cpp Records and transfers segments and selects channel readout.
src/​TMS_DetectorSimulation.h Declares the channel-readout stage.
src/​TMS_DetectorSimulation.cpp Implements deposit-level light, photon timing, and channel readout.
config/​TMS_Readout_Default_Config.toml Documents and supplies simulation defaults.
app/​CMakeLists.txt Registers and installs the new validation executable.
app/​ChannelReadoutTest.cpp Exercises readout windows, deadtime, and split channels.

Review effort: Balanced

Comment thread src/TMS_DetectorSimulation.cpp Resolved
Comment thread src/TMS_Readout_Manager.cpp Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
SFBayLaser and others added 5 commits November 12, 2026 18:39
SimulateOpticalModel() Poisson-draws the produced PE, splits it binomially
between the short and long fiber paths, and only then scales each path by
WLS attenuation, end reflection, additional-fiber and readout coupling
efficiencies. The result is a fractional PE whose fluctuations are scaled
down with it: the variance/mean (Fano factor) of the detected PE equals the
path efficiency (~0.31 for the harness crossing) instead of 1.

New Sim.Optical.PoissonAfterAttenuation (default false, no behaviour
change) applies all the path efficiencies to the expected PE first and
Poisson-draws each path from its own expected mean. Photons survive
independently, so this is the photon-counting distribution: integer PE with
Poisson variance and the same mean. This is Phase 4 of the detector-response
redesign and is what per-segment channel accumulation (Phase 5) needs:
Poisson means add, attenuated draws do not.

The default path keeps the previous arithmetic and random-number sequence
exactly (ArtificialResegmentationTest output byte-identical to the 1.1.0
baseline, and to the Phase 3 output with UseResponseElements on).

Validation (ArtificialResegmentationTest, 4 scenarios x 5 segment counts):
- Readout noise and pedestal threshold off, 20000 throws per cell: mean
  total PE agrees between the two orders in all 20 cells (chi2/ndf 14.4/20,
  max |z| 1.76); Fano factor 1.00 +- 0.02 with the option, ~0.31 without;
  PE always integer with the option.
- Default readout: survival of the 1.5 mm grazing crossing (mean ~2 PE,
  below the 3 PE threshold) rises from 14.5% to 24.8%, because the old
  draw was ~3x too narrow; bright crossings are unchanged in survival and
  mean PE, first-hit time +0.2 ns, rms +0.3 ns.

Real spills (MiniProdN5 files 1-15, option on vs off, with a seed-salt
null control for scale): hits above threshold +1.09% (null -0.04%),
detected PE summed over short+long paths -0.010% (null -0.004%), tracks
+1.10% (null +0.43%), muon vertices with a muon track +1.17% (null
+0.46%).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With Sim.DetSim.UseResponseElements=true, each hit now keeps the raw
edep-sim steps it was built from (TMS_Event side table, carried through the
pre-simulation merge, hit removal and spill overlay like the truth and
photon-arrival tables). SimulateOpticalModel() stitches them into passages
and ~1 mm optical deposits (TMS_Passage, Phase 3) and, per deposit:
- applies Birks suppression from the deposit's own dE/dx,
- computes short/long fiber path efficiencies at the deposit's own
  position along the bar,
- Poisson-draws the detected photons per path from the attenuated mean
  (Phase 4 semantics), and
- gives every photon an explicit sensor arrival time (deposit time +
  propagation from the deposit, corrected to the strip centre, + scintillator
  and WLS decays).
SimulateTimingModel() then takes the first photon plus electronic noise.
New config: Sim.DetSim.DepositBinLength (1 mm), Sim.DetSim.PassageMaxGap
(0.5 mm). The timing-model constants move to [Sim.Timing] with their old
values. Default behaviour (flag off, with or without
PoissonAfterAttenuation) is unchanged: ArtificialResegmentationTest output is
byte-identical, and all trees of a real spill file (0000007) are identical.

Validation (MiniProdN5 files 1-15; baseline = Phase 3 + Phase 4 option, i.e.
flag on with PoissonAfterAttenuation; null = this build with another RNG
seed, for scale):
- Harness: matches the baseline within statistics in all 20 cells (PE, PE
  spread, survival, time, time spread), flat across 1-20 steps, exactly one
  hit. Expected, since the synthetic crossings have uniform dE/dx.
- Real spills: detected PE per MeV -0.42% for muon-dominated hits (null
  -0.44%) but -16.7% for hadronic hits; total detected PE -6.0%, hits above
  threshold -9.0%, tracks -1.7%.
- The whole difference is Birks: with BirksConstant=0 (files 2, 7, 12) the
  two agree to 0.06% (hadronic) and 0.01% (muon), and every other
  quantity to within 0.15%.
- Against the default pipeline, which applies Birks per Geant4 step: the
  Phase 3 pre-simulation merge had raised hadronic PE per MeV by 22.7% (dE/dx
  averaged over everything merged into a hit, under-quenching stopping
  hadrons); with this change it is within 2.3% of the default, and total
  detected PE and hits above threshold are within ~1%.
- CPU time +0.9% relative to the baseline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds TMS_ChannelId (plane, bar, view) and TMS_Hit::GetChannelId(). The
existing readout code identifies a channel by (z, NotZ): the post-simulation
merge compares them directly and the deadtime code builds the surrogate
NotZ + 100000*z. That key does not distinguish the two halves of a split
X-bar (e.g. plane 81 bars 128/129), which are separate channels read out at
opposite ends: on MiniProdN5 files 1-15, 2880 of the 12864 distinct
(z, NotZ) keys cover two channels, while (plane, bar, view) maps one-to-one.

With Sim.DetSim.UseResponseElements=true:
- New SimulateChannelReadout() replaces SimulateDeadtime() and the
  post-simulation MergeCoincidentHits(): per channel, in time order, the
  first hit opens a readout window (Sim.Readout.ReadoutTime), later hits in
  it are merged (with their truth, photon arrivals and raw steps), and the
  existing deadtime/zombie-time rules apply. One stage does the windowing,
  so the merge can no longer double-merge or mask a deadtime decision.
- The electronic time noise is drawn once per readout (after the merge)
  instead of once per sub-hit, as the readout PE noise already is.
- The pre-simulation merge in ProcessTG4Event() also requires the same
  channel, so one vertex's steps in the two halves of an X-bar are no longer
  simulated as one hit attenuated towards one end.
Default behaviour is unchanged (harness output byte-identical; real spill
file 0000007 identical in every branch of every tree).

New ChannelReadoutTest app: two crossings of known bars at a known time
difference through the real FinalizeEvent(), checked against the readout
window/deadtime/zombie configuration in effect. All cases pass with the flag
on (no deadtime; 500 ns deadtime; 500 ns deadtime + 100 ns zombie time).
With the flag off it shows the old behaviour: two simultaneous crossings
of the two halves of an X-bar give one hit.

Validation (MiniProdN5 files 1-15, flag on, against Phase 5; Phase 5 with
another RNG seed gives the noise scale):
- Harness: identical to Phase 5 (single crossings, one noise draw).
- Readout hits +0.91% (noise 0.00%): exactly the X-bar half pairs now kept
  apart, 36945 pairs within 120 ns (2973 with both halves above threshold,
  13027 with one). In truth, 60% of these pairs come from the same
  interaction (median dt 11.5 ns), i.e. mostly one event depositing in both
  halves, which the old key merged into a single hit on one side.
- Tracks +1.01% (noise -0.33%), muon vertices covered +0.61% (-0.44%),
  hits above threshold +0.06%, PE per MeV -0.14% (muon) / -0.38% (hadronic).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… zero-PE hits, deadtime fields, zombie stamp

- TMS_Readout_Manager: the keys added with the response-element pipeline (PoissonAfterAttenuation,
  DepositBinLength, PassageMaxGap and the [Sim.Timing] constants) are read with find_or and the
  shipped values, so older custom readout configs still load with the flag off.
- SimulateOpticalModel: without Poisson throws the per-deposit PE is fractional and rounding each
  deposit up made the photon count depend on DepositBinLength. The count per path is now the
  ceiling of the running total, so it does not depend on how the path is split.
- SimulateChannelReadout: hits with no detected photon no longer open a readout window or a
  deadtime; per-hit DeadtimeStart/Stop are set when RECORD_HIT_DEADTIME is defined; a readout keeps
  the time it was opened at when later hits join it (a zombie readout opens at the end of the
  deadtime, and MergeWith() kept the earlier crossing time, inside the deadtime).
- ChannelReadoutTest: new zombie_pair case (two crossings in the zombie time: one readout,
  stamped after the deadtime).

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

Crossings closer than the readout time are merged before the simulation, so the zombie_pair case
could not reach the readout stage with two hits. The case now needs ZombieTime >= ReadoutTime + 60
ns (e.g. Deadtime 300, ZombieTime 200 with ReadoutTime 120), checks the readout time (the latest
readout must be stamped after the deadtime), and prints the mean latest readout time. Without the
timestamp fix in the previous commit it fails (readout stamped at ~380 ns, inside the deadtime);
with it it passes (430.7 ns). The same_bar readout + 80 ns case is skipped when a deadtime is set,
where it sits at the zombie edge.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_channel_readout branch from 8061024 to 314185a Compare November 13, 2026 03:07
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 03:09

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/CMakeLists.txt Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
Comment thread src/TMS_DetectorSimulation.cpp Resolved
The two decay-time draws were operands of one + expression; their evaluation order is unspecified
in C++ and they share one generator, so the photon times could differ between compilers for the
same seed. Draw the scintillator time, then the WLS time, in separate statements (as the legacy
timing loops do). Documented that without Poisson throws the photon of a fractional path is
emitted where the running total first crosses an integer.

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.

🟢 Approval recommended

No active review issues remain for the opt-in detector-response and channel-readout changes.

No open issues 🎉

3 resolved since last review

Review effort: Balanced

…ader comment

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

Human assessment is needed because accepted timing configurations can violate random-distribution preconditions, potentially producing invalid delays or aborts.

No open issues 🎉

Review effort: Balanced

…sigma positive

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

Copy link
Copy Markdown
Member Author

Copilot's latest review (on 0e76d8d) notes that accepted timing configurations can violate random-distribution preconditions. Checked: an infinite decay time passed the positivity check (exponential_distribution with rate 0), and a time noise of 0 is not a valid normal_distribution sigma. 7cd372b requires finite decay times, refractive index and time noise, and keeps the time-noise sigma at a small positive minimum so noise-free runs still work. Shipped defaults are unchanged (flag off: 2636 branches identical to main; an infinite scintillator decay time is rejected at load).

…ve sigma for its noise draw

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

Copy link
Copy Markdown
Member Author

Pushed 8fba322 after a final local review: the Sim.Timing settings (decay times, refractive index, time noise, MaxTimingPhotons) are now validated for the legacy timing model too, not only with UseResponseElements, and the legacy time-noise draw keeps a positive sigma. 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