Skip to content

Detector sim 3/4: A5202 timing-mode front end and light provenance (flag off by default) - #357

Draft
SFBayLaser wants to merge 10 commits into
feature/usher_detsim_channel_readoutfrom
feature/usher_detsim_truth_output
Draft

SFBayLaser wants to merge 10 commits into
feature/usher_detsim_channel_readoutfrom
feature/usher_detsim_truth_output

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 3 of 4 in a stack, tracked in #330. Base: the per-channel readout PR (#356). Above it: the decoder/bad-channel PR.

A5202 timing-mode front end, and light provenance in the truth output

  1. Timing-mode front end (Sim.DetSim.FrontEndTimingMode, default false): per channel, the fast-shaper pulses of all detected photoelectrons are summed and a discriminator gives one hit per pulse with a crossing time and a time over threshold (ToT), on the A5202's 0.5 ns TDC step. New RecoHitToT branch (-999 when not measured). Sourced constants are listed in the commit message (Citiroc-1A datasheet, DUNE ND PDR).
  2. Retune from the A5202 manual's ToT curve: FastShaperOrder 1 -> 2 and threshold 3.0 -> 1.7 pe (rms 2.8 ns against 11.8 ns for order 1; fit in scripts/Validation/DetSim/fit_tot_curve.py), 9-bit ToT clip (ToTMax = 255.5 ns), optional hysteresis. Timing and ToT-energy resolution at these settings have not been re-measured. Dark counts are not simulated.
  3. Which particles produced each hit's light: every detected photon carries its parent's trajectory and vertex id. New branches TrueHitNPhotons, TrueHitPrimaryIdByLight, TrueHitVertexIdByLight, TrueHitLightShare, TrueHitFirstPhotonPrimaryId, TrueHitFirstPhotonVertexId (-999 unless the flag is on).

Default behavior

Existing branches are unchanged; the only differences are the new branches above. Against main at 60f2edf, default config, 4 real spills (1, 4, 6, 7): 2636 pre-existing branches, 0 differences.

Known limitations

  • SiPM pixel saturation is applied to the reported PE only. The waveform, the discriminator crossings (time stamp and ToT) and the ToT-derived energy use the unsaturated charge. This only matters for charges of order the pixel count (1584) or more, far above the tens of PE of typical hits; modeling it inside the waveform would change the physics model and need retuning.
  • A hit spanning several discriminator pulses is read out once (documented in the code).
  • The retune is a fit to the A5202 manual's ToT curve (the 2.8 ns rms is that fit, not a measured resolution of the simulation). The timing and ToT-energy resolutions of the simulation at the retuned settings have not been measured against data, which is why the timing mode stays off by default.

🤖 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 truth output Detector sim 3/4: A5202 timing-mode front end and light provenance (flag off by default) Nov 12, 2026
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch 2 times, most recently from 9b296a0 to 92883a1 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 critical defects can make older configurations fail during construction and discard valid discriminator-pulse readouts or corrupt their photon provenance.

5 open issues
What changed in this PR

This third detector-response PR extends per-channel readout with optional A5202 timing simulation and photon-source truth data. Timing mode remains disabled by default, pending post-production validation.

Changes:

  • Adds discriminator-based hit timing, time over threshold (ToT), and optional ToT-derived energy.
  • Tracks photon contributors and writes light-provenance branches to truth output.
  • Adds front-end configuration and a script fitting the shaper model to the A5202 reference curve.
File Description
src/​TMS_TrueHit.h Stores and copies light-provenance summaries.
src/​TMS_TreeWriter.h Declares light-provenance output arrays.
src/​TMS_TreeWriter.cpp Creates and fills slice-level provenance branches.
src/​TMS_ReadoutTreeWriter.h Declares provenance and ToT arrays.
src/​TMS_ReadoutTreeWriter.cpp Writes provenance and ToT readout branches.
src/​TMS_Readout_Manager.h Exposes front-end settings.
src/​TMS_Readout_Manager.cpp Loads timing-mode configuration.
src/​TMS_Hit.h Adds photon-source identifiers and hit ToT.
src/​TMS_Event.h Extends photon recording and declares provenance summarization.
src/​TMS_Event.cpp Selects timing-mode readout and summarizes photon contributors.
src/​TMS_DetectorSimulation.h Declares the timing-mode simulation interface.
src/​TMS_DetectorSimulation.cpp Implements photon attribution, discriminator pulses, and ToT calibration.
scripts/​Validation/​DetSim/​fit_tot_curve.py Fits shaper parameters to the reference ToT curve.
config/​TMS_Readout_Default_Config.toml Documents front-end parameters and disabled-by-default timing mode.

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
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch from 92883a1 to 9afb5b6 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 src/TMS_Readout_Manager.cpp Resolved
Comment thread src/TMS_Readout_Manager.cpp Resolved
Comment thread src/TMS_Event.cpp Resolved
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch from 9afb5b6 to a817538 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.

🟡 Changes recommended

The configuration accepts a positive stop threshold above the start threshold, which can produce repeated discriminator crossings and an incorrect 0 ns ToT instead of a single pulse.

1 open issue
3 resolved since last review

Review effort: Balanced

Comment thread src/TMS_Readout_Manager.cpp Resolved

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 SiPM saturation is applied after waveform computation, leaving timing, ToT, and ToT-derived energy based on unsaturated charge.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@SFBayLaser

Copy link
Copy Markdown
Member Author

Copilot's latest review (on 3be3e3e) raised SiPM saturation, which is applied to the reported PE only and not inside the waveform (so timing, ToT and ToT-derived energy use the unsaturated charge). Agreed as a known limitation: it only matters for charges of order the 1584 pixel count, far above typical hits. Documented in a code comment (f671e37) and in the PR description.

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 an unpublished finding identifies a configuration edge case that can greatly inflate simulated signals and corrupt reconstructed energy.

No open issues 🎉

Review effort: Balanced

@SFBayLaser

Copy link
Copy Markdown
Member Author

Copilot's latest review (on f671e37) mentions an unpublished finding about a configuration edge case that can inflate simulated signals. I could not see the detail, so I checked the saturation curve: pixels*(1-exp(-q/pixels)) blows up for a non-positive pixel count. 3c46803 now rejects non-positive SiPMPixels and ToTMax at configuration time (timing mode on). If Copilot meant a different setting, please point me at it.

@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch from 3c46803 to e172313 Compare November 13, 2026 19:25
@SFBayLaser
SFBayLaser requested a balanced review from Copilot November 13, 2026 19:32

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 retuned front end changes detector physics when enabled, but timing and ToT-energy resolutions remain unmeasured, requiring detector/electronics expertise and representative runtime validation.

No open issues 🎉

Review effort: Balanced

@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch from e172313 to ea05365 Compare November 13, 2026 19:55
@SFBayLaser

Copy link
Copy Markdown
Member Author

Copilot's latest review (on e172313) notes that the retuned front end changes the physics when enabled and that its timing and ToT-energy resolutions are not measured. Agreed, and now stated in the description under Known limitations: the retune is a fit to the A5202 manual's ToT curve, the resolutions of the simulation at these settings have not been measured against data, and the timing mode stays opt-in for that reason.

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 cause an infinite waveform loop, overestimate ToT-derived energy when reflected light is present, and trigger assertion failures for zero timing jitter.

3 open issues

Review effort: Balanced

Comment on lines +751 to +755
auto arrival_pdf = [&](double s) {
if (s <= 0) return 0.0;
if (std::fabs(tau_wls - tau_scint) < 1e-9) return s * std::exp(-s / tau_wls) / (tau_wls * tau_wls);
return (std::exp(-s / tau_wls) - std::exp(-s / tau_scint)) / (tau_wls - tau_scint);
};

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 that the ToT calibration covers direct light only. ec5a507 rejects EnergyFromToT with reflected light (WSFEndReflectionEff > 0 or ShouldSimulateFiberLengths = false) until the calibration includes the delayed photons; shipped defaults are unaffected (EnergyFromToT off, reflection 0).

Comment thread src/TMS_Readout_Manager.cpp Outdated
}
if (_SIM_DETSIM_UseResponseElements && _SIM_DETSIM_FrontEndTimingMode) {
if (_SIM_FRONTEND_FastShaperOrder <= 0) throw std::runtime_error("Sim.FrontEnd.FastShaperOrder must be positive (the pulse tail never decays otherwise)");
if (!(_SIM_FRONTEND_FastShaperPeakingTime > 0)) throw std::runtime_error("Sim.FrontEnd.FastShaperPeakingTime must be positive");

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.

Fixed in ec5a507: FastShaperPeakingTime must be positive and finite (also the threshold and TDC step), so an infinite value is rejected at load instead of hanging the waveform loop (checked with inf).

Comment thread src/TMS_DetectorSimulation.cpp Outdated
const double pixels = config.Get_Sim_FrontEnd_SiPMPixels();
const bool energy_from_tot = config.Get_Sim_FrontEnd_EnergyFromToT();
const double calibration = TMS_Manager::GetInstance().Get_RECO_CALIBRATION_EnergyCalibration();
std::normal_distribution<double> jitter(0.0, config.Get_Sim_FrontEnd_TimingJitter());

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.

Fixed in ec5a507: with TimingJitter = 0 no draw is made, and a negative or non-finite value is rejected at load (checked: zero jitter runs a full spill, negative is rejected).

SFBayLaser and others added 10 commits November 13, 2026 19:23
New Sim.DetSim.FrontEndTimingMode (default false; needs UseResponseElements)
replaces the readout-window model with the CAEN A5202 timing mode described
in the DUNE ND Preliminary Design Report (section 1.2.4.4): per channel, the
fast-shaper pulses of all detected photoelectrons are summed and a
discriminator gives one hit per pulse, with the threshold-crossing time and
the time over threshold (ToT), both floored to the 0.5 ns TDC step. The
channel cannot retrigger while above threshold (deadtime = ToT). SiPM
optical crosstalk and pixel saturation are applied. Hits whose photons never
cross the threshold are kept as suppressed, as with the pedestal threshold.

- TMS_Hit gets a separate ToT member (-999 = not measured); E and PE are
  still filled from the detected photons, so downstream code is unchanged
  and can migrate to ToT independently. The readout tree gets RecoHitToT.
- Optional Sim.FrontEnd.EnergyFromToT sets E from ToT by inverting the mean
  waveform (fast-shaper pulse smeared by the scintillator and WLS decay
  times), as real timing-mode data would need.
- New [Sim.FrontEnd] config. Sourced: 15 ns fast-shaper peaking time, fixed
  (CAEN Citiroc-1A datasheet); 0.5 ns TDC step (A5202, PDR); < 100 ps jitter
  (datasheet); 3% crosstalk and 1584 pixels (S13360-2050VE, PDR Table 1.16).
  ASSUMED: pulse shape (t/tp)^n exp(n(1-t/tp)) with n = 1. Threshold 3.0 pe
  to match the default pedestal threshold (the chip allows down to 1/3 pe;
  TMS setting to be decided). Dark counts are not simulated yet.

Default behaviour is unchanged apart from the new RecoHitToT branch (-999):
harness output byte-identical, and on real spill file 0000007 every existing
branch of every tree is identical. The 6a readout-window path is also
byte-identical in the harness.

Validation:
- Harness (timing mode, 3 pe): time stamps all on the 0.5 ns grid; results
  flat across 1-20 steps; one hit per crossing. Discriminator threshold scan
  for a 12 pe muon crossing: time resolution 2.7 ns rms at 0.5 pe, 3.4 at
  1.0, 5.6 at 3.0 (the PDR requires 2-3 ns); time offset 14.6-22.5 ns;
  1.5 mm grazing crossing survival 87.5% at <= 1 pe, 11% at 3 pe. A
  3 pe pulse-height threshold needs several photons within the 15 ns
  shaping, which the 20 ns WLS decay spreads out.
- EnergyFromToT: muon crossing 1.13 MeV (37% rms) from ToT vs 1.10 MeV (30%)
  from the photon count; 2x dE/dx 2.27 (35%) vs 2.18 (21%).
- Real spills (MiniProdN5 files 1-15) vs the readout-window model; another
  RNG seed moves these by ~1%: 3 pe threshold: hits above threshold -7.4%,
  tracks -5.9%, muon vertices covered -4.6%. 1 pe threshold: hits above
  threshold +46%, tracks +3.4%, muon vertices -0.2% (optimistic without dark
  counts). Detected photons identical. Reconstruction is tuned to the old hit
  model, so these reco-level changes are before any retuning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ToT curve; ToT clip at 9 bits; optional hysteresis

FastShaperOrder 1 -> 2 and DiscriminatorThreshold 3.0 -> 1.7 pe, from a fit to the ToT-versus-charge curve in the A5202
manual (UM7945 rev. 4 sec. 9.3.2; scripts/Validation/DetSim/fit_tot_curve.py): rms 2.8 ns, against 11.8 ns for order 1.
New Sim.FrontEnd.ToTMax (255.5 ns, the 9-bit ToT) clips longer ToTs; new DiscriminatorStopThreshold (default off) lets the
pulse end below a lower threshold. Both new keys are read with defaults so existing override tomls keep working.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
With Sim.DetSim.UseResponseElements=true, every detected photon now carries
the trajectory (edep-sim track id) and global vertex id of the particle whose
deposit produced it: a photon from a deposit with several contributing
particles is assigned to one of them in proportion to their deposited energy
(no extra random draw for single-contributor deposits). After the readout
(window model or A5202 timing mode), TMS_Event::FillLightProvenance()
summarises each hit's photons onto its TMS_TrueHit, which is carried into the
time slices:
- number of detected photons;
- the particle (trajectory, vertex) that produced the most photons and its
  share (ties go to the smallest (vertex, trajectory), as for the
  energy-based TrueHitPrimaryId);
- the particle that produced the first photon, which sets the hit time.

New branches in Truth_Info and in the readout tree: TrueHitNPhotons,
TrueHitPrimaryIdByLight, TrueHitVertexIdByLight, TrueHitLightShare,
TrueHitFirstPhotonPrimaryId, TrueHitFirstPhotonVertexId. Existing branches
are unchanged; the new ones are -999 unless the flag is on (the default
pipeline only draws a capped number of timing photons, with fractional
counts, so a light share there would be misleading) and for hits with no
detected photons.

Verification:
- Default: harness output byte-identical; on real spill file 0000007 every
  existing branch of every tree is identical and the new branches are never
  filled.
- Flag on, MiniProdN5 files 1-15 (2.0M true hits): TrueHitNPhotons equals the
  detected PE (short + long path) for every hit. Hits without light
  provenance are exactly those with no detected photons (all below
  threshold). Single-contributor hits: the most-light, most-energy and
  first-photon particle always agree, share 1. Multi-contributor hits: the
  most-light particle is the most-energy particle in 94.7% of hits, and
  produced the first photon in 95.2% (85.5% in timing mode, where a hit
  collects light over its whole time over threshold).
- Reconstruction-level quantities change by at most 0.3% relative to the
  same configuration without this change (the extra draws shift the random
  sequence).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ith hysteresis, expired photons, provenance draws

- TMS_Readout_Manager: the front-end keys are read with find_or and the shipped values, so older
  custom readout configs load with the flag off.
- EnergyFromToT table: with a stop threshold below the start threshold the measured ToT ends at the
  stop threshold, but the table ended at the start threshold, inflating the reconstructed energy.
  The table now starts at the threshold and ends at the stop threshold.
- A photoelectron whose modeled pulse had expired before a later pulse rose is no longer credited
  to that pulse (charge and light provenance).
- Light provenance: several steps of one particle share a trajectory and no longer trigger a
  source draw, so subdividing a step does not change the random sequence.
- Documented: a hit whose photons span several discriminator pulses is read out once.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…hoton count for empty hits

- With response elements and the timing-mode front end on, FastShaperOrder <= 0 (the tail search
  never ends), a non-positive peaking time, threshold or TDC step, and SiPMCrosstalkProbability
  outside [0, 1) (the crosstalk charge loop never ends) now throw at configuration time with a
  message instead of hanging on the first event.
- A simulated hit with no detected photon now has TrueHitNPhotons = 0 instead of -999, so a
  simulated zero can be told apart from provenance that is not available (flag off). The particle
  ids and the share stay at -999.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ored, US spelling

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…er, reject ToT energy with reflected light

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@SFBayLaser
SFBayLaser force-pushed the feature/usher_detsim_truth_output branch from ec5a507 to 7d409a8 Compare November 14, 2026 03:38
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