### Particle Tools

Tools to compute particle kinematic quantities from four-vectors, such as transverse momentum $p_T$, rapidity $y$, and azimuthal angle $\phi$, and vice versa.

#### p4s_from_ptyphims

```
energyflow.p4s_from_ptyphims(ptyphims)
```

Calculate Euclidean four-vectors from transverse momentum, rapidity, azimuthal angle, and (optionally) mass for each input.

**Arguments**

**ptyphims**:*numpy.ndarray*or*list*- An array with shape
`(M,4)`

of`[pT,y,phi,m]`

for each particle. An array with shape`(M,3)`

is also accepted where the masses are taken to be zero. A single particle is also accepted.

- An array with shape

**Returns**

*numpy.ndarray*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. If a single particle was given as input, a single four-vector will be returned.

- An event as an

#### p4s_from_ptyphis

```
energyflow.p4s_from_ptyphis(ptyphis)
```

*Legacy function*: Will be removed in version 1.0. Use `p4s_from_ptyphims`

for equivalent functionality.

#### ptyphims_from_p4s

```
energyflow.ptyphims_from_p4s(p4s, phi_ref=None, keep_allzeros=True)
```

Compute the `[pt,y,phi,m]`

representation of a four-vector for each Euclidean
four-vector given as input. All-zero four-vectors are removed unless `keep_shape`

is `True`

.

**Arguments**

**p4s**:*numpy.ndarray*or*list*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. A single particle as a one-dimensional array or list is also accepted.

- An event as an
**phi_ref**:*float*- A reference value used so that all phis will be within $\pm\pi$ of this value.
A value of
`None`

means that no phi fixing will be applied.

- A reference value used so that all phis will be within $\pm\pi$ of this value.
A value of
**keep_allzeros**:*bool*- Flag to determine if all-zero four-vectors will be retained as such. Otherwise, they are removed (resulting in a change in the shape of the output).

**Returns**

*numpy.ndarray*- An array of size
`(M,4)`

consisting of the transverse momentum, rapidity, azimuthal angle, and mass of each particle. If a single particle was given as input, a one-dimensional array is returned.

- An array of size

#### pts_from_p4s

```
energyflow.pts_from_p4s(p4s)
```

Calculate the transverse momenta of a collection of four-vectors

**Arguments**

**p4s**:*numpy.ndarray*or*list*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. A single particle as a one-dimensional array or list is also accepted.

- An event as an

**Returns**

*numpy.ndarray*- An
`M`

-length array consisting of the transverse momentum of each particle. If a single particle was given as input, a single float is returned.

- An

#### ys_from_p4s

```
energyflow.ys_from_p4s(p4s)
```

Calculate the rapidities of a collection of four-vectors

**Arguments**

**p4s**:*numpy.ndarray*or*list*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. A single particle as a one-dimensional array or list is also accepted.

- An event as an

**Returns**

*numpy.ndarray*- An
`M`

-length array consisting of the rapidity of each particle. If a single particle was given as input, a single float is returned.

- An

#### phis_from_p4s

```
energyflow.phis_from_p4s(p4s, phi_ref=None)
```

Calculate the azimuthal angles of a collection of four-vectors. If `phi_ref`

is
not `None`

, then `phi_fix`

is called using this value. Otherwise,
the angles are chosen to be in the inverval $[0,2\pi]$.

**Arguments**

**p4s**:*numpy.ndarray*or*list*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. A single particle as a one-dimensional array or list is also accepted.

- An event as an
**phi_ref**:*float*- See
`phi_fix`

- See

**Returns**

*numpy.ndarray*- An
`M`

-length array consisting of the azimuthal angle of each particle. If a single particle was given as input, a single float is returned.

- An

#### ms_from_p4s

```
energyflow.ms_from_p4s(p4s)
```

Calculate the masses of a collection of four-vectors.

**Arguments**

**p4s**:*numpy.ndarray*or*list*- An event as an
`(M,4)`

array of four-vectors`[E,px,py,pz]`

for each particle. A single particle as a one-dimensional array or list is also accepted.

- An event as an

**Returns**

*numpy.ndarray*- An
`M`

-length array consisting of the mass of each particle. If a single particle was given as input, a single float is returned.

- An

#### phi_fix

```
energyflow.phi_fix(phis, phi_ref, copy=False)
```

A function to ensure that all phi values are within $\pi$ of `phi_ref`

.
It is assumed that all starting phi values are within $2\pi$ of `phi_ref`

.

**Arguments**

**phis**:*numpy.ndarray*or*list*- One-dimensional array of phi values.

**phi_ref**:*float*- A reference value used so that all phis will be within $\pm\pi$ of this value.

**copy**:*bool*- Determines if
`phis`

are copied or not. If`False`

then`phis`

may be modified in place.

- Determines if

**Returns**

*numpy.ndarray*- An array of the fixed phi values.

#### flat_metric

```
energyflow.flat_metric(dim)
```

The Minkowski metric in `dim`

spacetime dimensions in the mostly-minus convention.

**Arguments**

**dim**:*int*- The number of spacetime dimensions (thought to be four in our universe).

**Returns**

*1-d numpy.ndarray*- A
`dim`

-length, one-dimensional (not matrix) array equal to`[+1,-1,...,-1]`

- A

### Random Events

Functions to generate random sets of four-vectors. Includes an implementation of the RAMBO algorithm for sampling uniform M-body massless phase space. Also includes other functions for various random, non-center of momentum, and non-uniform sampling.

#### gen_random_events

```
energyflow.gen_random_events(nevents, nparticles, dim=4, mass=0)
```

Generate random events with a given number of particles of a given mass in a given spacetime dimension. The spatial components of the momenta are distributed uniformly in $[-1,+1]$. These events are not guaranteed to uniformly sample phase space.

**Arguments**

**nevents**:*int*- Number of events to generate.

**nparticles**:*int*- Number of particles in each event.

**dim**:*int*- Number of spacetime dimensions.

**mass**:*float*- Mass of the particles to generate.

**Returns**

*numpy.ndarray*- An
`(nevents,nparticles,dim)`

array of events. The particles are specified as`[E,p1,p2,...]`

.

- An

#### gen_random_events_mcom

```
energyflow.gen_random_events_mcom(nevents, nparticles, dim=4)
```

Generate random events with a given number of massless particles in a given spacetime dimension. The total energy and momentum are made to sum to zero by making about half of the particles incoming. These events are not guaranteed to uniformly sample phase space.

**Arguments**

**nevents**:*int*- Number of events to generate.

**nparticles**:*int*- Number of particles in each event.

**dim**:*int*- Number of spacetime dimensions.

**Returns**

*numpy.ndarray*- An
`(nevents,nparticles,dim)`

array of events. The particles are specified as`[E,p1,p2,...]`

.

- An

#### gen_massless_phase_space

```
energyflow.gen_massless_phase_space(nevents, nparticles, energy=1)
```

Implementation of the RAMBO algorithm for uniformly sampling massless M-body phase space for any center of mass energy.

**Arguments**

**nevents**:*int*- Number of events to generate.

**nparticles**:*int*- Number of particles in each event.

**energy**:*float*- Total center of mass energy of each event.

**Returns**

*numpy.ndarray*- An
`(nevents,nparticles,4)`

array of events. The particles are specified as`[E,p_x,p_y,p_z]`

.

- An

### Data Tools

Functions for dealing with datasets. These are not importable from
the top level `energyflow`

module, but must instead be imported
from `energyflow.utils`

.

#### get_examples

```
energyflow.utils.get_examples(path='~/.energyflow', which='all', overwrite=False)
```

Pulls examples from GitHub. To ensure availability of all examples update EnergyFlow to the latest version.

**Arguments**

**path**:*str*- The destination for the downloaded files.

**which**: {*list*,`'all'`

}- List of examples to download, or the string
`'all'`

in which case all the available examples are downloaded.

- List of examples to download, or the string
**overwrite**:*bool*- Whether to overwrite existing files or not.

#### data_split

```
energyflow.utils.data_split(*args, train=-1, val=0.0, test=0.1, shuffle=True)
```

A function to split a dataset into train, test, and optionally validation datasets.

**Arguments**

***args**: arbitrary*numpy.ndarray*datasets- An arbitrary number of datasets, each required to have the same number of elements, as numpy arrays.

**train**: {*int*,*float*}- If a float, the fraction of elements to include in the training
set. If an integer, the number of elements to include in the
training set. The value
`-1`

is special and means include the remaining part of the dataset in the training dataset after the test and (optionally) val parts have been removed

- If a float, the fraction of elements to include in the training
set. If an integer, the number of elements to include in the
training set. The value
**val**: {*int*,*float*}- If a float, the fraction of elements to include in the validation
set. If an integer, the number of elements to include in the
validation set. The value
`0`

is special and means do not form a validation set.

- If a float, the fraction of elements to include in the validation
set. If an integer, the number of elements to include in the
validation set. The value
**test**: {*int*,*float*}- If a float, the fraction of elements to include in the test set. If an integer, the number of elements to include in the test set.

**shuffle**:*bool*- A flag to control whether the dataset is shuffle prior to being split into parts.

**Returns**

*list*- A list of the split datasets in train, [val], test order. If
datasets
`X`

,`Y`

, and`Z`

were given as`args`

(and assuming a non-zero`val`

), then [`X_train`

,`X_val`

,`X_test`

,`Y_train`

,`Y_val`

,`Y_test`

,`Z_train`

,`Z_val`

,`Z_test`

] will be returned.

- A list of the split datasets in train, [val], test order. If
datasets

#### to_categorical

```
energyflow.utils.to_categorical(labels, num_classes=None)
```

One-hot encodes class labels.

**Arguments**

**labels**:*1-d numpy.ndarray*- Labels in the range
`[0,num_classes)`

.

- Labels in the range
**num_classes**: {*int*,`None`

}- The total number of classes. If
`None`

, taken to be the maximum label plus one.

- The total number of classes. If

**Returns**

*2-d numpy.ndarray*- The one-hot encoded labels.

#### remap_pids

```
energyflow.utils.remap_pids(events, pid_i=3)
```

Remaps PDG id numbers to small floats for use in a neural network.
`events`

are modified in place and nothing is returned.

**Arguments**

**events**:*3-d numpy.ndarray*- The events as an array of arrays of particles.

**pid_i**:*int*- The index corresponding to pid information along the last
axis of
`events`

.

- The index corresponding to pid information along the last
axis of

### Image Tools

Functions for dealing with image representations of events. These are
not importable from the top level `energyflow`

module, but must
instead be imported from `energyflow.utils`

.

#### pixelate

```
energyflow.utils.pixelate(jet, npix=33, img_width=0.8, nb_chan=1, norm=True, charged_counts_only=False)
```

A function for creating a jet image from an array of particles.

**Arguments**

**jet**:*numpy.ndarray*- An array of particles where each particle is of the form
`[pt,y,phi,pid]`

where the particle id column is only used if`nb_chan=2`

and`charged_counts_only=True`

.

- An array of particles where each particle is of the form
**npix**:*int*- The number of pixels on one edge of the jet image, which is taken to be a square.

**img_width**:*float*- The size of one edge of the jet image in the rapidity-azimuth plane.

**nb_chan**: {`1`

,`2`

}- The number of channels in the jet image. If
`1`

, then only a $p_T$ channel is constructed (grayscale). If`2`

, then both a $p_T$ channel and a count channel are formed (color).

- The number of channels in the jet image. If
**norm**:*bool*- Whether to normalize the $p_T$ pixels to sum to
`1`

.

- Whether to normalize the $p_T$ pixels to sum to
**charged_counts_only**:*bool*- If making a count channel, whether to only include charged
particles. Requires that
`pid`

information be given.

- If making a count channel, whether to only include charged
particles. Requires that

**Returns**

*3-d numpy.ndarray*- The jet image as a
`(nb_chan, npix, npix)`

array.

- The jet image as a

#### standardize

```
energyflow.utils.standardize(*args, channels=None, copy=False, reg=10**-10)
```

Normalizes each argument by the standard deviation of the pixels in
arg[0]. The expected use case would be `standardize(X_train, X_val, X_test)`

.

**Arguments**

***args**: arbitrary*numpy.ndarray*datasets- An arbitrary number of datasets, each required to have the same shape in all but the first axis.

**channels**:*int*- A list of which channels (assumed to be the second axis)
to standardize.
`None`

is interpretted to mean every channel.

- A list of which channels (assumed to be the second axis)
to standardize.
**copy**:*bool*- Whether or not to copy the input arrays before modifying them.

**reg**:*float*- Small parameter used to avoid dividing by zero. It's important that this be kept consistent for images used with a given model.

**Returns**

*list*- A list of the now-standardized arguments.

#### zero_center

```
energyflow.utils.zero_center(args, kwargs)
```

Subtracts the mean of arg[0] from the arguments. The expected
use case would be `standardize(X_train, X_val, X_test)`

.

**Arguments**

***args**: arbitrary*numpy.ndarray*datasets- An arbitrary number of datasets, each required to have the same shape in all but the first axis.

**channels**:*int*- A list of which channels (assumed to be the second axis)
to zero center.
`None`

is interpretted to mean every channel.

- A list of which channels (assumed to be the second axis)
to zero center.
**copy**:*bool*- Whether or not to copy the input arrays before modifying them.

**Returns**

*list*- A list of the zero-centered arguments.