API

Contents

API#

Python bindings for the EvtGen particle decay generator.

The package ships a statically linked build of EvtGen together with its default decay table (DECAY_FILE) and particle table (PARTICLE_TABLE).

A Generator, created once with generator = Generator(seed=42), generates decay trees:

>>> event = generator.decay("D*+")
>>> event.name, event.pdg_id
('D*+', 413)
>>> all(not p.daughters for p in event.final_state())
True
class pyevtgen.EvtAbsRadCorr#

Bases: object

Engine for final-state radiation.

class pyevtgen.EvtDecayBase#

Bases: object

Decay model of one decay channel.

getArgStr(self, j: int) → str#
getBranchingFraction(self) → float#
getDaug(self, i: int) → pyevtgen.EvtId#
getModelName(self) → str#
getNArg(self) → int#
getNDaug(self) → int#
getParentId(self) → pyevtgen.EvtId#
class pyevtgen.EvtDecayTable#

Bases: object

Decay tables that EvtGen has read.

getDecay(self, ipar: int, imode: int, tableIndex: int = 0) → pyevtgen.EvtDecayBase#
getInstance = <nanobind.nb_func object>#
getNDecayTables(self) → int#
getNMode(self, ipar: int, tableIndex: int = 0) → int#

Number of decay channels of the particle with alias index ipar.

class pyevtgen.EvtExternalGenList(*args, **kwargs)#

Bases: object

Decay models and FSR engines of external generators.

getListOfModels(self) → list[pyevtgen.EvtDecayBase]#
getVinciaQEDModel(self, infraredCutOff: float = 1e-07) → pyevtgen.EvtAbsRadCorr#
class pyevtgen.EvtGen(*args, **kwargs)#

Bases: object

The EvtGen generator. Only one instance can exist per process.

generateDecay(self, p: pyevtgen.EvtParticle) → None#
readUDecay(self, udecay_name: str, useXml: bool = False) → None#
class pyevtgen.EvtGenKine#

Bases: object

PhaseSpace = <nanobind.nb_func object>#
class pyevtgen.EvtId(*args, **kwargs)#

Bases: object

Identifier of a particle or alias in the EvtGen tables.

getAlias(self) → int#
getId(self) → int#
getName(self) → str#
isAlias(self) → bool#
isConjugate(self, id: pyevtgen.EvtId) → bool#
class pyevtgen.EvtMTRandomEngine(*args, **kwargs)#

Bases: EvtRandomEngine

Mersenne Twister random engine.

class pyevtgen.EvtPDL#

Bases: object

Particle data table, with static methods.

chargeConj = <nanobind.nb_func object>#
chg3 = <nanobind.nb_func object>#
entries = <nanobind.nb_func object>#
evtIdFromStdHep = <nanobind.nb_func object>#
getEntry = <nanobind.nb_func object>#
getId = <nanobind.nb_func object>#
getMass = <nanobind.nb_func object>#
getMaxMass = <nanobind.nb_func object>#
getMeanMass = <nanobind.nb_func object>#
getMinMass = <nanobind.nb_func object>#
getSpinType = <nanobind.nb_func object>#
getStdHep = <nanobind.nb_func object>#
getWidth = <nanobind.nb_func object>#
getctau = <nanobind.nb_func object>#
name = <nanobind.nb_func object>#
reSetMass = <nanobind.nb_func object>#
reSetMassMax = <nanobind.nb_func object>#
reSetMassMin = <nanobind.nb_func object>#
reSetWidth = <nanobind.nb_func object>#
class pyevtgen.EvtParticle#

Bases: object

Particle in an EvtGen decay tree.

Create one with EvtParticleFactory.particleFactory() and release the tree with deleteTree() once it is no longer needed. As in C++, using a particle of a deleted tree is undefined behavior.

deleteTree(self) → None#

Delete this particle and all its descendants.

get4Pos(self) → pyevtgen.EvtVector4R#

Production four-position (ct, x, y, z) in mm in the lab frame.

getChannel(self) → int#
getDaug(self, i: int) → pyevtgen.EvtParticle#
getId(self) → pyevtgen.EvtId#
getLifetime(self) → float#

Sampled proper decay time as c*t in mm.

getNDaug(self) → int#
getName(self) → str#
getP4(self) → pyevtgen.EvtVector4R#

Four-momentum in the rest frame of the parent.

getP4Lab(self) → pyevtgen.EvtVector4R#
getP4LabBeforeFSR(self) → pyevtgen.EvtVector4R#
getP4Restframe(self) → pyevtgen.EvtVector4R#
getPDGId(self) → int#
getParent(self) → pyevtgen.EvtParticle#
getSpinDensityForward(self) → pyevtgen.EvtSpinDensity#
getSpinStates(self) → int#
getSpinType(self) → pyevtgen._core.EvtSpinType.spintype#
isDecayed(self) → bool#
mass(self) → float#
printTree(self) → None#
setDiagonalSpinDensity(self) → None#
setSpinDensityForward(self, rho: pyevtgen.EvtSpinDensity) → None#
setSpinDensityForwardHelicityBasis(self, rho: pyevtgen.EvtSpinDensity) → None#
setVectorSpinDensity(self) → None#
treeStr(self) → str#
class pyevtgen.EvtParticleFactory#

Bases: object

particleFactory = <nanobind.nb_func object>#
class pyevtgen.EvtRandom#

Bases: object

Flat = <nanobind.nb_func object>#
Gaussian = <nanobind.nb_func object>#
setRandomEngine = <nanobind.nb_func object>#
class pyevtgen.EvtRandomEngine#

Bases: object

lastSeed(self) → int#
random(self) → float#
setSeed(self, seed: int) → None#
class pyevtgen.EvtSpinDensity(*args, **kwargs)#

Bases: object

Spin density matrix.

get(self, i: int, j: int) → complex#
getDim(self) → int#
normalizedProb(self, d: pyevtgen.EvtSpinDensity) → float#
set(self, i: int, j: int, rhoij: complex) → None#
setDiag(self, n: int) → None#
setDim(self, n: int) → None#
class pyevtgen.EvtSpinType#

Bases: object

DIRAC = 3#
NEUTRINO = 5#
PHOTON = 4#
RARITASCHWINGER = 7#
SCALAR = 0#
SPIN3 = 8#
SPIN4 = 9#
SPIN5HALF = 10#
SPIN7HALF = 11#
STRING = 6#
TENSOR = 2#
VECTOR = 1#
getSpin2 = <nanobind.nb_func object>#
getSpinStates = <nanobind.nb_func object>#
class spintype(*values)#

Bases: Enum

SCALAR = 0#
VECTOR = 1#
TENSOR = 2#
DIRAC = 3#
PHOTON = 4#
NEUTRINO = 5#
STRING = 6#
RARITASCHWINGER = 7#
SPIN3 = 8#
SPIN4 = 9#
SPIN5HALF = 10#
SPIN7HALF = 11#
class pyevtgen.EvtVector4R(*args, **kwargs)#

Bases: object

Four-vector (E, px, py, pz) in GeV.

applyBoostTo(self, p4: pyevtgen.EvtVector4R, inverse: bool = False) → None#
applyRotateEuler(self, alpha: float, beta: float, gamma: float) → None#
cont(self, v4: pyevtgen.EvtVector4R) → float#

Minkowski scalar product.

d3mag(self) → float#
dot(self, v2: pyevtgen.EvtVector4R) → float#

Scalar product of the spatial components.

get(self, i: int) → float#
mass(self) → float#
mass2(self) → float#
set(self, i: int, d: float) → None#
set(self, e: float, px: float, py: float, pz: float) → None
class pyevtgen.Generator(decay_file: str | os.PathLike | Sequence[str | os.PathLike] = PosixPath('/home/runner/work/pyevtgen-test/pyevtgen-test/.venv/lib/python3.14/site-packages/pyevtgen/data/DECAY.DEC'), particle_table: str | os.PathLike = PosixPath('/home/runner/work/pyevtgen-test/pyevtgen-test/.venv/lib/python3.14/site-packages/pyevtgen/data/evt.pdl'), *, user_decay_file: str | os.PathLike | None = None, fsr: bool = False, seed: int | None = None, mixing_type: int = 1)#

Bases: object

EvtGen decay generator.

This class sets up EvtGen with Pythia8 for the PYTHIA decay model, in the same way as EvtGen’s C++ examples, and copies the generated decay trees into Particle objects. The underlying EvtGen instance is available as evtgen for everything else that EvtGen offers.

EvtGen keeps its particle and decay tables in global state, so only one generator can be created per process.

Parameters:
  • decay_file – Main decay table, or several tables that are read in order.

  • particle_table – Particle property table in EvtGen’s evt.pdl format.

  • user_decay_file – Decay file whose entries override those of the main decay table, for instance to force a single decay channel.

  • fsr – Simulate final-state radiation with Vincia QED from Pythia8 for decay channels that are marked with FSR (or the deprecated PHOTOS) in the decay table.

  • seed – Seed for the Mersenne Twister random engine. A random seed is drawn if not given.

  • mixing_type – Neutral meson mixing treatment, passed on to EvtGen’s EvtCPUtil::setMixingType.

decay(parent: str | int, p4: Sequence[float] | None = None) → Particle#

Generate a single decay tree.

Parameters:
  • parent – EvtGen particle name or PDG ID of the decaying particle.

  • p4 – Four-momentum \((E, p_x, p_y, p_z)\) of the parent in GeV. Defaults to the parent at rest with its nominal mass.

generate(parent: str | int, n: int, p4: Sequence[float] | None = None) → list[Particle]#

Generate n decay trees, see decay().

particles() → list[ParticleProperties]#

Return all entries of the particle table.

properties(particle: str | int) → ParticleProperties#

Look up a particle by EvtGen name or PDG ID.

Raises KeyError if the particle is not in the particle table.

>>> generator.properties(-511)
ParticleProperties(name='anti-B0', pdg_id=-511, mass=5.279640)
read_user_decay_file(path: str | PathLike) → None#

Override entries of the decay table with those of a user decay file.

property seed: int#

Seed with which the random engine was last initialized.

class pyevtgen.Particle(name: str, pdg_id: int, p4: tuple[float, float, float, float], position: tuple[float, float, float, float], lifetime: float, decay_mode: int, daughters: tuple[Particle, ...])#

Bases: object

Copy of a particle in a generated decay tree.

Momenta are in GeV in the lab frame. Positions are in mm, with the time component as \(ct\). Unlike an EvtParticle, a copy stays valid after EvtGen deleted the tree it came from.

final_state() → list[Particle]#

Return the stable particles at the leaves of the decay tree.

classmethod from_evt_particle(particle: EvtParticle) → Particle#

Copy an EvtGen decay tree, see EvtParticle.getP4Lab().

property mass: float#

Invariant mass of p4 in GeV.

name: str#
pdg_id: int#
p4: tuple[float, float, float, float]#
position: tuple[float, float, float, float]#
lifetime: float#
decay_mode: int#
daughters: tuple[Particle, ...]#
class pyevtgen.ParticleProperties(name: str, pdg_id: int, mass: float, width: float, min_mass: float, max_mass: float, ctau: float, charge: float, spin2: int)#

Bases: object

Entry of the EvtGen particle table, see EvtPDL.

classmethod from_evt_id(evt_id: EvtId) → ParticleProperties#
name: str#
pdg_id: int#
mass: float#
width: float#
min_mass: float#
max_mass: float#
ctau: float#
charge: float#
spin2: int#
pyevtgen.final_state_momenta(events: Iterable[Particle]) → np.ndarray#

Stack the final-state four-momenta of decay trees into one array.

Returns:

Array of shape (n_events, n_final_state, 4) with the four-momenta \((E, p_x, p_y, p_z)\) in GeV.

Raises:

ValueError – If the events do not share the same final state, for instance because they decayed through different channels or radiated photons.

pyevtgen.phase_space(parent_mass: float, masses: Sequence[float], n: int, seed: int | None = None) → np.ndarray#

Generate unweighted \(n\)-body phase space decays with EvtGen.

This calls the EvtGenKine::PhaseSpace routine directly with plain masses, so it needs no Generator, particle table, or decay table. It can be used next to a Generator and with different masses in one process.

The routine uses accept-reject sampling, whose efficiency drops by about a factor of ten per additional daughter. Beyond about nine daughters it becomes impractically slow, and a running call cannot be interrupted.

Parameters:
  • parent_mass – Mass of the decaying state in GeV.

  • masses – Masses of the 2 to 15 daughters in GeV.

  • n – Number of events.

  • seed – Seed for the random engine. A random seed is drawn if not given. Each call starts a new sequence, so use different seeds to extend a sample.

Returns:

Four-momenta \((E, p_x, p_y, p_z)\) in GeV in the rest frame of the parent with shape (n, len(masses), 4), with daughters in the order of masses.

>>> import numpy as np
>>> momenta = phase_space(3.097, [0.135, 0.14, 0.14], n=5, seed=0)
>>> momenta.shape
(5, 3, 4)
>>> np.allclose(momenta.sum(axis=1), [3.097, 0, 0, 0])
True
pyevtgen.boostTo(rs: pyevtgen.EvtVector4R, p4: pyevtgen.EvtVector4R, inverse: bool = False) → pyevtgen.EvtVector4R#
pyevtgen.rotateEuler(rs: pyevtgen.EvtVector4R, alpha: float, beta: float, gamma: float) → pyevtgen.EvtVector4R#
pyevtgen.DECAY_FILE: pathlib.Path#

Default EvtGen decay table that is bundled with the package.

pyevtgen.PARTICLE_TABLE: pathlib.Path#

Default EvtGen particle table that is bundled with the package.

pyevtgen.PYTHIA8_XML_DIR: pathlib.Path#

Pythia8 settings and particle data, used by EvtGen’s PYTHIA decay model.

pyevtgen.EVTGEN_VERSION: str#

Release tag of EvtGen that the package is built with.

pyevtgen.HEPMC3_VERSION: str#

Version of HepMC3 that the package is built with.

pyevtgen.PYTHIA8_VERSION: str#

Version of Pythia8 that the package is built with.