pylhe: A Lightweight Python interface to Les Houches Event files

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

Tested Monte Carlo Generators' LHE output

Generator	Tested Versions
MadGraph5	2.0.0, 2.2.1, 3.5.8
POWHEG-BOX-V2	r4027
Pythia	6.413, 8.3.14
Sherpa	3.0.1
Whizard	3.1.4

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
write_lhe_file(file.init, file.events, "myevents.lhe.gz", rwgt=True, weights=False)

Citation

The preferred BibTeX entry for citation of pylhe is

@software{pylhe,
  author = {Lukas Heinrich and Matthew Feickert and Eduardo Rodrigues and Alexander Puck Neuwirth},
  title = "{pylhe: v1.0.4}",
  version = {v1.0.4},
  doi = {10.5281/zenodo.1217031},
  url = {https://github.com/scikit-hep/pylhe},
}

pylhe has been referenced in:

• 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.