Package: eec
EnergyEnergyCorrelatorsThis library can be used to compute various Energy-Energy Correlators (EECs) [1, 2, 3] on collections of particles. The core computations are carried out efficiently in C++ utilizing theBOOST Histogram package(a copy of which is distributed with this library). Note that a C++14-compatible compiler is required by the BOOST Histogram package. The C++ interface is header-only to facilitate easy integration into any existing framework, including theFastJet library. A convenient Python interface is also provided using Cython and multiprocessing.DocumentationThis README is currently the documentation for the EEC library. In the future, this package may be incorporated into other projects, such asEnergyFloworFastJet contrib.The EEC library provides a variety of types of energy-energy correlators that can be computed, utilizing a flexible design sctructure that facilitates adding new computations easily. Each computation is represented by its own C++ class, which derives from the commonEECBaseclass that contains common functionality such as passing in particles and extracting the histogrammed result.Since the value of any EEC on a given event is a distribution, a histogram must be declared in advance that will be filled event-by-event. The computation classes are templated to allow for user specification of axes transformations. The template arguments should be models of theBOOST Histogram Transform concept, such asboost::histogram::axis::transform::id(the identity transform, bins will be linearly spaced) orboost::histgraom::axis::transform::log(to get logarithmically spaced bins).Since version0.1.0, the EEC library can raise the transverse momentum of each vertex of the EEC to an arbitrary power (only an exponent of 1 is infrared and collinear safe). Additionally, charge-dependent EECs can be computed by passing in particle charges and specifying an integer exponent for the charge of each vertex of the EEC.Current EEC computations are described below:EECLongestSide: Computes the N-point EEC distribution binned according to the longest side (largest angle) between the N particles. Supported values of N are 2, 3, 4, and 5 (larger values are simply computationally untenable). Since the resulting distribution is one-dimensional, there is a single template argument (that defaults to the identity) specifying which type of axis should be used. Theconstructortakes four required arguments: the number of bins, axis minimum, axis maximum, and value of N. Additionally, there are futher default arguments which are detailed below.EECLongestSide_idandEECLongestSide_logare provided as typdefs of this class with the axis transform already included.EECTriangleOPE: This is a three-dimensional EEEC that uses coordinates that are particularly suited for studying the OPE limit where two of the three particles are close to collinear. There are three template arguments, corresponding to thexL,xi, andphiaxes, respectively. Theconstructortakes nine arguments: for each axis (in the same order as the template arguments), the number of bins, axis minimum, and axis maximum. Additionally, the sameEECTriangleOPE_id_id_id,EECTriangleOPE_log_id_id,EECTriangleOPE_id_log_id, andEECTriangleOPE_log_log_idare provided as typedefs of this class with the axes transforms already specified.Common arguments to each EEC class are the following:bool norm: whether or not to divide the transverse momenta by their sum prior to computing the EEC.vector<double> pt_powers: exponent for the pT on each vertex of the EEC. Length must match the number of particles being correlated, or else be length 1 in which case the same power is used for all vertices.vector<unsigned int> ch_powers: similar topt_powersexcept that these are the exponents of the charges for each vertex. If any of these are non-zero, then particle charges are expected to be provided.bool check_degen: do no EEC computation but check if any particle distances are degenerate will each other in a given event.bool average_verts: do not separate the computation based on the asymmetry of the vertices, but instead average over all combinations (see below).Ifpt_powersandch_powerscreate distinguished vertices, then more than one histogram will be employed to calculate the EEC for each possibility (theaverage_vertsoption turns off this behavior). Currently, this is only relevant for N=3 computations: N=2 is automatically symmetric and N=4 and N=5 require symmetric vertices. Thedescriptionmethod of the class contains information about the different histograms created.The resulting histogram and corresponding errors can be accessed with theget_histmethod, which accepts a boolean for whether or not to include the overflow bins and an index which defaults to 0 for which histogram to select (see above for how there can be multiple histograms per computation) and returns a pair of vectors of doubles, which are the flattened  (C-style) histogram values and uncertainties. There are alsobin_edgesandbin_centersmethods (specific to each computation class) that return the bins, which take an integer to specify an axis (if there is more than one).Additionally, if theEEC_HIST_FORMATTED_OUTPUTmacro is defined prior to the includion ofEEC.hh(note that this requires thatboost/format.hppis available), then the histograms are printable to any output stream using theoutputmethod.C++ Usage (Header-only)The entire library is contained in a single header file,eec/include/EEC.hh. If you plan on using the EEC library with FastJet, ensure thatPseudoJet.hhis included prior to includingEEC.hh. This will expose an overloadedcomputemethod for each EEC computation that accepts a vector ofPseudoJetobjects. Otherwise, there is acomputemethod that takes a vector of doubles, which must be size3NwhereNis the number of particles, arranged aspT1, rap1, phi1, pT2, rap2, phi2, ..., pTN, rapN, phiN.Python UsageThe EEC library also contains a Cython-based wrapper of the core C++ code. This is most easily used by installing viapip, e.g.pip install eec. NumPy is the only required package. Note that a C++14-enabled compiler must be available for the compilation from source to succeed.There is one Python class for each EEC computation. The templated arguments are dealt with by specifying the axis transforms as a tuple of strings. Currently, only'id'and'log'are supported, in the combinations for which there is a provided C++ typedef (see above). The arguments to the classes are straightforward, and can be examined more closely incore.pyx. There is also aneecmethod that can be used to parallelize computations on many events in Python.References[1] H. Chen, M. Luo,  I. Moult, T. Yang, X. Zhang, H. X. Zhu,Three Point Energy Correlators in the Collinear Limit: Symmetries, Dualities and Analytic Results, [1912.11050].[2] H. Chen, I. Moult, X. Zhang, H. X. Zhu,Rethinking Jets with Energy Correlators: Tracks, Resummation and Analytic Continuation, [2004.11381].[3] L. Dixon, P. T. Komiske, I. Moult, J. Thaler, H. X. Zhu,Analyzing N-Point Energy Correlators with CMS Open Data, to appear soon.