particletools documentation¶
Introduction¶
The module particletools.tables is a convenience library for translating
particle codes from one particle event-generator into the more general
naming convention of the Particle Data Group PDG.
It also gives you access to different properties of known particles,
such as their mass, charge, life-time and the known decay channels including
the branching ratio.
The database particletools relies on an XML database that is part
of the PYTHIA 8
Monte Carlo event-generator (GPLv2). Its popularity in the high-energy physics
community and continuous maintenance, I hope that this particle database is
well maintained. Of course, neither I, nor the PYTHIA developers, exclude
mistakes, outdated data, etc. It is up to your own responsibility as a researcher
to convince yourself that this piece of code produces output that fulfills your
quality requirements. Feel very encouraged to read
the ‘comments on the data’
by the authors of this XML file.
The largest part of the information contained in this XML is ignored and could be subject for future extensions if needed. This version here is based on the 2006 version of the PDG + things from ‘PYTHIA’.
Caching¶
The instance of table.PYTHIAParticleData parses the XML database
and saves pickles the content to a cache file in your working directory.
Subsequent instatiations of this class will try to load this file instead
of parsing the XML repeatedly. To force parsing the XML file again just
delete the file “ParticleData.ppl”.
Module documentation¶
particletools — collection of classes dealing with particle properties and indices¶
This tool gives convenient Python access to the particle database from the PYTHIA 8 Monte Carlo.
The default particle ID (in all of my codes) follows the Particle Data Group
PDG particle naming convention. Various particle event generators
use, however, proprietary index schemes. The derived classes, such as SibyllParticleTable,
provide conversion routines from these proprietary IDs/names into PDG indices. These can be then
used with the class PYTHIAParticleData to obtain particle properties such as
mass PYTHIAParticleData.mass(), life-time PYTHIAParticleData.ctau(), etc.
- Example:
enter in a Python shell:
$ from particletools.tables import * $ test()
-
class
tables.ParticleDataDict[source]¶ Dict-like class to store ParticleData and provide extended lookup
-
class
tables.PYTHIAParticleData(cache_file=<open file '<fdopen>', mode 'w+b'>, use_cache=True)[source]¶ Class wraps around the original ParticleData.xml from PYTHIA 8.
Operates on in-memory dictionary that is generated by parsing the XML file. Supply the cache_file argument to reduce initialization time.
- Args:
- cache_file (str): path to the cache file use_cache (bool): enable cache, or parse XML file every time
-
pdg_id(str_id)[source]¶ Returns PDG particle ID.
- Args:
- str_id (str): PYTHIA style name of particle
- Returns:
- (int): PDG ID
-
name(pdg_id)[source]¶ Returns PYTHIA particle name.
- Args:
- pdg_id (int): particle PDG ID
- Returns:
- (str): particle name string
-
decay_channels(pid_or_name)[source]¶ Returns decay channels as list of tuples.
Warning, this function reflects only the status in PYTHIA and is not a representation of PDG. Be warned!
- Args:
- pdg_id (int): particle PDG ID
- Returns:
- (list): (BR-ratio,[prod1, prod2, …])
-
mass(pid_or_name)[source]¶ Returns particle mass in GeV. The mass is calculated from the width if not given in the XML table.
- Args:
- pid_or_name: particle PDG ID or string ID
- Returns:
- (float): mass in GeV
-
ctau(pid_or_name)[source]¶ Returns decay length in cm.
- Args:
- pid_or_name: particle PDG ID or string ID
- Returns:
- (float): decay length
in cm
-
charge(pid_or_name)[source]¶ Returns charge.
- Args:
- pid_or_name: particle PDG ID or string ID
- Returns:
- (float): charge
-
class
tables.InteractionModelParticleTable(part_table)[source]¶ This abstract class provides conversions from interaction model specific particle IDs/names to PDG IDs and vice versa.
Interaction model specifics can be added by deriving from this class like it is done in
SibyllParticleTable,QGSJetParticleTableandDpmJetParticleTable.-
list_leptons(use_pdg=False)[source]¶ Returns list of lepton names or PDG IDs.
- Args:
- use_pdg (bool, optional): If True, PDG IDs are return
- otherwise particle names
- Returns:
- list: list of lepton names or PDG IDs
-
-
class
tables.SibyllParticleTable[source]¶ This derived class provides conversions from SIBYLL particle IDs/names to PDG IDs and vice versa.
The table part_table is written by hand from the manual of SIBYLL 2.3.
-
class
tables.UrQMDParticleTable[source]¶ This derived class provides conversions from UrQMD particle IDs+isospins/names to PDG IDs and vice versa.
The table part_table is written by hand from the manual of UrQMD 3.4.
Author: Sonia El Hedri (github:soso128)
-
class
tables.QGSJetParticleTable[source]¶ This derived class provides conversions from QGSJET particle IDs/names to PDG IDs and vice versa.
The table part_table is written by hand based on the source code documentation of QGSJET-II-04. This class also converts indices of earlier versions down to QGSJET01c.
Due to specifics of the interaction with the QGSJet source code, an additional variable is needed for the particle charge
charge_tab.
-
class
tables.DpmJetParticleTable[source]¶ This derived class provides conversions from DPMJET-III particle IDs/names to PDG IDs and vice versa and derives from
SibyllParticleTable.In principle DPMJET uses the PDG indices. However, the PDG table provides information about special or hypothetical particles which are not important, yet. The DPMJET table is therefore derived from a reduced list of particles that are known to SIBYLL.
-
tables.print_stable(min_life_time=1e-10, pdata=None, title=None, **kwargs)[source]¶ Prints a list of particles with a lifetime longer than specified argument value in s.
-
tables.print_decay_channels(pid, pdata=None, **kwargs)[source]¶ Prints branching ratios and decay channels from PYTHIA data.
-
tables.make_stable_list(min_life_time, pdata=None, full_record=False)[source]¶ Returns a list of particles PDG IDs with a lifetime longer than specified argument value in s. Stable particles, such as photons, neutrinos, nucleons and electrons are not included. If full_record is set to true, tuples of PDG IDs and particle data are returned.