Event content definition

Event content definition#

Event content object#

A couple of specific objects containing the full information of a physics event at a given snapshot of its processing are defined. The cepgen::Event object can be seen as an extended collection of cepgen::Particle components with the attributes defined hereafter.

Particle properties#

The cepgen::Particle object holds the minimal amount of information needed to define a particle: a momentum (as a cepgen::Momentum wrapper of the 4-momentum kinematics), some status (as a cepgen::Particle::Status enum) and role in event (the cepgen::Particle::Role enum) flags, a cepgen::pdgid_t PDG identifier, a mothers/daughters parentage, helicity, …

The detailed description of the object’s attributes can be shown below:

class Particle#

Kinematic information for one particle.

Public Types

enum class Status#

Internal status code for a particle.

Values:

enumerator PrimordialIncoming#: Incoming beam particle.

enumerator DebugResonance#: Intermediate resonance (for processes developers)

enumerator Resonance#: Already decayed intermediate resonance.

enumerator Fragmented#: Already fragmented outgoing beam.

enumerator Propagator#: Generic propagator.

enumerator Incoming#: Incoming parton.

enumerator Undefined#: Undefined particle.

enumerator FinalState#: Stable, final state particle.

enumerator Undecayed#: Particle to be decayed externally.

enumerator Unfragmented#: Particle to be hadronised externally.

Public Functions

explicit Particle(Role role = Role::UnknownRole, pdgid_t id = 0, Status st = Status::Undefined)#

Build using the role of the particle in the process and its PDG id.

Parameters:

role – [in] Role of the particle in the process
id – [in] PDG identifier
st – [in] Current status

bool operator<(const Particle&) const#: Comparison operator (from unique identifier)

bool operator==(const Particle&) const#: Equality operator.

inline int id() const#: Unique identifier (in a Event object context) Set the particle unique identifier in an event.

float charge() const#: Electric charge (given as a float number, for the quarks and bound states) Set whether we are coping with the particle or its antiparticle.

inline Role role() const#: Role in the considered process Set the particle role in the process.

inline Status status() const#: Particle status Set the particle decay/stability status.

inline Particle &setStatus(int status)#: Set the particle decay/stability status.

Particle &setPdgId(pdgid_t pdg, short ch = 0)#

Set the PDG identifier (along with the particle’s electric charge)

Parameters:

pdg – [in] PDG identifier
ch – [in] Electric charge (0, 1, or -1)

pdgid_t pdgId() const#

Retrieve the objectified PDG identifier Set the PDG identifier (along with the particle’s electric charge)

Parameters:: pdg_id – [in] PDG identifier (incl. electric charge in e)

long integerPdgId() const#: Retrieve the integer value of the PDG identifier.

inline float helicity() const#: Particle’s helicity Set the helicity of the particle.

inline Momentum &momentum()#: Retrieve the momentum object associated with this particle Retrieve the momentum object associated with this particle.

Particle &setMomentum(const Momentum&, bool offshell = false)#

Associate a momentum object to this particle.

Parameters:: offshell – [in] allow the 4-momentum mass to compensate for E-p balance?

Particle &setMomentum(double px, double py, double pz, double e = -1.)#

Set the 3- or 4-momentum associated to the particle.

Parameters:

px – [in] Momentum along the \(x\)-axis, in GeV/c
py – [in] Momentum along the \(y\)-axis, in GeV/c
pz – [in] Momentum along the \(z\)-axis, in GeV/c
e – [in] Energy, in GeV

inline Particle &setMomentum(double p[4])#

Set the 4-momentum associated to the particle.

Parameters:: p – [in] 4-momentum

bool valid()#: Is this particle a valid particle which can be used for kinematic computations?

inline bool primary() const#: Is this particle a primary particle?

Particle &addMother(Particle &part)#: Set the mother particle.

inline ParticlesIds mothers() const#: Identifier to the mother particles.

inline ParticlesIds &mothers()#: Identifier to the mother particles.

Particle &addDaughter(Particle &part)#: Add a decay product.

inline ParticlesIds daughters() const#: Identifiers list of all daughter particles.

inline ParticlesIds &daughters()#: Identifiers list of all daughter particles.

Friends

friend std::ostream &operator<<(std::ostream &os, const Status&)#: Human-readable particle’s status Role of the particle in the process.

friend std::ostream &operator<<(std::ostream &os, const Role&)#: Human-readable particle’s role in the event.

friend std::ostream &operator<<(std::ostream&, const Particle&)#: Human-readable dump of particle information.

Event properties#

In addition to a map between a particles’ role in the event and a collection of all particles with this role, the event object cepgen::Event also handles a few useful accessors, helpers, and properties. To quote a few:

cepgen::Event::cmEnergy() allows to compute the centre-of-mass energy of the incoming particles states,
cepgen::Event::compress() returns a compressed event, where all intermediate “vertex-like” states are skipped, only to keep the minimal 2-to-N event content,
cepgen::Event::missingMomentum() allows to compute the missing momentum from a “standard” detector’s perspective (the sum of all invisible particles, such as neutrinos/neutralinos/…)

The detailed description of the object’s methods and attributes can be found in cepgen::Event.

Event accessors#

The interaction with event content was simplified from CepGen version 1.1.0 to introduce a base placeholder object with the full knowledge of the cepgen::Event object. This intermediate object, the cepgen::EventHandler provides a few base utilities, such as:

an cepgen::EventHandler::initialise() initialisation procedure to prepare the external algorithm ;
an optional cepgen::EventHandler::engine() algorithm engine retrieval method (if exists), to allow a more specific steering for complex cases.

class EventHandler : public NamedModule<EventHandler>#

Class template for modules interacting with events.

Author: Laurent Forthomme laurent.forthomme@cern.ch
Date: Jan 2023

Subclassed by EventExporter, EventImporter, EventModifier

Public Functions

void initialise(const RunParameters&)#: Initialise the handler and its inner parameterisation.

const RunParameters &runParameters() const#: List of run parameters.

template<typename T> inline T *engine()#: Retrieve the engine object.

inline const std::string &name() const#: Module unique indexing name.

inline bool operator==(const SteeredObject &oth) const#: Equality operator.

inline bool operator!=(const SteeredObject &oth) const#: Inequality operator.

inline virtual const ParametersList &parameters() const override#: Module user-defined parameters.

inline virtual void setParameters(const ParametersList &params) override#: Set module parameters.

inline void setDescribedParameters(const ParametersList &params_orig)#: Set (documented) module parameters.

The implementations of event accessors can be classified into three categories: importers, modifiers, and exporters.

Event importer#

This category was introduced in CepGen version 1.2.0, and allows to load cepgen::Event objects from an external source. It can be useful when, for instance, CepGen is used as an interface to several modification algorithms (as described below), or to convert a dataset between two event formats.

class EventImporter : public EventHandler #

Base event importer module.

Author: Laurent Forthomme laurent.forthomme@cern.ch
Date: Dec 2022

Subclassed by HepMC2Importer, HepMC3Importer< T >, LHEFHepMCImporter, EventImporter

Public Functions

virtual bool operator>>(Event&) = 0#: Read the next event.

inline const Value &crossSection() const#: Process cross section and uncertainty, in pb.

void initialise(const RunParameters&)#: Initialise the handler and its inner parameterisation.

const RunParameters &runParameters() const#: List of run parameters.

template<typename T> inline T *engine()#: Retrieve the engine object.

inline const std::string &name() const#: Module unique indexing name.

inline bool operator==(const SteeredObject &oth) const#: Equality operator.

inline bool operator!=(const SteeredObject &oth) const#: Inequality operator.

inline virtual const ParametersList &parameters() const override#: Module user-defined parameters.

inline virtual void setParameters(const ParametersList &params) override#: Set module parameters.

inline void setDescribedParameters(const ParametersList &params_orig)#: Set (documented) module parameters.

Event modifier#

Event modifiers are basic buiding blocks for e.g. hadronisation algorithms interfaces, or treatment algorithms to match one event content definition to another. They are fully described in the Event modification algorithms section of this documentation.

Event exporter#

Event exporters, or output modules are providing an interface to major output formats definitions and writers. Again, a full documentation of this sub-class can be found in the Output formats section.

String-based event accessors#

Added in version 0.9.7.

The cepgen::utils::EventBrowser object was introduced to allow an easier interaction to all its attributes, either at the event level, or for each of its individual particles (single, or combined) and momenta.

It can be used the following way:

#include <CepGen/EventFilter/EventBrowser.h>

int main() {
    auto evt = cepgen::Event();
    //... define event attributes

    auto browser = cepgen::utils::EventBrowser();
    const double variable_value = browser.get(evt, "variable");

    return 0;
}

where the variable string can follow one of the three following conventions:

var for event-level information (e.g. diffractive outgoing proton state multiplicity)
var(role) for the retrieval of a single particle with a given role.

These particle roles may be one of the followings:
- ib1 and ib2 (resp. ob1 and ob2) for the incoming (resp. outgoing) beam kinematics,
- pa1 and pa2 for the parton/initiator particle emitted from the first/second incoming beam particle respectively,
- cs for the two-parton/initators system, and
- int for any intermediate \(s\)-channel particle exchange (depending on the process),
as documented in

const std::unordered_map<std::string, Particle::Role> cepgen::utils::EventBrowser::role_str_ = {{"ib1", Particle::Role::IncomingBeam1}, {"ib2", Particle::Role::IncomingBeam2}, {"ob1", Particle::Role::OutgoingBeam1}, {"ob2", Particle::Role::OutgoingBeam2}, {"pa1", Particle::Role::Parton1}, {"pa2", Particle::Role::Parton2}, {"cs", Particle::Role::CentralSystem}, {"int", Particle::Role::Intermediate}}#
var(id) for the retrieval of a single particle with a given integer identifier
var(role1,role2) or var(id1,id2) for the multi-particles kinematics correlation.

The following momentum-based variables var are currently handled, either for single particle or combined multi-particles systems:

const std::unordered_map<std::string, pMethod> cepgen::utils::EventBrowser::m_mom_str_ = {{"px", &Momentum::px}, {"py", &Momentum::py}, {"pz", &Momentum::pz}, {"pt", &Momentum::pt}, {"pt2", &Momentum::pt2}, {"eta", &Momentum::eta}, {"phi", &Momentum::phi}, {"m", &Momentum::mass}, {"m2", &Momentum::mass2}, {"mt", &Momentum::massT}, {"mt2", &Momentum::massT2}, {"e", &Momentum::energy}, {"e2", &Momentum::energy2}, {"et", &Momentum::energyT}, {"et2", &Momentum::energyT2}, {"p", &Momentum::p}, {"p2", &Momentum::p2}, {"th", &Momentum::theta}, {"y", &Momentum::rapidity}, {"beta", &Momentum::beta}, {"gamma", &Momentum::gamma}, {"gamma2", &Momentum::gamma2}}#: Mapping of string variables to momentum getter methods.

In addition, particles momenta’s correlations can be accessed through the following keywords:

const std::unordered_map<std::string, pMethodOth> cepgen::utils::EventBrowser::m_two_mom_str_ = {{"deta", &Momentum::deltaEta}, {"dphi", &Momentum::deltaPhi}, {"dpt", &Momentum::deltaPt}, {"dr", &Momentum::deltaR}}#

Event content definition

Contents

Event content definition#

Event content object#

Particle properties#

Event properties#

Event accessors#

Event importer#

Event modifier#

Event exporter#

String-based event accessors#