Background Package

9. Background Package#

In the following we describe the background package (documentation still under development).

The background package is how we introduce beam background hit rates in MC samples. Things users should consider when using this package are the following:

  • Run conditions (i.e. indepedent vs dependent MC samples):

    • Run Indepedent or Simulated Beam Backgrounds: The experiment number used for “Exp: 100X” (ex. 1002 for phase 2, 1003 for phase 3 Run 1, and 1004 for Run 2). The files produced from these ‘experiments’ are in coordination with the background group and are used in run-independent MC proudction.

    • Run Dependent or Random Trigger Events: These files are used to produce BG overlay files for use in run-dependent MC production. Essentially, a random trigger is used to collect events that don’t contain physic signals and therefore represent the effect of beam backgrounds and detector noise.

  • Method in which one wants to include backgrounds (i.e. Overlay vs. Mixing)

    • Overlay (default method): Adding raw hits (digits or waveforms) of measured (or simulated) background to simulated physics event. In case of simulated background the raw hits are prepared by background mixing.

    • Mixing: Adding simulated hits of many simulated background events to a single simulated physics event. Each simulated background event is in addition randomly shifted within the given time window. The number of events added is determined from the rate of a particular background type. There are two categories: beam-induced backgrounds (Touschek, beam-gas interactions etc), luminosity backgrounds (radiative Bhabha, two-photon). The former ones are simulated with SAD simulation provided by the Accelerator group and the latter ones within basf2 using the corresponding particle generator. The rates of the beam-induced backgrounds depend on the accelerator lattice, collimator settings, gas pressure and beam currents, while the rates of luminosity backgrounds are proportional to luminosity. Needless to say that this method is slow and very much statistically limited. For the list of background types see framework/dataobjects/include/BackgroundMetaData.h

For details on background overlays for each release, see here: Data Production Gitlab for BGOverlays

For details for run dependent generation, see here: Data Production Gitlab For MCRD Production

9.1. Useful Python Tools:#

background.add_output(path, bgType, realTime, sampleType, phase=3, fileName='output.root', excludeBranches=None)[source]#

A function to be used for output of BG simulation.

Parameters:

  • path – path name

  • bgType – background type, to get available types: basf2 -m BeamBkgTagSetter

  • realTime – equivalent time of superKEKB running in [ns]

  • sampleType – ‘study’ (for BG studies) or ‘usual’, ‘PXD’, ‘ECL’ (for BG mixer)

  • specify – the Phase, 1 for Phase 1, 2 for Phase 2, and 3 for Physics Run or Phase 3

  • fileName – optional file name, can be overridden by basf2 -o

background.get_background_files(folder=None, output_file_info=True)[source]#

Loads the location of the background files from the environmant variable BELLE2_BACKGROUND_DIR which is set on the validation server and ensures that background files exist and returns the list of background files which can be directly used with add_simulation() :

>>> add_simulation(main, bkgfiles=background.get_background_files())

Will fail with an assert if no background folder set or if no background file was found in the set folder.

Parameters:

  • folder (str) – A specific folder to search for background files can be given as an optional parameter

  • output_file_info (str) – If true, a list of the found background files and there size will be printed This is useful to understand later which background campaign has been used to simulate events.

9.2. Modules#

This is a list of the background modules.

BGOverlayExecutor#

Overlay of measured background with simulated data

Package:

background

Library:

libBGOverlayExecutor.so

Parameters:
  • ARICHDigitsName (str, default=’’)

    name of ARICH collection to overlay with BG

  • CDCHitsName (str, default=’’)

    name of CDC collection to overlay with BG

  • KLMDigitsName (str, default=’’)

    name of KLM collection to overlay with BG

  • PXDDigitsName (str, default=’’)

    name of PXD collection to overlay with BG

  • SVDShaperDigitsName (str, default=’’)

    name of SVD collection to overlay with BG

  • TOPDigitsName (str, default=’’)

    name of TOP collection to overlay with BG

  • bkgInfoName (str, default=’’)

    name of the BackgroundInfo StoreObjPtr

  • components (list(str), default=[])

    Detector components to be included in overlay (empty list means all)

BGOverlayInput#

Input for BG overlay, either in form of Digits or raw data. For run-dependent MC (experiments 1 to 999) the overlay samples corresponding to the simulated run are automatically selected from the input list at each beginRun(), enabling production of multiple runs in a single job. This feature can be turned off by setting ignoreRunNumbers to True.

Package:

background

Library:

libBGOverlayInput.so

Required Parameters:
  • inputFileNames (list(str))

    List of files with measured beam background

Parameters:
  • bkgInfoName (str, default=’’)

    Name of the BackgroundInfo StoreObjPtr

  • extensionName (str, default=’_beamBG’)

    Name added to default branch names

  • ignoreRunNumbers (bool, default=False)

    If True, ignore run numbers in case of run-dependend MC (experiments 1 to 999).

  • skipExperimentCheck (bool, default=False)

    If True, skip the check on the experiment number consistency between the basf2 process and the beam background files; for experiments 1 to 999 ignore also run numbers. By default, it is set to false, since the check should be skipped only by experts.

BeamBkgGenerator#

Beam background generator based on SAD files. The generator picks up particles from the SAD file randomly according to their rates. Number of events is determined from ‘realTime’ and overall rate, and the generator terminates the execution when this number is reached.

Package:

background

Library:

libBeamBkgGenerator.so

Required Parameters:
  • fileName (str)

    name of the SAD file converted to root

  • realTime (float)

    equivalent superKEKB running time to generate sample [ns].

  • ringName (str)

    name of the superKEKB ring (LER or HER)

Parameters:
  • treeName (str, default=’sad’)

    name of the TTree in the SAD file

BeamBkgHitRateMonitor#

A module for off-line monitoring of beam background hit rates.

Package:

background

Library:

libBeamBkgHitRateMonitor.so

Parameters:
  • additionalDataDescription (dict(str -> str), default={})

    Additional dictionary of name->value pairs to be added to the file metadata to describe the data

  • cdcEnableBackgroundHitFilter (bool, default=True)

    CDC: flag to enable the CDC background hit (crosstakl, noise) filter

  • cdcEnableBadWireTreatment (bool, default=True)

    CDC: flag to enable the bad wire treatment

  • cdcEnableMarkBackgroundHit (bool, default=False)

    CDC: flag to enable to mark background flag on CDCHit (set 0x100 bit for CDCHit::m_status).

  • cdcTimeWindowLowerEdgeNormalCell (int, default=4200)

    CDC: lower edge of the time window for normal cells [tdc count = ns]

  • cdcTimeWindowLowerEdgeSmallCell (int, default=4550)

    CDC: lower edge of the time window for small cells [tdc count = ns]

  • cdcTimeWindowUpperEdgeNormalCell (int, default=5050)

    CDC: upper edge of the time window for normal cells [tdc count = ns]

  • cdcTimeWindowUpperEdgeSmallCell (int, default=5050)

    CDC: upper edge of the time window for small cells [tdc count = ns]

  • detectors (list(str), default=[])

    Detectors to be included in the output tree, if empty, all detectors are included

  • outputFileName (str, default=’beamBkgHitRates.root’)

    output file name

  • svdIgnoreHotStripsPayload (bool, default=False)

    If true, also SVD hot strips are counted as active

  • svdIgnoreMaskedStripsPayload (bool, default=False)

    If true, also SVD FADC-masked strips are counted as active

  • svdShaperDigitsName (str, default=’’)

    SVDShaperDigits collection name

  • svdThrCharge (float, default=15000.0)

    Energy cur on SVD Cluster charge in electrons

  • topTimeOffset (float, default=25.0)

    TOP: time offset of hits (to be subtracted) [ns]

  • topTimeWindow (float, default=100.0)

    TOP: time window in which to count hits [ns]

  • treeName (str, default=’tree’)

    output tree name

  • trgTypes (list(int), default=[5, 7, 13])

    trigger types for event selection (see TRGSummary.h for definitions). Empty list means all trigger types.

  • writeEmptyTimeStamps (bool, default=False)

    if true, write to ntuple also empty time stamps

BeamBkgMixer#

Beam background mixer at SimHit level that uses beam background simulation output directly (collision files) and not ROF files. Each background event is shifted in time randomly within a time window specified with minTime and maxTime.

Package:

background

Library:

libBeamBkgMixer.so

Required Parameters:
  • backgroundFiles (list(str))

    List of background (collision) files (wildcards not allowed - use python glob.glob() to expand to list of files)

Parameters:
  • beambackhits (bool, default=False)

    If true also add the BeamBackHits collection for the selected subdetectors to the output file

  • cacheSize (int, default=0)

    file cache size in Mbytes. If negative, use root default

  • components (list(str), default=[])

    Detector components to be included, empty list means all components

  • maxEdepECL (float, default=1.0)

    maximal deposited energy of ECLHit to accept BG event for mixing(0 means accept all events)

  • maxTime (float, default=800.0)

    Time window upper edge in nano seconds

  • maxTimeECL (float, default=8500.0)

    Time window upper edge for ECL in nano seconds

  • maxTimePXD (float, default=10000.0)

    Time window upper edge for PXD in nano seconds

  • minTime (float, default=-1000.0)

    Time window lower edge in nano seconds

  • minTimeECL (float, default=-17600.0)

    Time window lower edge for ECL in nano seconds

  • minTimePXD (float, default=-10000.0)

    Time window lower edge for PXD in nano seconds

  • overallScaleFactor (float, default=1.0)

    Overall factor to scale rates of backgrounds

  • scaleFactors (list(tuple(str, float)), default=[])

    Factors to scale rates of backgrounds. Possible tag names: BHWide, BHWideLargeAngle, BHWide_HER, BHWide_LER, Brems_HER, Brems_LER, Brems_base_HER, Brems_base_LER, Brems_dynamic_HER, Brems_dynamic_LER, Coulomb_HER, Coulomb_LER, Coulomb_base_HER, Coulomb_base_LER, Coulomb_dynamic_HER, Coulomb_dynamic_LER, InjectionHER, InjectionLER, RBB, RBB_HER, RBB_HER_far, RBB_LER, RBB_LER_far, RBB_gamma, SynchRad_HER, SynchRad_LER, Touschek_HER, Touschek_HER_far, Touschek_LER, Touschek_LER_far, twoPhoton, other

  • wrapAround (bool, default=True)

    if true wrap around events passing time window upper edge

BeamBkgTagSetter#

Sets beam background tag variable in SimHits and adds BackgroundMetaData branch in persistent tree; returns true if at least one of the SimHit store arrays has entries. Return value can be used to discard empty events at output.

Package:

background

Library:

libBeamBkgTagSetter.so

Required Parameters:
  • backgroundType (str)

    one of: BHWide, BHWideLargeAngle, BHWide_HER, BHWide_LER, Brems_HER, Brems_LER, Brems_base_HER, Brems_base_LER, Brems_dynamic_HER, Brems_dynamic_LER, Coulomb_HER, Coulomb_LER, Coulomb_base_HER, Coulomb_base_LER, Coulomb_dynamic_HER, Coulomb_dynamic_LER, InjectionHER, InjectionLER, RBB, RBB_HER, RBB_HER_far, RBB_LER, RBB_LER_far, RBB_gamma, SynchRad_HER, SynchRad_LER, Touschek_HER, Touschek_HER_far, Touschek_LER, Touschek_LER_far, twoPhoton, other

  • realTime (float)

    equivalent time of superKEKB running in [ns] to obtain this sample

Parameters:
  • Phase (int, default=3)

    specify the Phase: 1 for Phase 1, 2 for Phase 2, 3 for Physics Run or Phase 3

  • specialFor (str, default=’’)

    tag ordinary file (default) or additional file (‘ECL’ or ‘PXD’)

Contents