The first end-to-end differentiable optical particle-detector simulator — gradients flow through emission, propagation, scattering, and sensor response, so calibration and track reconstruction become gradient-based optimization in one framework.
Accompanies the paper "End-to-end Differentiable Calibration and Reconstruction for Optical Particle Detectors" — arXiv:2602.24129.
LUCiD is a JAX-based simulation of optical photon transport in particle detectors — water-Cherenkov tanks, water-based liquid scintillator (WbLS), and neutrino telescopes. Inside the loop, a SIREN (a small sinusoidal neural network trained on GEANT4/PhotonSim photon tables) stands in for GEANT4 as the differentiable light emitter. Units are meters, nanoseconds, MeV throughout.
The core install needs only JAX — no GEANT4/PhotonSim — to simulate, calibrate, and reconstruct:
pip install -e . # core; extras: [training] (torch), [docs], [all]
./scripts/download_data.sh # example SIREN emitter + PhotonSim tables
python examples/hello_simulate.py # simulate a 1 GeV muon, display its Cherenkov ringThen open the tutorials in tutorials/ (start with 00_quickstart.ipynb) or read
the docs at https://cider-ml.github.io/LUCiD/.
- Simulate optical events in any supported geometry — one differentiable forward call.
- Reconstruct particle tracks (energy, vertex, direction, t₀) by gradient fit —
examples/hello_reconstruct.py, or config-drivenlucid-optimize. - Calibrate optical parameters (scattering, absorption, reflection, QE, per-PMT QE) and
read the achievable uncertainty from the Fisher / Cramér–Rao bound —
examples/hello_calibrate.py. - Model diverse detectors: cylinder (SK / HK / WCTE, algorithmic or from measured PMT
.npz), sphere (JUNO), box, and neutrino-telescope strings (IceCube); water, WbLS, and ice. - Produce datasets from GEANT4/PhotonSim (+ optional GENIE flux) → four parallel HDF5 files —
lucid-run-job.
Narrated notebooks in tutorials/:
| Notebook | What it shows |
|---|---|
00_quickstart |
build a simulator, shoot a muon, display the event |
track_optimization |
reconstruct a track (seed → Fisher-Gauss-Newton fit); + a JUNO-sphere example |
calibration_optimization |
fit optical parameters vs the Cramér–Rao bound |
calibration_gradients |
calibration loss landscape, the Hessian/Fisher, and the fit before/after |
track_gradients |
reconstruction loss landscapes and gradients |
data_vs_prediction |
per-PMT charge/time likelihood: data vs the differentiable model |
event_displays |
2D / animation / 3D event views across geometries and materials |
Short, copy-paste scripts live in examples/:
hello_simulate.py, hello_reconstruct.py, hello_calibrate.py, seed_reconstruct.py, hello_telescope.py.
lucid/simulation/—setup_event_simulator(the JIT-compiled forward hub),photon_step,sensor_response.lucid/geometry/— registry-dispatched detectors (cylinder,sphere,box,string);Cylinder.from_pmt_file(npz)for measured SK/HK/WCTE arrays.lucid/propagation/— differentiable ray–geometry intersection and multi-bounce transport.lucid/wavelength/— wavelength-dependent optics (medium,spectrum,optical_model).lucid/siren/— SIREN surrogate for Cherenkov/dE-dx emission (trained on PhotonSim tables).lucid/sources/— track/cascade/calibration emitters and dataset event I/O.lucid/fitting/— one damped Gauss-Newton loop (gauss_newton) serving both problems: calibration (closureto validate a setup, thencalibrate;CalibrationParamsfor the published estimand orFieldParamsfor anyDetectorParamsleaves) and reconstruction (ReconModel,fit_track,fit_track_multistart).crbgives the Cramer-Rao bound.lucid/optimization/— hierarchical seed search + thelucid-optimizedriver.lucid/gradient_analysis/— 1D/2D loss-landscape sweeps.lucid/production/— PhotonSim/GENIE → HDF5 dataset chain and cluster deployment.
Console entry points: lucid-optimize, lucid-train-siren, lucid-run-job,
lucid-build-photon-table, lucid-build-dedx-table.
Generating training data or datasets uses the external PhotonSim GEANT4 utility (only needed for this chain, not for simulate/calibrate/reconstruct):
export PHOTONSIM_BIN=/path/to/PhotonSim/build/PhotonSim
lucid-run-job --config lucid/production/configs/GeV/02_mu.json \
--detector SK_WAND \
--n-events 1000 --job-id 1 --master-seed 42 --output-dir out/See docs/guides/production/local.md (local), the cluster runbooks
(docs/guides/production/deploy-{s3df,nersc,lxplus}.md, fronted by
docs/guides/production/cluster-abstraction.md), and the dataset schema in
docs/reference/dataset-schema.md. The container
ghcr.io/cider-ml/lucid:latest ships PhotonSim + GENIE pre-built.
If you use LUCiD, please cite the paper (see CITATION.cff):
O. Alterkait, C. Jesús-Valls, R. Matsumoto, P. de Perio, K. Terao, End-to-end Differentiable Calibration and Reconstruction for Optical Particle Detectors, arXiv:2602.24129 (2026).
The license is being finalized and will be added shortly.
