# Energy Flow Polynomials

Energy Flow Polynomials (EFPs) are a set of observables, indexed by non-isomorphic multigraphs, which linearly span the space of infrared and collinear (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.

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

Since a standalone EFP defines and holds a `Measure`

instance, all
`Measure`

keywords are accepted.

**Arguments**

**edges**:*list*- Edges of the EFP graph specified by pairs of vertices.

**weights**:*list*of*int*or`None`

- If not
`None`

, the multiplicities of each edge.

- If not
**measure**: {`'hadr'`

,`'hadrdot'`

,`'hadrefm'`

,`'ee'`

,`'eeefm'`

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

- If a number, the energy weighting parameter \kappa. If
**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`

.

- The

### compute

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

Computes the value of the EFP on a single event. Note that `EFP`

also is callable, in which case this method is invoked.

**Arguments**

**event**: 2-d array_like or`fastjet.PseudoJet`

- The event as an array of particles in the coordinates specified
by
`coords`

.

- The event as an array of particles in the coordinates specified
by
**zs**: 1-d array_like- If present,
`thetas`

must also be present, and`zs`

is used in place of the energies of an event.

- If present,
**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.

- If present,
**nhats**: 2-d array like- If present,
`zs`

must also be present, and`nhats`

is used in place of the scaled particle momenta. Only applicable when EFMs are being used.

- If present,

**Returns**

*float*- The EFP value.

### batch_compute

```
batch_compute(events, n_jobs=None)
```

Computes the value of the observable 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`

.

- The events as an array of arrays of particles in coordinates
matching those anticipated by
**n_jobs**:*int*or`None`

- The number of worker processes to use. A value of
`None`

will use as many processes as there are CPUs on the machine.

- The number of worker processes to use. A value of

**Returns**

*1-d numpy.ndarray*- A vector of the observable values for each event.

### properties

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

#### weights

```
weights
```

Edge weights (counts) for the graph of this EFP.

#### weight_set

```
weight_set
```

Set of edge weights (counts) for the graph of this EFP.

#### einstr

```
einstr
```

Einstein summation string for the EFP computation.

#### einpath

```
einpath
```

NumPy einsum path specification for EFP computation.

#### efm_spec

```
efm_spec
```

List of EFM signatures corresponding to efm_einstr.

#### efm_einstr

```
efm_einstr
```

Einstein summation string for the EFM computation.

#### efm_einpath

```
efm_einpath
```

NumPy einsum path specification for EFM computation.

#### efmset

```
efmset
```

Instance of `EFMSet`

help by this EFP if using EFMs.

#### np_optimize

```
np_optimize
```

The np_optimize keyword argument that initialized this EFP instance.

#### n

```
n
```

Number of vertices in the graph of this EFP.

#### e

```
e
```

Number of edges in the simple graph of this EFP.

#### d

```
d
```

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

#### v

```
v
```

Maximum valency of any vertex in the graph.

#### k

```
k
```

Index of this EFP. Determined by EFPSet or -1 otherwise.

#### c

```
c
```

VE complexity \chi of this EFP.

#### p

```
p
```

Number of connected components of this EFP. Note that the empty graph conventionally has one connected component.

#### h

```
h
```

Number of valency 1 vertices ('hanging chads) of this EFP.

#### spec

```
spec
```

Specification array for this EFP.

#### ndk

```
ndk
```

Tuple of `n`

, `d`

, and `k`

values which form a unique identifier of
this EFP within an `EFPSet`

.

## 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=None,
coords=None, check_input=True, verbose=0)
```

`EFPSet`

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

**Graphs**- Pass in graphs as lists of edges, just as for individual EFPs.**Generator**- Pass in a custom`Generator`

object as the first positional argument.**Custom File**- Pass in the name of a`.npz`

file saved with a custom`Generator`

.**Default**- Use the d\le10 EFPs that come installed with the`EnergFlow`

package.

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. Note that no specifications
should be passed in when initializing from explicit graphs.

Since an EFP defines and holds a `Measure`

instance, all `Measure`

keywords are accepted.

**Arguments**

***args**:*arbitrary positional arguments*- Depending on the method of initialization, these can be either
1) graphs to store, as lists of edges 2) a Generator instance
followed by some number of valid arguments to
`sel`

or 3,4) valid arguments to`sel`

. When passing in specific graphs, no arguments to`sel`

should be given.

- Depending on the method of initialization, these can be either
1) graphs to store, as lists of edges 2) a Generator instance
followed by some number of valid arguments to
**filename**:*string*- Path to a
`.npz`

file which has been saved by a valid`energyflow.Generator`

. A value of`None`

will use the provided graphs, if a file is needed at all.

- Path to a
**measure**: {`'hadr'`

,`'hadr-dot'`

,`'ee'`

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

- If a number, the energy weighting parameter \kappa. If
**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**:*int*- Controls printed output when initializing
`EFPSet`

from a file or`Generator`

.

- Controls printed output when initializing

### compute

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

Computes the values of the stored EFPs on a single event. Note that
`EFPSet`

also is callable, in which case this method is invoked.

**Arguments**

**event**: 2-d array_like or`fastjet.PseudoJet`

- The event as an array of particles in the coordinates specified
by
`coords`

.

- The event as an array of particles in the coordinates specified
by
**zs**: 1-d array_like- If present,
`thetas`

must also be present, and`zs`

is used in place of the energies of an event.

- If present,
**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.

- If present,
**nhats**: 2-d array like- If present,
`zs`

must also be present, and`nhats`

is used in place of the scaled particle momenta. Only applicable when EFMs are being used.

- If present,

**Returns**

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

### batch_compute

```
batch_compute(events, n_jobs=None)
```

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`

.

- The events as an array of arrays of particles in coordinates
matching those anticipated by
**n_jobs**:*int*or`None`

- The number of worker processes to use. A value of
`None`

will attempt to use as many processes as there are CPUs on the machine.

- The number of worker processes to use. A value of

**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. Note that
this function has no effect if the `EFPSet`

was initialized with
specific graphs.

**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`

.

- 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

**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).

- 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

**Returns**

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

### csel

```
csel(*args)
```

Same as `sel`

except using `cspecs`

to select from.

### 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`

.

- Valid arguments to be passed to

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

- Valid arguments to be passed to

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

- Valid arguments to be passed to

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

### properties

#### efps

```
efps
```

List of EFPs held by the `EFPSet`

.

#### efmset

```
efmset
```

The `EFMSet`

held by the `EFPSet`

, if using EFMs.

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

#### weight_set

```
weight_set
```

The union of all weights needed by the EFPs stored by the
`EFPSet`

.

#### cols

```
cols
```

Column labels for `specs`

. Each EFP has a property corresponding to
each column.

`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').