Details of the output

Detailed file data definition can be found in the 2x2_sim wiki.

Briefly, the larnd-sim output includes generator truth information, edep-sim/geant4 truth information, simulated charge detector output, charge backtracking information, detector propagated light truth information, simulated light detector output and light backtracking information.

The generator truth information includes mc_hdr and mc_stack which are reserved for neutrino interaction records. mc_hdr is the log for neutrino interactions, and mc_stack is the log for the initial-state and final-state particles from the neutrino interactions. This part is copied directly from the root converted h5 input file. If the upstream simulation does not run neutrino generator, rather cosmic or particle bomb simulation instead, then this information will not be presented in the output.

The edep-sim/geant4 truth information contains vertices (interaction-level or equivalent), trajectories (particle-level) and segments (segment of energy depositions). Primary trajectories should overlap with the final-state particles in mc_stack if it originates from neutrino generators. segments is the essential input to the simulation. This part should exist in the output regardless the simulation setup, and it is a direct copy of the corresponding part in the input with possible minor extensions such as event time (vertices['t_event']).

The simulated charge detector output is stored in packets which is compatible with the converted raw data from LArPix. A data packet could be considered as a point-like charge readout in time and the LArPix plane (anode). It encodes information of the readout charge, position and time. Other type of packets such as trigger, timestamp and sync are also available in the simulated packets dataset. A general discription can be found in the LArPix HDF5 documentation.

The charge backtracking information is namely mc_packets_assn which records the contribution of segments to each packet. It has the same size as the packets dataset, and the index are shared between packets and mc_packets_assn. Each packet is associated with backtracking information of event_ids, segment_ids and fraction regardless its packet type. However, only the data packets can have meaningful backtracking information filled. event_ids is a new feature implemented in this commit. It has a size of one and contains the true event_id. The length of segment_ids and fraction are the same and are set by fee.ASSOCIATION_COUNT_TO_STORE. The contributed segments are sorted by their fractional order and filled correspondingly for segment_ids and fraction. The total number of contribution considered in the calculation ofsegment fraction is set by fee.MAX_ADC_VALUES. It makes sense to set fee.MAX_ADC_VALUES >= fee.ASSOCIATION_COUNT_TO_STORE. Please see this Git Issue for further details and discussion.

The detector propagated light truth information is saved as light_dat. If the module-by-module variation is turned on, the simulation is carried out for each module separately, and this information is stored for each module as light_dat/light_dat_module{Z} where Z is the module numbering. Otherwise, the information is recorded under light_dat/light_dat_allmodules. It has the shape of (#segments, #light readout channels), where the #segments and #light readout channels are within individual modules or the whole detector respectively. Each segment is labelled by segment_id. n_photons_det -- the number of photons which would detected by the SiPM, and t0_det -- the light arrival time on the SiPMs, are also provided in this dataset.

The simulated light detector output are light_trigand light_wvfm. Currently in larnd-sim, we have implemented two trigger mode: threshold (light.LIGHT_TRIG_MODE = 0) and beam (light.LIGHT_TRIG_MODE = 1) trigger that activate all light readout channels. See this Git Isuue for the discussion of light triggers in larnd-sim. light_trig has the shape of number of light triggers. In case of beam triggering mode, the number of light triggers is the same as the simulated events (beam spills) in the input. Therefore, not necessarily all light triggers correspond to charge and meaningful light signals. light_trig has attributes of op_channel, ts_s and ts_sync. op_channel records the triggered light readout channels. For light.LIGHT_TRIG_MODE = 0 and 1, op_channel stores all the light readout channel id. ts_s is the trigger time in seconds, and ts_sync is the trigger time in LArPix time ticks which considers the time sync, e.g PPS or LArPix clock rollover. light_wvfm has the shape of (#light triggers, #light readout channels, #light samples). The #light triggers is the same as in light_trig. For light.LIGHT_TRIG_MODE = 0 and 1, #light readout channels is the number of all the available channels in the entire detector. #light samples are determined by light.LIGHT_TRIG_WINDOW and light.LIGHT_DIGIT_SAMPLE_SPACING. For a light trigger and a readout channel light_wvfm gives a waveform as in the light readout data. The waveforms are in digitized ADC counts. For 2x2, and the cosmic data taking with Module 123, due to the setup, in order to get the ADC counts correspond to the light signal, the waveform values needs to be divided by 4. Note that the internal light simulation can have higher resolution before digitization if the light.LIGHT_TICK_SIZE is set to a smaller number.

The light backtracking information will be stored in light_wvfm_mc if light.MAX_MC_TRUTH_IDS is set to a non-zero value. light_wvfm_mc has the same shape as light_wvfm, (#light triggers, #light readout channels, #light samples). At one time sample of a light readout channel from one trigger, it stores segment_ids and pe_current with the length of light.MAX_MC_TRUTH_IDS.

For all light related datasets, as larnd-sim currently does not consider a complicated or realistic light readout channel mapping, their order is as the channel id which follows geometrical order sequentially from bottom to top, TPC-by-TPC.