Welcome to EnergyFlow

EnergyFlow is a Python package containing a suite of particle physics tools. Originally designed to compute Energy Flow Polynomials (EFPs), as of version 0.10.0 the package expanded to include implementations of Energy Flow Networks (EFNs) and Particle Flow Networks (PFNs). As of version 0.11.0, functions for facilitating the computation of the Energy Mover's Distance (EMD) on particle physics events are included. To summarize the main features:

  • 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.

  • 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.

  • 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.

Beyond the primary functions described above, the EnergyFlow package also provides useful supplementary features. These include a large quark/gluon jet dataset, implementations of additional machine learning architectures useful for collider physics, and many examples exhibiting the usage of the package.

  • Jet Tagging Datasets: A dataset of 2 million simulated quark and gluon jets is provided.

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

  • Detailed Examples: Examples showcasing EFPs, EFNs, PFNs, EMDs, and more. Also see the demos.

The current version is 0.12.1. 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!

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, 1902.02346.

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.