Python API

The PDG Python API provides a high-level tool for programmatically accessing PDG data. For most users, this is the recommended way to access PDG data in machine-readable format. The Python API provides straightforward navigation from particles to their properties and the corresponding information included in the Review of Particle Physics. After the initial installation, the Python API does not require an Internet connection.

The Python API is implemented in Python package pdg and uses a PDG database file as it’s default data repository. The database file corresponding to the current edition of the Review of Particle Physics at the time of releasing a given version of the package is installed together with the package. When the Review of Particle Physics is updated, a new version of the pdg package with the latest data is released.

To access the data from other editions, additional database files can be downloaded from the PDG website and used with the Python API. Since SQLAlchemy is used for all database access, the necessary database tables could be copied from the SQLite database file into an existing database system (as long as it is supported by SQLAlchemy), and the Python API could then be used with that database system.

The pdg package is released as open source software and can be found at github.com/particledatagroup/api.

Requirements

The PDG Python API supports Python 3 and requires SQLAlchemy version 1.4 or greater. For the time being, Python 2.7 is still supported.

Installation

The PDG Python API can be installed like any other Python package. For example, the following command will download and install package pdg and its dependencies:

python -m pip install pdg

Usage

Any use of the PDG Python API starts with importing the package and connecting the API to a database file:

import pdg
api = pdg.connect()

As discussed below, connect() takes two optional arguments:

1. The URL of the database to use. The default is to use the SQLite database file installed with the pdg package.

2. Whether the API should operate in pedantic mode or not. Pedantic mode is disabled by default.

Connecting to a different database

To connect e.g. to a SQLite database file pdgall-2023-v0.1.sqlite, which was downloaded from the PDG website into the current directory, one would use

api = pdg.connect('sqlite:///pdgall-2023-v0.1.sqlite')

Pedantic mode

Given the nature of the PDG dataset, there are many special cases and sometimes additional knowledge is needed to determine the correct answer. For example, when asking for the mass of the top quark, in most cases the mass resulting from direct measurements is expected, but sometimes the user may want the mass determined from cross-section measurements. By default, if the user asks for a single value (rather than an iterable over all values), the API will either make an assumption that is expected to be correct in most cases, or simply return the value listed first in the Summary Tables or Particle Listings. If this default behaviour is not desirable, the API can connect in pedantic mode to the database:

api = pdg.connect(pedantic=True)

Then, rather than making assumptions in cases where the answer is ambiguous, a PdgAmbiguousException will be raised. Thus, taking the example above of the top quark mass,

pdg.connect().get_particle_by_name('t').mass

will return a value of about 173 GeV (2022 edition), while

pdg.connect(pedantic=True).get_particle_by_name('t').mass

will raise pdg.errors.PdgAmbiguousValueError: Ambiguous best property for t mass (Q007/2023).

Getting information about the database being used

After connecting to a database, the API object can be printed for a summary of edition, citation, versions and license information. These and more quantities (see api.info_keys()) can be accessed as properties of the API object or by using api.info(key). For example

api.edition

provides the edition (publication year) of the Review of Particle Physics from which the data is taken.

Navigation

Unless the PDG Identifier of the quantity of interest is known, one will generally retrieve the information for the desired particle and then navigate to the properties of interest. Particles can be retrieved by their ASCII name, Monte Carlo particle number, or PDG Identifier. For example, the following three statements each retrieve the data for the Higgs particle:

by_name = api.get_particle_by_name('H')
by_mcid = api.get_particle_by_mcid(25)
by_pdgid = api.get('S126')

In addition, one can iterate over all particles using api.get_particles(), and api.get_all() allows to iterate over all PDG Identifiers, optionally specifying to iterate only over identifiers referring to a particular type of data such as mass. For example, the following complete code snippet will print the list of all PDG Identifiers with their descriptions:

import pdg
api = pdg.connect()
for item in api.get_all():
  print('%-20s  %s' % (item.pdgid, item.description))

Examples

After retrieving the desired particle, one can then either directly get the desired quantity such as particle mass or quantum numbers, or obtain an iterator over the desired information such as all exclusive branching fractions for which PDG has data. A few examples with complete code snippets are given below.

Particle Monte Carlo number, mass and quantum numbers

The following code snippet could be used to print the Monte Carlo particle number, mass (without rounding or errors), and spin of the negative pion:

import pdg
api = pdg.connect()
pi_minus = api.get_particle_by_name('pi-')
print('MC ID  = ', pi_minus.mcid)
print('mass   = ', pi_minus.mass, 'GeV')
print('spin J = ', pi_minus.quantum_J)

Branching fractions

The following code snippet prints all exclusive branching fractions of the charged B meson with their description, ‘True’ if the value denotes a limit, and the raw value (as an unrounded floating point number or None).

import pdg
api = pdg.connect()
for bf in api.get_particle_by_name('B+').exclusive_branching_fractions():
    print('%-60s    %4s    %s' % (bf.description, bf.is_limit, bf.value))

Particle properties (except branching fractions)

The following code snippet prints all properties other than branching fractions of the charged pion (retrieved this time via Monte Carlo number rather than name). For each property, the PDG Identifier, the description, and the rounded value with error is shown.

import pdg
api = pdg.connect()
for p in api.get_particle_by_mcid(211).properties():
    print('%16s:  %-60s    %s' % (p.pdgid, p.description, p.display_value_text))

Detailed software documentation

Detailed information on all public classes, methods and utility functions provided by the PDG Python API is given below, based on the inline code documentation.

pdg package

Python API to access PDG data.

The Python package pdg provides access to the particle physics data published by the Particle Data Group (PDG) in the Review of Particle Physics.

For documentation see https://pdgapi.lbl.gov/doc.

For general information about PDG and the Review of Particle Physics please visit https://pdg.lbl.gov.

pdg.connect(database_url=None, pedantic=False)

Connect to PDG database and return configured PDG API object.

Submodules

• pdg.api module
• pdg.data module
• pdg.decay module
• pdg.errors module
• pdg.particle module
• pdg.units module
• pdg.utils module

License

The data obtained from the PDG REST API is subject to the license used by the corresponding edition of the Review of Particle Physics. Starting with the 2022 edition, and until further notice, PDG uses the CC BY-NC 4.0 license.