LHEReader: LHE to ROOT Converter

• LHEReader is a lightweight Python program that converts LHE format events into ROOT TTrees for fast analysis in high-energy physics.
• It processes both .lhe and .lhe.gz files, extracting essential event-level and particle-level data including momenta, spin, and color flow.
• The tool provides a minimal, stable schema for immediate downstream analysis with ROOT/C++ or PyROOT, supporting quick kinematic checks and sample validation.

Searching arXiv for the specified paper and closely related context. LHEReader is a lightweight program designed to convert Les Houches Event (LHE) files into ROOT files so that parton-level Monte Carlo events can be analyzed directly within the ROOT ecosystem. It is presented as a Python script, LHEReader.py, that reads .lhe or compressed .lhe.gz inputs event-by-event and writes a ROOT file containing a single TTree named events, carrying event-level and particle-level information required for immediate analysis in ROOT/C++ or PyROOT (Desai, 2 Mar 2026).

1. Purpose and scope

LHEReader addresses a specific interface problem in high-energy physics workflows. Monte Carlo event generators such as MadGraph5 produce parton-level events in the standard LHE format, and these files encode particle identities, status codes, four-momenta, spin, parentage and color information, together with event-level quantities such as scales, $\alpha_{\mathrm{QED}}$, $\alpha_{\mathrm{QCD}}$, and event weights. While LHE is widely supported across the HEP toolchain, ROOT-based analyses typically require data in ROOT TTrees. LHEReader solves this by converting LHE content into a ROOT representation with a stable and minimal schema (Desai, 2 Mar 2026).

The documented use cases are pragmatic rather than expansive. The program is presented as useful for quick kinematic checks, validation of generated samples, educational workflows, and for reading LHE output produced not only by matrix-element generators but also by tools like MadAnalysis5. Its role is therefore not to replace the broader event-generation stack, but to provide a direct bridge between LHE-formatted hard-scatter or parton-level records and downstream ROOT analysis.

2. Program architecture and ROOT schema

The program is implemented as a Python script using ROOT/PyROOT. The paper states that it reads LHE files event-by-event and fills branches in a ROOT TTree; it does not describe the XML parsing strategy in detail beyond that point, and no specific LHE schema version or XML library details are given (Desai, 2 Mar 2026).

The output consists of a single TTree named events. At the event level, the documented scalar branches are:

• numParticles (int): number of particles in the event
• eventweight (float): event weight from the LHE record
• scale (float): event scale
• alpha_qed (float): $\alpha_{\mathrm{QED}}$ used for the event
• alpha_qcd (float): $\alpha_{\mathrm{QCD}}$ used for the event

At the particle level, the program stores one std::vector<T> per event for each of the following quantities:

• pid (vector<int>): PDG ID for each particle
• status (vector<int>): status code
• mother1, mother2 (vector<int>): mother indices as in LHE
• color1, color2 (vector<int>): color-flow tags
• px, py, pz (vector<float>): momentum components
• energy, mass (vector<float>): particle energy and mass
• tau (vector<float>): proper lifetime
• spin (vector<float>): spin/helicity information

These branches are sufficient to reconstruct basic kinematics, mother-daughter relations, and color connections at the parton level. The paper explicitly notes that the output does not report run numbers, event numbers, PDF IDs, $x_1/x_2$, $Q^2$, or lists of alternative weights.

The paper also provides a C++ example for reading the output:

$Q^2$9

and a loop skeleton:

$p_T = \sqrt{p_x^2 + p_y^2}$0

A branch naming discrepancy is therefore documented: the branch table lists eventweight, while the code snippet uses weight. Users are advised to check the actual branch name in the produced output file. The example further illustrates selection of final-state particles with status == 1, use of PDG IDs to identify species, and a simple truth-level missing transverse energy proxy constructed from neutrinos.

3. Supported inputs, event content, and kinematic semantics

LHEReader supports both .lhe and .lhe.gz as inputs. The output branch definitions show that it reads particle PDG IDs, status codes, mother indices, color tags, four-momenta, mass, spin, lifetime, and the event-level quantities scale, alpha_qed, alpha_qcd, and eventweight (Desai, 2 Mar 2026).

The paper is explicit about what it does not specify. It does not list supported LHE versions or the exact tags and blocks parsed, such as <init>, <initrwgt>, <rwgt>, or PDF blocks. It does not mention x1/x2, PDF IDs, $Q^2$, beam information, or per-event multiple weights and systematics. Only a single eventweight branch is documented. This means that workflows relying on multiweight schemes, PDF information, or beam configurations are outside the documented feature set.

The conventions and units are also only indirectly characterized. The paper does not explicitly state units in the branches, although the selection examples use GeV thresholds, which is consistent with standard LHE momentum units. The kinematic relations used or implied in the analysis examples are:

• $p_T = \sqrt{p_x^2 + p_y^2}$
• $m_{ab}^2 = (p_a + p_b)^2$
• $$\Delta R = \sqrt{(\Delta \eta)^2 + (\Delta \phi)^2}$$

For event weighting, the ROOT output contains a scalar eventweight branch copied from the LHE. The paper does not specify an explicit histogram normalization or scaling formula implemented within LHEReader. It notes, for context, that a common event weight in analyses is $\alpha_{\mathrm{QCD}}$0 or $\alpha_{\mathrm{QCD}}$1 when scaling to luminosity $\alpha_{\mathrm{QCD}}$2, but it does not state that LHEReader applies such a formula internally.

4. Installation, invocation, and downstream analysis

The documented installation target is Linux with ROOT and PyROOT enabled, and Python 3.10 is reported as tested. The repository is given as https://github.com/amanmdesai/LHEReader.git. The conversion commands are presented in minimal form (Desai, 2 Mar 2026):

$p_T = \sqrt{p_x^2 + p_y^2}$1

$p_T = \sqrt{p_x^2 + p_y^2}$2

Compressed inputs are likewise accepted:

$p_T = \sqrt{p_x^2 + p_y^2}$3

The downstream usage pattern is equally direct. A ROOT or PyROOT analysis opens the generated ROOT file, retrieves the events tree, binds the necessary scalar and vector branches, and loops over entries and particles to apply selections or fill histograms. The paper gives a corresponding C++ pattern:

$p_T = \sqrt{p_x^2 + p_y^2}$4

Within the documented workflow, LHEReader sits between upstream event production and downstream ROOT analysis. Upstream tools include MadGraph5 and MadAnalysis5, with Pythia8 and FastJet in the fast-simulation chain; downstream, the output is intended for any ROOT-based analysis in C++ or PyROOT. The paper includes an EventLoop C++ skeleton showing how to read the events tree, use status and pid to implement truth-level selections, compute variables such as $\alpha_{\mathrm{QCD}}$3 from neutrinos, and fill histograms.

5. Demonstration analyses and performance evaluation

The paper evaluates conversion performance using two leading-order MadGraph5 samples: $\alpha_{\mathrm{QCD}}$4 and $\alpha_{\mathrm{QCD}}$5. For $\alpha_{\mathrm{QCD}}$6, the reported average conversion time is approximately $\alpha_{\mathrm{QCD}}$7 ms per event for $\alpha_{\mathrm{QCD}}$8 events, with a total of $\alpha_{\mathrm{QCD}}$9 s, and approximately $\alpha_{\mathrm{QED}}$0 ms/event for $\alpha_{\mathrm{QED}}$1 events, with a total of $\alpha_{\mathrm{QED}}$2 s. For $\alpha_{\mathrm{QED}}$3, the reported rates are approximately $\alpha_{\mathrm{QED}}$4 ms/event for $\alpha_{\mathrm{QED}}$5 events, with a total of $\alpha_{\mathrm{QED}}$6 s, and approximately $\alpha_{\mathrm{QED}}$7 ms/event for $\alpha_{\mathrm{QED}}$8 events, with a total of $\alpha_{\mathrm{QED}}$9 s (Desai, 2 Mar 2026).

The physics workflow example is $\alpha_{\mathrm{QCD}}$0 with $\alpha_{\mathrm{QCD}}$1 and $\alpha_{\mathrm{QCD}}$2. Generation is performed with MadGraph5 at leading order, with beam energy set to $\alpha_{\mathrm{QCD}}$3 TeV for LHC Run 3 and using PDF4LHC21 PDFs via LHAPDF6. The quoted cross-section, including branching fractions and as reported from MadGraph5 in the paper, is $\alpha_{\mathrm{QCD}}$4 fb$\alpha_{\mathrm{QCD}}$5; the unit appears in the paper exactly in that form. Parton shower and hadronization are performed with Pythia8, and object reconstruction is carried out via MadAnalysis5 using FastJet with the anti-$\alpha_{\mathrm{QCD}}$6 algorithm and $\alpha_{\mathrm{QCD}}$7. Samples are scaled to an integrated luminosity of $\alpha_{\mathrm{QCD}}$8 fb$\alpha_{\mathrm{QCD}}$9 for illustrative plots.

The analysis selections are described at both parton and reconstructed levels. The illustrative lepton requirements are exactly two opposite-sign, same-flavor isolated leptons with:

• $x_1/x_2$0 GeV
• $x_1/x_2$1
• $x_1/x_2$2 GeV $x_1/x_2$3 GeV

Jets are required to satisfy:

• $x_1/x_2$4 GeV
• $x_1/x_2$5

For $x_1/x_2$6 tagging, parton-level $x_1/x_2$7 jets are identified from truth using PDG ID. At reconstructed level, the pid branch is used for a simplified truth-based tag, and a $x_1/x_2$8 $x_1/x_2$9-tag efficiency is assumed. Isolation between selected leptons and $Q^2$0 jets is enforced through $Q^2$1. Higgs reconstruction requires at least two $Q^2$2 jets, and the leading and subleading $Q^2$3 jets are used, with a combined transverse momentum greater than $Q^2$4 GeV, to reconstruct the Higgs-candidate $Q^2$5 system.

The paper reports several illustrative outputs: reconstructed-level distributions of the $Q^2$6 of muons, electrons, and $Q^2$7 jets; the $Q^2$8 of the $Q^2$9 pair; dilepton invariant-mass distributions peaking around the $Q^2$0 boson mass for the $Q^2$1 and $Q^2$2 channels; and a Higgs mass distribution exhibiting a delta-like peak at parton level and a broadened distribution after reconstruction. A simple $Q^2$3 proxy from neutrinos is shown in the code illustration, and an example veto cut of $Q^2$4 GeV is mentioned, although the summation procedure is not formalized beyond the snippet.

6. Limitations, reproducibility, and relation to other tools

The limitations are defined primarily by omission in the documented schema rather than by an explicit unsupported-feature list. The paper does not state support for <initrwgt> blocks or multiple per-event systematic weights, PDF information such as $Q^2$5, $Q^2$6, or PDF IDs, beam energies or beam IDs at the TTree level, or run and event numbers. Only one eventweight branch is documented. Users needing richer metadata are therefore directed, in effect, to verify availability or extend the program (Desai, 2 Mar 2026).

The treatment of beyond-the-Standard-Model content is similarly narrow in scope. No specific guidance is given for BSM particles beyond general PDG ID handling; mother-daughter and color-flow vectors are preserved as in the LHE. This suggests that the program is structurally agnostic to particle content so long as it is encoded in standard LHE fields, but the paper does not formalize any BSM-specific validation.

The paper cites other LHE readers, including scikit-hep/pylhe, but does not present a detailed comparison. The stated advantage of LHEReader is its simplicity: a direct LHE-to-ROOT conversion with a stable, minimal TTree schema and a ready-to-use ROOT EventLoop example. Reproducibility details include Linux as the target environment, ROOT with PyROOT enabled, Python 3.10 as tested, and the use of MadGraph5, Pythia8, MadAnalysis5, FastJet with anti-$Q^2$7 and $Q^2$8, and PDF4LHC21 via LHAPDF6 in the demonstration chain. The program is also reported as having been released on Zenodo, with initial v1.0 in 2023 and an update to v1.6.1 by 2026, and as having been presented at AIP Congress 2024.

Taken together, these characteristics define LHEReader as a practical bridge from LHE to ROOT centered on essential event- and particle-level information rather than comprehensive preservation of all possible LHE metadata. Where the paper is silent, the appropriate interpretation is that support is not specified and should be verified against the documented output.