Data format reference

Every field of every tree GRANDlib reads and writes, with its type, unit and meaning. Run-level trees hold what stays the same for a whole run, one entry per run; event-level trees hold one entry per event. The data model explains how the trees fit together and how to read them.

Each tree is stored in its own file, named after the tree type: shower_*.root for TShower, run_*.root for TRun and so on.

Run-level trees

`TRun`

What stays the same over a run: the site, the layout and the detection units. File: run_*.root; API: TRun.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`run_mode`	`uint32`	–	Run mode (calibration, test or physics). The values are not yet defined.
`first_event`	`uint32`	–	Number of the run’s first event.
`first_event_time`	`uint32`	–	Time of the first event, in Unix seconds.
`last_event`	`uint32`	–	Number of the run’s last event.
`last_event_time`	`uint32`	–	Time of the last event, in Unix seconds.
`data_source`	`str`	–	Where the data come from: `detector`, `sim` or `other`.
`data_generator`	`str`	–	Name of the program that produced the data.
`data_generator_version`	`str`	–	Version of the program that produced the data.
`event_type`	`uint32`	–	Trigger type: 0x1000 for the 10-second trigger, 0x8000 for a random trigger; any other value is a shower trigger.
`event_version`	`uint32`	–	Version of the DAQ’s event format.
`site`	`str`	–	Name of the site, such as `Dunhuang` or `Xiaodushan`.
`site_layout`	`str`	–	Name of the antenna layout, such as `GP300`.
`origin_geoid`	`array of shape 3, float32`	–	Origin of the array frame: (latitude in degrees, longitude in degrees, height in meters). du_xyz is relative to it.
`du_id`	`std::vector<int>`	–	Identifier of each detection unit.
`du_geoid`	`std::vector<vector<float>>`	–	Detector unit (antenna) position: (latitude in degrees, longitude in degrees, height in meters) per DU.
`du_xyz`	`std::vector<vector<float>>`	–	Position of each unit in the array frame, in meters: x north, y west and z up, relative to `origin_geoid`.
`du_type`	`std::vector<string>`	–	Antenna type of each unit.
`du_tilt`	`std::vector<vector<float>>`	–	Tilt of each antenna, as two angles.
`du_ground_tilt`	`std::vector<vector<float>>`	–	Tilt of the ground at each antenna, as two angles.
`du_nut`	`std::vector<int>`	–	Identifier of each unit’s nut, the antenna head that holds the low-noise amplifier.
`du_feb`	`std::vector<int>`	–	Identifier of each unit’s front-end board.
`t_bin_size`	`std::vector<float>`	ns	Sampling interval of each unit’s traces, in ns: the inverse of the sampling frequency.

`TRunVoltage`

Settings of the voltage traces, common to all events of a run. File: runvoltage_*.root; API: TRunVoltage.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`digi_ctrl`	`std::vector<vector<unsigned short>>`	–	Control parameters - the list of general parameters that can set the mode of operation, select trigger sources and preset the common coincidence read out time window (Digitizer mode parameters in the manual).
`firmware_version`	`std::vector<unsigned short>`	–	Firmware version.
`trace_length`	`std::vector<vector<int>>`	–	Nominal trace length in units of samples.
`adc_sampling_frequency`	`std::vector<unsigned short>`	–	ADC sampling frequency in MHz.
`adc_sampling_resolution`	`std::vector<unsigned short>`	–	ADC sampling resolution in bits.
`adc_input_channels`	`std::vector<unsigned short>`	–	ADC input channels - > 16 BIT WORD (4*4 BITS) LOWEST IS CHANNEL 1, HIGHEST CHANNEL 4. FOR EACH CHANNEL IN THE EVENT WE HAVE: 0: ADC1, 1: ADC2, 2:ADC3, 3:ADC4 4:FILTERED ADC1, 5:FILTERED ADC 2, 6:FILTERED ADC3, 7:FILTERED ADC4. ToDo: decode this?
`adc_enabled_channels`	`std::vector<unsigned short>`	–	ADC enabled channels - LOWEST 4 BITS STATE WHICH CHANNEL IS READ OUT ToDo: Decode this?
`gain`	`std::vector<vector<int>>`	–	Value of the Variable gain amplification on the board.
`adc_conversion`	`std::vector<vector<float>>`	–	Conversion factor from bits to V for ADC.
`digi_prepost_trig_windows`	`std::vector<vector<unsigned short>>`	–	Window parameters - describe Pre Coincidence, Coincidence and Post Coincidence readout windows (Digitizer window parameters in the manual). ToDo: Decode?
`channel_properties_x`	`std::vector<vector<unsigned short>>`	–	Channel x properties - described in Channel property parameters in the manual. ToDo: Decode?
`channel_properties_y`	`std::vector<vector<unsigned short>>`	–	Channel y properties - described in Channel property parameters in the manual. ToDo: Decode?
`channel_properties_z`	`std::vector<vector<unsigned short>>`	–	Channel z properties - described in Channel property parameters in the manual. ToDo: Decode?
`channel_trig_settings_x`	`std::vector<vector<unsigned short>>`	–	Channel x trigger settings - described in Channel trigger parameters in the manual. ToDo: Decode?
`channel_trig_settings_y`	`std::vector<vector<unsigned short>>`	–	Channel y trigger settings - described in Channel trigger parameters in the manual. ToDo: Decode?
`channel_trig_settings_z`	`std::vector<vector<unsigned short>>`	–	Channel z trigger settings - described in Channel trigger parameters in the manual. ToDo: Decode?

`TRunRawVoltage`

Settings of the raw voltage traces, common to all events of a run. File: runrawvoltage_*.root; API: TRunRawVoltage.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`trigger_position`	`std::vector<unsigned short>`	–	Trigger position in the trace (trigger start = nanoseconds - 2*sample number)
`firmware_version`	`std::vector<unsigned short>`	–	Firmware version.
`adc_sampling_frequency`	`std::vector<unsigned short>`	–	ADC sampling frequency in MHz.
`adc_sampling_resolution`	`std::vector<unsigned short>`	–	ADC sampling resolution in bits.
`adc_input_channels_ch`	`std::vector<vector<unsigned char>>`	–	ADC input channels for fv2: 0: ADC1, 1: ADC2, 2:ADC3, 3:ADC4, 4:FILTERED ADC1, 5:FILTERED ADC2, 6:FILTERED ADC3, 7:FILTERED ADC4, 15: off.
`adc_enabled_channels_ch`	`std::vector<vector<bool>>`	–	ADC enabled channels - LOWEST 4 BITS STATE WHICH CHANNEL IS READ OUT.
`pre_coincidence_window_ch`	`std::vector<vector<unsigned short>>`	–	Digitizer window parameters - describe Pre Coincidence, Coincidence and Post Coincidence readout windows (Digitizer window parameters in the manual). The unit is samples (to get time, multiply by 2).
`post_coincidence_window_ch`	`std::vector<vector<unsigned short>>`	–	Digitizer window parameters - describe Pre Coincidence, Coincidence and Post Coincidence readout windows (Digitizer window parameters in the manual). The unit is samples (to get time, multiply by 2).
`gain_correction_ch`	`std::vector<vector<unsigned short>>`	–	Channel property parameters.
`integration_time_ch`	`std::vector<vector<unsigned short>>`	–	–
`offset_correction_ch`	`std::vector<vector<unsigned char>>`	–	–
`base_maximum_ch`	`std::vector<vector<unsigned short>>`	–	–
`base_minimum_ch`	`std::vector<vector<unsigned short>>`	–	–
`signal_threshold_ch`	`std::vector<vector<unsigned short>>`	–	Channel trigger parameters.
`noise_threshold_ch`	`std::vector<vector<unsigned short>>`	–	–
`tper_ch`	`std::vector<vector<unsigned short>>`	–	The unit is samples (to get time, multiply by 2)
`tprev_ch`	`std::vector<vector<unsigned short>>`	–	–
`ncmax_ch`	`std::vector<vector<unsigned short>>`	–	–
`tcmax_ch`	`std::vector<vector<unsigned short>>`	–	–
`qmax_ch`	`std::vector<vector<unsigned short>>`	–	–
`ncmin_ch`	`std::vector<vector<unsigned short>>`	–	–
`qmin_ch`	`std::vector<vector<unsigned short>>`	–	–
`notch_filters_no_ch`	`std::vector<vector<unsigned char>>`	–	–
`trace_length`	`std::vector<unsigned int>`	–	Trace length.
`adc_conversion`	`std::vector<float>`	–	ADC to voltage conversion factor.

`TRunEfieldSim`

Simulation settings of the electric-field traces, common to all events of a run. File: runefieldsim_*.root; API: TRunEfieldSim.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`refractivity_model`	`str`	–	Name of the atmospheric index of refraction model.
`refractivity_model_parameters`	`std::vector<double>`	–	Parameters of `refractivity_model`; their meaning depends on the model (the CoREAS converter writes the placeholder [1, 1, 1])
`t_pre`	`float32`	–	Start of the antenna data window before the trigger, in ns (it can be shorter than the voltage trace, so this can differ from the voltage’s)
`t_post`	`float32`	–	End of the antenna data window after the trigger, in ns.
`site`	`str`	–	Site for which the efield simulation was done.
`sim_name`	`str`	–	Simulator name (aires/corsika, etc.)
`sim_version`	`str`	–	Simulator version string.

`TRunShowerSim`

Simulation settings of the showers, common to all events of a run. File: runshowersim_*.root; API: TRunShowerSim.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`rel_thin`	`float32`	–	relative thinning energy.
`maximum_weight`	`float32`	–	the maximum weight, computed in zhaires as PrimaryEnergyRelativeThinningWeightFactor/14.0 (see aires manual section 3.3.6 and 2.3.2) to make it mean the same as Corsika Wmax.
`hadronic_thinning`	`float32`	–	the ratio of energy at wich thining starts in hadrons and electromagnetic particles.
`hadronic_thinning_weight`	`float32`	–	the ratio of electromagnetic to hadronic maximum weights.
`lowe_cut_e`	`float32`	–	low energy cut for electrons (GeV)
`lowe_cut_gamma`	`float32`	–	low energy cut for gammas (GeV)
`lowe_cut_mu`	`float32`	–	low energy cut for muons (GeV)
`lowe_cut_meson`	`float32`	–	low energy cut for mesons (GeV)
`lowe_cut_nucleon`	`float32`	–	low energy cut for nucleons (GeV)
`site`	`str`	–	Site for which the shower simulation was done.
`sim_name`	`str`	–	Simulator name (aires/corsika, etc.)
`sim_version`	`str`	–	Simulator version string.

`TRunNoise`

Settings of the Galactic-noise generation for a run. File: runnoise_*.root; API: TRunNoise.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number, which identifies the entry.
`gal_noise_map`	`str`	–	Info to retrieve the map of galactic noise.
`gal_noise_LST`	`float32`	–	Local sidereal time, in hours (0 to 24), at which the galactic noise was generated.
`gal_noise_sigma`	`std::vector<vector<float>>`	–	Galactic-noise standard deviation for each arm of each antenna, in µV.

Event-level trees

`TADC`

Digitized traces of each event, in ADC counts, with each detection unit’s status and firmware settings. File: adc_*.root; API: TADC.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`event_size`	`uint32`	–	Size of the event as recorded by the DAQ.
`t3_number`	`uint32`	–	Number of the T3 (array-level) trigger that recorded the event.
`first_du`	`uint32`	–	Identifier of the first unit that triggered.
`time_seconds`	`uint32`	–	Time of the event’s trigger, in Unix seconds, converted from GPS time.
`time_nanoseconds`	`uint32`	–	Nanoseconds to add to `time_seconds`, for the first unit that triggered.
`event_type`	`uint32`	–	Trigger type: 0x1000 for the 10-second trigger, 0x8000 for a random trigger; any other value is a shower trigger.
`event_version`	`uint32`	–	Version of the DAQ’s event format.
`du_count`	`uint32`	–	Number of detection units in the event.
`event_id`	`std::vector<unsigned short>`	–	Number of the T3 trigger, for each unit.
`du_id`	`std::vector<unsigned short>`	–	Identifier of each detection unit, in the order of the traces.
`du_seconds`	`std::vector<unsigned int>`	–	Trigger time of each unit, in Unix seconds.
`du_nanoseconds`	`std::vector<unsigned int>`	ns	Nanoseconds to add to `du_seconds`, for each unit.
`trigger_position`	`std::vector<unsigned short>`	–	Sample of each unit’s trace at which it triggered.
`trigger_flag`	`std::vector<unsigned short>`	–	Trigger type of each unit, with the codes of `event_type`; for simulations with the offline T1 trigger, 1 if the unit passed and 0 if not.
`atm_temperature`	`std::vector<unsigned short>`	–	Atmospheric temperature (read via I2C)
`atm_pressure`	`std::vector<unsigned short>`	–	Atmospheric pressure.
`atm_humidity`	`std::vector<unsigned short>`	–	Atmospheric humidity.
`acceleration_x`	`std::vector<unsigned short>`	–	Acceleration of the antenna in X.
`acceleration_y`	`std::vector<unsigned short>`	–	Acceleration of the antenna in Y.
`acceleration_z`	`std::vector<unsigned short>`	–	Acceleration of the antenna in Z.
`battery_level`	`std::vector<unsigned short>`	–	Battery voltage.
`firmware_version`	`std::vector<unsigned short>`	–	Firmware version.
`adc_sampling_frequency`	`std::vector<unsigned short>`	–	ADC sampling frequency in MHz.
`adc_sampling_resolution`	`std::vector<unsigned short>`	–	ADC sampling resolution in bits.
`adc_input_channels_ch`	`std::vector<vector<unsigned char>>`	–	ADC input channels.
`adc_enabled_channels_ch`	`std::vector<vector<bool>>`	–	ADC enabled channels.
`adc_samples_count_ch`	`std::vector<vector<unsigned short>>`	–	Number of samples recorded on each channel, for each unit.
`trigger_pattern_ch`	`std::vector<vector<bool>>`	–	Which channels triggered, for each unit.
`trigger_pattern_ch0_ch1`	`std::vector<bool>`	–	Whether the coincidence of channels 0 and 1 triggered the unit.
`trigger_pattern_notch0_ch1`	`std::vector<bool>`	–	Whether channel 1 without channel 0 triggered the unit.
`trigger_pattern_redch0_ch1`	`std::vector<bool>`	–	Whether the reduced coincidence of channels 0 and 1 triggered the unit.
`trigger_pattern_ch2_ch3`	`std::vector<bool>`	–	Whether the coincidence of channels 2 and 3 triggered the unit.
`trigger_pattern_calibration`	`std::vector<bool>`	–	Whether a calibration trigger recorded the unit.
`trigger_pattern_10s`	`std::vector<bool>`	–	Whether the 10-second trigger recorded the unit.
`trigger_pattern_external_test_pulse`	`std::vector<bool>`	–	Whether an external test pulse triggered the unit.
`trigger_rate`	`std::vector<unsigned short>`	–	Number of triggers each unit recorded in the second before the event.
`clock_tick`	`std::vector<unsigned int>`	–	Clock tick at which the event was triggered (used to calculate the trigger time)
`clock_ticks_per_second`	`std::vector<unsigned int>`	–	Clock ticks per second.
`gps_offset`	`std::vector<float>`	–	Offset between the GPS one-pulse-per-second signal and the true second.
`gps_leap_second`	`std::vector<unsigned short>`	–	GPS leap second.
`gps_status`	`std::vector<unsigned short>`	–	GPS status.
`gps_alarms`	`std::vector<unsigned short>`	–	GPS alarms.
`gps_warnings`	`std::vector<unsigned short>`	–	GPS warnings.
`gps_time`	`std::vector<unsigned int>`	–	GPS time.
`gps_long`	`std::vector<unsigned long long>`	–	Longitude of each unit, as reported by its GPS receiver.
`gps_lat`	`std::vector<unsigned long long>`	–	Latitude of each unit, as reported by its GPS receiver.
`gps_alt`	`std::vector<unsigned long long>`	–	Altitude of each unit, as reported by its GPS receiver.
`gps_temp`	`std::vector<unsigned int>`	–	GPS temperature.
`enable_auto_reset_timeout`	`std::vector<bool>`	–	Digital control register.
`force_firmware_reset`	`std::vector<bool>`	–	Firmware control register: force a reset.
`enable_filter_ch`	`std::vector<vector<bool>>`	–	Whether each channel’s digital filter is on, for each unit.
`enable_1PPS`	`std::vector<bool>`	–	Firmware control register: the GPS one-pulse-per-second signal is on.
`enable_DAQ`	`std::vector<bool>`	–	Firmware control register: data taking is on.
`enable_trigger_ch`	`std::vector<vector<bool>>`	–	Trigger enable mask register.
`enable_trigger_ch0_ch1`	`std::vector<bool>`	–	Whether the coincidence of channels 0 and 1 may trigger the unit.
`enable_trigger_notch0_ch1`	`std::vector<bool>`	–	Whether channel 1 without channel 0 may trigger the unit.
`enable_trigger_redch0_ch1`	`std::vector<bool>`	–	Whether the reduced coincidence of channels 0 and 1 may trigger the unit.
`enable_trigger_ch2_ch3`	`std::vector<bool>`	–	Whether the coincidence of channels 2 and 3 may trigger the unit.
`enable_trigger_calibration`	`std::vector<bool>`	–	Whether calibration triggers are on.
`enable_trigger_10s`	`std::vector<bool>`	–	Whether the 10-second trigger is on.
`enable_trigger_external_test_pulse`	`std::vector<bool>`	–	Whether an external test pulse may trigger the unit.
`enable_readout_ch`	`std::vector<vector<bool>>`	–	Test pulse rate divider and channel readout enable.
`fire_single_test_pulse`	`std::vector<bool>`	–	Firmware control register: fire one test pulse.
`test_pulse_rate_divider`	`std::vector<unsigned char>`	–	Divider that sets the test-pulse rate.
`common_coincidence_time`	`std::vector<unsigned short>`	–	Common coincidence readout time window.
`selector_readout_ch`	`std::vector<vector<unsigned char>>`	–	Input selector for readout channel.
`pre_coincidence_window_ch`	`std::vector<vector<unsigned short>>`	–	Readout window before the coincidence, per channel, as set in the unit’s firmware.
`post_coincidence_window_ch`	`std::vector<vector<unsigned short>>`	–	Readout window after the coincidence, per channel, as set in the unit’s firmware.
`gain_correction_ch`	`std::vector<vector<unsigned short>>`	–	Gain correction, per channel, as set in the unit’s firmware.
`integration_time_ch`	`std::vector<vector<unsigned short>>`	–	Integration time, per channel, as set in the unit’s firmware.
`offset_correction_ch`	`std::vector<vector<unsigned char>>`	–	Offset correction, per channel, as set in the unit’s firmware.
`base_maximum_ch`	`std::vector<vector<unsigned short>>`	–	Upper limit of the baseline, per channel, as set in the unit’s firmware.
`base_minimum_ch`	`std::vector<vector<unsigned short>>`	–	Lower limit of the baseline, per channel, as set in the unit’s firmware.
`signal_threshold_ch`	`std::vector<vector<unsigned short>>`	–	T1 threshold (`th1` in `grand.sim.detector.trigger`), per channel, as set in the unit’s firmware.
`noise_threshold_ch`	`std::vector<vector<unsigned short>>`	–	T2 threshold (`th2`), per channel, as set in the unit’s firmware.
`tper_ch`	`std::vector<vector<unsigned short>>`	–	T1 window length (`t_period`), per channel, as set in the unit’s firmware.
`tprev_ch`	`std::vector<vector<unsigned short>>`	–	Quiet time before the T1 crossing (`t_quiet`), per channel, as set in the unit’s firmware.
`ncmax_ch`	`std::vector<vector<unsigned short>>`	–	Largest number of T2 crossings (`nc_max`), per channel, as set in the unit’s firmware.
`tcmax_ch`	`std::vector<vector<unsigned short>>`	–	Largest separation between T2 crossings (`t_sepmax`), per channel, as set in the unit’s firmware.
`qmax_ch`	`std::vector<vector<unsigned char>>`	–	Upper limit of the charge ratio (`q_max`), per channel, as set in the unit’s firmware.
`ncmin_ch`	`std::vector<vector<unsigned short>>`	–	Smallest number of T2 crossings (`nc_min`), per channel, as set in the unit’s firmware.
`qmin_ch`	`std::vector<vector<unsigned char>>`	–	Lower limit of the charge ratio (`q_min`), per channel, as set in the unit’s firmware.
`ioff`	`std::vector<unsigned short>`	–	Offset of the ADC trace, for each unit; its exact meaning is not documented.
`trace_ch`	`std::vector<vector<vector<short>>>`	–	ADC counts of each unit’s channels 0 to 3: one row per unit, one trace per channel.
`pps_id`	`std::vector<unsigned int>`	–	PPS-ID.
`fpga_temp`	`std::vector<unsigned int>`	–	FPGA temperature.
`adc_temp`	`std::vector<unsigned int>`	–	ADC temperature.
`hardware_id`	`std::vector<unsigned int>`	–	Hardware ID.
`trigger_status`	`std::vector<unsigned short>`	–	Trigger status.
`trigger_ddr_storage`	`std::vector<unsigned short>`	–	Trigger DDR storage.
`data_format_version`	`std::vector<unsigned short>`	–	Data format version.
`adaq_version`	`std::vector<unsigned short>`	–	ADAQ version.
`dudaq_version`	`std::vector<unsigned short>`	–	DUDAQ version.
`trigger_pattern_ch0_ch1_ch2`	`std::vector<bool>`	–	Trigger selection: ch0&ch1&ch2.
`trigger_pattern_ch0_ch1_notch2`	`std::vector<bool>`	–	Trigger selection: ch0&ch1&~ch2.
`trigger_pattern_20Hz`	`std::vector<bool>`	–	Trigger selection: 20 Hz.
`trigger_external_test_pulse_period`	`std::vector<int>`	–	External pulse trigger period.
`gps_sec_sun`	`std::vector<unsigned int>`	–	GPS seconds since Sunday 00:00.
`gps_week_num`	`std::vector<unsigned short>`	–	GPS week number.
`gps_receiver_mode`	`std::vector<unsigned char>`	–	GPS receiver mode.
`gps_disciplining_mode`	`std::vector<unsigned char>`	–	GPS disciplining mode.
`gps_self_survey`	`std::vector<unsigned char>`	–	GPS self-survey progress.
`gps_minor_alarms`	`std::vector<unsigned short>`	–	GPS minor alarms.
`gps_gnss_decoding`	`std::vector<unsigned char>`	–	GPS GNSS decoding.
`gps_disciplining_activity`	`std::vector<unsigned short>`	–	GPS disciplining activity.
`notch_filters_no_ch`	`std::vector<vector<unsigned char>>`	–	Notch filter number.
`nutrig_rhox`	`std::vector<unsigned short>`	–	NUTRIG correlation with X.
`nutrig_rhoy`	`std::vector<unsigned short>`	–	NUTRIG correlation with Y.

`TRawVoltage`

Voltage at the ADC input of each event, converted from TADC to physical units. File: rawvoltage_*.root; API: TRawVoltage.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`event_size`	`uint32`	–	Common for the whole event Event size.
`first_du`	`uint32`	–	First detector unit that triggered in the event.
`time_seconds`	`uint32`	–	Unix time corresponding to the GPS seconds of the trigger.
`time_nanoseconds`	`uint32`	–	GPS nanoseconds corresponding to the trigger of the first triggered station.
`du_count`	`uint32`	–	Number of detector units in the event - basically the antennas count.
`du_id`	`std::vector<unsigned short>`	–	Detector unit (antenna) ID.
`du_seconds`	`std::vector<unsigned int>`	–	Unix time of the trigger for this DU.
`du_nanoseconds`	`std::vector<unsigned int>`	ns	Nanoseconds of the trigger for this DU.
`trigger_flag`	`std::vector<unsigned short>`	–	Same as event_type, but event_type could consist of different triggered DUs.
`trigger_position`	`std::vector<unsigned short>`	–	Trigger position in the trace, in samples.
`atm_temperature`	`std::vector<float>`	–	Atmospheric temperature (read via I2C)
`atm_pressure`	`std::vector<float>`	–	Atmospheric pressure.
`atm_humidity`	`std::vector<float>`	–	Atmospheric humidity.
`du_acceleration`	`std::vector<vector<float>>`	–	Acceleration of the antenna in (x,y,z) in m/s2.
`battery_level`	`std::vector<float>`	–	Battery voltage.
`adc_samples_count_channel`	`std::vector<vector<unsigned short>>`	–	ADC samples callected in channels (0,1,2,3)
`trigger_pattern`	`std::vector<unsigned short>`	–	Trigger pattern - which of the trigger sources (more than one may be present) fired to actually the trigger the digitizer - explained in the docs. ToDo: Decode this?
`trigger_rate`	`std::vector<unsigned short>`	–	Trigger rate - the number of triggers recorded in the second preceding the event.
`clock_tick`	`std::vector<unsigned int>`	–	Clock tick at which the event was triggered (used to calculate the trigger time)
`clock_ticks_per_second`	`std::vector<unsigned int>`	–	Clock ticks per second.
`gps_offset`	`std::vector<float>`	–	GPS offset - offset between the PPS and the real second (in GPS). ToDo: is it already included in the time calculations?
`gps_leap_second`	`std::vector<unsigned short>`	–	GPS leap second.
`gps_status`	`std::vector<unsigned short>`	–	GPS status.
`gps_alarms`	`std::vector<unsigned short>`	–	GPS alarms.
`gps_warnings`	`std::vector<unsigned short>`	–	GPS warnings.
`gps_time`	`std::vector<unsigned int>`	–	GPS time.
`gps_long`	`std::vector<double>`	–	Longitude.
`gps_lat`	`std::vector<double>`	–	Latitude.
`gps_alt`	`std::vector<double>`	–	Altitude.
`gps_temp`	`std::vector<float>`	–	GPS temperature.
`ioff`	`std::vector<unsigned short>`	–	?? What is it? Some kind of the adc trace offset?
`trace_ch`	`std::vector<vector<vector<float>>>`	–	Voltage traces for channels 1,2,3,4 in muV.
`nutrig_rhox`	`std::vector<float>`	–	NUTRIG correlation with X.
`nutrig_rhoy`	`std::vector<float>`	–	NUTRIG correlation with Y.

`TVoltage`

Voltage traces of each event, in µV, as simulated by Efield2Voltage. File: voltage_*.root; API: TVoltage.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`first_du`	`uint32`	–	Identifier of the first unit that triggered.
`time_seconds`	`uint32`	–	Time of the event’s trigger, in Unix seconds, converted from GPS time.
`time_nanoseconds`	`uint32`	–	Nanoseconds to add to `time_seconds`, for the first unit that triggered.
`du_count`	`uint32`	–	Number of detection units in the event.
`du_id`	`std::vector<unsigned short>`	–	Identifier of each detection unit, in the order of the traces.
`du_seconds`	`std::vector<unsigned int>`	–	Trigger time of each unit, in Unix seconds.
`du_nanoseconds`	`std::vector<unsigned int>`	ns	Nanoseconds to add to `du_seconds`, for each unit.
`trigger_flag`	`std::vector<unsigned short>`	–	Trigger type of each unit, with the codes of `event_type`.
`trigger_position`	`std::vector<unsigned short>`	–	Sample of each unit’s trace at which it triggered.
`du_acceleration`	`std::vector<vector<float>>`	–	Acceleration measured at each unit, as (x, y, z), in m/s².
`trigger_rate`	`std::vector<unsigned short>`	–	Number of triggers each unit recorded in the second before the event.
`trace`	`std::vector<vector<vector<float>>>`	–	Voltage at each unit, in µV: one row per unit, holding the X (south-north), Y (east-west) and Z (vertical) arms. A simulated voltage is at the ADC input, or at the antenna terminals when the RF chain is left out.
`p2p`	`std::vector<vector<float>>`	–	Peak-to-peak amplitude of each arm, for each unit, in µV.
`time_max`	`std::vector<vector<float>>`	–	Time of the peak of each component, for each unit, in ns.
`grandlib_version`	`str`	–	Version of GRANDlib that produced this file. Written by `Efield2Voltage`. The simulated voltage depends on the code as well as on the input: the Galactic-noise level, for example, changed by a factor of \(\sqrt2\) on 7 September 2026. Files written before that date carry no version. It sat at `0.1.0.dev0` across twenty-seven milestone tags, which would have made the stamp useless; see the note in `pyproject.toml`.

`TEfield`

Electric-field traces of each event at each detection unit, in µV/m. File: efield_*.root; API: TEfield.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`time_seconds`	`uint32`	–	Time of the event’s trigger, in Unix seconds, converted from GPS time.
`time_nanoseconds`	`uint32`	–	Nanoseconds to add to `time_seconds`, for the first unit that triggered.
`event_type`	`uint32`	–	Trigger type: 0x1000 for the 10-second trigger, 0x8000 for a random trigger; any other value is a shower trigger.
`du_count`	`uint32`	–	Number of detection units in the event.
`du_id`	`std::vector<unsigned short>`	–	Identifier of each detection unit, in the order of the traces.
`du_seconds`	`std::vector<unsigned int>`	–	Trigger time of each unit, in Unix seconds.
`du_nanoseconds`	`std::vector<unsigned int>`	ns	Nanoseconds to add to `du_seconds`, for each unit.
`trigger_position`	`std::vector<unsigned short>`	–	Sample of each unit’s trace at which it triggered.
`trace`	`std::vector<vector<vector<float>>>`	–	Electric field at each unit, in µV/m: one row per unit, holding the x, y and z components.
`fft_mag`	`std::vector<vector<vector<float>>>`	–	Magnitude of the Fourier transform of each component, for each unit.
`fft_phase`	`std::vector<vector<vector<float>>>`	–	Phase of the Fourier transform of each component, for each unit.
`p2p`	`std::vector<vector<float>>`	–	Peak-to-peak amplitude of each component, for each unit, in µV/m.
`pol`	`std::vector<vector<float>>`	–	Polarization of the field at each unit.
`time_max`	`std::vector<vector<float>>`	–	Time of the peak of each component, for each unit, in ns.

`TShower`

The shower of each event: primary, energy, direction, core and shower maximum. File: shower_*.root; API: TShower.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`primary_type`	`str`	–	Primary particle, as a PDG code written as text, such as `"2212"` for a proton.
`energy_em`	`float32`	GeV	Energy in the electromagnetic component of the shower (electrons and positrons), which produces the radio emission, in GeV.
`energy_primary`	`float32`	GeV	Energy of the primary particle, in GeV.
`azimuth`	`float32`	degrees	Azimuth of the direction the shower comes from, in degrees, measured from north toward west in the array frame (x north, y west, z up).
`zenith`	`float32`	degrees	Zenith angle of the direction the shower comes from, in degrees: 0 for a vertical shower, above 90 for an upgoing one.
`direction`	`array of shape 3, float32`	–	Unit vector along which the shower travels, in the array frame (x north, y west, z up): minus the direction that `zenith` and `azimuth` name, so its z component is negative for a downgoing shower.
`shower_core_pos`	`array of shape 3, float32`	–	Position of the shower core, where the shower axis meets the ground, in meters in the array frame. Not defined for an upgoing shower.
`atmos_model`	`str`	–	Name of the atmospheric model the simulation used.
`atmos_model_param`	`array of shape 3, float32`	–	Parameters of the atmospheric model; their meaning depends on the model and the simulation code.
`magnetic_field`	`array of shape 3, float32`	–	Geomagnetic field the simulation used: inclination and declination in degrees, then the strength in µT. Files from older CoREAS conversions hold the strength in mT or in gauss.
`core_alt`	`float32`	–	Altitude of the ground at the core, in meters above sea level.
`xmax_grams`	`float32`	g/cm2	Atmospheric depth of the shower maximum, measured along the shower axis, in g/cm².
`xmax_pos`	`array of shape 3, float32`	–	Position of the shower maximum, in meters in the array frame, the frame of `du_xyz` and `shower_core_pos`. NaN if unknown.
`xmax_pos_shc`	`array of shape 3, float32`	–	Position of the shower maximum relative to the core, as the simulation gives it.
`core_time_s`	`float64`	–	Time at which the shower reached the core, in Unix seconds.
`core_time_ns`	`float64`	–	Nanoseconds to add to `core_time_s`.

`TShowerSim`

What a simulation records about the shower of each event, beyond TShower. File: showersim_*.root; API: TShowerSim.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`input_name`	`str`	–	File name in the simulator.
`event_date`	`uint32`	–	The date for which we simulate the event (epoch)
`rnd_seed`	`float64`	–	Random seed.
`primary_inj_point_shc`	`std::vector<vector<float>>`	–	Primary injection point in Shower Coordinates.
`primary_inj_alt_shc`	`std::vector<float>`	–	Primary injection altitude in Shower Coordinates.
`primary_inj_dir_shc`	`std::vector<vector<float>>`	–	Primary injection direction in Shower Coordinates.
`atmos_altitude`	`std::vector<vector<float>>`	–	Table of air density [g/cm3] and vertical depth [g/cm2] versus altitude [m].
`atmos_density`	`std::vector<vector<float>>`	–	Air density at each altitude of `atmos_altitude`, in g/cm3.
`atmos_depth`	`std::vector<vector<float>>`	–	Vertical depth at each altitude of `atmos_altitude`, in g/cm2.
`hadronic_model`	`str`	–	High energy hadronic model (and version) used.
`low_energy_model`	`str`	–	Energy model (and version) used.
`cpu_time`	`float32`	–	Time it took for the sim.
`long_depth`	`std::vector<float>`	–	Slant depth of the observing levels for longitudinal development tables.
`long_pd_depth`	`std::vector<float>`	–	Slant depth of the levels of the particle-number profiles (`long_pd_*`), in g/cm2.
`long_pd_eminus`	`std::vector<float>`	–	Number of electrons.
`long_pd_eplus`	`std::vector<float>`	–	Number of positrons.
`long_pd_muminus`	`std::vector<float>`	–	Number of muons-.
`long_pd_muplus`	`std::vector<float>`	–	Number of muons+.
`long_pd_gamma`	`std::vector<float>`	–	Number of gammas.
`long_pd_hadron`	`std::vector<float>`	–	Number of pions, kaons, etc.
`long_gamma_elow`	`std::vector<float>`	–	Energy in low energy gammas.
`long_e_elow`	`std::vector<float>`	–	Energy in low energy e+/e-.
`long_e_edep`	`std::vector<float>`	–	Energy deposited by e+/e-.
`long_mu_elow`	`std::vector<float>`	–	Energy in low energy mu+/mu-.
`long_mu_edep`	`std::vector<float>`	–	Energy deposited by mu+/mu-.
`long_hadron_elow`	`std::vector<float>`	–	Energy in low energy hadrons.
`long_hadron_edep`	`std::vector<float>`	–	Energy deposited by hadrons.
`long_neutrino`	`std::vector<float>`	–	Energy in created neutrinos.
`tested_core_positions`	`std::vector<vector<float>>`	–	Core positions tested for that shower to generate the event (effective area study)
`event_weight`	`uint32`	–	statistical weight given to the event.
`tested_cores`	`std::vector<vector<float>>`	–	tested core positions.

`TRecons`

Reconstruction results of each event: the fits of grand.analysis. File: recons_*.root; API: TRecons.

Field	Type	Unit	Description
`run_number`	`uint32`	–	Run number; with the event number it identifies the entry.
`event_number`	`uint32`	–	Event number, unique within its run.
`peak_amps`	`std::vector<float>`	–	Event processing Maximum amplitude of the Hilbert envelope (in ADC counts or µV/m depending on the input)
`peak_time`	`std::vector<float>`	–	Time corresponding to the peak amplitude (in seconds)
`Xants`	`std::vector<vector<float>>`	–	Antenna positions in the GRAND detector reference frame (in meters)
`du_count`	`uint32`	–	Number of triggered antennas.
`zenith_pwf`	`float32`	radians	Plane Wave Fits (PWF) reconstruction outputs The angles and their bounds are in radians: a value in degrees by mistake (85.0) warns, as it lies outside 0 to pi (#206) Shower zenith angle from PWF (in radians) Coordinate system: NWU, origin at layout center, “coming from”.
`azimuth_pwf`	`float32`	radians	Shower azimuth angle from PWF (in radians) Coordinate system: NWU, origin at layout center, “coming from”.
`chi2_pwf`	`float32`	–	Non-reduced (raw) chi² from PWF; NaN if not filled Divide by du_count - 2, the degrees of freedom, to obtain the reduced chi².
`zenith_swf`	`float32`	radians	Spherical Wave Fits (SWF) Reconstruction outputs polar zenith from SWF (in rad)
`azimuth_swf`	`float32`	radians	polar azimuth from SWF (in rad)
`r_xmax`	`float32`	–	Distance between the reconstructed Xsource and the origin = layout center (in meters)
`t_s`	`float32`	–	Emission time from SWF (in seconds)
`Xsource`	`std::vector<vector<float>>`	–	Reconstructed shower emission point (Xsource) in GRAND detector frame (in meters) Coordinate system: NWU, origin at layout center.
`chi2_swf`	`float32`	–	Non-reduced (raw) chi² from SWF; NaN if not filled Divide by du_count - 4, the degrees of freedom, to obtain the reduced chi².
`distance_source_antenna`	`std::vector<float>`	–	Distance between the reconstructed Xsource and each antenna (in meters)
`zenith_adf`	`float32`	radians	Angular Distribution Function (ADF) Shower zenith angle from ADF (in radians) Coordinate system: NWU, origin at layout center, “coming from”.
`azimuth_adf`	`float32`	radians	Shower azimuth angle from ADF (in radians) Coordinate system: NWU, origin at layout center, “coming from”.
`width`	`float32`	–	Width parameter from ADF fit (delta_omega)
`scaling_factor`	`float32`	–	Scaling factor A from ADF fit.
`chi2_adf`	`float32`	–	Non-reduced (raw) chi² from ADF; NaN if not filled Divide by du_count - 4, the degrees of freedom, to obtain the reduced chi².
`eta`	`std::vector<float>`	–	Azimuth angle in the shower plane (in radians)
`omega`	`std::vector<float>`	–	Angular distance to the shower axis (in radians)
`omega_cr`	`std::vector<float>`	–	Cherenkov angle (computed using a two emission points toy model) (in radians)
`adf_amplitude`	`std::vector<float>`	–	Amplitude predicted by the ADF model at each antenna (in ADC counts or µV/m)
`energy_elm_voltage`	`float32`	–	(Electromagnetic energy in eV, obtained directly from voltage data)
`crb_zenith_adf`	`float32`	radians	Cramér-Rao (lower) bound (CRB); NaN if not filled (main_DOI.py fills them, main_AOI.py does not) CRB of shower zenith angle from ADF (in radians)
`crb_azimuth_adf`	`float32`	radians	CRB of shower azimuth angle from ADF (in radians)
`crb_scaling_factor`	`float32`	–	CRB of scaling factor A from ADF fit.
`crb_width`	`float32`	–	CRB of width parameter from ADF fit (delta_omega)
`crb_zenith_swf`	`float32`	radians	CRB of shower zenith from SWF (in rad)
`crb_azimuth_swf`	`float32`	radians	CRB of shower azimuth from SWF (in rad)
`crb_r_xmax`	`float32`	–	CRB of distance between the reconstructed Xsource and the origin = layout center (in meters)
`crb_t_s`	`float32`	–	CRB of emission time from SWF (in seconds)
`crb_zenith_pwf`	`float32`	radians	CRB of shower zenith from PWF (in radians)
`crb_azimuth_pwf`	`float32`	radians	CRB of shower azimuth from PWF (in radians)

Data format reference

Run-level trees

TRun

TRunVoltage

TRunRawVoltage

TRunEfieldSim

TRunShowerSim

TRunNoise

Event-level trees

TADC

TRawVoltage

TVoltage

TEfield

TShower

TShowerSim

TRecons