pylhe v1.0.2-2-g1245db0 documentation

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.2}",
  version = {v1.0.2},
  doi = {10.5281/zenodo.1217031},
  url = {https://github.com/scikit-hep/pylhe},
}

pylhe has been referenced in:

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} 💻 📖