# pylhe: Python LHE interface
[](https://github.com/scikit-hep/pylhe)
[](https://doi.org/10.5281/zenodo.1217031)
[](https://scikit-hep.org/)
[](https://pypi.org/project/pylhe/)
[](https://github.com/conda-forge/pylhe-feedstock)
[](https://pypi.org/project/pylhe/)
[](https://github.com/scikit-hep/pylhe/actions/workflows/ci.yml?query=branch%3Amain)
[](https://codecov.io/gh/scikit-hep/pylhe?branch=main)
[](https://results.pre-commit.ci/latest/github/scikit-hep/pylhe/main)
[](https://github.com/psf/black)
Small and thin Python interface to read [Les Houches Event (LHE)](https://inspirehep.net/record/725284) files
## Tested Monte Carlo Generators' LHE output
| 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 |
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.
### 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.read_lhe_with_attributes(lhe_file)
print(f"Number of events: {pylhe.read_num_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/write_monte_carlo_example.ipynb) or [filter](examples/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
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: v0.9.2}",
version = {v0.9.2},
doi = {10.5281/zenodo.1217031},
url = {https://github.com/scikit-hep/pylhe},
}
```
## Contributors
We hereby acknowledge the contributors that made this project possible ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
