Functions
def	get_default_decayfile ()

def	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)

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

def	add_kkmc_generator (path, finalstate='', signalconfigfile='', useTauolaBelle=False, tauinputfile='')

def	add_evtgen_generator (path, finalstate='', signaldecfile=None, coherentMixing=True, parentParticle='Upsilon(4S)')

def	add_continuum_generator (path, finalstate, userdecfile='', *skip_on_failure=True)

def	add_inclusive_continuum_generator (path, finalstate, particles, userdecfile='', *include_conjugates=True, max_iterations=100000)

def	add_bhwide_generator (path, minangle=0.5)

def	add_babayaganlo_generator (path, finalstate='', minenergy=0.01, minangle=10.0, fmax=-1.0, generateInECLAcceptance=False)

def	add_phokhara_generator (path, finalstate='')

def	add_phokhara_evtgen_combination (path, final_state_particles, user_decay_file, beam_energy_spread=True)

def	add_koralw_generator (path, finalstate='', enableTauDecays=True)

def	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)

def	add_treps_generator (path, finalstate='', useDiscreteAndSortedW=False)

Detailed Description

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`_

Contact: Torben Ferber (ferber@physics.ubc.ca)

.. _BELLE2-NOTE-PH-2015-006: https://docs.belle2.org/record/282

Function Documentation

◆ add_aafh_generator()

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

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)

Definition at line 84 of file generators.py.

 def add_aafh_generator(
         path,
         finalstate='',
         preselection=False,
         enableTauDecays=True,
         minmass=0.5,
         subweights=[],
         maxsubweight=1,
         maxfinalweight=3.0):
     """
     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)
     """
  
     if finalstate == 'e+e-e+e-':
         aafh_mode = 5
         if not subweights:  # default subweights are for minmass=0.5
             aafh_subgeneratorWeights = [1.0, 7.986e+01, 5.798e+04, 3.898e+05, 1.0, 1.664e+00, 2.812e+00, 7.321e-01]
         else:
             aafh_subgeneratorWeights = subweights
         if abs(minmass - 0.5) > 0.01 and not subweights:
             B2WARNING("add_aafh_generator: non default invariant mass cut without updated subweights requested!")
     elif finalstate == 'e+e-mu+mu-':
         aafh_mode = 3
         if not subweights:  # default subweights are for minmass=0.5
             aafh_subgeneratorWeights = [1.000e+00, 1.520e+01, 3.106e+03, 6.374e+03, 1.000e+00, 1.778e+00, 6.075e+00, 6.512e+00]
         else:
             aafh_subgeneratorWeights = subweights
         if abs(minmass - 0.5) > 0.01 and not subweights:
             B2WARNING("add_aafh_generator: non default invariant mass cut without updated subweights requested!")
     elif finalstate == 'e+e-tau+tau-':
         aafh_mode = 4
         particle = 'tau-'
         minmass = 0
         if not subweights:
             aafh_subgeneratorWeights = [1.000e+00, 2.214e+00, 1.202e+01, 1.536e+01, 1.000e+00, 1.664e+00, 1.680e+01, 6.934e+00]
         else:
             aafh_subgeneratorWeights = subweights
         if preselection:
             B2WARNING(
                 f"You requested a generator preselection for the final state {finalstate}: "
                 "please consider to remove it, since the cross section is small.")
     elif finalstate == 'mu+mu-mu+mu-':
         aafh_mode = 2
         minmass = 0
         maxsubweight = 3
         if not subweights:
             aafh_subgeneratorWeights = [0.000e+00, 0.000e+00, 1.000e+00, 3.726e+00, 1.000e+00, 1.778e+00, 1.000e+00, 1.094e+00]
         else:
             aafh_subgeneratorWeights = subweights
         if preselection:
             B2WARNING(
                 f"You requested a generator preselection for the final state {finalstate}: "
                 "please consider to remove it, since the cross section is small.")
     elif finalstate == 'mu+mu-tau+tau-':
         aafh_mode = 1
         particle = 'tau-'
         minmass = 0
         maxsubweight = 3
         if not subweights:
             aafh_subgeneratorWeights = [0.000e+00, 0.000e+00, 1.000e+00, 1.715e+00, 1.000e+00, 1.778e+00, 1.000e+00, 6.257e-01]
         else:
             aafh_subgeneratorWeights = subweights
         if preselection:
             B2WARNING(
                 f"You requested a generator preselection for the final state {finalstate}: "
                 "please consider to remove it, since the cross section is small.")
     elif finalstate == 'tau+tau-tau+tau-':
         B2FATAL(f"AAFH is not able to generate the {finalstate} final state. Please use KoralW instead.")
     else:
         B2FATAL(f"add_aafh_generator final state not supported: {finalstate}")
  
     aafh_maxSubgeneratorWeight = maxsubweight
     aafh_maxFinalWeight = maxfinalweight
  
     path.add_module(
         'AafhInput',
         mode=aafh_mode,
         rejection=2,
         maxSubgeneratorWeight=aafh_maxSubgeneratorWeight,
         maxFinalWeight=aafh_maxFinalWeight,
         subgeneratorWeights=aafh_subgeneratorWeights,
         suppressionLimits=[1e100] * 4,
         minMass=minmass
     )
  
     if preselection:
         generator_emptypath = create_path()
         add_generator_preselection(
             path=path,
             emptypath=generator_emptypath,
             nChargedMin=1,
             MinChargedPt=0.1,
             MinChargedTheta=17.0,
             MaxChargedTheta=150.0)
  
     if 'tau+tau-' in finalstate:
         if enableTauDecays:
             path.add_module('EvtGenDecay')
         else:
             B2WARNING("The tau decays will not be generated.")
  
  

◆ add_babayaganlo_generator()

def generators.add_babayaganlo_generator	(	path,
		finalstate = `''`,
		minenergy = `0.01`,
		minangle = `10.0`,
		fmax = `-1.0`,
		generateInECLAcceptance = `False`
	)

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.

Definition at line 476 of file generators.py.

◆ add_bhwide_generator()

def generators.add_bhwide_generator	(	path,
		minangle = `0.5`
	)

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

Definition at line 453 of file generators.py.

◆ add_continuum_generator()

def generators.add_continuum_generator	(		path,
			finalstate,
			userdecfile = `''`,
		*	skip_on_failure = `True`
	)

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

Definition at line 331 of file generators.py.

◆ add_cosmics_generator()

def 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`
	)

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).

Definition at line 684 of file generators.py.

◆ add_evtgen_generator()

def generators.add_evtgen_generator	(	path,
		finalstate = `''`,
		signaldecfile = `None`,
		coherentMixing = `True`,
		parentParticle = `'Upsilon(4S)'`
	)

Add EvtGen for mixed and charged BB

Parameters:
    path (basf2.Path): path where the generator should be added
    finalstate (str): Either "charged" for B+/B- or "mixed" for B0/anti-B0
    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 interla limiation 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).

Definition at line 263 of file generators.py.

◆ add_generator_preselection()

def 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`
	)

    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 fullfilled.
    If not, the events are given to the emptypath.
    The main usecase 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

Definition at line 22 of file generators.py.

◆ add_inclusive_continuum_generator()

def generators.add_inclusive_continuum_generator	(		path,
			finalstate,
			particles,
			userdecfile = `''`,
		*	include_conjugates = `True`,
			max_iterations = `100000`
	)

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:
    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 <LogLevel.FATAL>` error so for rare particles one might need a
        larger number.

Definition at line 411 of file generators.py.

◆ add_kkmc_generator()

def generators.add_kkmc_generator	(	path,
		finalstate = `''`,
		signalconfigfile = `''`,
		useTauolaBelle = `False`,
		tauinputfile = `''`
	)

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.

Definition at line 192 of file generators.py.

◆ add_koralw_generator()

def generators.add_koralw_generator	(	path,
		finalstate = `''`,
		enableTauDecays = `True`
	)

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)

Definition at line 648 of file generators.py.

◆ add_phokhara_evtgen_combination()

def generators.add_phokhara_evtgen_combination	(	path,
		final_state_particles,
		user_decay_file,
		beam_energy_spread = `True`
	)

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).

Definition at line 564 of file generators.py.

◆ add_phokhara_generator()

def generators.add_phokhara_generator	(	path,
		finalstate = `''`
	)

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 possible final state "mu+mu-", "pi+pi-", "pi+pi-pi0"

Definition at line 531 of file generators.py.

◆ add_treps_generator()

def generators.add_treps_generator	(	path,
		finalstate = `''`,
		useDiscreteAndSortedW = `False`
	)

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.

Definition at line 803 of file generators.py.

◆ get_default_decayfile()

def generators.get_default_decayfile ( )

Return the default DECAY.dec for Belle2

Definition at line 17 of file generators.py.

Functions