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.EvtDecayBase#
Bases:
objectDecay model of one decay channel.
- getDaug(self, i: int) pyevtgen.EvtId#
- getParentId(self) pyevtgen.EvtId#
- class pyevtgen.EvtDecayTable#
Bases:
objectDecay tables that EvtGen has read.
- getDecay(self, ipar: int, imode: int, tableIndex: int = 0) pyevtgen.EvtDecayBase#
- getInstance = <nanobind.nb_func object>#
- class pyevtgen.EvtExternalGenList(*args, **kwargs)#
Bases:
objectDecay 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:
objectThe EvtGen generator. Only one instance can exist per process.
- generateDecay(self, p: pyevtgen.EvtParticle) None#
- class pyevtgen.EvtId(*args, **kwargs)#
Bases:
objectIdentifier of a particle or alias in the EvtGen tables.
- isConjugate(self, id: pyevtgen.EvtId) bool#
- class pyevtgen.EvtMTRandomEngine(*args, **kwargs)#
Bases:
EvtRandomEngineMersenne Twister random engine.
- class pyevtgen.EvtPDL#
Bases:
objectParticle 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:
objectParticle 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.
- get4Pos(self) pyevtgen.EvtVector4R#
Production four-position (ct, x, y, z) in mm in the lab frame.
- getDaug(self, i: int) pyevtgen.EvtParticle#
- getId(self) pyevtgen.EvtId#
- 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#
- getParent(self) pyevtgen.EvtParticle#
- getSpinDensityForward(self) pyevtgen.EvtSpinDensity#
- getSpinType(self) pyevtgen._core.EvtSpinType.spintype#
- setSpinDensityForward(self, rho: pyevtgen.EvtSpinDensity) None#
- setSpinDensityForwardHelicityBasis(self, rho: pyevtgen.EvtSpinDensity) None#
- class pyevtgen.EvtRandom#
Bases:
object- Flat = <nanobind.nb_func object>#
- Gaussian = <nanobind.nb_func object>#
- setRandomEngine = <nanobind.nb_func object>#
- class pyevtgen.EvtSpinDensity(*args, **kwargs)#
Bases:
objectSpin density matrix.
- normalizedProb(self, d: pyevtgen.EvtSpinDensity) float#
- 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 pyevtgen.EvtVector4R(*args, **kwargs)#
Bases:
objectFour-vector (E, px, py, pz) in GeV.
- applyBoostTo(self, p4: pyevtgen.EvtVector4R, inverse: bool = False) None#
- cont(self, v4: pyevtgen.EvtVector4R) float#
Minkowski scalar product.
- dot(self, v2: pyevtgen.EvtVector4R) float#
Scalar product of the spatial components.
- 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:
objectEvtGen decay generator.
This class sets up
EvtGenwith Pythia8 for thePYTHIAdecay model, in the same way as EvtGen’s C++ examples, and copies the generated decay trees intoParticleobjects. The underlyingEvtGeninstance is available asevtgenfor 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.pdlformat.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 deprecatedPHOTOS) 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
ndecay trees, seedecay().
- 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
KeyErrorif the particle is not in the particle table.>>> generator.properties(-511) ParticleProperties(name='anti-B0', pdg_id=-511, mass=5.279640)
- 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:
objectCopy 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.- classmethod from_evt_particle(particle: EvtParticle) Particle#
Copy an EvtGen decay tree, see
EvtParticle.getP4Lab().
- 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:
objectEntry of the EvtGen particle table, see
EvtPDL.- classmethod from_evt_id(evt_id: EvtId) ParticleProperties#
- 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::PhaseSpaceroutine directly with plain masses, so it needs noGenerator, particle table, or decay table. It can be used next to aGeneratorand 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 ofmasses.
>>> 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
PYTHIAdecay model.