13.1. Generators python modules#

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, eventType='')[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)

  • minmass (float) – minimum invariant mass

  • subweights (list(float)) – list of four or eight values (first four are interpreted as WAP, rest as WBP) which specify the relative weights for each of the four sub generators

  • maxsubweight (float) – maximum expected subgenerator weight for rejection scheme

  • maxfinalweight (float) – maximum expected final weight for rejection scheme

  • eventType (str) – event type information

generators.add_babayaganlo_generator(path, finalstate='', minenergy=0.01, minangle=10.0, fmax=- 1.0, generateInECLAcceptance=False, eventType='')[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-), mm(mu+mu-) or gg (gammagamma).

  • minenergy (float) – minimum particle (leptons for ‘ee’ or ‘mm’, 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.

  • eventType (str) – event type information

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, eventType='')[source]#

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

See also

add_inclusive_continuum_generator() to add continuum generation with preselected particles

Parameters

  • path (basf2.Path) – path where the generator should be added

  • finalstate (str) – uubar, ddbar, ssbar, ccbar

  • userdecfile (str) – EvtGen decfile used for particle decays

  • skip_on_failure (bool) – If True stop event processing right after fragmentation fails. Otherwise continue normally

  • eventType (str) – event type information

generators.add_cosmics_generator(path, components=None, global_box_size=None, accept_box=None, keep_box=None, geometry_xml_file='geometry/Beast2_phase2.xml', cosmics_data_dir='data/generators/modules/cryinput/', setup_file='generators/scripts/cry.setup', data_taking_period='gcr2017', top_in_counter=False)[source]#

Add the cosmics generator CRY with the default parameters to the path.

Warning

Please remember to also change the reconstruction accordingly, if you set “special” parameters here!

Parameters

  • path (basf2.Path) – path where the generator should be added

  • components (list(str)) – list of geometry components to add in the geometry module, or None for all components.

  • global_box_size (tuple(float, float, float)) – sets global length, width and height (in meters) in which to generate. Default is [100, 100, 100]

  • accept_box (tuple(float, float, float)) – sets the size of the accept box in meter. As a default it is set to [8.0, 8.0, 8.0] (the Belle II detector size).

  • keep_box (tuple(float, float, float)) – sets the size of the keep box (keep box >= accept box).

  • geometry_xml_file (str) – Name of the xml file to use for the geometry.

  • cosmics_data_dir (str) – parameter CosmicDataDir for the cry module (absolute or relative to the basf2 repo).

  • setup_file (str) – location of the cry.setup file (absolute or relative to the basf2 repo)

  • data_taking_period (str) – The cosmics generation will be added using the parameters, that where used in this period of data taking. The periods can be found in cdc/cr/__init__.py.

  • top_in_counter (bool) – time of propagation from the hit point to the PMT in the trigger counter is subtracted (assuming PMT is put at -z of the counter).

generators.add_evtgen_generator(path, finalstate='', signaldecfile=None, coherentMixing=True, parentParticle='Upsilon(4S)', eventType='')[source]#

Add EvtGen for mixed and charged BB

Parameters

  • path (basf2.Path) – path where the generator should be added

  • finalstate (str) – Either “charged” for generation of generic B+/B-, “mixed” for generic B0/anti-B0, or “signal” for generation of user-defined signal mode

  • signaldecfile (str) – path to decfile which defines the signal decay to be generated (only needed if finalstate set to “signal”)

  • coherentMixing – Either True or False. Switches on or off the coherent decay of the B0-B0bar pair. It should always be True, unless you are generating Y(5,6S) -> BBar. In the latter case, setting it False solves the internal limitation of Evtgen that allows to make a coherent decay only starting from the Y(4S).

  • parentParticle (str) – initial state (used only if it is not Upsilon(4S).

  • eventType (str) – event type information

generators.add_generator_preselection(path, emptypath, nChargedMin=0, nChargedMax=999, MinChargedP=- 1.0, MinChargedPt=- 1.0, MinChargedTheta=0.0, MaxChargedTheta=180.0, nPhotonMin=0, nPhotonMax=999, MinPhotonEnergy=- 1, MinPhotonTheta=0.0, MaxPhotonTheta=180.0, applyInCMS=False, stableParticles=False)[source]#

Adds generator preselection. Should be added to the path after the generator.add_abc_generator but before simulation.add_simulation modules It uses all particles from the event generator (i.e. primary, non-virtual, non-initial particles). It checks if the required conditions are fulfilled. If not, the events are given to the emptypath. The main use case is a reduction of simulation time. Note that you have to multiply the generated cross section by the retention fraction of the preselection.

Parameters

  • path (basf2.Path) – path where the generator should be added

  • emptypath (basf2.Path) – path where the skipped events are given to

  • nChargedMin (int) – minimum number of charged particles

  • nChargedMax (int) – maximum number of charged particles

  • MinChargedP (float) – minimum charged momentum [GeV]

  • MinChargedPt (float) – minimum charged transverse momentum (pt) [GeV]

  • MinChargedTheta (float) – minimum polar angle of charged particle [deg]

  • MaxChargedTheta (float) – maximum polar angle of charged particle [deg]

  • nPhotonMin (int) – minimum number of photons

  • nPhotonMax (int) – maximum number of photons

  • MinPhotonEnergy (float) – minimum photon energy [GeV]

  • MinPhotonTheta (float) – minimum polar angle of photon [deg]

  • MaxPhotonTheta (float) – maximum polar angle of photon [deg]

  • applyInCMS (bool) – if true apply the P,Pt,theta, and energy cuts in the center of mass frame

  • stableParticles (bool) – if true apply the selection criteria for stable particles in the generator

generators.add_inclusive_continuum_generator(path, finalstate, particles, userdecfile='', *, include_conjugates=True, max_iterations=100000, eventType='')[source]#

Add continuum generation but require at least one of the given particles be present in the event.

For example to only generate ccbar events which contain a “D*+” or an electron one could would use

>>> add_inclusive_continuum_generator(path, "ccbar", ["D*+", 11])

If you are unsure how the particles are named in Belle II please have a look at the b2help-particles executable or the pdg python module.

See also

add_continuum_generator() to add continuum generation without preselection

Parameters

  • path (basf2.Path) – path to which the generator should be added

  • finalstate (str) – uubar, ddbar, ssbar, ccbar

  • particles (list) – A list of particle names or pdg codes. An event is only accepted if at lease one of those particles appears in the event.

  • userdecfile (str) – EvtGen decfile used for particle decays

  • include_conjugates (bool) – If True (default) accept the event also if a charge conjugate of the given particles is found

  • max_iterations (int) – maximum tries per event to generate the requested particle. If exceeded processing will be stopped with a FATAL error so for rare particles one might need a larger number.

  • eventType (str) – event type information

generators.add_kkmc_generator(path, finalstate='', signalconfigfile='', useTauolaBelle=False, tauinputfile='', eventType='')[source]#

Add the default muon pair and tau pair generator KKMC. For tau decays, TauolaBelle and TauolaBelle2 are available. Signal events can be produced setting a configuration file. Please notice that the configuration files for TauolaBelle and TauolaBelle2 has a very different structure (see the examples below generators/examples).

Parameters

  • path (basf2.Path) – path where the generator should be added

  • finalstate (str) – either “mu-mu+” or “tau-tau+”

  • signalconfigfile (str) – File with configuration of the signal event to generate. It doesn’t affect mu-mu+ decays.

  • useTauolaBelle (bool) – If true, tau decay is driven by TauolaBelle. Otherwise TauolaBelle2 is used. It doesn’t affect mu-mu+ decays.

  • tauinputfile (str) – File to override KK2f_defaults. Only [sometimes] needed when tau decay is driven by TauolaBelle.

  • eventType (str) – event type information

generators.add_koralw_generator(path, finalstate='', enableTauDecays=True, eventType='')[source]#

Add KoralW generator for radiative four fermion final states (only four leptons final states are currently supported).

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-’, ‘mu+mu-tau+tau-’ or ‘tau+tau-tau+tau-’

  • enableTauDecays (bool) – if True, allow tau leptons to decay (using EvtGen)

  • eventType (str) – event type information

generators.add_phokhara_evtgen_combination(path, final_state_particles, user_decay_file, beam_energy_spread=True, isr_events=False, min_inv_mass_vpho=0.0, max_inv_mass_vpho=0.0, eventType='')[source]#

Add combination of PHOKHARA and EvtGen to the path. Phokhara is acting as ISR generator by generating e+ e- -> mu+ mu-, the muon pair is then replaced by a virtual photon. Finally, the virtual photon is decayed by EvtGen.

Parameters

  • path (basf2.Path) – Path where the generator should be added.

  • final_state_particles (list) – List of final-state particles of the virtual-photon decay. It is necessary to define the correct mass threshold in PHOKHARA. For example, for the process e+ e- -> J/psi eta_c, the list should be [‘J/psi’, ‘eta_c’]; it does not depend on subsequent J/psi or eta_c decays.

  • user_decay_file (str) – Name of EvtGen user decay file. The initial particle must be the virtual photon (vpho).

  • beam_energy_spread (bool) – Whether beam-energy spread should be simulated

  • isr_events (bool) – If true, then PHOKHARA is used with ph0 (LO in basf2) = 0, i.e. generation of processes with one photon.

  • min_inv_mass_hadrons (float) – Minimum invariant mass of the virtual photon. This parameter is used only if isr_events is true, otherwise the minimum mass is computed from the masses of the final-state particles.

  • max_inv_mass_hadrons (float) – Maximum invariant mass of the virtual photon. This parameter is used only if isr_events is true, otherwise the maximum mass is not restricted.

  • eventType (str) – event type information

generators.add_phokhara_generator(path, finalstate='', eventType='')[source]#

Add the high precision QED generator PHOKHARA to the path. Almost full acceptance settings for photons and hadrons/muons.

Parameters

  • path (basf2.Path) – path where the generator should be added

  • finalstate (str) – One of the following final states: “mu+mu-”, “pi+pi-”, “pi+pi-pi0”, “pi+pi-pi+pi-” (or “2(pi+pi-)”), “pi+pi-pi0pi0” or (“pi+pi-2pi0”), “pi+pi-eta”, “K+K-”, “K0K0bar”, “ppbar”, “n0n0bar” or “Lambda0Lambda0bar”

  • eventType (str) – event type information

generators.add_treps_generator(path, finalstate='', useDiscreteAndSortedW=False, eventType='')[source]#

Add TREPS generator to produce hadronic two-photon processes.

Parameters

  • path (basf2.Path) – path where the generator should be added

  • finalstate (str) – “e+e-pi+pi-”, “e+e-K+K-” or “e+e-ppbar”

  • useDiscreteAndSortedW (bool) – if True, wListTableFile is used for discrete and sorted W. evtNumList must be set proper value.

  • eventType (str) – event type information

generators.get_default_decayfile()[source]#

Return the default DECAY.dec for Belle2