pylhe: A Lightweight Python interface to Les Houches Event files

Small and thin Python interface to read Les Houches Event (LHE) files

Why pylhe?

A small script can parse the basic particle records in a simple LHE file, but production files contain LHE3 weights and weight groups, scale and generator metadata, optional attributes and comments, compression, and generator-specific variations. pylhe provides event-generator users and analysts with a maintained and tested implementation of these details, exposed through a common typed data model. It supports streaming, writing, conversion between LHE and LHEH5, and integration with Awkward Array.

Tested Monte Carlo Generators' LHE output

LHE XML

LHEH5

Note: test files are provided via the scikit-hep-testdata package. Please open an issue of create directly a PR for the inclusion of new files for testing.

Install

To install pylhe from PyPI you can just do

python -m pip install pylhe

The visualization capabilities require the external dependency of Graphviz.

Get started

The example below provides a simple overview. Full functionality can be inspected from the functions provided in the pylhe module. For more information about the LHE format, see the LHE format documentation.

Reading

import itertools

# You can use LHE files from scikit-hep-testdata
from skhep_testdata import data_path

import pylhe

lhe_file = data_path("pylhe-testlhef3.lhe")
events = pylhe.LHEFile.fromfile(lhe_file).events
print(f"Number of events: {pylhe.LHEFile.count_events(lhe_file)}")

# Get event 1
event = next(itertools.islice(events, 1, 2))

# A DOT language graph of the event can be inspected as follows
print(event.graph.source)

# The graph is nicely displayed as SVG in Jupyter notebooks
event

# To save a DOT graph render the graph to a supported image format
# (refer to the Graphviz documentation for more)
event.graph.render(filename="test", format="png", cleanup=True)
event.graph.render(filename="test", format="pdf", cleanup=True)

Writing

For a full example see write or filter. The values in the sketch below are intentionally left empty since they depend on the use-case. The data structure of pylhe is:

import pylhe

file = pylhe.LHEFile(
    init=pylhe.LHEInit(
        initInfo=pylhe.LHEInitInfo(
            beamA=...,
            beamB=...,
            energyA=...,
            energyB=...,
            PDFgroupA=...,
            PDFgroupB=...,
            PDFsetA=...,
            PDFsetB=...,
            weightinStrategy=...,
            numProcesses=...,
        ),
        procInfo=pylhe.LHEProcInfo(
            xSection=...,
            error=...,
            unitWeight=...,
            procId=...,
        ),
    ),
    events=[
        pylhe.LHEEvent(
            eventinfo=pylhe.LHEEventInfo(
                nparticles=...,
                pid=...,
                weight=...,
                scale=...,
                aqed=...,
                aqcd=...,
            ),
            particles=[
                pylhe.LHEParticle(
                    id=...,
                    status=...,
                    mother1=...,
                    mother2=...,
                    color1=...,
                    color2=...,
                    px=...,
                    py=...,
                    pz=...,
                    e=...,
                    m=...,
                    lifetime=...,
                    spin=...,
                ),
            ],
            weights=None,
            attributes=None,
            optional=None,
        ),
    ],
)

# write to file, compressed if gz/gzip suffix
file.tofile("myevents.lhe.gz", lheformat=pylhe.LHEXMLFormat(compress=True))

Citation

The preferred BibTeX entry for citation of pylhe is both the published paper and the Zenodo archive:

@article{PuckNeuwirth:2026nco,
    author = "Puck Neuwirth, Alexander and Feickert, Matthew and Heinrich, Lukas and Rodrigues, Eduardo",
    title = "{pylhe: A Lightweight Python interface to Les Houches Event files}",
    eprint = "2607.29352",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    month = "7",
    year = "2026"
}
@software{pylhe,
  author = {Lukas Heinrich and Matthew Feickert and Eduardo Rodrigues and Alexander Puck Neuwirth},
  title = "{pylhe: v2.1.0}",
  version = {v2.1.0},
  doi = {10.5281/zenodo.1217031},
  url = {https://github.com/scikit-hep/pylhe},
}

pylhe has been referenced in:

• LHEREADER: simplified conversion from Les Houches event files to ROOT format (2026)
• Prompt diphoton production compared to measurements at 13 TeV in kT-factorization: A comparative analysis of unintegrated PDF models (2025)
• Flow Annealed Importance Sampling Bootstrap meets Differentiable Particle Physics (2024)
• Interference effects in resonant di-Higgs production at the LHC in the Higgs singlet extension (2024)
• Search for nearly degenerate higgsinos via photon fusion with the semileptonic channel at the LHC (2024)
• Strategy to measure tau via photon fusion in LHC proton collisions (2024)
• Probing dark photons from a light scalar at Belle II (2024)
• Constraints on the trilinear and quartic Higgs couplings from triple Higgs production at the LHC and beyond (2023)
• BSM reach of four-top production at the LHC (2023)
• Probing compressed higgsinos with forward protons at the LHC (2023)
• FLArE up dark sectors with EM form factors at the LHC Forward Physics Facility (2022)
• Probing Neutrino-Portal Dark Matter at the Forward Physics Facility (2021)
• Looking forward to test the KOTO anomaly with FASER (2020)
• Probing Light Gauge Bosons in Tau Neutrino Experiments (2020)
• Benchmarking simplified template cross sections in WH production (2019)
• MadMiner: Machine learning-based inference for particle physics (2019)
• Search Strategy for Sleptons and Dark Matter Using the LHC as a Photon Collider (2018)

Contributors

We hereby acknowledge the contributors that made this project possible (emoji key):

Matthew Feickert 🚧 🎨 💻 📖	Lukas 🚧 🎨 💻 📖	Eduardo Rodrigues 🚧 💻 📖	Alexander Puck Neuwirth 🚧 🎨 💻 📖	Johannes Schumann 💻	Henry Schreiner 💻	ariaradick 💻	Junghwan John Goh 💻
fuenfundachtzig 💻	Shantanu Gontia 💻	Tom Eichlersmith 💻	Iason Krommydas 💻 📖

This project follows the all-contributors specification.