Digitizer and trigger¶
Dataset production (lucid-run-job) turns the simulated photon deposits into what a detector's
electronics record. Two NumPy stages, with no gradients, run after the simulator:
lucid.simulation.digitizer (charge integration, single-photoelectron charge, time jitter, dark
noise) and lucid.simulation.trigger (a sliding-window multiplicity trigger). Reconstruction
and calibration do not use them.
Where the settings come from¶
Two top-level blocks, "digitizer" and "trigger". Each is taken from the dataset config when
it has the key (null included), otherwise from the detector's physics config. A block in
neither stops the job before PhotonSim runs.
Only config/SK_WAND_physics_config.json and config/HK_WAND_physics_config.json carry the
blocks, so a GeV dataset config (which states none) runs only with --detector SK_WAND or
HK_WAND. To use another detector, state the readout in the dataset config:
"digitizer": "basic" (or "ski", "hk") and "trigger": null (or a block).
"digitizer": null is refused. The Solar, SN and Test configs state their own.
The shipped blocks:
| detector | digitizer |
trigger |
|---|---|---|
SK_WAND |
{"model": "ski"} |
window_ns 200, n_thr 25, pad_before_ns 300, pad_after_ns 300 |
HK_WAND |
{"model": "hk"} |
window_ns 200, n_thr 45, pad_before_ns 300, pad_after_ns 300 |
Digitizer¶
"digitizer" is a model name, or {"model": name, ...} where any other key overrides that
preset value (for example "dark_rate_khz" or "threshold_pe").
| model | window | threshold | charge | time | TDC step | dark rate |
|---|---|---|---|---|---|---|
basic |
infinite | 0 pe | SK-like fractional smearing | none | none | 0 |
ski |
200 ns | 0.25 pe | sampled SK single-photoelectron spectrum | SK Gaussian jitter | 0.4 ns | 4.2 kHz |
hk |
200 ns | 0.25 pe | sampled HK single-photoelectron spectrum | HK exponentially modified Gaussian | 0.4 ns | 4.2 kHz |
Dead time is 0 in all three. ski and hk follow WCSim's SKI digitizer and its SK and HK PMT
models; basic is an idealised pass-through with one digit per hit PMT.
Per sensor: sort the hits by time, open a window at the first, sum the charge in it, record a digit if the sum clears the threshold, then repeat from the next hit after the window (and dead time). A digit's time is its first hit's. A sensor can therefore record several digits per event.
Dark noise: a Poisson number of 1 pe hits per sensor at dark_rate_khz, uniform over the span
of the event's real hits, added before windowing. The span is padded on each side by
max(pad_before_ns, pad_after_ns) + window_ns of the trigger (500 ns for the WAND blocks), so
every possible gate is filled with dark noise, or by 100 ns without a trigger. Dark hits are labelled
emission_process = 2 with particle_idx = -1 in hits/. An event with no detected photons
gets no dark hits.
Deposits later than 100 μs after the event start (late neutron-capture or de-excitation light) are dropped before digitizing.
Trigger¶
"trigger": window_ns, n_thr, pad_before_ns, pad_after_ns (or pad_ns for both).
Omitted keys take the TriggerConfig defaults: 200 ns, 30, 30 ns, 30 ns. null turns the
trigger off.
The trigger counts digits in a trailing window over the whole detector. A gate opens where the
count reaches n_thr (moved earlier by pad_before_ns) and closes where it drops below
(moved later by pad_after_ns); overlapping gates merge. Only digits inside a gate are kept.
An event with no gate is dropped from the dataset entirely, leaving a gap in
source_event_idx. Gates are written to labl/.../per_window
(schema).
Digit times are rounded to the 0.4 ns TDC step, and 200 ns is a multiple of it, so an event
exactly at n_thr can flip on a one-tick change in one arrival.
Selection¶
The dataset config's "selection" block decides which interactions are written:
{"mode": "trigger"}: those the trigger keeps (allGeVconfigs andTest).{"mode": "min_physics_hits", "n": N}: those with at leastNreal (non-dark) hits, a cheap truth-level cut in place of the trigger (Solar,SN). It needs"trigger": null: a trigger block together with it is refused. A supernova config must use it.
Choosing¶
Use basic with no trigger when the electronics are not the point, or to compare with
one-hit-per-PMT datasets. Use ski or hk for realistic charge resolution, time jitter, TDC
granularity and dark noise. Add a trigger when acceptance and dark-noise triggers matter; to
only drop near-empty interactions, min_physics_hits is cheaper.