11. Event Generators¶

This package contains all code related to physics generators. Please have a look at Overview of the Belle II Physics Generators. As a general rule users are strongly encouraged to use the functions provided by the generators python module and not manually add generator modules directly to the path.

11.1. The generators Python Module¶

This module contains convenience functions to setup most commonly used physics generators correctly with their default settings. More information can be found in BELLE2-NOTE-PH-2015-006

generators.add_aafh_generator(path, finalstate='', preselection=False, enableTauDecays=True, minmass=0.5, subweights=[], maxsubweight=1, maxfinalweight=3.0)[source]¶

Add the default two photon generator for four fermion final states

Parameters

path (basf2.Path) – path where the generator should be added
finalstate (str) – either “e+e-e+e-”, “e+e-mu+mu-”, “e+e-tau+tau-”, “mu+mu-mu+mu-” or “mu+mu-tau+tau-”
preselection (bool) – if True, select events with at least one medium pt particle in the CDC acceptance
enableTauDecays (bool) – if True, allow tau leptons to decay (using EvtGen)

generators.add_babayaganlo_generator(path, finalstate='', minenergy=0.01, minangle=10.0, fmax=- 1.0, generateInECLAcceptance=False)[source]¶

Add the high precision QED generator BabaYaga@NLO to the path.

Parameters

path (basf2.Path) – path where the generator should be added.
finalstate (str) – ee (e+e-) or gg (gammagamma).
minenergy (float) – minimum particle (leptons for ‘ee’, photons for ‘gg’) energy in GeV.
minangle (float) – angular range from minangle to 180-minangle for primary particles (in degrees).
fmax (float) – maximum of differential cross section weight. This parameter should be set only by experts.
generateInECLAcceptance (bool) – if True, the GeneratorPreselection module is used to select only events with both the primary particles within the ECL acceptance.

generators.add_bhwide_generator(path, minangle=0.5)[source]¶

Add the high precision QED generator BHWIDE to the path. Settings are the default L1/HLT study settings with a cross section of about 124000 nb (!)

Parameters

path (basf2.Path) – path where the generator should be added
minangle (float) – minimum angle of the outgoing electron/positron in the CMS in degrees

generators.add_continuum_generator(path, finalstate, userdecfile='', *, skip_on_failure=True)[source]¶

Add the default continuum generators KKMC + PYTHIA including their default decfiles and PYTHIA settings

11.2. Modules in the Generators Package¶

Apart from the default settings above the generators can also be setup directly and there are special generators not covered above.

Warning

Please use the function from the generators module to setup event generation if possible.

AafhInput¶

AAFH Generator to generate non-radiative two-photon events like e+e- -> e+e-e+e-

Package

generators

Library

libaafhinput.so

Parameters

maxFinalWeight (float, default=1.0)
maximum expected final weight for rejection scheme (ESFT)
maxSubgeneratorWeight (float, default=1.0)
maximum expected subgenerator weight for rejection scheme (ESWE)
maxTries (int, default=1000000)
Maximum tries for event generation (ITOT)
minMass (float, default=0.0)
minimum invariant mass of generated fermion pair. Will automatically be set to at least 2 times the generated particle mass
mode (int, default=5)
decay mode to generate. 1: e+e- -> mu+mu-L+L-, 2: e+e- -> mu+mu-mu+mu-, 3: e+e- -> e+e-mu+mu-, 4: e+e- -> e+e-L+L-, 5: e+e- -> e+e-e+e-. L is a user defined particle (default: tau)
particle (str, default=’tau-‘)
name of the generated particle for mode 1 and 4
rejection (int, default=2)
Rejection method. 1: apply once for the final event weight, 2: apply for the subgenerator weight and for the final weight
subgeneratorWeights (list(float), default=[1.0, 1.0, 1.0, 1.0, 1.0, 10.0, 10000.0, 10000.0])
relative weights of the subgenerators: this must be a list of four or eight values (first four are interpreted as WAP, rest as WBP) which specify the relativ weights for each of the four sub generators. The orginial code states that it the program run most efficient when the maximum weight is equal in all sub generators and that if one wants to be sure that all peaks in the differential cross section are accounted the chance to enter each sub generator should be equal. Values which try to fullfill both conditions are printed at after generation when the output level is set to INFO
suppressionLimits (list(float), default=[1000.0, 1000.0, 1000.0, 1000000000.0])
suppression limits for the matrix element calculations. This must be a list of four values, [FACE, FACM, FACL, PROC]. For FACE, FACM and FACL these specify the size of the propagator for which the corresponding spin configurations will be omitted. A value of 1e3 will calculate the dominat part correctly and a very large value compared to the mass (i.e. 1e50) will calculate it exactly. PROC specifies that feynman diagrams which contribute less than 1/PROC of the biggest contribution are omitted. For exact calculation it should be very big but 1e9 should be considerably faster without affecting the result very much

BBBremInput¶

Generates low scattering angle radiative Bhabha events (Beam-Beam Bremsstrahlung).

Package

generators

Library

libbbbreminput.so

Parameters

DensityCorrectionMode (int, default=1)
Mode for bunch density correction (none=0, hard=1 (default), soft=2)
DensityCorrectionParameter (float, default=1.68e-17)
Density correction parameter tc (=(hbarc/sigma_y)^2)
MaxWeight (float, default=2000.0)
The max weight (only for Unweighted=True).
MinPhotonEnergyFraction (float, default=1e-06)
Fraction of the minimum photon energy.
Unweighted (bool, default=True)
Produce unweighted or weighted events.

BHWideInput¶

Generates radiative BhaBha scattering events with BHWide.

Package

generators

Library

libbhwideinput.so

Parameters

MaxAcollinearity (float, default=180.0)
Maximum acollinearity angle between finale state leptons/photons [degree]
MinEnergy (float, default=0.2)
Minimum energy for electrons in the final state [GeV] (default: 0.2 GeV)
ScatteringAngleRangeElectron (list(float), default=[15.0, 165.0])
Min [0] and Max [1] value for the scattering angle [deg] of the electron.
ScatteringAngleRangePositron (list(float), default=[15.0, 165.0])
Min [0] and Max [1] value for the scattering angle [deg] of the positron.
VacuumPolarization (str, default=’burkhardt’)
Vacuum polarization: off (off - EW off, too), Burkhardt89 (bhlumi), Eidelman/Jegerlehner95 (eidelman) or Burkhardt/Pietrzyk95 (burkhardt)
WeakCorrections (bool, default=True)
EW correction ON/OFF
WtMax (float, default=3.0)
Maximum of weight (wtmax, default: 3.0), if <0: internal maximum search

BabayagaNLOInput¶

Generates radiative Bhabha scattering and exclusive two-photon events with the high precision QED generator called BabaYaga@NLO.

Package

generators

Library

libbabayaganloinput.so

Parameters

DebugEnergySpread (float, default=0.005)
TEMPORARY SOLUTION! Approximate energy spread per beam (CMS)
EEMIN (float, default=-1.0)
Minimum CMS energy of the tagged e-/e+ (GeV)
EEVETO (float, default=-1.0)
Minimum CMS energy to veto e-/e+ (GeV)
EGMIN (float, default=-1.0)
Minimum CMS energy of the gamma (GeV)
EGVETO (float, default=-1.0)
Minimum CMS energy to veto gamma (GeV)
Epsilon (float, default=1e-07)
Soft/hard photon separator [fraction of ECMS/2], must be <=1e-7 for ee and mumu, <=1e-5 for gg
ExtraFile (str, default=’’)
ROOT file that contains additional information.
FMax (float, default=-1.0)
Maximum of differential cross section weight (fmax)
FinalState (str, default=’ee’)
Final state: ee (default), mm or gg
MaxAcollinearity (float, default=180.0)
Maximum acollinearity angle between finale state leptons/photons [degree]
MaxPrescale (float, default=1.0)
Maximum prescale factor (used for maximum differential cross section)
MinEnergy (float, default=0.1)
Minimum energy for leptons (ee or mm mode) or photons (gg mode) in the final state [GeV]
MinEnergyFrac (float, default=-1.0)
Fractional minimum energy for leptons (ee or mm mode) or photons (gg mode) in the final state [fraction of ECMS]
Mode (str, default=’unweighted’)
Mode: weighted or unweighted (default)
Model (str, default=’matched’)
Model: ps or matched (default)
NPhotons (int, default=-1)
Fixed number of (hard) photons are generated, -1 for any number
NSKDataFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/babayaganlo/vpol_novosibirsk.dat’)
File that contain VP data from Novosibirsk (nsk)
Order (str, default=’exp’)
Order: born, alpha, exp (default)
ScatteringAngleRange (list(float), default=[15.0, 165.0])
Min [0] and Max [1] value for the scattering angle [deg].
SearchMax (int, default=500000)
Number of events used to search for maximum of differential cross section
TEMIN (float, default=-1.0)
Minimum CMS angle between the tagged e-/e+ and -z axis (deg)
TEVETO (float, default=-1.0)
Maximum CMS theta of e-/e+ in final state (deg)
TGMIN (float, default=-1.0)
Minimum CMS angle between the gamma and -z axis (deg)
TGVETO (float, default=-1.0)
Maximum CMS angle between the gamma and -z axis (deg)
UserMode (str, default=’NONE’)
User mode similar to TEEGG: ETRON, EGAMMA, GAMMA or PRESCALE or NONE (default)
VPUncertainty (bool, default=False)
Calculate VP uncertainty by internal reweighting
VacuumPolarization (str, default=’hlmnt’)
Vacuum polarization: off, hadr5 (Jegerlehner) or hlmnt (Teubner, default)

BeamParameters¶

Setting of beam parameters. This module allows to set the beamparameters to be used by generators and analyis. One can either select from a list of predefined parameter sets or manually set the parameters to use.

Package

generators

Library

libgenerators_modules.so

Parameters

angleXHER (float, default=0.0415)
angle of the High Energy Ring in the x-z plane. Negative values are interpreted as pi - value
angleXLER (float, default=-0.0415)
angle of the Low Energy Ring in the x-z plane. Negative values are interpreted as pi - value
angleYHER (float, default=0.0)
angle of the High Energy Ring in the y-z plane. Negative values are interpreted as pi - value
angleYLER (float, default=0.0)
angle of the Low Energy Ring in the y-z plane. Negative values are interpreted as pi - value
covHER (list(float), default=[0.0])
covariance matrix of the High Energy Ring. This can either be one value which is the squared energy spread, three values corresponding to the variances of energy and the horizontal and vertial spread (E, theta_x, theta_y) or a full covariance matrix with 9 elements
covLER (list(float), default=[0.0])
covariance matrix of the Low Energy Ring. This can either be one value which is the squared energy spread, three values corresponding to the variances of energy and the horizontal and vertial spread (E, theta_x, theta_y) or a full covariance matrix with 9 elements
covVertex (list(float), default=[0.0])
covariance matrix of the nominal vertex position. Can be either one value which is the common variance for all directions, three values for the variance of x, y and z or a full covariance matrix
createPayload (bool, default=False)
if true create a database payload with the iov given with the payloadIov parameter
energyHER (float, default=7.0)
Energy of the High Energy Ring
energyLER (float, default=4.0)
Energy of the Low Energy Ring
generateCMS (bool, default=False)
if true, generate events in CMS, not lab system
payloadIov (list(int), default=[0, 0, -1, -1])
iov of the payload to be created. List of four numbers: first experiment, first run, last experiment, last run
smearDirection (bool, default=True)
if true, smear beam direction when generating initial events
smearEnergy (bool, default=True)
if true, smear energy when generating initial events
smearVertex (bool, default=True)
if true, smear vertex position when generating initial events
vertex (list(float), default=[0.0, 0.0, 0.0])
nominal vertex position

BoostMCParticles¶

Module for boosting the MCParticles from CM to LAB frame. The module must be appended to the path only when HepMC, Hepevt or LHE input files are used.

Package

generators

Library

libgenerators_modules.so

Parameters

MCParticlesStoreArrayName (str, default=’’)
Name of the MC particles StoreArray.

CRYInput¶

Generates cosmic showers with CRY.

The showers will be generated in the xz plane in a square plane of n bt n meters centered at the IP (n can be choosen with the boxLength parameter). Then the cosmics will be propagated from there to the boundary of the detector world volume.

Finally, if the track would intersect with the acceptance volume the track is kept. The acceptance volume can be either a sphere, a cylinder or a box centered at the IP. This depends on how many values are given to the acceptance parameter.

Package

generators

Library

libcryinput.so

Parameters

CosmicDataDir (str, default=’’)
Directory that holds the cosmic data for CRY. Empty string will look in the default location
acceptance (list(float), default=[])
Size of the acceptance volume. This can be either be:
1. one value being the radius of a sphere
2. two values for the radius (in xy) and the half-length (in z) of a cylinder
3. three values for x,y,z half-length of a box
All volumes are centered around the IP. All values are in cm
boxLength (float, default=10000.0)
Length of the side of the square in the xz plane in which CRY will generate cosmics in cm. Will be rounded down to meters. According to the CRY documentation good values are 1, 3, 10, 30, 100 and 300m but anything in between should work as well. The default is 100m and should be fine for almost all use cases.
date (str, default=’1-1-2019’)
Date used for the generation: a string in the form of ‘month-date-year’. The cosmic-ray distribution is adjusted to account for the eleven year, sunspot cycle (the default solar minimum date is January 1, 2008).
kineticEnergyThreshold (float, default=0.01)
Energy threshold [GeV]
maxTrials (int, default=10000)
Maximum number of trials per event
returnElectrons (bool, default=True)
Whether or not CRY should return electrons
returnGammas (bool, default=True)
Whether or not CRY should return gammas
returnKaons (bool, default=True)
Whether or not CRY should return kaons
returnMuons (bool, default=True)
Whether or not CRY should return muons
returnNeutrons (bool, default=True)
Whether or not CRY should return neutrons
returnPions (bool, default=True)
Whether or not CRY should return pions
returnProtons (bool, default=True)
Whether or not CRY should return protons
timeOffset (float, default=0.0)
Time offset [s]

Cosmics¶

cosmics generator to generate cosmic ray tracks

Package

generators

Library

libgenerators_modules.so

Parameters

cylindricalR (float, default=125.0)
Radius of tube around detector at whose surface particles are generated (in cm), default is 125, but this does not include whole Belle 2 detector!
ipRequirement (int, default=0)
Radial and longitudinal constraints near the Interaction Point can be required (ipRequirement == 1), default is 0 (no additional IP requirements)
ipdr (float, default=3.0)
Constraint on the radial distance from the IP in cm, default is 3.
ipdz (float, default=3.0)
Constraint on the longitudinal distance from the IP in cm, default is 3, default is 3.
level (int, default=1)
level of the generator (1 or 2 with slightly different kinematic distributions and mu+/mu- ratio), default is 1
ptmin (float, default=0.7)
Minimal value of the transverse momentum in GeV, default is 0.7

EventT0Generator¶

Module generates discrete event t0 in ~4ns steps (bunch spacing) according to double gaussian distribution and adds it to the production and decay times of MCParticles. This means that after this module the time origin (t = 0) is set to what L1 trigger would give as the collision time. In case of cosmics, the L1 triggerjitter is generated according to a continuos double gaussian distribution

Package

generators

Library

libgenerators_modules.so

Parameters

coreGaussWidth (float, default=5.6)
sigma of core gaussian [ns]
coreGaussWidthCosmics (float, default=13.0)
sigma of core gaussian for cosmics [ns]
fixedT0 (float, default=nan)
If set, a fixed event t0 is used instead of simulating the bunch timing.
isCosmics (bool, default=False)
if True simulate L1 jitter for cosmics
maximumT0 (float, default=nan)
If set, randomize between -maximum and maximum.
tailGaussFraction (float, default=0.08)
fraction (by area) of tail gaussian
tailGaussFractionCosmics (float, default=0.09)
fraction (by area) of tail gaussian for cosmics
tailGaussMeanCosmics (float, default=28.0)
mean of tail gaussian for cosmics [ns]
tailGaussWidth (float, default=14.5)
sigma of tail gaussian [ns]
tailGaussWidthCosmics (float, default=15.0)
sigma of tail gaussian for cosmics [ns]

EventT0Shifter¶

Shift the time of all MCParticles so that the collision time is t=0.It reverts the shift done by the EventT0Generator module and should be used after the simulation.Note that the collisionTime in the MCInitialParticles is not changed.

Package: generators
Library: libgenerators_modules.so

EvtGenDecay¶

This module decays unstable particles using EvtGen. The event should be already generated by another generator. If you need to generate full event with EvtGen, then use the module ‘EvtGenInput’.

Package

generators

Library

libevtgendecay.so

Parameters

DecFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/decfiles/dec/DECAY_BELLE2.DEC’)
EvtGen decay file (DECAY.DEC)
MCParticleColName (str, default=’’)
MCParticle collection name.
UserDecFile (str, default=’’)
User EvtGen decay file

EvtGenInput¶

EvtGenInput module. The module is served as an interface for EvtGen Event Generator so that the EvtGen generator can store the generated particles into MCParticles. The users need to provide their own decay mode based on the standard DECAY.DEC.

Package

generators

Library

libevtgeninput.so

Parameters

CoherentMixing (bool, default=True)
decay the neutral B meson pairs coherently or non-coherently
DECFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/decfiles/dec/DECAY_BELLE2.DEC’)
global DECfile to be used
InclusiveParticle (str, default=’’)
Inclusive Particle Name
InclusiveType (int, default=0)
inclusive decay type (0: generic, 1: inclusive, 2: inclusive (charge conjugate)
ParentParticle (str, default=’Upsilon(4S)’)
Parent Particle Name
maxTries (int, default=100000)
Number of tries to generate a parent particle from the beam energies which fits inside the mass window before giving up
userDECFile (str, default=’’)
user DECfile name

Fragmentation¶

Fragmention of (u/d/s/c) quarks using PYTHIA8

Package

generators

Library

libfragmentation.so

Parameters

CoherentMixing (bool, default=True)
Decay the B0-B0bar coherently (should always be true)
DecFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/decfiles/dec/DECAY_BELLE2.DEC’)
EvtGen decay file (DECAY.DEC)
ListPYTHIAEvent (int, default=0)
List event record of PYTHIA after hadronization
ParameterFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/generators/modules/fragmentation/data/pythia_belle2.dat’)
Input parameter file for PYTHIA
UseEvtGen (int, default=1)
Use EvtGen for specific decays
UserDecFile (str, default=’’)
User EvtGen decay file

GeneratedVertexDisplacer¶

“”Takes a list of PDG values and lifetime paramters to displaces the vertex of MCParticles with matching PDG value corresponding to the given lifetime parameter. Can be used betwenerator and the detector simulation.

Package

generators

Library

libgenerators_modules.so

Parameters

ctau (bool, default=True)
Input unit option. True (default): module expects lifetime as ctau [cm]. False: lifetime as tau [ns].
lifetime (list(float), default=[0.0])
Set the numerical value of the lifetime c*tau in units of [cm]. Example: (lifetime_1, lifetime_2, … ,lifetime_N). Lifetime_X is set for PDG_X.
lifetimeOption (str, default=’fixed’)
Set the lifetime option, either ‘fixed’, ‘flat’ or ‘exponential’. Option is set globally.
maxDecayTime (float, default=300.0)
Set the maximal allowed decay time in c*tau [cm] for the option ‘flat’. The ‘exponential’ option is not bound. Default 300cm.
pdgVal (list(int), default=[-999])
PDG values of MCParticles that should be displaced. Subsequent daughters of these will be displaced accordingly. Example: (PDG_1, PDG_2, … , PDG_N). PDG_X corresponds to lifetime_X.

GeneratorPreselection¶

Preselection based on generator truth information. Returns 0 if no cut have been passed, 1 if only the charged cut has been passed, 10 if only the photon cut has been passed, and 11 if both charged and photon cuts have been passed.

Package

generators

Library

libgenerators_modules.so

Parameters

MaxChargedTheta (float, default=150.0)
maximum polar angle of charged particle [deg]
MaxPhotonTheta (float, default=165.0)
maximum polar angle of photon [deg]
MinChargedP (float, default=0.25)
minimum charged momentum [GeV]
MinChargedPt (float, default=0.1)
minimum charged transverse momentum (pt) [GeV]
MinChargedTheta (float, default=17.0)
minimum polar angle of charged particle [deg]
MinPhotonEnergy (float, default=-1.0)
minimum photon energy [GeV]
MinPhotonTheta (float, default=15.0)
minimum polar angle of photon [deg]
applyInCMS (bool, default=False)
if true apply the P,Pt,theta, and energy cuts in the center of mass frame
nChargedMax (int, default=999)
maximum number of charged particles
nChargedMin (int, default=0)
minimum number of charged particles
nPhotonMax (int, default=999)
maximum number of photons
nPhotonMin (int, default=0)
minimum number of photons
stableParticles (bool, default=False)
if true apply the selection criteria for stable particles in the generator

GeneratorPreselectionLeptonic¶

Filtering based on generator truth information. Returns 0 if cuts have not been passed, 1 only if all cuts are passed.

Package

generators

Library

libgenerators_modules.so

Parameters

UMax (float, default=10.0)
maximum value of U = E - p (calculated using vector sum of momenta and energy for neutrinos in CMS)
UMin (float, default=-10.0)
minimum value of U = E - p (calculated using vector sum of momenta and energy for neutrinos in CMS)
angleMax (float, default=1.0)
maximum value for the cosine of the angle between the tau and signal lepton momentum vectors (in CMS)
angleMin (float, default=-1.0)
minimum value for the cosine of the angle between the tau and signal lepton momentum vectors (in CMS)
projectionMax (float, default=10.0)
maximum value for projection of tau lepton onto signal lepton momentum (in CMS)
projectionMin (float, default=-10.0)
minimum value for projection of tau lepton onto signal lepton momentum (in CMS)
signalLeptonPDG (float, default=11.0)
PDG code for the signal lepton
signalLeptonPMax (float, default=5.0)
maximum momentum (CMS) for signal lepton
signalLeptonPMin (float, default=0.0)
minimum momentum (CMS) for signal lepton
tauLeptonPMax (float, default=5.0)
maximum momentum (CMS) for tau daughter lepton
tauLeptonPMin (float, default=0.0)
minimum momentum (CMS) for tau daughter lepton
zDiffMax (float, default=5.0)
maximum value for difference between production vertex z-component for signal and tau leptons
zDiffMin (float, default=-5.0)
minimum value for difference between production vertex z-component for signal and tau leptons

HepMCInput¶

HepMC file input. This module loads an event record from HEPMC2 format and store the content into the MCParticle collection. HEPMC format is used by for example pythia8.

Package

generators

Library

libhepmcreader.so

Required Parameters

inputFileList (list(str))
List of names of HepMC2 files

Parameters

expNum (int, default=-1)
Experiment number
ignoreReadEventNr (bool, default=False)
Parallel pythia can have dublicate event nrs.
maxEvt (int, default=2147483647)
Stop converting at event number.
minEvt (int, default=-1)
Start converting at event number.
nVirtualParticles (int, default=0)
Number of particles at the beginning of the events that should be made virtual.
runNum (int, default=-1)
Run number
useWeights (bool, default=False)
Set to ‘true’ to if generator weights should be propagated.
wrongSignPz (bool, default=False)
Boolean to signal that directions of HER and LER were switched

HepMCOutput¶

HepMC file output. This module loads an event record from the MCParticle collection and store the content back into the HepMC (2) format. HepMC format is a standard event record format to contain an event record in a Monte Carlo-independent format.

Package

generators

Library

libhepmcwriter.so

Required Parameters

OutputFilename (str)
The filename of the output file

Parameters

StoreVirtualParticles (bool, default=False)
Store also virtual particles in the HepMC file.

HepevtInput¶

HepEvt file input. This module loads an event record from HEPEVT format and store the content into the MCParticle collection. HEPEVT format is a standard event record format to contain an event record in a Monte Carlo-independent format.

Package

generators

Library

libgenerators_modules.so

Required Parameters

inputFileList (list(str))
List of names of Hepevt files

Parameters

expNum (int, default=-1)
Experiment number
makeMaster (bool, default=False)
Boolean to indicate whether the event numbers from input file should be used.
nVirtualParticles (int, default=0)
Number of particles at the beginning of the events that should be made virtual.
runNum (int, default=-1)
Run number
skipEvents (int, default=0)
Skip this number of events before starting.
useWeights (bool, default=False)
Set to ‘true’ to if generator weights should be propagated.
wrongSignPz (bool, default=False)
Boolean to signal that directions of HER and LER were switched

HepevtOutput¶

HepEvt file output. This module loads an event record from the MCParticle collection and store the content back into the HEPEVT format. HEPEVT format is a standard event record format to contain an event record in a Monte Carlo-independent format.

Package

generators

Library

libgenerators_modules.so

Required Parameters

OutputFilename (str)
The filename of the output file

Parameters

FullFormat (bool, default=True)
Write the full HepEvt format to file. Set it to false for a compact format.
MirrorPz (bool, default=False)
If the directions of HER and LER are switched, mirror Pz.
StoreVirtualParticles (bool, default=False)
Store also virtual particles in the HePEvt file.

InclusiveParticleChecker¶

Check for the existence of one or more inclusive particles in the list of generated particles. If any of the particles is found the event is accepted and the return value is set to True. Otherwise the return value is set to false.

The particles to look for can either be given as numerical pdg codes or as particle names or even as a mix of both:

>>> checker = path.add_module("InclusiveParticleChecker", particles = [11, "pi+"])

Valid names are defined in the evt.pdl of evtgen and can be inspected using either the pdg module or b2help-particles.

This module is intended for inclusive signal generation where we run a generator which produces generic events and we require a certain particle to be present in the resulting list of particles.

Package

generators

Library

libgenerators_modules.so

Required Parameters

particles (list(variant(str, int)))
Name or PDG code of the particles to look for. If any of those is found in the event the event is accepted

Parameters

includeConjugates (bool, default=True)
If true look for either the particles or their charge conjugates

KKGenInput¶

KKGenInput module. This an interface for KK2f Event Generator for basf2. The generated events are stored into MCParticles. You can find an expample of its decay file (tau_decaytable.dat) for tau-pair events at ${BELLE2_RELEASE_DIR}/data/generators/kkmc. On the other hand, when you like to generate mu-pair events, ${BELLE2_RELEASE_DIR}/data/generators/kkmc/mu.input.dat should be set to tauinputFile in your steering file.

Package

generators

Library

libkkgeninput.so

Parameters

KKdefaultFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/kkmc/KK2f_defaults.dat’)
default KKMC setting filename
kkmcoutputfilename (str, default=’’)
KKMC output filename
taudecaytableFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/kkmc/tau.input.dat’)
tau-decay-table file name
tauinputFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/kkmc/KK2f_defaults.dat’)
user-defined tau/mu/q-pairs generation setting

KoralWInput¶

Generates four fermion final state events with KoralW.

Package

generators

Library

libkoralwinput.so

Parameters

DataPath (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/koralw’)
The path to the KoralW input data files.
UserDataFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/koralw/KoralW_eeee.data’)
The filename of the user KoralW input data file.

LHEInput¶

LHE file input. This module loads an event record from LHE format and store the content into the MCParticle collection. LHE format is a standard event record format to contain an event record in a Monte Carlo-independent format.

Package

generators

Library

libgenerators_modules.so

Required Parameters

inputFileList (list(str))
List of names of LHE files

Parameters

Rmax (float, default=1000000.0)
Maximum of distance between displaced vertex to IP in CM frame
Rmin (float, default=0.0)
Minimum of distance between displaced vertex to IP in CM frame
expNum (int, default=-1)
Experiment number
makeMaster (bool, default=False)
Boolean to indicate whether the event numbers from input file should be used.
meanDecayLength (float, default=0.0)
Mean decay length(mean lifetime * c) between displaced vertex to IP in the CM frame, default to be zero, unit in cm
nInitialParticles (int, default=0)
Number of MCParticles at the beginning of the events that should be flagged c_Initial.
nVirtualParticles (int, default=0)
Number of MCParticles at the beginning of the events that should be flagged c_IsVirtual.
pdg_displaced (int, default=9000008)
PDG code of the displaced particle being studied
runNum (int, default=-1)
Run number
skipEvents (int, default=0)
Skip this number of events before starting.
useWeights (bool, default=False)
Set to ‘true’ to if generator weights should be propagated (not implemented yet).
wrongSignPz (bool, default=True)
Boolean to signal that directions of HER and LER were switched

OverrideGenerationFlags¶

Ovverride generation flags for BeamParameters from database.

Package

generators

Library

libgenerators_modules.so

Parameters

generateCMS (bool, default=False)
Generate events in CMS, not lab system.
smearDirection (bool, default=True)
Smear beam direction when generating initial events.
smearEnergy (bool, default=True)
Smear energy when generating initial events.
smearVertex (bool, default=True)
Smear vertex position when generating initial events.

PairGen¶

Simple module to generate tracks of given PDG back to back in CMS.

Package

generators

Library

libpairgen.so

Parameters

pdgCode (int, default=11)
PDG code for generated particles
saveBoth (bool, default=True)
Store both particles if true, one if false

ParticleGun¶

Particle gun to generate simple tracks. This module allows to generate simple events where all tracks have the same momentum, angular and vertex distributions. Several distributions are available for momentum, phi, theta and vertex position generation:

fixed:: Fixed value, only one parameter has to be specified [value]
uniform:: Uniform between two given values [min, max]
uniformPt:: Generate flat transverse momentum pt [min_pt, max_pt]
uniformCos:: Generate uniformly in the cosine, e.g. flat in cos(theta). Parameters are still the minimum and maximum angle (not the cosine of the angle) [min_theta, max_theta]
uniformLog:: Generate uniformly in the logarithm. Parameters are still the normal values [min, max]
uniformLogPt:: Like uniformLog but for the transverse momentum.
normal:: Normal (Gaussian) distributed [mean, width]
normalPt:: Generate normal distributed transverse momentum pt [mean_pt, width_pt]
normalCos:: Generate normal distributed cosine of the angle [mean, width]
polyline:: Generate according to a pdf given as polyline, first the sorted x coordinates and then the non-negative y coordinates [x1, x2, x3, ... xn, y1, y2, y3, ..., yn]
polylinePt:: Like polyline but for pt, not p
polylineCos:: Like polyline, but for the cos(), not the absolute value
inversePt:: Generate uniformly in the inverse of pt, that is uniform in track curvature [min_pt, max_pt]
discrete:: Discrete Spectrum given as a list of weights and values (useful for radioactive sources) [weight1, value1, weight2, value2, ...]
discretePt:: same as above but for transverse momentum

Package

generators

Library

libgenerators_modules.so

Parameters

fixedMomentumPerEvent (bool, default=False)
generates particle momentum according to the specified distribution and assigns this momentum to all particles generated for one event
independentVertices (bool, default=False)
If false, all tracks of one event will start from the same vertex, otherwise a new vertex is generated for every particle
momentumGeneration (str, default=’uniform’)
Momentum distribution: one of fixed, uniform, normal, polyline, uniformLog, uniformPt, normalPt, inversePt, polylinePt, uniformLogPt or discrete
momentumParams (list(float), default=[0.05, 3.0])
Parameters for the momentum generation. Meaning of the parameters depends on the chosen distribution
nTracks (float, default=1.0)
The number of tracks to be generated per event. If <=0, one particle will be created for each entry in ‘pdgCodes’. Otherwise N particles will be created and the Particle ID for each particle will be picked randomly from ‘pdgCodes’
pdgCodes (list(int), default=[-11, 11])
PDG codes for generated particles
phiGeneration (str, default=’uniform’)
Phi distribution: one of fixed, uniform, normal, normalCos, polyline, uniformCos, polylineCos or discrete
phiParams (list(float), default=[0.0, 360.0])
Parameters for the phi generation in degrees. Meaning of the parameters depends on the chosen distribution
thetaGeneration (str, default=’uniform’)
Theta distribution: one of fixed, uniform, normal, normalCos, polyline, uniformCos, polylineCos or discrete
thetaParams (list(float), default=[17.0, 150.0])
Parameters for the theta generation in degrees. Meaning of the parameters depends on the chosen distribution
timeGeneration (str, default=’fixed’)
Time distribution: one of fixed, uniform, normal, normalCos, polyline, uniformCos, polylineCos or discrete
timeParams (list(float), default=[0.0])
Time offset
varyNTracks (bool, default=False)
If true, the number of tracks per event is varied using a Poisson distribution. Only used if ‘nTracks’>0
vertexGeneration (str, default=’fixed’)
Vertex (x,y,z) distribution: one of fixed, uniform, normal, polyline or discrete
xVertexGeneration (str, default=’’)
X vertex distribution: same options as ‘vertexGeneration’. If this parameter is not specified the value from ‘vertexGeneration’ is used
xVertexParams (list(float), default=[0.0, 0.001])
Parameters for the x vertex generation. Meaning of the parameters depends on the chosen distribution
yVertexGeneration (str, default=’’)
Y vertex distribution: same options as ‘vertexGeneration’. If this parameter is not specified the value from ‘vertexGeneration’ is used
yVertexParams (list(float), default=[0.0, 5.9e-06])
Parameters for the y vertex generation. Meaning of the parameters depends on the chosen distribution
zVertexGeneration (str, default=’’)
Z vertex distribution: same options as ‘vertexGeneration’. If this parameter is not specified the value from ‘vertexGeneration’ is used
zVertexParams (list(float), default=[0.0, 0.019])
Parameters for the z vertex generation. Meaning of the parameters depends on the chosen distribution

PhokharaInput¶

Generates radiative return events with PHOKHARA 10.

Package

generators

Library

libphokharainput.so

Parameters

Alpha (int, default=1)
Vacuum polarization switch: off (0), on (1,[by Fred Jegerlehner], default), on (2,[by Thomas Teubner])
BeamEnergySpread (bool, default=False)
Simulate beam-energy spread (initializes PHOKHARA for every event - very slow).
BeamResolution (float, default=0.0)
beamres - beam resolution for pion==11 and pion==12 only
ChiSW (int, default=0)
chi_sw: Radiative return(0), Chi production(1), Radiative return + Chi production (2). Works only for pion=11 and pion=12.
Epsilon (float, default=0.0001)
Soft/hard photon separator
FinalState (int, default=1)
Final state: mu+mu-(0), pi+pi-(1), 2pi0pi+pi-(2), 2pi+2pi-(3), ppbar(4), nnbar(5), K+K-(6), K0K0bar(7), pi+pi-pi0(8), lamb(->pi-p)lambbar(->pi+pbar)(9), eta pi+ pi- (10), chi_c1 production (11), chi_c2 production (12), pi0 g (13), eta g (14), etaP g (15)
ForceMinInvMassHadronsCut (bool, default=False)
Force application of the MinInvMassHadrons cut It is ignored by PHOKHARA with LO = 1, NLO = 1.
FullNLO (int, default=0)
full NLO : No(0), Yes(1). Allowed only for ph0=1, nlo=1, fsr=2, fsrnlo=1
IFSNLO (int, default=0)
IFSNLO: no(0), yes(1)
KaonFF (int, default=0)
Kaon FF: KaonFormFactor constrained(0, default), KaonFormFactor unconstrained(1) KaonFormFactor old(2)
LO (int, default=0)
ph0 Born: 1ph(0), Born: 0ph(1), only Born: 0ph(-1)
MaxInvMassHadrons (float, default=112.0)
Maximal hadrons/muons invariant mass squared [GeV^2]
MinEnergyGamma (float, default=0.15)
Minimal photon energy/missing energy, must be greater than 0.0098 * CMS energy [GeV]
MinInvMassHadrons (float, default=0.2)
Minimal hadrons/muons invariant mass squared [GeV^2]
MinInvMassHadronsGamma (float, default=0.0)
Minimal hadrons/muons-gamma invariant mass squared [GeV^2]
NLO (int, default=0)
1 photon : Born(0), NLO(1)
NarrowRes (int, default=0)
Only for m_finalState = 0,1,6,7: No narrow resonances (0, default), J/Psi (1) and Psi(2S) (2)
ParameterFile (str, default=’/gpfs/group/belle2/dataprod/validation/release_doc/build/data/generators/phokhara/const_and_model_paramall10.0.dat’)
File that contains particle properties.
PionFF (int, default=0)
Pion FF: KS PionFormFactor(0, default), GS old 1), GS new(2)
PionStructure (int, default=0)
For pi+pi- only: f0+f0(600): K+K- model(0, default), no structure model(1), no f0+f0(600)(2), f0 KLOE(3)
ProtonFF (int, default=1)
ProtonFormFactor old(0), ProtonFormFactor new(1)
QED (int, default=0)
ISR only(0, default), ISR+FSR(1), ISR+INT+FSR(2)
ReplaceMuonsByVirtualPhoton (bool, default=False)
Replace muons by a virtual photon (for FinalState == 0 only).
ScatteringAngleRangeFinalStates (list(float), default=[0.0, 180.0])
Min [0] and Max [1] value for the scattering angle of pions(muons,nucleons,kaons) [deg], default (0, 180)
ScatteringAngleRangePhoton (list(float), default=[0.0, 180.0])
Min [0] and Max [1] value for the scattering angle of photons [deg], default (0, 180)
SearchMax (int, default=100000)
Number of events used to search for maximum of differential cross section
SwitchBeamResolution (int, default=0)
be_r: without beam resolution(0), with beam resolution(1). Works only for pion=11 and pion=12; (0) assumes exact CMS-Energy, (1) each beam ennergy (=CMS-Energy/2) is smeared with Gaussian distribution of the given variance=BeamResolution**2.
Weighted (int, default=0)
generate weighted events
nMaxTrials (int, default=10000)
Maximum trials per event

PrintTauTauMCParticles¶

Print an MCParticle Collection

Package

generators

Library

libgenerators_modules.so

Parameters

collectionName (str, default=’’)
Collection to print
maxLevel (int, default=-1)
Show only up to specified depth level, -1 means no limit
onlyPrimaries (bool, default=True)
Show only primary particles

RemoveMCParticles¶

Remove particles from the MCParticle Collection.

Warning

At the moment, Relations to that MCParticle collection will become invalid and are not fixed automatically

Package

generators

Library

libgenerators_modules.so

Parameters

alsoChildren (bool, default=True)
If true, all children of a particle are removed together with the particle, otherwise children are kept
collectionName (str, default=’’)
Collection to perform the cuts on
maxPt (float, default=0.0)
Maximum Pt value of Particles to be kept. If smaller or equal to minPt, no cut on Pt is performed
maxR (float, default=0.0)
Maximum Rphi value of Particles to be kept. If smaller or equal to minR, no cut on Rphi is performed
maxTheta (float, default=180.0)
Maximum theta value of Particles to be kept
maxZ (float, default=0.0)
Maximum Z value of Particles to be kept. If smaller or equal to minZ, no cut on z is performed
minPt (float, default=0.0)
Minimum Pt value of Particles to be kept. If bigger or equal to maxPt, no cut on Pt is performed
minR (float, default=0.0)
Minimum Rphi value of Particles to be kept. If bigger or equal to maxR, no cut on Rphi is performed
minTheta (float, default=0.0)
Minimum theta value of Particles to be kept
minZ (float, default=0.0)
Minimum Z value of Particles to be kept. If bigger or equal to maxZ, no cut on z is performed
pdgCodes (list(int), default=[])
If not empty, cuts will only be performed on particles matching the given PDG codes. To remove all particles with a given code just set maxTheta to 0 and fill this list with all codes to be removed

SADInput¶

Reads the SAD data from a root file and stores it into the MCParticle collection.

Package

generators

Library

libgenerators_modules.so

Required Parameters

AccRing (int)
The accelerator ring: 0 = LER, 1 = HER
Filename (str)
The filename of the SAD input file.

Parameters

PxResolution (float, default=0.01)
The resolution for the x momentum component of the SAD real particle.
PyResolution (float, default=0.01)
The resolution for the y momentum component of the SAD real particle.
Range (float, default=300.0)
All particles within the range around the IP are loaded [cm].
ReadMode (int, default=0)
The read mode: 0 = one SAD particle per event, 1 = one real particle per event, 2 = all SAD particles per event
ReadoutTime (float, default=20000.0)
The readout time of the detector [ns]
RotateParticles (float, default=0.0)
Rotate the SAD particles around the nominal beam axis [deg] (just for unphysical tests !!!).

SmearPrimaryVertex¶

Smears primary vertex and all subsequent vertices of all the MCParticles using the informations stored in BeamParameters.

Package

generators

Library

libgenerators_modules.so

Parameters

MCParticlesStoreArrayName (str, default=’’)
Name of the MCParticles StoreArray.

TeeggInput¶

Generates events with TEEGG.

Package

generators

Library

libteegginput.so

Parameters

CMSEnergy (float, default=0.0)
CMS energy [GeV] (default: take from xml)
CONFIG (str, default=’EGAMMA’)
Specifies the event configuration (EGAMMA, GAMMA, GAMMAE or ETRON)
CUTOFF (float, default=0.25)
Cutoff energy for radiative corrections (in CM frame) (in GeV)
EEMIN (float, default=2.0)
Minimum energy of the e- (EGAMMA and ETRON conf.) (in GeV)
EEVETO (float, default=0.0)
Minimum energy to veto (GAMMA config with hard rad. corr.) (in GeV)
EGMIN (float, default=2.0)
Minimum energy of the gamma (EGAMMA and GAMMA conf.) (in GeV)
EGVETO (float, default=0.0)
Minimum energy to veto (ETRON/GAMMA config with hard rad. corr.) (in GeV)
EPS (float, default=0.01)
Param. epsilon_s (smaller val. increases sampling of k_s^pbc)
EPSPHI (float, default=0.0001)
Param. epsilon_phi (‘cutoff’ of the phi_ks peak)
FRAPHI (float, default=0.0)
Fraction of time phi_ks is generated with peak(hard rad corr)
MATRIX (str, default=’BKM2’)
Specifies which eeg matrix element (BK, BKM2, TCHAN or EPA)
MTRXGG (str, default=’EPADC’)
Specifies which eegg matrix element (EPADC, BEEGG or MEEGG)
PEGMIN (float, default=0.0)
Minimum phi sep of e-gamma (EGAMMA config with hard rad. corr.) (in deg)
PHVETO (float, default=0.0)
Minimum phi sep to veto (ETRON/GAMMA config with hard rad. corr. (in deg)
RADCOR (str, default=’NONE’)
Specifies radiative correction (NONE, SOFT or HARD)
TEMIN (float, default=20.0)
Minimum angle between the e- and -z axis (EGAMMA conf. only) (in deg)
TEVETO (float, default=0.1)
Maximum theta of e+ in final state (in deg)
TGMIN (float, default=20.0)
Minimum angle between the gamma and -z axis (in deg)
TGVETO (float, default=0.05)
Maximum angle between the gamma and -z axis(ETRON conf. only) (in deg)
UNWEIGHTED (int, default=1)
If true then generate unweighted events
VACPOL (str, default=’hlmnt’)
Vacuum polarization: off, nsk (Novosibirsk) or hlmnt (Teubner et al., default)
WGHT1M (float, default=1.001)
Maximum weight for generation of QP0, cos(theta QP)
WGHTMX (float, default=1.0)
Maximum weight for the trial events

TouschekTURTLEInput¶

Reads the Touschek data from a TURTLE file and stores it into the MCParticle collection.

Package

generators

Library

libgenerators_modules.so

Required Parameters

FilenameHER (str)
The filename of the HER TURTLE input file.
FilenameLER (str)
The filename of the LER TURTLE input file.

Parameters

MaxParticles (int, default=-1)
The maximum number of particles per event that should be read. -1 means all of the particles are read.
ReadHER (bool, default=True)
Set to false to skip reading the HER data.
ReadLER (bool, default=True)
Set to false to skip reading the LER data.
zCoordinate (float, default=50.0)
Indicates the z-coordinate of the TURTLE particles in the file. (default is 50cm, 400cm is also implemented.)

TrepsInput¶

Input from TREPS generator (No-tag), Input from TREPS generator for ee->ee hadrons

Package

generators

Library

libtrepsinput.so

Parameters

ApplyCosThetaCutCharged (bool, default=True)
Whether to apply cut on $|cos(theta)|$ for charged particles only.
ApplyTransverseMomentumCutCharged (bool, default=True)
Whether to apply cut on the minimal transverse momentum for charged particles only.
DifferentialCrossSectionFile (str, default=’pipidcs.dat’)
file name for differential cross section table input. If UseDiscreteAndSortedW is true, the file is used
MaximalAbsCosTheta (float, default=1.01)
Maximal $|\cos(\theta)|$, where $\theta$ is the final-state particle polar angle.
MaximalQ2 (float, default=-1.0)
Maximal $Q^2 = -q^2$, where q is the difference between the initial and final electron or positron momenta. Negative means no cut.
MinimalTransverseMomentum (float, default=0.0)
Minimal transverse momentum of the final-state particles.
ParameterFile (str, default=’treps_par.dat’)
parameter file for TREPS input
UseDiscreteAndSortedW (bool, default=False)
if true, use WListTable for discrete and sorted W. if false (default), use DifferentialCrossSection
WListTableFile (str, default=’wlist_table.dat’)
file name for W-List table input. If UseDiscreteAndSortedW is false (default), the file is used