Add/Update Decay Vertices in HepMC3 Events

Generating a correction to the decay-vertex position is important for relatively long-lived particles, such as tau leptons, in KKMCee event generation. The displacement of the decay vertex also affects the positions of subsequent decays in the daughter decay chain. Therefore, the correction must be propagated consistently through the event record.

As input, the position of the interaction point or production vertex is needed. For this reason, this kind of vertex-position generation is sometimes not performed directly inside the event generator itself, but instead in the interface between the generator and the detector-response or simulation code.

At present, the vertex-position code is an independent application acting directly on a HepMC3 data file. It can also be integrated into other stages of the event-generation or detector-simulation chain, depending on the needs of the analysis or experiment. The main vertex-handling logic is implemented in VertexManager.cxx, with its corresponding interface defined in VertexManager.h.

This example program reads a HepMC3 ASCII event file, adds or updates decay-vertex positions for a user-selected particle PDG id, and writes the modified event record to a new HepMC3 ASCII file. Optionally, the same modified events can also be written to a HepMC3 ROOTTree file.

The main intended use case is KKMCee/TAUOLA output in HepMC3 format, where the decay tree is already present but the spatial and time coordinates of decay vertices need to be filled or shifted. Although the example is motivated by tau decays, the code can be used for any particle by providing the appropriate PDG id.

This application is based on modified code from the TAUOLA universal interface written by T. Przedzinski. The development also benefited from Jim John’s previous experience with neutrino event generators, particularly GENIE.

Download

• vertex-add_v1.tar.gz

Dependencies

Required:

• C++17-compatible compiler
• ROOT
• HepMC3

For ROOTTree output, HepMC3 must be built with ROOT I/O support.

Compile and Run:

mkdir -p build
cd build
cmake ..  -DWITH_HEPMC3=/<path to hepmc>/HepMC3/HepMC3-3.3.0
make
./Run --input hepmc.out --pdgid -15 --lifetime 0.08703 --ascii output.hepmc3 --root output.root

The output filenames are currently given through the inputs:

output.hepmc3
output.root

What the example program does

For each event, the example program:

1. Reads one event from a HepMC3 ASCII input file.
2. Finds the particle with PDG ID given with the parser --pdgid.
3. Computes a decay position from the particle production vertex and four-momentum.
4. Updates the particle decay vertex position in the HepMC3 event record.
5. Optionally propagates vertex positions through daughter decay chains.
6. Writes the modified event to the HepMC3 ASCII output file, and optionally to a ROOTTree output file.

The decay-position formula used in the code is

x_decay = x_production + (p_tau / m_tau) * L

where L is the proper decay length in the same length unit used by the HepMC3 event record.

ROOT usage and integration notes

• In the present example, the ROOT random-number generator is used only in one place to sample the decay length. This can be replaced by any random-number generator available in the user's own software environment.

• The remaining ROOT dependencies are connected to the optional ROOTTree output format. If ROOTTree output is not needed, the corresponding ROOT-output code can be commented out or removed.

• After replacing the random-number generator and disabling the optional ROOTTree output, the application can work without the ROOT library.

• The application is currently provided as an independent program that reads and writes HepMC3 files. It can also be integrated directly into user code, in which case the HepMC3 event record can be updated on the fly during the generation or detector-simulation chain. Please contact Jim John(jim.john@ifj.edu.pl) for help with such integration, if necessary.

Runtime configuration

The current configuration is set in example.cxx:

VertexManager::Options vertex_cfg;
vertex_cfg.propagate_to_daughters = true;
vertex_cfg.overwrite_existing_positions = false;
vertex_cfg.create_missing_end_vertex = true;

VertexManager vertex_manager(vertex_cfg);

Important options:

Also the decay length of secondary particles should be controlled through the corresponding options in VertexManager.

To load the root file

root
gSystem->AddDynamicPath("/home/<path to hepmc3>/HepMC3/HepMC3-3.3.0/lib");
gSystem->Load("libHepMC3");
gSystem->Load("libHepMC3rootIO");
TFile* f = TFile::Open("output.root");