Repository navigation
Detector sim 3/4: A5202 timing-mode front end and light provenance (flag off by default) - #357
SFBayLaser wants to merge 10 commits into
Conversation
9b296a0 to
92883a1
Compare
There was a problem hiding this comment.
🟡 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
92883a1 to
9afb5b6
Compare
9afb5b6 to
a817538
Compare
There was a problem hiding this comment.
🟡 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
There was a problem hiding this comment.
🔵 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
|
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'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. |
3c46803 to
e172313
Compare
There was a problem hiding this comment.
🔵 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
e172313 to
ea05365
Compare
|
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. |
| 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); | ||
| }; |
There was a problem hiding this comment.
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).
| } | ||
| 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"); |
There was a problem hiding this comment.
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).
| 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()); |
There was a problem hiding this comment.
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).
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>
ec5a507 to
7d409a8
Compare


A5202 timing-mode front end, and light provenance in the truth output
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. NewRecoHitToTbranch (-999 when not measured). Sourced constants are listed in the commit message (Citiroc-1A datasheet, DUNE ND PDR).FastShaperOrder1 -> 2 and threshold 3.0 -> 1.7 pe (rms 2.8 ns against 11.8 ns for order 1; fit inscripts/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.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
mainat 60f2edf, default config, 4 real spills (1, 4, 6, 7): 2636 pre-existing branches, 0 differences.Known limitations
🤖 Generated with Claude Code