diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 00000000..b7053c0f --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,24 @@ +name: Draft PDF +on: [push] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + - name: Upload + uses: actions/upload-artifact@v4 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf diff --git a/.gitignore b/.gitignore index 55d458be..036c3001 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,6 @@ docs/source/_autosummary docs/source/examples/*.lhe docs/source/examples/*.lhe.gz docs/source/examples/*.parquet + +paper/paper.pdf +paper/jats diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..f8cf98e0 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,568 @@ +@inproceedings{Boos:2001cv, + author = "Boos, E. and others", + title = "{Generic User Process Interface for Event Generators}", + booktitle = "{2nd Les Houches Workshop on Physics at TeV Colliders}", + eprint = "hep-ph/0109068", + archivePrefix = "arXiv", + reportNumber = "FERMILAB-CONF-01-496-T", + month = "9", + year = "2001" +} + +@article{Buckley:2019xhk, + author = {Buckley, Andy and Ilten, Philip and Konstantinov, Dmitri and L{\"o}nnblad, Leif and Monk, James and Pokorski, Witold and Przedzinski, Tomasz and Verbytskyi, Andrii}, + title = "{The HepMC3 event record library for Monte Carlo event generators}", + eprint = "1912.08005", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "MPP-2019-258, MCNET-19-27, LU-TP 19-58", + doi = "10.1016/j.cpc.2020.107310", + journal = "Comput. Phys. Commun.", + volume = "260", + pages = "107310", + year = "2021" +} + +@article{Alwall:2006yp, + author = "Alwall, J. and others", + title = "{A Standard format for Les Houches event files}", + eprint = "hep-ph/0609017", + archivePrefix = "arXiv", + reportNumber = "FERMILAB-PUB-06-337-T, CERN-LCGAPP-2006-03", + doi = "10.1016/j.cpc.2006.11.010", + journal = "Comput. Phys. Commun.", + volume = "176", + pages = "300--304", + year = "2007" +} + +@article{Brehmer:2019xox, + author = "Brehmer, Johann and Kling, Felix and Espejo, Irina and Cranmer, Kyle", + title = "{MadMiner: Machine learning-based inference for particle physics}", + eprint = "1907.10621", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1007/s41781-020-0035-2", + journal = "Comput. Softw. Big Sci.", + volume = "4", + number = "1", + pages = "3", + year = "2020" +} + +@article{Kofler:2024efb, + author = "Kofler, Annalena and Stimper, Vincent and Mikhasenko, Mikhail and Kagan, Michael and Heinrich, Lukas", + title = "{Flow annealed importance sampling bootstrap meets differentiable particle physics}", + eprint = "2411.16234", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1088/2632-2153/addbc1", + journal = "Mach. Learn. Sci. Tech.", + volume = "6", + number = "2", + pages = "025061", + year = "2025" +} + +@article{Brehmer:2019gmn, + author = "Brehmer, Johann and Dawson, Sally and Homiller, Samuel and Kling, Felix and Plehn, Tilman", + title = "{Benchmarking simplified template cross sections in $WH$ production}", + eprint = "1908.06980", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "YITP-SB-19-22", + doi = "10.1007/JHEP11(2019)034", + journal = "JHEP", + volume = "11", + pages = "034", + year = "2019" +} + +@article{Stylianou:2023tgg, + author = "Stylianou, Panagiotis and Weiglein, Georg", + title = "{Constraints on the trilinear and quartic Higgs couplings from triple Higgs production at the LHC and beyond}", + eprint = "2312.04646", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "DESY-23-203", + doi = "10.1140/epjc/s10052-024-12722-9", + journal = "Eur. Phys. J. C", + volume = "84", + number = "4", + pages = "366", + year = "2024" +} + +@article{Feuerstake:2024uxs, + author = "Feuerstake, Finn and Fuchs, Elina and Robens, Tania and Winterbottom, Daniel", + title = "{Interference effects in resonant di-Higgs production at the LHC in the Higgs singlet extension}", + eprint = "2409.06651", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "RBI-ThPhys-2024-15", + doi = "10.1007/JHEP04(2025)094", + journal = "JHEP", + volume = "04", + pages = "094", + year = "2025" +} + +@article{Beresford:2018pbt, + author = "Beresford, Lydia and Liu, Jesse", + title = "{Search Strategy for Sleptons and Dark Matter Using the LHC as a Photon Collider}", + eprint = "1811.06465", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1103/PhysRevLett.123.141801", + journal = "Phys. Rev. Lett.", + volume = "123", + number = "14", + pages = "141801", + year = "2019" +} + +@article{Anisha:2023xmh, + author = "Anisha and Atkinson, Oliver and Bhardwaj, Akanksha and Englert, Christoph and Naskar, Wrishik and Stylianou, Panagiotis", + title = "{BSM reach of four-top production at the LHC}", + eprint = "2302.08281", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "DESY-23-025", + doi = "10.1103/PhysRevD.108.035001", + journal = "Phys. Rev. D", + volume = "108", + number = "3", + pages = "035001", + year = "2023" +} + +@article{Zhou:2022jgj, + author = "Zhou, Hang and Liu, Ning", + title = "{Probing compressed higgsinos with forward protons at the LHC}", + eprint = "2208.10406", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1007/JHEP10(2022)092", + journal = "JHEP", + volume = "10", + pages = "092", + year = "2022" +} + +@article{Zhou:2024fjf, + author = "Zhou, Hang and Liu, Ning", + title = "{Search for nearly degenerate higgsinos via photon fusion with the semileptonic channel at the LHC}", + eprint = "2405.11271", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1016/j.nuclphysb.2024.116752", + journal = "Nucl. Phys. B", + volume = "1010", + pages = "116752", + year = "2025" +} + +@article{Kling:2022ykt, + author = "Kling, Felix and Kuo, Jui-Lin and Trojanowski, Sebastian and Tsai, Yu-Dai", + title = "{FLArE up dark sectors with EM form factors at the LHC forward physics facility}", + eprint = "2205.09137", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "DESY-22-084, UCI-HEP-TR-2022-06, FERMILAB-PUB-22-975-V", + doi = "10.1016/j.nuclphysb.2023.116103", + journal = "Nucl. Phys. B", + volume = "987", + pages = "116103", + year = "2023" +} + +@article{Kelly:2021mcd, + author = "Kelly, Kevin J. and Kling, Felix and Tuckler, Douglas and Zhang, Yue", + title = "{Probing neutrino-portal dark matter at the Forward Physics Facility}", + eprint = "2111.05868", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "FERMILAB-PUB-21-588-T, CERN-TH-2021-186, DESY 21-188", + doi = "10.1103/PhysRevD.105.075026", + journal = "Phys. Rev. D", + volume = "105", + number = "7", + pages = "075026", + year = "2022" +} + +@article{Kling:2020mch, + author = "Kling, Felix and Trojanowski, Sebastian", + title = "{Looking forward to test the KOTO anomaly with FASER}", + eprint = "2006.10630", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1103/PhysRevD.102.015032", + journal = "Phys. Rev. D", + volume = "102", + number = "1", + pages = "015032", + year = "2020" +} + +@article{Cheung:2024oxh, + author = "Cheung, Kingman and Kim, Yongkyu and Kwon, Youngjoon and Ouseph, C. J. and Soffer, Abner and Wang, Zeren Simon", + title = "{Probing dark photons from a light scalar at Belle II}", + eprint = "2401.03168", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1007/JHEP05(2024)094", + journal = "JHEP", + volume = "05", + pages = "094", + year = "2024" +} + +@article{Kling:2020iar, + author = "Kling, Felix", + title = "{Probing light gauge bosons in tau neutrino experiments}", + eprint = "2005.03594", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1103/PhysRevD.102.015007", + journal = "Phys. Rev. D", + volume = "102", + number = "1", + pages = "015007", + year = "2020" +} + +@article{Beresford:2024dsc, + author = "Beresford, Lydia and Clawson, Savannah and Liu, Jesse", + title = "{Strategy to measure tau g-2 via photon fusion in LHC proton collisions}", + eprint = "2403.06336", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + doi = "10.1103/PhysRevD.110.092016", + journal = "Phys. Rev. D", + volume = "110", + number = "9", + pages = "092016", + year = "2024" +} + +@article{Alwall:2014hca, + author = "Alwall, J. and Frederix, R. and Frixione, S. and Hirschi, V. and Maltoni, F. and Mattelaer, O. and Shao, H. -S. and Stelzer, T. and Torrielli, P. and Zaro, M.", + title = "{The automated computation of tree-level and next-to-leading order differential cross sections, and their matching to parton shower simulations}", + eprint = "1405.0301", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "CERN-PH-TH-2014-064, CP3-14-18, LPN14-066, MCNET-14-09, ZU-TH-14-14", + doi = "10.1007/JHEP07(2014)079", + journal = "JHEP", + volume = "07", + pages = "079", + year = "2014" +} + + +@article{Nason:2004rx, + author = "Nason, Paolo", + title = "{A New method for combining NLO QCD with shower Monte Carlo algorithms}", + eprint = "hep-ph/0409146", + archivePrefix = "arXiv", + reportNumber = "BICOCCA-FT-04-11", + doi = "10.1088/1126-6708/2004/11/040", + journal = "JHEP", + volume = "11", + pages = "040", + year = "2004" +} + +@article{Frixione:2007vw, + author = "Frixione, Stefano and Nason, Paolo and Oleari, Carlo", + title = "{Matching NLO QCD computations with Parton Shower simulations: the POWHEG method}", + eprint = "0709.2092", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "BICOCCA-FT-07-9, GEF-TH-21-2007", + doi = "10.1088/1126-6708/2007/11/070", + journal = "JHEP", + volume = "11", + pages = "070", + year = "2007" +} + +@article{Alioli:2010xd, + author = "Alioli, Simone and Nason, Paolo and Oleari, Carlo and Re, Emanuele", + title = "{A general framework for implementing NLO calculations in shower Monte Carlo programs: the POWHEG BOX}", + eprint = "1002.2581", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "DESY-10-018, SFB-CPP-10-22, IPPP-10-11, DCPT-10-22", + doi = "10.1007/JHEP06(2010)043", + journal = "JHEP", + volume = "06", + pages = "043", + year = "2010" +} + +@article{Gleisberg:2008ta, + author = "Gleisberg, T. and Hoeche, Stefan. and Krauss, F. and Schonherr, M. and Schumann, S. and Siegert, F. and Winter, J.", + title = "{Event generation with SHERPA 1.1}", + eprint = "0811.4622", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "FERMILAB-PUB-08-477-T, SLAC-PUB-13420, ZU-TH-17-08, DCPT-08-138, IPPP-08-69, EDINBURGH-2008-30, MCNET-08-14", + doi = "10.1088/1126-6708/2009/02/007", + journal = "JHEP", + volume = "02", + pages = "007", + year = "2009" +} + +@article{Sherpa:2019gpd, + author = "Bothmann, Enrico and others", + collaboration = "Sherpa", + title = "{Event Generation with Sherpa 2.2}", + eprint = "1905.09127", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "FERMILAB-PUB-19-218-T, SLAC-PUB-17433, IPPP/19/42, MCNET-19-11", + doi = "10.21468/SciPostPhys.7.3.034", + journal = "SciPost Phys.", + volume = "7", + number = "3", + pages = "034", + year = "2019" +} + +@article{Corcella:2000bw, + author = "Corcella, G. and Knowles, I. G. and Marchesini, G. and Moretti, S. and Odagiri, K. and Richardson, P. and Seymour, M. H. and Webber, B. R.", + title = "{HERWIG 6: An Event generator for hadron emission reactions with interfering gluons (including supersymmetric processes)}", + eprint = "hep-ph/0011363", + archivePrefix = "arXiv", + reportNumber = "CAVENDISH-HEP-99-03, CERN-TH-2000-284, RAL-TR-2000-048", + doi = "10.1088/1126-6708/2001/01/010", + journal = "JHEP", + volume = "01", + pages = "010", + year = "2001" +} + +@article{Bahr:2008pv, + author = "Bahr, M. and others", + title = "{Herwig++ Physics and Manual}", + eprint = "0803.0883", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "CERN-PH-TH-2008-038, CAVENDISH-HEP-08-03, KA-TP-05-2008, DCPT-08-22, IPPP-08-11, CP3-08-05", + doi = "10.1140/epjc/s10052-008-0798-9", + journal = "Eur. Phys. J. C", + volume = "58", + pages = "639--707", + year = "2008" +} + +@article{Bellm:2015jjp, + author = "Bellm, Johannes and others", + title = "{Herwig 7.0/Herwig++ 3.0 release note}", + eprint = "1512.01178", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "CERN-PH-TH-2015-289, MAN-HEP-2015-15, IFJPAN-IV-2015-13, KA-TP-18-2015, DCPT-15-142, MCNET-15-28, IPPP-15-71, HERWIG-2015-01", + doi = "10.1140/epjc/s10052-016-4018-8", + journal = "Eur. Phys. J. C", + volume = "76", + number = "4", + pages = "196", + year = "2016" +} + +@article{Bellm:2019zci, + author = "Bellm, Johannes and others", + title = "{Herwig 7.2 release note}", + eprint = "1912.06509", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "MAN/HEP/2019/011, CERN-TH-2019-213, IFJPAN-IV-2019-18, HERWIG-2019-02, UWTHPH-19-36, KA-TP-24-2019, LU-TP 19-57, MCnet-19-28, IPPP/19/91", + doi = "10.1140/epjc/s10052-020-8011-x", + journal = "Eur. Phys. J. C", + volume = "80", + number = "5", + pages = "452", + year = "2020" +} + +@article{Bewick:2023tfi, + author = "Bewick, Gavin and others", + title = "{Herwig 7.3 Release Note}", + eprint = "2312.05175", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "CERN-TH-2023-223, HERWIG-2023-01, KA-TP-28-2023, MCnet-23-19, + IPPP/23/66, MCnet-23-19, IPPP/23/66", + month = "12", + year = "2023" +} + +@article{Sjostrand:2006za, + author = "Sjostrand, Torbjorn and Mrenna, Stephen and Skands, Peter Z.", + title = "{PYTHIA 6.4 Physics and Manual}", + eprint = "hep-ph/0603175", + archivePrefix = "arXiv", + reportNumber = "FERMILAB-PUB-06-052-CD-T, LU-TP-06-13", + doi = "10.1088/1126-6708/2006/05/026", + journal = "JHEP", + volume = "05", + pages = "026", + year = "2006" +} + +@article{Sjostrand:2014zea, + author = {Sj\"ostrand, Torbj\"orn and Ask, Stefan and Christiansen, Jesper R. and Corke, Richard and Desai, Nishita and Ilten, Philip and Mrenna, Stephen and Prestel, Stefan and Rasmussen, Christine O. and Skands, Peter Z.}, + title = "{An introduction to PYTHIA 8.2}", + eprint = "1410.3012", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "LU-TP-14-36, MCNET-14-22, CERN-PH-TH-2014-190, FERMILAB-PUB-14-316-CD, DESY-14-178, SLAC-PUB-16122", + doi = "10.1016/j.cpc.2015.01.024", + journal = "Comput. Phys. Commun.", + volume = "191", + pages = "159--177", + year = "2015" +} + + +@article{Sjostrand:2007gs, + author = "Sjostrand, Torbjorn and Mrenna, Stephen and Skands, Peter Z.", + title = "{A Brief Introduction to PYTHIA 8.1}", + eprint = "0710.3820", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "CERN-LCGAPP-2007-04, LU-TP-07-28, FERMILAB-PUB-07-512-CD-T", + doi = "10.1016/j.cpc.2008.01.036", + journal = "Comput. Phys. Commun.", + volume = "178", + pages = "852--867", + year = "2008" +} + +@article{Bierlich:2022pfr, + author = "Bierlich, Christian and others", + title = "{A comprehensive guide to the physics and usage of PYTHIA 8.3}", + eprint = "2203.11601", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "LU-TP 22-16, MCNET-22-04, FERMILAB-PUB-22-227-SCD", + doi = "10.21468/SciPostPhysCodeb.8", + journal = "SciPost Phys. Codeb.", + volume = "2022", + pages = "8", + year = "2022" +} + +@article{Kilian:2007gr, + author = "Kilian, Wolfgang and Ohl, Thorsten and Reuter, Jurgen", + title = "{WHIZARD: Simulating Multi-Particle Processes at LHC and ILC}", + eprint = "0708.4233", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + reportNumber = "DESY-11-126, EDINBURGH-2010-36, FR-PHENO-2010-037, SI-HEP-2010-18", + doi = "10.1140/epjc/s10052-011-1742-y", + journal = "Eur. Phys. J. C", + volume = "71", + pages = "1742", + year = "2011" +} + +@article{Moretti:2001zz, + author = "Moretti, Mauro and Ohl, Thorsten and Reuter, Jurgen", + editor = "Behnke, Ties and Bertolucci, S. and Heuer, Rolf D. and Miller, David and Richard, Francois and Settles, Ron and Telnov, V. and Zerwas, Peter", + title = "{O'Mega: An Optimizing matrix element generator}", + eprint = "hep-ph/0102195", + archivePrefix = "arXiv", + reportNumber = "IKDA-2001-06, LC-TOOL-2001-040", + pages = "1981--2009", + month = "2", + year = "2001" +} + +@inproceedings{Boos:2001cv, + author = "Boos, E. and others", + title = "{Generic User Process Interface for Event Generators}", + booktitle = "{2nd Les Houches Workshop on Physics at TeV Colliders}", + eprint = "hep-ph/0109068", + archivePrefix = "arXiv", + reportNumber = "FERMILAB-CONF-01-496-T", + month = "9", + year = "2001" +} + + + +@article{Dobbs:2001ck, + author = "Dobbs, Matt and Hansen, Jorgen Beck", + title = "{The HepMC C++ Monte Carlo event record for High Energy Physics}", + reportNumber = "ATL-SOFT-2000-001", + doi = "10.1016/S0010-4655(00)00189-2", + journal = "Comput. Phys. Commun.", + volume = "134", + pages = "41--46", + year = "2001" +} + +@article{Verbytskyi:2020sus, + author = {Verbytskyi, Andrii and Buckley, Andy and Grellscheid, David and Konstantinov, Dima and William Monk, James and L\"onnblad, Leif and Przedzinski, Tomasz and Pokorski, Witold}, + title = "{HepMC3 Event Record Library for Monte Carlo Event Generators}", + doi = "10.1088/1742-6596/1525/1/012017", + journal = "J. Phys. Conf. Ser.", + volume = "1525", + number = "1", + pages = "012017", + year = "2020" +} + +@manual{hdf5, + title = {{HDF5} -- Hierarchical Data Format Version 5}, + author = {{The HDF Group}}, + year = 1998, + url = {https://www.hdfgroup.org/HDF5/}, +} + +@inproceedings{Butterworth:2010ym, + author = "Butterworth, J. M. and others", + title = "{THE TOOLS AND MONTE CARLO WORKING GROUP Summary Report from the Les Houches 2009 Workshop on TeV Colliders}", + booktitle = "{6th Les Houches Workshop on Physics at TeV Colliders}", + eprint = "1003.1643", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + month = "3", + year = "2010" +} + +@article{Andersen:2014efa, + author = "Andersen, J. R. and others", + title = "{Les Houches 2013: Physics at TeV Colliders: Standard Model Working Group Report}", + eprint = "1405.1067", + archivePrefix = "arXiv", + primaryClass = "hep-ph", + month = "5", + year = "2014" +} + +@software{Pivarski_Awkward_Array_2018, +author = {Pivarski, Jim and Osborne, Ianna and Ifrim, Ioana and Schreiner, Henry and Hollands, Angus and Biswas, Anish and Das, Pratyush and Roy Choudhury, Santam and Smith, Nicholas and Goyal, Manasvi and Fackeldey, Peter and Krommydas, Iason}, +doi = {10.5281/zenodo.4341376}, +month = oct, +title = {{Awkward Array}}, +year = {2018} +} + +@software{hans_dembinski_2022_7013498, + author = {Hans Dembinski and + Eduardo Rodrigues and + Anatoli Fedynitch}, + title = {scikit-hep/pyhepmc: v2.1.1}, + month = aug, + year = 2022, + publisher = {Zenodo}, + version = {v2.1.1}, + doi = {10.5281/zenodo.7013498}, + url = {https://doi.org/10.5281/zenodo.7013498}, +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..20600507 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,139 @@ +--- +title: "pylhe: A Lightweight Python interface to Les Houches Event files" +tags: + - Python + - physics + - high energy physics +authors: + - name: Alexander Puck Neuwirth^[Corresponding author.] + orcid: 0000-0002-2484-1328 + affiliation: "1, 2" + - name: Matthew Feickert + orcid: 0000-0003-4124-7862 + affiliation: 3 + - name: Lukas Heinrich + orcid: 0000-0002-4048-7584 + affiliation: 4 + - name: Eduardo Rodrigues + orcid: 0000-0003-2846-7625 + affiliation: 5 + +affiliations: + - name: University of Milan Bicocca + index: 1 + - name: INFN Milan Bicocca + index: 2 + - name: University of Wisconsin-Madison + index: 3 + - name: Technical University of Munich + index: 4 + - name: University of Liverpool + index: 5 + +date: 26 November 2025 # APN TODO: update date +bibliography: paper.bib +--- + +# Summary + +Historically, one of the first standards for event representation in high-energy physics were the HEPEVT and HEPRUP common blocks [@Boos:2001cv], which provided a Fortran-based structure for storing event information. +As the complexity of simulations increased, the need for a more flexible and extensible format led to the development of the Les Houches Event (LHE) file format [@Alwall:2006yp]. +LHE introduced an XML structure that allowed for better organization of event data and facilitated interoperability between different Monte Carlo event generators. +Typically, LHE files are used to describe parton-level events generated by matrix element generators before they are passed to parton shower and hadronization programs producing HepMC files [@Dobbs:2001ck;@Verbytskyi:2020sus;@hans_dembinski_2022_7013498]. +In contrast to LHE files HepMC stores fewer details about the particles, but also contain many more particles. +Both files are plain text-based formats, making them human-readable but potentially large. +Hence, compression using gzip is common practice for both formats. +In the future a binary format such as HDF5 [@hdf5] could be considered for event storage to improve read/write performance and reduce file sizes further. + +The LHE format uses an XML-like structure, but the content within the `` and `` blocks consists of whitespace-separated values designed for straightforward parsing in Fortran. +The `
` block can contain arbitrary XML content, usually metadata or comments explaining how the events were generated. +The following skeleton example illustrates the overall structure of an LHE file using the `pylhe` naming of the attributes + +```xml + +
+ +beamA beamB energyA energyB PDFgroupA PDFgroupB PDFsetA PDFsetB weightingStrategy numProcesses +xSection error unitWeight procId +... +# additional hash-commented information can go here + + +nparticles pid weight scale aqed aqcd +id status mother1 mother2 color1 color2 px py pz e m lifetime spin +... +# additional hash-commented information can go here + +... + +``` + +The table below summarizes the main parameters found in LHE files grouped by their `dataclass` representation in `pylhe`. + +| Parameter | Type | Description | Unit | +|-----------|------|-------------|------| +| **LHEInitInfo** | | | | +| beamA | int | PDG ID of first beam particle | - | +| beamB | int | PDG ID of second beam particle | - | +| energyA | float | Energy of first beam particle | GeV | +| energyB | float | Energy of second beam particle | GeV | +| PDFgroupA | int | PDF group ID for first beam | - | +| PDFgroupB | int | PDF group ID for second beam | - | +| PDFsetA | int | PDF set ID for first beam | - | +| PDFsetB | int | PDF set ID for second beam | - | +| weightingStrategy | int | Weighting strategy | - | +| numProcesses | int | Number of processes | - | +| **LHEProcInfo** | | | | +| xSection | float | Cross section | pb | +| error | float | Cross section uncertainty | pb | +| unitWeight | float | Maximum cross section. | pb | +| procId | int | Process ID | - | +| **LHEEventInfo** | | | | +| nparticles | int | Number of particles in event | - | +| pid | int | Process ID for this event | - | +| weight | float | Event weight | - | +| scale | float | Factorization/renormalization scale | GeV | +| aqed | float | QED coupling constant | - | +| aqcd | float | QCD coupling constant | - | +| **LHEParticle** | | | | +| id | int | PDG particle ID | - | +| status | int | Particle status code | - | +| mother1 | int | Index of first mother particle | - | +| mother2 | int | Index of second mother particle | - | +| color1 | int | First color line index | - | +| color2 | int | Second color line index | - | +| px | float | x-component of momentum | GeV | +| py | float | y-component of momentum | GeV | +| pz | float | z-component of momentum | GeV | +| e | float | Energy | GeV | +| m | float | Mass | GeV | +| lifetime | float | Proper lifetime | mm | +| spin | float | Spin information. 9.0 for unpolarized. | - | + +Further details can be found in the original definition of the Les Houches Event file standard. +Besides the original publication there were two extensions to the LHE format, version 2.0 in 2009 [@Butterworth:2010ym] and version 3.0 in 2012 [@Andersen:2014efa]. +However, `pylhe` currently only implements the widely adopted extension from version 1.0, that is the addition of multiple weights via ``, ``, ``,``, ``, and ``. +If in the future there is a demand for ``, ``, ``, or `` support these can be added as well. + +# Statement of need + +The format is used by all major Monte Carlo event generators such as MadGraph [@Alwall:2014hca], POWHEG-BOX [@Nason:2004rx;@Frixione:2007vw;@Alioli:2010xd], Sherpa [@Gleisberg:2008ta;@Sherpa:2019gpd], HERWIG [@Corcella:2000bw;@Bahr:2008pv;@Bellm:2015jjp;@Bellm:2019zci;@Bewick:2023tfi], Pythia [@Sjostrand:2006za;@Sjostrand:2007gs;@Sjostrand:2014zea;@Bierlich:2022pfr], Whizard [@Kilian:2007gr;@Moretti:2001zz]. +They produce hard scattering events in the LHE format which are then passed to parton shower and hadronization programs or directly to analysis frameworks. +While interfaces for C/C++/Fortran exist in the respective generators, a lightweight and easy-to-use Python interface was missing until the inception of `pylhe` in 2015. + +`pylhe` allows for easy reading and writing of `.lhe` and `.lhe.gz` files in Python, enabling seamless integration into modern pythonic data analysis workflows in high-energy physics. +The generator-based approach allows for memory-efficient processing of arbitrarily large LHE files by streaming events one at a time rather than loading entire files into memory. +The library facilitates quick validation of event files through programmatic access to event structure and particle properties, making it straightforward to perform sanity checks on generated events. +This can be done for example via the integration with Awkward Array [@Pivarski_Awkward_Array_2018] through the `to_awkward()` function, which converts LHE events into columnar data structures optimized for vectorized operations and efficient analysis of large datasets. +Additionally, `pylhe` can serve as a crucial interface for emerging machine learning applications in particle physics, allowing researchers to efficiently extract event data for training neural networks and other ML models used in event classification, anomaly detection, and physics analysis. + +## Impact + +`pylhe` has already been used in various research projects and publications within high-energy physics. +It has been cited in Higgs studies [@Brehmer:2019gmn;@Stylianou:2023tgg;@Feuerstake:2024uxs], SUSY / BSM / dark matter searches [@Beresford:2018pbt;@Kling:2020iar;@Anisha:2023xmh;@Zhou:2022jgj;@Zhou:2024fjf;@Cheung:2024oxh;@Beresford:2024dsc], forward physics [@Kling:2022ykt;@Kelly:2021mcd;@Kling:2020mch], but also in methodological studies involving machine learning techniques for event generation and analysis [@Brehmer:2019xox;@Kofler:2024efb]. + +# Acknowledgements + +We would additionally like to thank the contributors of pylhe and the Scikit-HEP community for their support. + +# References diff --git a/pyproject.toml b/pyproject.toml index b3a16395..bd62739d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -165,3 +165,4 @@ ignore = [ # https://github.com/codespell-project/codespell/issues/2801 # Ignore very long base64-like strings ignore-regex = '[A-Za-z0-9+/]{100,}' +skip = "*.bib"