Skip to content

Command-line tools

pip install -e . installs five commands. The scripts in scripts/ run from the repository root with python scripts/<name>.py. Every tool prints its full option list with --help.

lucid-run-job

Produces one batch of a dataset: writes a GEANT4 macro, runs PhotonSim (the binary named by $PHOTONSIM_BIN), then the LUCiD simulation, digitizer and writer. A config with "primary_source": "genie" runs GENIE (gevgen, gntpc) first; a supernova config runs sntools first. Guides: local, container.

export PHOTONSIM_BIN=/path/to/PhotonSim/build/PhotonSim
lucid-run-job --config lucid/production/dataprod/configs/GeV/02_mu.json \
              --detector SK_WAND --n-events 1000 --job-id 1 --master-seed 42 --output-dir out/
flag meaning
--config required. The dataset config (JSON)
--output-dir required. The dataset directory; the batch goes to sensor/, hits/, step/, labl/ under it
--job-id required. 1-based; the batch's file index is job_id − 1
--detector selects config/<detector>_{geom,physics}_config.json. Required unless the config declares detector (then it must match) or with --skip-lucid. The readout comes from the dataset config, else from this physics config; only SK_WAND and HK_WAND carry one (digitizer and trigger)
--n-events events in this job (default: the config's n_events_per_job, else 100)
--test 2 events; overrides --n-events
--master-seed seed for the generator, PhotonSim/GEANT4 and, unless --lucid-seed is given, the LUCiD draws (default: drawn from the clock). The batch records it and every seed derived from it. Required when the job is split across invocations (--skip-genie, --skip-photonsim, --skip-lucid), so that each derives the same seeds
--lucid-seed seed for the LUCiD draws only (vertex, rotation, t0, propagation, smearing), to re-place the same GEANT4 sample
--override-energy-MeV monoenergetic primaries at this energy (MeV), for energy scans
--keep-root keep the intermediate PhotonSim ROOT file (otherwise cleanup_root_files in the config decides)
--skip-genie skip the generator step (GENIE or supernova); no effect for particle-gun configs
--skip-photonsim, --skip-lucid run only the other half, reusing or leaving the ROOT file
--sn-model, --sn-ordering a supernova config's model and mass ordering, one entry each of supernova.models and supernova.orderings; optional when the list has one entry

It ends by printing a line starting OK and exits non-zero on failure. Output: dataset schema.

lucid-build-photon-table, lucid-build-dedx-table

Build the SIREN training tables from a PhotonSim energy scan (SIREN training).

lucid-build-photon-table --data-dir SCAN --material water --particle mu- --output photon_lookup_table.h5
lucid-build-dedx-table   --data-dir SCAN --material water --particle mu- --output dedx_lookup_table.h5
flag meaning
--data-dir required. Holds <material>/<particle>/<E>MeV/photonsim.root; every <E>MeV directory found is used
--material, --particle required. The scan cell and its smax_fit.csv
--output required. Output .h5 (file or directory)
--photonsim-dir the PhotonSim checkout holding data/<material>/<particle>/smax_fit.csv (default: $PHOTONSIM_DEV_PATH, or a sibling of --data-dir)
--require-list CFG fail unless every energy in the config's energy_list_MeV is on disk
--no-validate skip the check that re-reads the written table

lucid-train-siren

Trains a SIREN emitter on one table. The kind (Cherenkov or dE/dx), material and particle come from the table.

lucid-train-siren --h5-path photon_lookup_table.h5 --output-dir runs/water_muon --seed 1
flag meaning
--h5-path required. The table
--output-dir required. Must not already hold an emitter.json
--recipe recipe JSON (default lucid/siren/training/nominal.json, the recipe of the shipped emitters)
--<field> override one recipe field, e.g. --seed 1, --num-steps 20000, --learning-rate 1e-4
--init weights.npz to start from (an emitter or a checkpoint)
--checkpoint-every N write checkpoint_step_<N>.npz every N steps
--no-prediction-plots skip the prediction-against-table PDFs (--prediction-plot-every, default 10000 steps)

It writes emitter.json and weights.npz (the emitter), recipe.json, training_history.json, final_training_progress.pdf and prediction_plots/. Judge convergence by the validation loss (val_loss in training_history.json), not the training loss: the learning rate drops when it plateaus for patience validations (100 in the nominal recipe), and a flat val_loss with no further drops means it is done. The run is installed with lucid-siren-promote.

lucid-siren-promote

Installs a training run as an emitter in data/<material>/<particle>/<kind>/, adding what the simulator needs and the trainer cannot know (stage 5).

lucid-siren-promote --run runs/water_muon --smax-fit PhotonSim/data/water/mu-/smax_fit.csv \
    --t0 timing_parameters.json --emission-band-nm 274.91 673.83
flag meaning
--run required. The training run (emitter.json, weights.npz)
--smax-fit required. The smax_fit.csv its table was built with; the run's s_max_mm must equal it
--t0 Cherenkov, required: the t0 fit, timing_parameters.json of PhotonSim/tools/t0_correction/calculate_t0.py
--emission-band-nm LO HI Cherenkov, required: the band (nm) PhotonSim counted N_photons(E) over; water 274.91 673.83
--selection how the run was chosen, recorded in the provenance
--dest output directory (default: data/<material>/<particle>/<kind>/ of this checkout)
--force replace an emitter already at --dest

It checks the result with validate_record and records the run, the selection, the s_max fit, the time and the commit in provenance.

Scripts

script does main options
download_data.py installs the example data into data/ (install) --from-dir DIR, --verify-only, --paper
visualize_detector.py prints a geometry's sensor count and extent, writes a 3D HTML view (and a 2D PNG for cylinders); needs [viz] --geom, --out
geofile_to_npz.py converts a WCSim geofile to a PMT .npz GEOFILE OUT.npz
find_optimal_k.py the smallest scattering count K that keeps a target charge fraction --detector, --source, --target (0.999), --nphot, --k-max
inspect_dataset.py a text summary of a dataset batch --path, --batch, --event
benchmark_forward.py wall time of the reconstruction and calibration forward and gradient against photon count and K --what, --geom, --physics, --n, --k
check_gradients.py autodiff against finite-difference gradients of the calibration loss --geom, --physics, --nphot, --rel-h