pylhe

KO | EN

gitlite — search

#python #hacktoberfest #react #golang #rust #deep-learning #linux #docker #macos #nodejs #java #windows #vue #mcp

(★ 49)

Lightweight Python interface to read and write Les Houches Event (LHE) files

pylhe Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# pylhe: A Lightweight Python interface to Les Houches Event files

[![GitHub Project](https://img.shields.io/badge/GitHub--blue?style=social&logo=GitHub)](https://github.com/scikit-hep/pylhe)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1217031.svg)](https://doi.org/10.5281/zenodo.1217031)
[![Scikit-HEP](https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg)](https://scikit-hep.org/)

[![RTD Docs](https://readthedocs.org/projects/pylhe/badge/?version=latest)](https://pylhe.readthedocs.io/en/latest/?badge=latest)
[![Live Docs](https://img.shields.io/badge/docs-main-blue.svg)](https://scikit-hep.org/pylhe/)

[![PyPI version](https://img.shields.io/pypi/v/pylhe.svg)](https://pypi.org/project/pylhe/)
[![Conda-forge version](https://img.shields.io/conda/vn/conda-forge/pylhe.svg)](https://github.com/conda-forge/pylhe-feedstock)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/pylhe.svg)](https://pypi.org/project/pylhe/)

[![GitHub Actions Status](https://github.com/scikit-hep/pylhe/actions/workflows/ci.yml/badge.svg)](https://github.com/scikit-hep/pylhe/actions/workflows/ci.yml?query=branch%3Amain)
[![Code Coverage](https://codecov.io/gh/scikit-hep/pylhe/branch/main/graph/badge.svg)](https://app.codecov.io/gh/scikit-hep/pylhe/tree/main)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/scikit-hep/pylhe/main.svg)](https://results.pre-commit.ci/latest/github/scikit-hep/pylhe/main)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/scikit-hep/pylhe/main?urlpath=lab/tree/docs/source/examples/00_quickstart.ipynb)

Small and thin Python interface to read [Les Houches Event (LHE)](https://inspirehep.net/literature/725284) files

## Tested Monte Carlo Generators' LHE output

### LHE XML

| Generator                                      | Tested Versions       |
|------------------------------------------------|-----------------------|
| [MadGraph5](https://launchpad.net/mg5amcnlo)   | 2.0.0, 2.2.1, 3.5.8   |
| [POWHEG-BOX-V2](http://powhegbox.mib.infn.it/) | r4027                 |
| [Pythia](https://pythia.org/)                  | 6.413, 8.3.14         |
| [Sherpa](https://sherpa-team.gitlab.io/)       | 3.0.1                 |
| [Whizard](https://whizard.hepforge.org/)       | 3.1.4                 |

### LHEH5

| Generator                                      | Tested Versions       |
|------------------------------------------------|-----------------------|
| [Sherpa](https://sherpa-team.gitlab.io/)       | 2.3.0                 |

Note: test files are provided via the [scikit-hep-testdata](https://github.com/scikit-hep/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](https://graphviz.org/).

## 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](https://pylhe.readthedocs.io/en/latest/lhe.html).

### Reading

```python
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](examples/03_write_monte_carlo_example.ipynb) or [filter](examples/02_filter_events_example.ipynb).
The values in the sketch below are intentionally left empty since they depend on the use-case.
The data structure of `pylhe` is:

```python
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](https://zenodo.org/) archive:

```bibtex
@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.0.0}",
  version = {v2.0.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](https://inspirehep.net/literature/3124696) (2026)
* [Prompt diphoton production compared to measurements at 13 TeV in kT-factorization: A comparative analysis of unintegrated PDF models](https://inspirehep.net/literature/3081675) (2025)
* [Flow Annealed Importance Sampling Bootstrap meets Differentiable Particle Physics](https://inspirehep.net/literature/2851739) (2024)
* [Interference effects in resonant di-Higgs production at the LHC in the Higgs singlet extension](https://inspirehep.net/literature/2826958) (2024)
* [Search for nearly degenerate higgsinos via photon fusion with the semileptonic channel at the LHC](https://inspirehep.net/literature/2788228) (2024)
* [Strategy to measure tau  via photon fusion in LHC proton collisions](https://inspirehep.net/literature/2767190) (2024)
* [Probing dark photons from a light scalar at Belle II](https://inspirehep.net/literature/2744442) (2024)
* [Constraints on the trilinear and quartic Higgs couplings from triple Higgs production at the LHC and beyond](https://inspirehep.net/literature/2734125) (2023)
* [BSM reach of four-top production at the LHC](https://inspirehep.net/literature/2633019) (2023)
* [Probing compressed higgsinos with forward protons at the LHC](https://inspirehep.net/literature/2140007) (2023)
* [FLArE up dark sectors with EM form factors at the LHC Forward Physics Facility](https://inspirehep.net/literature/2085195) (2022)
* [Probing Neutrino-Portal Dark Matter at the Forward Physics Facility](https://inspirehep.net/literature/1966337) (2021)
* [Looking forward to test the KOTO anomaly with FASER](https://inspirehep.net/literature/1801897) (2020)
* [Probing Light Gauge Bosons in Tau Neutrino Experiments](https://inspirehep.net/literature/1794757) (2020)
* [Benchmarking simplified template cross sections in WH production](https://inspirehep.net/literature/1750323) (2019)
* [MadMiner: Machine learning-based inference for particle physics](https://inspirehep.net/literature/1746275) (2019)
* [Search Strategy for Sleptons and Dark Matter Using the LHC as a Photon Collider](https://inspirehep.net/literature/1703804) (2018)

## Contributors

We hereby acknowledge the contributors that made this project possible ([emoji key](https://allcontributors.org/docs/en/emoji-key)):



<table>
 <tbody>
 <tr>
 <td align="center" valign="top" width="14.28%"><a href="http://www.matthewfeickert.com/"><img src="https://avatars.githubusercontent.com/u/5142394?v=4?s=100" width="100px;" alt="Matthew Feickert"/> Matthew Feickert</a> <a href="#maintenance-matthewfeickert" title="Maintenance">🚧</a> <a href="#design-matthewfeickert" title="Design">🎨</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=matthewfeickert" title="Code">💻</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=matthewfeickert" title="Documentation">📖</a></td>
 <td align="center" valign="top" width="14.28%"><a href="http://www.lukasheinrich.com"><img src="https://avatars.githubusercontent.com/u/2318083?v=4?s=100" width="100px;" alt="Lukas"/> Lukas</a> <a href="#maintenance-lukasheinrich" title="Maintenance">🚧</a> <a href="#design-lukasheinrich" title="Design">🎨</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=lukasheinrich" title="Code">💻</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=lukasheinrich" title="Documentation">📖</a></td>
 <td align="center" valign="top" width="14.28%"><a href="http://cern.ch/eduardo.rodrigues"><img src="https://avatars.githubusercontent.com/u/5013581?v=4?s=100" width="100px;" alt="Eduardo Rodrigues"/> Eduardo Rodrigues</a> <a href="#maintenance-eduardo-rodrigues" title="Maintenance">🚧</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=eduardo-rodrigues" title="Code">💻</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=eduardo-rodrigues" title="Documentation">📖</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/APN-Pucky"><img src="https://avatars.githubusercontent.com/u/4533248?v=4?s=100" width="100px;" alt="Alexander Puck Neuwirth"/> Alexander Puck Neuwirth</a> <a href="#maintenance-APN-Pucky" title="Maintenance">🚧</a> <a href="#design-APN-Pucky" title="Design">🎨</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=APN-Pucky" title="Code">💻</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=APN-Pucky" title="Documentation">📖</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/8me"><img src="https://avatars.githubusercontent.com/u/17862090?v=4?s=100" width="100px;" alt="Johannes Schumann"/> Johannes Schumann</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=8me" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="http://iscinumpy.dev"><img src="https://avatars.githubusercontent.com/u/4616906?v=4?s=100" width="100px;" alt="Henry Schreiner"/> Henry Schreiner</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=henryiii" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/ariaradick"><img src="https://avatars.githubusercontent.com/u/53235605?v=4?s=100" width="100px;" alt="ariaradick"/> ariaradick</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=ariaradick" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/jhgoh"><img src="https://avatars.githubusercontent.com/u/4388926?v=4?s=100" width="100px;" alt="Junghwan John Goh"/> Junghwan John Goh</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=jhgoh" title="Code">💻</a></td>
 </tr>
 <tr>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/fuenfundachtzig"><img src="https://avatars.githubusercontent.com/u/8006302?v=4?s=100" width="100px;" alt="fuenfundachtzig"/> fuenfundachtzig</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=fuenfundachtzig" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://shantanu-gontia.github.io"><img src="https://avatars.githubusercontent.com/u/4872525?v=4?s=100" width="100px;" alt="Shantanu Gontia"/> Shantanu Gontia</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=shantanu-gontia" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/tomeichlersmith"><img src="https://avatars.githubusercontent.com/u/31970302?v=4?s=100" width="100px;" alt="Tom Eichlersmith"/> Tom Eichlersmith</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=tomeichlersmith" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/ikrommyd"><img src="https://avatars.githubusercontent.com/u/82155404?v=4?s=100" width="100px;" alt="Iason Krommydas"/> Iason Krommydas</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=ikrommyd" title="Code">💻</a> <a href="https://github.com/scikit-hep/pylhe/commits?author=ikrommyd" title="Documentation">📖</a></td>
 </tr>
 </tbody>
</table>

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.

pylhe

pylhe Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pylhe

pylhe Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README