How the simulator works¶
One forward model serves simulation, reconstruction, calibration and dataset production. It is
a chain of JAX functions, compiled with jax.jit and vectorised over photons, so a gradient
taken on its output reaches every input:
source ──► propagation ──► photon step (× K) ──► hits
emit rays ray-geometry scatter, reflect, what the sensors report
intersection absorb (charge, first-arrival time, ...)
lucid.simulation.setup_event_simulator assembles the chain from a geometry config and a
physics config and returns it as one callable. Its arguments are in the
simulator reference.
The stages¶
Source. Where the photons start:
- a particle track, whose Cherenkov light is drawn from a SIREN emitter. The emitter gives the
photon density over energy, opening angle and normalised track position
s/s_max(E), and carries the track ranges_max(E), the photon yieldN_photons(E)and an emission-time model. Trained emitters exist for muons and electrons in water. - scintillation, for a scintillating medium (WbLS): a dE/dx SIREN emitter drives isotropic light with quenched yield, a rise/fall emission delay and a sampled spectrum (optics).
- a calibration source passed at call time: a laser, an isotropic flasher, a cascade, or a "shotgun" of given rays.
- photons given at call time, for example read from a PhotonSim ROOT file
(
lucid.sources.root_reader, positions converted to metres on read).
Propagation. Each ray is intersected with the detector. Cylinder, sphere and box detectors have a closed wall that reflects and absorbs; light emitted outside the detector volume carries no weight. String detectors (neutrino telescopes) have no wall: each ray is matched to nearby strings and DOMs in an open medium.
Photon step. K iterations of scattering (Rayleigh and Mie), absorption and reflection.
K is a hard cut: light that would scatter more than K times is dropped.
Hits. The photon deposits become what the sensors report: per-sensor charge and first-arrival time, a per-photon list for the reconstruction likelihood, waveforms, or per-segment truth for datasets.
Expected and sampled¶
Two switches decide whether the output fluctuates like data:
transport='expected'carries each photon's expected weight through every scatter, absorption and reflection. The output is the mean, with no shot noise, and is smooth in the parameters.transport='sampled'draws each branch, like a Monte Carlo.detectiondoes the same for QE, transit-time spread and charge resolution at the sensor.
Fits use the expected forward as the model and compare it with sampled (or real) data.
Which sensor a photon reaches is a soft assignment: a Gaussian kernel of width
temperature × sensor_radius around the photon's closest approach. temperature=None makes it
a hard step, which is exact but has no gradient with respect to geometry. Discrete choices that
remain, such as specular against diffuse reflection, get their gradient from a score-function
(DiCE) term.
Datasets¶
Dataset production (lucid-run-job) runs the same chain with given PhotonSim photons and
hits='segment_truth', then two NumPy stages with no gradients: a digitizer (charge
integration windows, SPE charge, time jitter, dark noise) and an optional sliding-window
trigger. See digitizer and trigger and the
dataset schema.
Package map¶
| package | contents |
|---|---|
lucid.simulation |
setup_event_simulator, the photon step, the hits functions (HITS), digitizer and trigger |
lucid.geometry |
the detector classes (cylinder, sphere, box, string), generate_detector(path) |
lucid.propagation |
ray-geometry intersection and sensor lookup |
lucid.wavelength |
media, spectra and the per-photon optical model |
lucid.siren |
SIREN emitters and their training (lucid.siren.training) |
lucid.sources |
track, cascade and calibration sources; the PhotonSim ROOT reader; event placement |
lucid.fitting |
calibration, reconstruction, the Gauss-Newton loop, the Cramér-Rao bound |
lucid.gradient_analysis |
1D and 2D loss-landscape sweeps |
lucid.dataset |
the HDF5 dataset format: writer, reader, layout |
lucid.production |
the PhotonSim and GENIE dataset chain and its cluster tools |
lucid.detector_params |
DetectorParams, ParticleParams, the physics-config loader |
lucid.losses, lucid.visualization |
likelihoods; event displays |
Precision on GPU¶
LUCiD runs in float32 throughout and never enables jax_enable_x64. On an NVIDIA GPU, JAX's
default float32 matrix product uses TF32 (reduced-precision accumulation); on a CPU it is exact.
The published numbers use JAX's default. Measured on one L40S, switching to full precision moved
the per-PMT prediction sum by 1.3e-3, the loss gradient by a factor 2.3 (with sign flips), the
autodiff Fisher matrix by 5.8x and a fitted vertex by 11.2 cm. To run at full float32 precision,
set JAX_DEFAULT_MATMUL_PRECISION=highest before JAX initialises, and say so with the results.