Energy Flow Polynomials (EFPs) are a set of observables, indexed by non-isomorphic multigraphs, which linearly span the space of infrared and collinear safe (IRC-safe) observables.

An EFP, indexed by a multigraph $G$, takes the following form: where $z_i$ is a measure of the energy of particle $i$ and $\theta_{ij}$ is a measure of the angular separation between particles $i$ and $j$. The specific choices for "energy" and "angular" measure depend on the collider context and are discussed in the Measures section.


EFP

A class for representing and computing a single EFP. Note that all keyword arguments are stored as properties of the EFP instance.

energyflow.EFP(edges, measure='hadr', beta=1, kappa=1, normed=True, coords=None, check_input=True, np_optimize='greedy')

Arguments

  • edges : list
    • Edges of the EFP graph specified by pairs of vertices.
  • measure : {'hadr', 'hadrdot', 'ee'}
    • The choice of measure. See Measures for additional info.
  • beta : float
    • The parameter $\beta$ appearing in the measure. Must be greater than zero.
  • kappa : {float, 'pf'}
    • If a number, the energy weighting parameter $\kappa$. If 'pf', use $\kappa=v-1$ where $v$ is the valency of the vertex.
  • normed : bool
    • Controls normalization of the energies in the measure.
  • coords : {'ptyphim', 'epxpypz', None}
    • Controls which coordinates are assumed for the input. See Measures for additional info.
  • check_input : bool
    • Whether to check the type of the input each time or assume the first input type.
  • np_optimize : {True, False, 'greedy', 'optimal'}
    • The optimize keyword of numpy.einsum_path.

compute

compute(event=None, zs=None, thetas=None)

Computes the value of the EFP on a single event.

Arguments

  • event : 2-d array_like or fastjet.PseudoJet
    • The event as an array of particles in the coordinates specified by coords.
  • zs : 1-d array_like
    • If present, thetas must also be present, and zs is used in place of the energies of an event.
  • thetas : 2-d array_like
    • If present, zs must also be present, and thetas is used in place of the pairwise angles of an event.

Returns

  • float
    • The EFP value.

batch_compute

batch_compute(events, n_jobs=-1)

Computes the value of the EFP on several events.

Arguments

  • events : array_like or fastjet.PseudoJet
    • The events as an array of arrays of particles in coordinates matching those anticipated by coords.
  • n_jobs : int
    • The number of worker processes to use. A value of -1 will attempt to use as many processes as there are CPUs on the machine.

Returns

  • 1-d numpy.ndarray
    • A vector of the EFP value for each event.
graph
graph

Graph of this EFP represented by a list of edges.

simple_graph
simple_graph

Simple graph of this EFP (forgetting all multiedges) represented by a list of edges.

n
n

Number of vertices in the graph of this EFP.

d
d

Degree, or number of edges, in the graph of this EFP.

c
c

VE complexity $\chi$ of this EFP.

EFPSet

A class that holds a collection of EFPs and computes their values on events. Note that all keyword arguments are stored as properties of the EFPSet instance.

energyflow.EFPSet(*args, filename=None, measure='hadr', beta=1, kappa=1, normed=True, coords='ptyphim', check_input=True, verbose=False)

EFPSet can be initialized in one of three ways (in order of precedence):

  1. Default - Use the ($d\le10$) EFPs that come installed with the EnergFlow package.
  2. Generator - Pass in a custom Generator object as the first positional argument.
  3. Custom File - Pass in the name of a .npz file saved with a custom Generator.

To control which EFPs are included, EFPSet accepts an arbitrary number of specifications (see sel) and only EFPs meeting each specification are included in the set.

Arguments

  • *args : arbitrary positional arguments
    • If the first positional argument is a Generator instance, it is used for initialization. The remaining positional arguments must be valid arguments to sel.
  • filename : string
    • Path to a .npz file which has been saved by a valid energyflow.Generator.
  • measure : {'hadr', 'hadr-dot', 'ee'}
  • beta : float
    • The parameter $\beta$ appearing in the measure. Must be greater than zero.
  • kappa : {float, 'pf'}
    • If a number, the energy weighting parameter $\kappa$. If 'pf', use $\kappa=v-1$ where $v$ is the valency of the vertex.
  • normed : bool
    • Controls normalization of the energies in the measure.
  • coords : {'ptyphim', 'epxpypz', None}
    • Controls which coordinates are assumed for the input. See Measures for additional info.
  • check_input : bool
    • Whether to check the type of the input each time or assume the first input type.
  • verbose : bool
    • Controls printed output when initializing EFPSet.

compute

compute(event=None, zs=None, thetas=None)

Computes the values of the stored EFPs on a single event.

Arguments

  • event : 2-d array_like or fastjet.PseudoJet
    • The event as an array of particles in the coordinates specified by coords.
  • zs : 1-d array_like
    • If present, thetas must also be present, and zs is used in place of the energies of an event.
  • thetas : 2-d array_like
    • If present, zs must also be present, and thetas is used in place of the pairwise angles of an event.

Returns

  • 1-d numpy.ndarray
    • A vector of the EFP values.

batch_compute

batch_compute(events, n_jobs=-1)

Computes the value of the stored EFPs on several events.

Arguments

  • events : array_like or fastjet.PseudoJet
    • The events as an array of arrays of particles in coordinates matching those anticipated by coords.
  • n_jobs : int
    • The number of worker processes to use. A value of -1 will attempt to use as many processes as there are CPUs on the machine.

Returns

  • 2-d numpy.ndarray
    • An array of the EFP values for each event.

calc_disc

calc_disc(X)

Computes disconnected EFPs according to the internal specifications using the connected EFPs provided as input.

Arguments

  • X : numpy.ndarray
    • Array of connected EFPs. Rows are different events, columns are the different EFPs. Can handle a single event (a 1-dim array) as input. EFPs are assumed to be in the order expected by the instance of EFPSet; the safest way to ensure this is to use the same EFPSet to calculate both connected and disconnected EFPs. This function is used internally in compute and batch_compute.

Returns

  • numpy.ndarray
    • A concatenated array of the connected and disconnected EFPs.

sel

sel(*args)

Computes a boolean mask of EFPs matching each of the specifications provided by the args.

Arguments

  • *args : arbitrary positional arguments
    • Each argument can be either a string or a length-two iterable. If the argument is a string, it should consist of three parts: a character which is a valid element of cols, a comparison operator (one of <, >, <=, >=, ==, !=), and a number. Whitespace between the parts does not matter. If the argument is a tuple, the first element should be a string containing a column header character and a comparison operator; the second element is the value to be compared. The tuple version is useful when the value is a variable that changes (such as in a list comprehension).

Returns

  • 1-d numpy.ndarray
    • A boolean array of length the number of EFPs stored by this object.

count

count(*args)

Counts the number of EFPs meeting the specifications of the arguments using sel.

Arguments

  • *args : arbitrary positional arguments
    • Valid arguments to be passed to sel.

Returns

  • int
    • The number of EFPs meeting the specifications provided.

graphs

graphs(*args)

Graphs meeting provided specifications.

Arguments

  • *args : arbitrary positional arguments
    • Valid arguments to be passed to sel, or, if a single integer, the index of a particular graph.

Returns

  • list, if single integer argument is given
    • The list of edges corresponding to the specified graph
  • 1-d numpy.ndarray, otherwise
    • An array of graphs (as lists of edges) matching the specifications.

simple_graphs

simple_graphs(*args)

Simple graphs meeting provided specifications.

Arguments

  • *args : arbitrary positional arguments
    • Valid arguments to be passed to sel, or, if a single integer, the index of particular simple graph.

Returns

  • list, if single integer argument is given
    • The list of edges corresponding to the specified simple graph
  • 1-d numpy.ndarray, otherwise
    • An array of simple graphs (as lists of edges) matching the specifications.
specs
specs

An array of EFP specifications. Each row represents an EFP and the columns represent the quantities indicated by cols.

cspecs
cspecs

Specification array for connected EFPs.

cols
cols

Column labels for specs. Those of primary interest are listed below.

  • n : Number of vertices.
  • e : Number of simple edges.
  • d : Degree, or number of multiedges.
  • v : Maximum valency (number of edges touching a vertex).
  • k : Unique identifier within EFPs of this (n,d).
  • c : VE complexity $\chi$.
  • p : Number of prime factors (or connected components).
  • h : Number of valency 1 vertices (a.k.a. 'hanging chads').