pdg.data module

Container base classes for PDG data.

All PDG data classes use lazy (i.e. only when needed) loading of data from the database as implemented in the PdgData base class. In most cases, the data is read only once and cached for subsequent use.

PdgProperty is a subclass of PdgData and adds the retrieval of summary values, measurement data, etc., that is shared by all classes supporting the retrieval of different kinds of particle physics properties such as branching fractions or particle masses.

class pdg.data.PdgConvertedValue(value: PdgSummaryValue, to_units: str)[source]

Bases: PdgSummaryValue

A PdgSummaryValue subclass for storing summary values after unit conversion.

After being initialized from some other PdgSummaryValue, a PdgConvertedValue can be treated like any PdgSummaryValue. The unit conversion will be reflected in all properties relating to the numerical value, its errors, and its units.

Parameters:

value – A PdgSummaryValue to convert.
to_units – The new units. See convert() for supported units.

class pdg.data.PdgData(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: object

Base class for PDG data containers.

This class implements the lazy data retrieval from the database and is the base class for all PDG data container classes.

When a PdgData object is instantiated, the edition of the Review of Particle Physics from which data will be retrieved is determined by the first edition information found from the following list:

An edition specified as part of the PDG Identifier
An edition specified by parameter edition of the constructor
The default edition specified by the database to which the API is connected

The chosen edition can be queried by calling edition() and changed at any time by calling set_edition().

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.

property cp_charge_flag: int | None[source]

The particular “CP charge” that this data corresponds to.

See PdgParticle.cp_charge documentation for the meaning of the “CP charge”. This flag will be None if the data applies to ALL particles listed under the PDG identifier.

property data_flags: str[source]: Flags augmenting data type information.

property data_type: str[source]: Type of data.

property description: str[source]: Description of data.

property edition: str | None[source]: Year of edition for which data is requested.

get_children(recurse: bool = False) → Iterator[PdgData][source]

Get all properties that descend from this one.

Parameters:: recurse – Whether to scan recursively and return grandchildren, etc.
Returns:: Iterator over descendent properties.

get_parent_pdgid(include_edition: bool = True) → str | None[source]

Return PDG Identifier of this data’s parent.

In most cases, this will be the PDG ID of the particle itself. For those properties, such as neutrino mixing angles, that don’t have a specific parent particle, the parent will be a top-level section (S067 in this case). If this property’s direct parent is a subsection header, it will be skipped, and the PDG Identifier of the top-level section or particle will be returned instead.

Parameters:: include_edition – Whether to include the edition when formatting the PDG Identifier.
Returns:: PDG Identifier of this property’s parent.

get_particle() → PdgParticle[source]

Get PdgParticle for this property’s particle.

Raises:: PdgAmbiguousValueError – If there are multiple matches.
Returns:: The parent particle for this property.

get_particles() → PdgParticleList[source]

Get PdgParticleList for this property’s particle.

Raises:: PdgNoDataError – If the identifier does not have any parent particles.
Returns:: All parent particles for this property.

class pdg.data.PdgLifetime(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: PdgProperty

A PdgProperty subclass representing a particle’s lifetime.

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.

class pdg.data.PdgMass(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: PdgProperty

A PdgProperty subclass representing a particle’s mass.

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.

class pdg.data.PdgProperty(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: PdgData

Base class for containers for data containers for particle properties.

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.

best_summary(summary_table_only: bool = False) → PdgSummaryValue | None[source]

Get the PDG “best” summary value for this quantity.

If there is either a single summary value in Particle Listings and Summary Tables, or there are multiple summary values but only one is included in the Summary Tables, then this value is returned as the PDG best value.

If there are multiple summary values (e.g. based on assuming or not assuming CPT in the evaluation) and the API is not in pedantic mode, the first value shown in Summary Tables or Particle Listings will be returned. In pedantic mode, a PdgAmbiguousValueError exception will be raised.

If there are no summary values, None is returned.

Parameters:: summary_table_only – If True, then the best value must be included in the Summary Table and cannot be shown only in the Particle Listings.
Returns:: “Best” summary value, or None (see above).
Raises:: PdgAmbiguousValueError – If the API is in pedantic mode and there are multiple relevant summary values.

property comment: str[source]: Shortcut for best_summary().comment.

property confidence_level: float | None[source]: Shortcut for best_summary().confidence_level.

property display_value_text: str[source]: Shortcut for best_summary().display_value_text.

property error: float | None[source]: Shortcut for best_summary().error.

property error_negative: float[source]: Shortcut for best_summary().error.

property error_positive: float[source]: Shortcut for best_summary().error.

get_measurements() → Iterator[PdgMeasurement][source]: Get all of the measurements associated with this property.

has_best_summary(summary_table_only: bool = False) → bool[source]

Query whether there is a single PDG “best” value for this property.

See documentation of best_summary() for definition of “best”.

Parameters:: summary_table_only – If True, then the best value must be included in the Summary Table and cannot be shown only in the Particle Listings.
Returns:: True if there is exactly one “best” value.

property is_limit: bool[source]: Shortcut for best_summary().is_limit.

n_summary_table_values() → int[source]: Get number of summary values in Summary Table for this quantity.

property num_measurements: int[source]: Get the number of measurements associated with this property.

property scale_factor: float[source]: Shortcut for best_summary().scale_factor.

summary_values(summary_table_only: bool = False) → list[PdgSummaryValue][source]

Get list of summary values for this quantity.

Parameters:: summary_table_only – Whether to get only summary values listed in the Summary Tables. By default, all summary values are included, even if they are only shown in the Particle Listings and not listed in the Summary Tables.
Returns:: List of summary values.

property units: str[source]: Shortcut for best_summary().units.

property value: float[source]: Shortcut for best_summary().value.

property value_text: str[source]: Shortcut for best_summary().value_text.

class pdg.data.PdgSummaryValue[source]

Bases: dict

Container for a single value from the Summary Tables.

property comment: str[source]: Details for or comments on this value.

property confidence_level: float | None[source]: Confidence level for limits, None otherwise.

property description: str[source]: Description of quantity for which value is given

property display_in_percent: bool[source]: True if value is rendered in percent for display in Listings. Implies that display_power_of_ten is -2.

property display_power_of_ten: int[source]: Unit multiplier (as power of ten) as used for display in Listings.

property display_value_text: str[source]: Value and uncertainty in plain text format as displayed in Listings tables. Does not include any power of ten or percent sign. Must be combined with the display_power_of_ten property in order to obtain the numerical value in units given by the property units.

property error: float | None[source]

Symmetric error or None.

The symmetric error is the average of positive and negative errors if they differ by less than 10% of their average. If not, or if the quantity is a limit, the symmetric error is None.

property error_negative: float[source]: Numerical value of negative error in units given by property units.

property error_positive: float[source]: Numerical value of positive error in units given by property units.

get_error(units: str | None = None) → float | None[source]

Get symmetric error in specified units.

Parameters:: units – Can be set to the desired unit (see convert() for supported units). If unspecified, the error is returned without conversion in the default units for this quantity.
Returns:: Symmetric error as average of positive and negative errors if they differ by less than 10% of their average. Otherwise, returns None. Also returns None if the quantity is a limit, or if there is otherwise no positive or negative error in the database, or if the unit conversion is invalid or unsupported.

get_error_negative(units: str | None = None) → float[source]

Get negative error in specified units.

Parameters:: units – Can be set to the desired unit (see convert() for supported units). If unspecified, the negative error is returned without conversion in the default units for this quantity.
Returns:: Negative error, or None if there is no negative error in the database or if the unit conversion is invalid or unsupported.

get_error_positive(units: str | None = None) → float[source]

Get positive error in specified units.

Parameters:: units – Can be set to the desired unit (see convert() for supported units). If unspecified, the positive error is returned without conversion in the default units for this quantity.
Returns:: Positive error, or None if there is no positive error in the database or if the unit conversion is invalid or unsupported.

get_value(units: str | None = None) → float | None[source]

Get value in specified units.

Note

Check properties is_limit(), is_lower_limit() and is_upper_limit() to determine if value is a central value or limit.

Parameters:: units – Can be set to the desired unit (see convert() for supported units). If unspecified, the value is returned without conversion in the default units for this quantity.
Returns:: Value, or None if there is no value in the database or if the unit conversion is invalid or unsupported.

property in_summary_table: bool[source]: True if value is included in Summary Table.

property is_limit: bool[source]: True if value is a limit.

property is_lower_limit: bool[source]: True if value is an lower limit.

property is_upper_limit: bool[source]: True if value is an upper limit.

property pdgid: str[source]: PDG Identifier of quantity for which value is given.

pprint() → None[source]: Print all data in this PdgSummaryValue object in a nice format (for debugging).

property scale_factor: float[source]: PDG error scale factor that was applied to error_positive and error_negative.

property units: str[source]: Units (in plain text format) used by value, error_positive, error_negative, and display_value_text.

property value: float[source]

Numerical value in units given by property units.

Check properties is_limit, is_lower_limit and is_upper_limit to determine if value is a central value or limit.

property value_text: str[source]: Value and uncertainty (in plain text format) in units given by property units, including the power of ten, if applicable (see display_power_of_ten)

property value_type: str[source]: Type of value, given as the PDG indicator string.

property value_type_key: str[source]

Type of value, given by its key.

See PdgApi.doc_value_type_keys for the meaning of the different value type keys.

class pdg.data.PdgText(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: PdgData

A PdgData subclass representing a generic text.

Used e.g. to represent subsection headings.

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.

class pdg.data.PdgWidth(api: PdgApi, pdgid: str, edition: str | None = None)[source]

Bases: PdgProperty

A PdgProperty subclass representing a particle’s decay width.

Note

In most cases, user code should not need to call the constructor directly. Instead, the use of e.g. PdgApi.get is recommended.

Parameters:

api – A PdgApi object to be used for retrieving data.
pdgid – The PDG Identifier for the desired data.
edition – If set, and if the pdgid does not specify the edition, then the data will be looked up in this edition.