pdg.particle module

Definition of top-level particle container class.

class pdg.particle.PdgItem(api: PdgApi, pdgitem_id: int, edition: str | None = None)

Bases: object

A class to represent an “item” encountered in e.g. a description of a decay’s products.

An item can correspond directly to one particle, indirectly to one particle (as an alias), to a set of particles (as a generic name), or to an arbitrary string. When possible, a PdgItem can be queried (via the particle and particles properties) for the associated particle(s).

Note

The constructor is intended for internal API use.

Parameters:

• api – API object for retrieving data.

• pdgitem_id – Primary key of the item in the SQLite file.

• edition – If set, specifies the edition of the RPP

property canonical_name: str

The canonical name of the unique particle referred to by this PdgItem.

If this item refers to more than one particle, then this is simply equal to the name property.

property has_particle: bool

Whether the PdgItem is associated with exactly one particle.

The property has_particles indicates whether it is associated with one or more particles, rather than exactly one.

property has_particles: bool

Whether the PdgItem is associated with at least one particle.

The property has_particle indicates whether it is associated with exactly one particle.

property item_type: str

The type of the PdgItem.

A single character with the following meanings:

Type	Meaning
P	Specific state (e.g. “pi+”)
A	“Also” alias
W	“Was” alias
S	Shortcut
B	Both charges (e.g. “pi+-“)
C	Both charges, conjugate (e.g. “pi-+”)
G	Generic state (e.g. “pi”)
L	General list (e.g. “leptons”)
I	Inclusive indicator (e.g. “X”)
T	Arbitrary text

property name: str

The name of the PdgItem.

property particle: PdgParticle

The particle associated with the PdgItem, if there is exactly one.

Raises:

PdgAmbiguousValueError – If there is more than one associated particle, in which case the particles property can be used instead.

property particles: list[PdgParticle]

The list of all particles associated with the PdgItem.

The property particles can be used when one expects exactly one associated particle.

class pdg.particle.PdgParticle(api: PdgApi, pdgid: str, edition: str | None = None, set_mcid: int | None = None, set_name: str | None = None)

Bases: PdgData

Container class for all information about a given particle.

In addition to access to basic particle properties such as mass, charge, quantum numbers and MC ID, this class provides methods to iterate over the data on all particle properties listed in Particle Listings and Summary Tables, including branching fractions, masses, life-times, etc.

Parameters:

• api – PDG API object to be used for retrieving data.

• pdgid – PDG Identifier for this particle (or multiplet, etc.).

• edition – Can be set to a specific edition, from which the data should later be retrieved.

• set_mcid – Can be set to a MC ID to select e.g. a particular charge state from a multiplet.

• set_name – Can be set to a particle name, similarly to set_mcid.

property antiparticle: PdgParticle

This particle’s antiparticle (or itself, if self-conjugate)

best(properties: Iterator[PdgProperty], quantity: str | None = None) → PdgProperty

Return the “best” property from an iterable of properties.

A series of heuristics are used to filter the set of candidates. The API’s pedantic setting determines the degree of ambiguity tolerated.

Parameters:

• properties – Iterator over PdgProperty objects to choose from.

• quantity – Optional string that describes what was being sought in case of error.

Returns:

“Best” property. If, after filtering, multiple candidates remain, then (unless the API is in pedantic mode) the returned property is the one that appears first according to the sort column in the SQLite file.

Raises:

• PdgNoDataError – If no property qualifies.

• PdgAmbiguousValueError – If the API is in pedantic mode and multiple candidates remain after filtering.

branching_fractions(data_type_key: str = 'BF%', require_summary_data: bool = True) → Iterator[PdgBranchingFraction]

Get iterator over given type(s) of branching fraction data.

Parameters:

• data_type_key – Can be set to e.g. ‘BFX2’ to select only those exclusive branching fractions that are two levels deep in the subdecay hierarchy. With a data_type_key of ‘BF%’ (the default), all branching fractions, including subdecay modes, are returned.

• require_summary_data – Can be set False to include branching fractions where the current edition has no summary value(s) in the Particle Listings or Summary Table.

property charge: float

Charge of particle in units of e.

property cp_charge: int

The charge of the nominal “particle” (as opposed to “antiparticle”) for this species.

E.g., for the proton and antiproton, this is 1. Useful for distinguishing e.g. the \(\Sigma_b^+\) (and \(\bar\Sigma_b^-\)) from the \(\Sigma_b^-\) (and \(\bar\Sigma_b^+\)).

exclusive_branching_fractions(include_subdecays: bool = False, require_summary_data: bool = True) → Iterator[PdgBranchingFraction]

Get iterator over exclusive branching fraction data.

Parameters:

• include_subdecays – Can be set to True (default is False) to also include subdecay modes (i.e. modes shown indented in the Summary Tables).

• require_summary_data – Can be set to False to include branching fractions where the current edition has no summary value(s) in the Particle Listings or Summary Table.

property has_lifetime_entry: bool

Whether the particle has at least one defined lifetime.

property has_mass_entry: bool

Whether the particle has at least one defined mass.

property has_width_entry: bool

Whether the particle has at least one defined decay width.

inclusive_branching_fractions(include_subdecays: bool = False, require_summary_data: bool = True) → Iterator[PdgBranchingFraction]

Get iterator over inclusive branching fraction data.

Parameters:

• include_subdecays – Can be set to True (default is False) to also include subdecay modes (i.e. modes shown indented in the Summary Tables).

• require_summary_data – Can be set to False to include branching fractions where the current edition has no summary value(s) in the Particle Listings or Summary Table.

property is_baryon: bool

True if particle is a baryon.

property is_boson: bool

True if particle is a gauge boson.

property is_lepton: bool

True if particle is a lepton.

property is_meson: bool

True if particle is a meson.

property is_quark: bool

True if particle is a quark.

property lifetime: float | None

Lifetime of the particle in seconds.

Returns:

Lifetime, or None if there is no best lifetime property and the API is not in pedantic mode. In non-pedantic mode, if there is no lifetime data, then the decay width will be used, if available. If there is no width data either, then the particle is assumed to be stable and a lifetime of infinity will be returned.

Raises:

PdgNoDataError – If there is no best lifetime and the API is in pedantic mode.

property lifetime_error: float | None

Symmetric error on lifetime of particle in seconds

Returns:

Lifetime error, or None if lifetime error are asymmetric or lifetime is a limit.

Raises:

PdgNoDataError – If there is no best lifetime and the API is in pedantic mode.

lifetime_measurements(require_summary_data: bool = True) → Iterator[PdgMeasurement]

Get iterator over all lifetime measurements for this particle.

lifetimes(require_summary_data: bool = True) → Iterator[PdgLifetime]

Get iterator over lifetime data.

See masses() for further commentary.

Parameters:

require_summary_data – Can be set to False to also include lifetimes where the selected edition of the Review of Particle Physics has no summary value(s) in the Particle Listings or Summary Table.

property mass: float | None

Mass of the particle in GeV.

property mass_error: float | None

Symmetric error on mass of particle in GeV, or None if mass error are asymmetric or mass is a limit.

mass_measurements(require_summary_data: bool = True) → Iterator[PdgMeasurement]

Get iterator over all mass measurements for this particle.

masses(require_summary_data: bool = True) → Iterator[PdgMass]

Get iterator over mass data.

For most particles, there is only a single mass property. However, for some particles (e.g. the top quark) there are different ways to determine the mass, and the user needs to decide which mass value is the most appropriate for their use case.

Parameters:

require_summary_data – Can be set to False to also include masses where the selected edition of the Review of Particle Physics has no summary value(s) in the Particle Listings or Summary Table.

property mcid: int

Monte Carlo ID of particle.

property name: str

Name of particle (ASCII format).

properties(data_type_key: str | None = None, require_summary_data: bool = True, in_summary_table: bool | None = None, omit_branching_ratios: bool = False) → Iterator[PdgData]

Get iterator over specified particle property data.

By default, all properties excluding branching fractions and branching fraction ratios are returned.

Parameters:

• data_type_key – Can be set to select specific properties. Possible keys are given by the list printed by PdgApi.doc_data_type_keys. The SQL wildcard character (‘%’) is allowed, so to select all properties, including branching fractions and ratios, set data_type_key to ‘%’. As another example, to get all mass properties, set data_type_key to ‘M’.

• require_summary_data – Can be set to False to also include properties where the selected edition of the Review of Particle Physics has no summary value(s) in the Particle Listings or Summary Table.

• in_summary_table – Can be set to select properties, where a summary value is (True) or is not (False) included in the Summary Table for the selected edition. Setting in_summary_table to a value other than None implies that require_summary_data is True.

• omit_branching_ratios – Can be set to True to exclude any branching fraction ratio properties that would be selected otherwise.

Returns:

Iterator over particle property data.

property quantum_C: str

Quantum number C (C parity) of particle.

property quantum_G: str

Quantum number G (G parity) of particle.

property quantum_I: str

Quantum number I (isospin) of particle.

property quantum_J: str

Quantum number J (spin) of particle.

property quantum_P: str

Quantum number P (parity) of particle.

property self_conjugate: bool

Whether this particle is self-conjugate.

property width: float | None

Width of the particle in GeV.

property width_error: float | None

Symmetric error on width of particle in GeV, or None if width error are asymmetric or width is a limit.

width_measurements(require_summary_data: bool = True) → Iterator[PdgMeasurement]

Get iterator over all decay width measurements for this particle.

widths(require_summary_data: bool = True) → Iterator[PdgWidth]

Get iterator over width data.

See masses() for further commentary.

Parameters:

require_summary_data – Can be set to False to also include widths where the selected edition of the Review of Particle Physics has no summary value(s) in the Particle Listings or Summary Table.

class pdg.particle.PdgParticleList(api: PdgApi, pdgid: str, edition: str | None = None)

Bases: PdgData, list

A PdgData subclass to represent a list of PdgParticle object.

A PdgParticleList is returned when PdgApi.get is called with the PDG Identifier of a (group of) particles.

Note

The constructor is intended for internal API use.

Parameters:

• api – API object for retrieving data.

• pdgitem_id – Primary key of the item in the SQLite file.

• edition – If set, specifies the edition of the RPP