Output format

In this page, the format of the hdf5 output files of nexus is described.

In all kinds of files there is a group named 'MC' and five tables:

/MC/configuration

/MC/hits

/MC/particles

/MC/sns_positions

/MC/sns_response

The first column of the hits, particles and sns_response tables is the event ID.

The particles table contains all the information related to the propagation of the simulated particles in the detector (optical photons and ionization electrons excluded).

  event_id  particle_id  particle_name  primary  mother_id  initial_x (mm)  initial_y (mm)  initial_z (mm) initial_t (ns)  final_x (mm) final_y (mm) final_z (mm)  final_t (ns) initial_volume  final_volume   initial_momentum_x (MeV)  initial_momentum_y (MeV)  initial_momentum_z (MeV)  final_momentum_x (MeV)  final_momentum_y (MeV)  final_momentum_z (MeV)    kin_energy (MeV)  length (mm)  creator_proc     final_proc
0        0            1             e-        1          0          -54.39          145.42           46.42          0.0        -54.39       145.44         46.44        0.002          ACTIVE        ACTIVE                     -0.060                   0.028                       0.073                     0.0                     0.0                  0.0           0.51099998     0.15547082          none     Scintillation
...

particle_id is the ID of the particle.

particle_name is the symbol of the particle (e- stand for electron, gamma stands for high energy photon...).

primary is 1 if the particle is the first one to be generated, and 0 if it is created as a product of another particle.

mother_id is the ID of the track that the particle originates from (it is 0 if the particle is primary).

initial_vertex_x/y/z are the coordinates of the position where the particle is created.

initial_t is the time when the particle is created.

final_vertex_x/y/z are the coordinates of the position where the particle trajectory ends.

final_t is the time when the particle trajectory ends.

initial_momentum_x/y/z are the initial 3-momentum of the particle.

final_momentum_x/y/z are the 3-momentum of the particle when its trajectory ends.

kin_energy is the kinetic energy of the particle when it is created.

length is the length of the particle trajectory, as calculated by GEANT4.

creator_proc is the process that has created the particle (the common ones are phot for photoelectric process, compt for Compton, brem for bremsstrahlung...). If the particle is primary, creator_proc is none.

final_proc is the process that kills the particle.

The hits table contains the information regarding the true hits of deposited energy. The format is the following:

   event_id          x (mm)       y (mm)        z (mm)    time (ns)   energy (MeV)        label  particle_id  hit_id
0         0      4.52160931  17.44470596  142.81471252   0.00044281     0.13235365       ACTIVE            1       0
1         0      4.51773214  17.47066879  142.74450684   0.00074826     0.11500714       ACTIVE            1       1
...

The label column is the name of the sensitive volume where the hit has been registered. In NEXT, so far, we have ACTIVE, BUFFER and NAI (when using the external scintillator). The particle_id column is the ID of the particle that has produced the hit, while the hit_id is the order of the hit inside the subset of the particle's hits that have the same label.

The sns_response table contains the times and the detected charge of the sensors, according to the time binning specified in the simulation (which is stored in the configuration table, see below).

       event_id  sensor_id  time_bin  charge
0             0         42         0      46
1             0         42         1      42
2             0         42         2      46
...

The sensor_id column is the ID of the sensor, the time_bin column is the ordered number of the time bin and the charge column is the number of photons detected in that time bin by that particular sensor. Notice that in the time_bin column the numbers are always increasing for a given event, but they can have gaps, since the time bins where no charge is detected don't appear in the table.

The configuration table contains all the configuration parameters that have been specified in the init and config macro files, plus the number of events generated, the number of events saved in the file and the number of events that have hits deposited in the ACTIVE volume.

                        param_key                    param_value
0                      num_events                             10
1                    saved_events                             10
2              interacting_events                              9
3    /PhysicsList/RegisterPhysics    G4EmStandardPhysics_option4
...

The time binning of the sensors is always stored, even if it has not been specified explicitly in the configuration file:

SiPM_binning       1. microsecond
PmtR11410_binning 25. nanosecond

Finally, the sns_position table contains, as its own name says, the xyz position of all the sensors that have detected at least one photoelectron. Moreover, a string identifying the type of sensor is also stored in the sensor_name column.

   sensor_id     sensor_name               x           y           z
0          5       PmtR11410   -1.821894e+02   32.124912  670.099976
1          0       PmtR11410   -2.394141e+01   65.778481  670.099976
2          2       PmtR11410    6.893655e+01  -12.155373  670.099976
...

In some specific runs, an additional group is created, DEBUG with the steps table, where all the information about individual steps of the particles is stored. Each line provides the ID of the particle, its name, the ID of the particular step, the volumes where the step starts and ends (initial and final), the points where the steps starts and ends and the time.