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.

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.

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

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.

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.

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.

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.

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.
  • phi_ref : float
    • See

Returns

  • numpy.ndarray or list
    • 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.

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.

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.

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.

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]

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 energy-momentum vectors have spatial components drawn randomly from [-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, each with nparticles particles with mass given by mass.

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, each with nparticles massless particles whose total energy and momentum are all zero.

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

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, each with nparticles massless particles and center of mass energy equal to energy.

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

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).
  • num_classes : {int, None}
    • The total number of classes. If None, taken to be the maximum label plus one.

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.

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.
  • 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).
  • norm : bool
    • Whether to normalize the $p_T$ pixels to sum to 1.
  • charged_counts_only : bool
    • If making a count channel, whether to only include charged particles. Requires that pid information be given.

Returns

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

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.
  • 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.
  • copy : bool
    • Whether or not to copy the input arrays before modifying them.

Returns

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