Download this notebook here.

Particle database

In PWA, you usually want to search for special resonances, possibly even some not listed in the PDG. The particle database that the expertsystem loads by default is therefore often not sufficient for your analysis. In this notebook, we go through a few ways to add or overwrite the database with your own particle definitions.

Loading the default database

In the usual workflow, you start by calling the StateTransitionManager. Upon construction, the function load_default_particle_list is called, which fills the expertsystem.state.particle.DATABASE instance with particle definitions as defined in particle_list.yml. Here, we call this method directly to illustrate what happens:

from expertsystem.state import particle
from expertsystem.ui import load_default_particle_list

print("Before loading:", len(particle.DATABASE))
load_default_particle_list()
print("After loading:", len(particle.DATABASE))

Before loading: 0
After loading: 69

The functions in the particle module can be used to add or modify particle definitions in the particle database. There are a few ways to add or overwrite particle definitions.

Finding particles

There are also functions to search for particles, either by name or by PID (see ParticleCollection.find):

particle.DATABASE.find(333)

Particle('phi(1020)', 333, QuantumState(spin=1.0, charge=0, isospin=None, strangeness=0, charmness=0, bottomness=0, topness=0, baryon_number=0, electron_lepton_number=0, muon_lepton_number=0, tau_lepton_number=0, parity=Parity(-1), c_parity=None, g_parity=Parity(-1)), 1.019461, 0.004266)

ParticleCollection.find_subset returns a ParticleCollection subset instead of one Particle instance.

subset = particle.DATABASE.find_subset("Delta")
list(subset)

['Delta(1232)++', 'Delta(1232)+', 'Delta(1232)0', 'Delta(1232)-']

Adding custom particle definitions through Python

A quick way to modify or overwrite particles, is through your Python script of notebook. Notice that the instances in the database are Particle instances:

omega = particle.DATABASE["omega(782)"]
omega

Particle('omega(782)', 223, QuantumState(spin=1.0, charge=0, isospin=None, strangeness=0, charmness=0, bottomness=0, topness=0, baryon_number=0, electron_lepton_number=0, muon_lepton_number=0, tau_lepton_number=0, parity=Parity(-1), c_parity=Parity(-1), g_parity=Parity(-1)), 0.78265, 1.491e-06)

The instances in the database are immutable. Therefore, if you want to modify, say, width, you have to create a new Particle instance from the particle you want to modify and add it back to the database.

from expertsystem.data import Particle

new_omega = Particle(
    name=omega.name,
    pid=omega.pid,
    mass=omega.mass,
    width=0.01,
    state=omega.state,
)
particle.DATABASE.add(new_omega)
particle.DATABASE["omega(782)"].width

0.01

When adding additional particles you may need for your research, it is also useful to work with an existing particle as template. Let’s say we want to study \(e^+e^-\) collisions of several energies:

energies_mev = [4180, 4220, 4420, 4600]
template_particle = particle.DATABASE["EpEm (4230 MeV)"]
for counter, energy_mev in enumerate(energies_mev, 1):
    energy_gev = energy_mev / 1e3
    new_particle = Particle(
        name=f"EpEm ({energy_mev} MeV)",
        pid=template_particle.pid,
        mass=energy_gev,
        width=template_particle.width,
        state=template_particle.state,
    )
    particle.DATABASE.add(new_particle)
len(particle.DATABASE)

73

list(particle.DATABASE.find_subset("EpEm"))

['EpEm (4230 MeV)',
 'EpEm (4180 MeV)',
 'EpEm (4220 MeV)',
 'EpEm (4420 MeV)',
 'EpEm (4600 MeV)']

Loading custom definitions from a YAML file

It’s also possible to add particles from a config file, with load_particles. Existing entries remain and if the loaded particle list file contains a particle with the same name, it is overwritten in the database. It’s easiest to work with YAML. Here, we use the provided additional_particles.yml example file:

print("Sigmas before loading:", list(particle.DATABASE.find_subset("Sigma")))
particle.load_particles("additional_particles.yml")
print("Sigmas after loading: ", list(particle.DATABASE.find_subset("Sigma")))

Sigmas before loading: []
Sigmas after loading:  ['Sigma(1385)+', 'Sigma(1660)+', 'Sigma(1750)+']

Writing to XML or YAML

You can also dump the existing particle lists to either YAML or XML. You do this with the expertsystem.io.write function.

from expertsystem import io

io.write(instance=particle.DATABASE, filename="dumped_particle_list.xml")
io.write(instance=particle.DATABASE, filename="dumped_particle_list.yaml")

Note that the function write can dump any ParticleCollection to an output file, also a specific subset.

from expertsystem.data import ParticleCollection

output = ParticleCollection()
output += particle.DATABASE["J/psi"]
output += particle.DATABASE.find(22)  # gamma
output += particle.DATABASE.find_subset("f")
output += particle.DATABASE.find_subset("pi")
io.write(output, "particle_list_selection.yml")
list(output)

['J/psi',
 'gamma',
 'f0(980)',
 'f0(1500)',
 'f2(1270)',
 'f2(1950)',
 'pi0',
 'pi+',
 'pi-']

As a side note, the expertsystem provides JSON schemas (e.g. yaml/particle-list.json) to validate your particle list files (see also jsonschema.validate):

import yaml
from expertsystem import io

with open("dumped_particle_list.yaml") as stream:
    definition = yaml.load(stream, Loader=yaml.SafeLoader)
io.yaml.validation.particle_list(definition)

In addition, if you have installed the expertsystem in Development mode and use VSCode, your YAML particle list are checked automatically in the GUI.