Welcome to EnergyFlow

Features

EnergyFlow is a Python package containing a suite of particle physics tools:

  • Energy Flow Polynomials: EFPs are a collection of jet substructure observables which form a complete linear basis of IRC-safe observables. EnergyFlow provides tools to compute EFPs on events for several energy and angular measures as well as custom measures.

  • Energy Flow Networks: EFNs are infrared- and collinear-safe models designed for learning from collider events as unordered, variable-length sets of particles. EnergyFlow contains customizable Keras implementations of EFNs. Available from version 0.10.0 onward.

  • Particle Flow Networks: PFNs are general models designed for learning from collider events as unordered, variable-length sets of particles, based on the Deep Sets framework. EnergyFlow contains customizable Keras implementations of PFNs. Available from version 0.10.0 onward.

  • Energy Mover's Distance: The EMD is a common metric between probability distributions that has been adapted for use as a metric between collider events. EnergyFlow contains code to facilitate the computation of the EMD between events based on an underlying implementation provided by the Python Optimal Transport (POT) library. Available from version 0.11.0 onward.

  • Energy Flow Moments: EFMs are moments built out of particle energies and momenta that can be evaluated in linear time in the number of particles. They provide a highly efficient means of implementing \beta=2 EFPs and are also very useful for reasoning about linear redundancies that appear between EFPs. Available from version 1.0.0 onward.

The EnergyFlow package also provides easy access to particle phyiscs datasets and useful supplementary features:

  • CMS Open Data in MOD HDF5 Format: Reprocessed datasets from the CMS Open Data, currently including jets with p_T>375 GeV and associated detector-level and generator-level Monte Carlo samples. EnergyFlow provides tools for downloading, reading, and manipulating these datasets.

  • Jet Tagging Datasets: Datasets of Pythia 8 and Herwig 7.1 simulated quark and gluon jets are provided, along with tools for downloading and reading them.

  • Additional Architectures: Implementations of other architectures useful for particle physics are also provided, such as convolutional neural networks (CNNs) for jet images.

  • Demos: Jupyter notebook demos that can run in your browser (without any installation) via Binder.

  • Detailed Examples: Examples showcasing EFPs, EFNs, PFNs, EMDs, and more.

The current version is 1.3.3. Changes are summarized in the Release Notes. Using the most up-to-date version is recommended. As of version 0.7.0, tests have been written covering the majority of the EFP and EMD code. The architectures code is currently tested by running the examples. The source code can be found on GitHub.

Get started by installing EnergyFlow, exploring the demos, and running the examples!

Authors

EnergyFlow is developed and maintained by:

References

[1] P. T. Komiske, E. M. Metodiev, and J. Thaler, Energy Flow Polynomials: A complete linear basis for jet substructure, JHEP 04 (2018) 013 [1712.07124].

[2] P. T. Komiske, E. M. Metodiev, and J. Thaler, Energy Flow Networks: Deep Sets for Particle Jets, JHEP 01 (2019) 121 [1810.05165].

[3] P. T. Komiske, E. M. Metodiev, and J. Thaler, The Metric Space of Collider Events, Phys. Rev. Lett. 123 (2019) 041801 [1902.02346].

[4] P. T. Komiske, R. Mastandrea, E. M. Metodiev, P. Naik, and J. Thaler, Exploring the Space of Jets with CMS Open Data, Phys. Rev. D 101 (2020) 034009 [1908.08542].

[5] P. T. Komiske, E. M. Metodiev, and J. Thaler, Cutting Multiparticle Correlators Down to Size, Phys. Rev. D 101 (2020) 036019 [1911.04491].

[6] A. Andreassen, P. T. Komiske, E. M. Metodiev, B. Nachman, and J. Thaler, OmniFold: A Method to Simultaneously Unfold All Observables, Phys. Rev. Lett. 124 (2020) 182001 [1911.09107].

[7] P. T. Komiske, E. M. Metodiev, and J. Thaler, The Hidden Geometry of Particle Collisions, JHEP 07 (2020) 006 [2004.04159].

EnergyFlow is licensed under GPLv3. See the LICENSE for detailed copyright information. EnergyFlow uses a customized einsumfunc.py from the NumPy GitHub repository as well as a few functions relating to downloading files copied from the Keras GitHub repository. The copyrights for these parts of the code are attributed to their respective owners in the LICENSE file.