4.6.9. pdg - access particle definitions

This module helps to access particle definitions. When the software is loaded a list of known particles is read from the EvtGen particle definition file framework/particledb/data/evt.pdl. This file contains all well-known standard-model particles and their properties: mass, width or lifetime, charge, spin. …

This module allows to easily access this information (see get) or if necessary add new particles using add_particle and even replace the whole particle definition list using load.

It also provides simple getters to convert PDG codes into particle names and vice versa for use with modules which require a list of PDG codes for the particles to generate. See from_name, from_names, to_name and to_names

pdg.add_particle(name, pdgCode, mass, width, charge, spin, max_width=None, lifetime=0, pythiaID=0)[source]

Add a new particle to the list of known particles.

The name cannot contain any whitespace character.

  • name (str) – name of the particle

  • pdgCode (int) – pdg code identifiert for the particle

  • mass (float) – mass of the particle in GeV

  • width (float) – width of the particle in GeV

  • charge (float) – charge of the particle in e

  • sping (float) – spin of the particle

  • max_width (float) – max width, if omitted 3*width will be used

  • lifetime (float) – lifetime in ns, should be 0 as geant4 cannot handle it correctly otherwise

  • pythiaID (int) – pythiaID of the particle (if any), if omitted 0 will be used


Function to return name of conjugated particle


Function to return pdg code for the given particle name.

>>> pdg.from_name("pi+")

for a list/tuple of particle names, return list of pdg codes.

>>> pdg.from_names(["e+","e-","gamma"])
[-11, 11, 22]

Function to return particle information (TParticlePDG) from ROOT Database.

‘name’ can be either the name of the particle, or a pdg code. Will throw an LookupError of no such particle exists.


Read particle database from given evtgen pdl file


Read default evt.pdl file

pdg.search(name=None, min_mass=None, max_mass=None, name_regex=False, include_width=False)[source]

Search for a particles by name or mass or both.

This function allows to search for particle by name or mass and will return a list of all particles which match the given criteria.

By default all searches for the name are case insensitive but if name starts with “~” the search will be case sensitive. The “~” will not be part of the search.

If name_regex=True the name will be interpreted as a python regular expression and the function will return all particles whose names match the expression. If name_regex=False the function will return a list of all particles containing the given pattern as substring ignoring case with two special cases:

  • if name begins with “^”, only particles beginning with the pattern will be searched. The “^” will not be part of the search.

  • if name ends with “$” the pattern will only be matched to the end of the particle name. The “$” will not be part of the search.

If include_width=True the search will include all particles if their (mass ± width) is within the given limit. If include_width is a positive number then the particle will be returned if \(m ± n*\Gamma\) is within the required range where n is the value of include_width and \(\Gamma\) the width of the particle.


Return a list of all particles

>>> search()

Search for all particles containing a “pi” somewhere in the name and ignore the case

>>> search("pi")

Search for all particles beginning with K or k

>>> search("^K")

Search for all particles ending with “+” and having a maximal mass of 3 GeV:

>>> search("+$", max_mass=3.0)

Search for all particles which contain a capital D and have a minimal mass of 1 GeV

>>> search("~D", min_mass=1.0)

Search for all partiles which contain a set of parenthesis containing a number

>>> search(r".*\(\d*\).*", name_regex=True)

Search all particles whose mass ± width covers 1 to 1.2 GeV

>>> search(min_mass=1.0, max_mass=1.2, include_width=True)

Search all particles whose mass ± 3*width touches 1 GeV

>>> search(min_mass=1.0, max_mass=1.0, include_width=3)
  • name (str) – Search pattern which will either be matched as a substring or as regular expression if name_regex=True

  • min_mass (float) – minimal mass for all returned particles or None for no limit

  • max_mass (float) – maximal mass for all returned particles or None for no limit

  • name_regex (bool) – if True then name will be treated as a regular expression

  • include_width (float or bool) – if True or >0 include the particles if (mass ± include_width*width) falls within the mass limits


Return particle name for given pdg code.

>>> pdg.to_name(321)

for a list/tuple of pdg codes, return list of paricle names.

>>> pdg.to_names([11, -11, -211, 3212])
['e-', 'e+', 'pi-', 'Sigma0']