Reading events

Sometimes it can be useful to provide some of the event information from an external source instead of using the internally generated data.

Pepper can read such external information from an HDF5 file. To enable this, simply add the input_path setting to the [events] section of the runcard (see Event generation options). For example:

[events]
input_path = events.hdf5

Note

Pepper must be configured with HDF5 support to enable this feature.

Currently, Pepper supports reading in random numbers (using the optional data set randomNumbers) and phase-space weights (using the optional data set weights). The random numbers that can thus be injected are currently only used for selecting the phase-space point and for selecting the helicity configuration when sampling helicities.

Warning

All input random numbers \(r\) must satisfy \(0 \leq r < 1.0\). Please make sure that only floating-point random numbers satisfying this condition are present in the randomNumber data set. In particular, do not be tempted to directly pass a random integer index for the helicity configuration. Instead, pass the corresponding floating-point random value \(r\).

For details, see examples/external-random-numbers-and-weights, which includes a simple example python script generate_input_datasets.py to generate an nput HDF5 file, and a Pepper runcard peppper.ini, which includes the required setting to read in the HDF5 file. To run the example, simply run the following commands in your shell:

python generate_input_datasets.py
<installation_prefix>/bin/pepper

# optionally, to inspect the generated input file:
h5dump random_numbers.hdf5

# optionally, to inspect the events written out by Pepper:
h5dump pepper_events.hdf5

When using h5dump to display the input and output events, you will find that the random numbers that are read in are also written out, without modification, because any additional remapping has been suppressed by disabling VEGAS phase-space optimisation in the runcard. The event weights, however, in the “NOMINAL” column of the event dataset, are not equal to the phase-space weights of the input events (which are all set to 1.0 by the example python script), because the “NOMINAL” event weight includes phase-space cuts (most events will likely be outside of the cuts and thus have a “NOMINAL” weight of zero), and moreover includes factors for the squared matrix elements, flux factors etc. However, the phase-space weight is included as a factor and can thus be used to attach a relative weight associated to the phase-space and helicity configurations.