6. List of Core Modules

This page contains a list of all modules in the framework package.

Note

If you are just getting started with your first analysis in basf2: While these modules are at the core of basf2, you will probably not need to use them directly for common tasks. Instead, head over to the documentation of the Analysis.

Of special importance to the users are the following modules:

• EventInfoSetter is used to create empty events and should usually be the first module in the path if new events are to be generated.

• RootOutput is used to write events to disk. This module can be added at any point in time and will usually write out the complete contents of the DataStore. For convenience there are special functions like mdst.add_mdst_output() which will limit the output to certain collections.

• RootInput can be used to read events created with RootOutput

EventErrorFlag

Returns error flags of the EventMetaData and can add further error flags.

Package:

framework

Library:

libcore.so

Parameters:

• errorFlag (int, default=0)

  Error flags to add

EventInfoPrinter

Prints the current event meta data information (exp, run, event numbers). LogLevel need to be set to INFO, at least for this module.

Package:

framework

Library:

libcore.so

Parameters:

• printTime (bool, default=False)

  Print time in addition to exp/run/evt numbers.

EventInfoSetter

Sets the event meta data information (exp, run, evt). You must use this module to tell basf2 about the number of events you want to generate, unless you have an input module that already does so. Note that all experiment/run combinations specified must be unique.

Package:

framework

Library:

libcore.so

Parameters:

• evtNumList (list(unsigned int), default=[1])

  List of the number of events which should be processed. Can be overridden via -n argument to basf2.

• expList (list(int), default=[0])

  List of experiment numbers. Can be overridden via –experiment argument to basf2.

• runList (list(int), default=[0])

  List of run numbers. Can be overridden via –run argument to basf2.

• skipNEvents (unsigned int, default=0)

  Skip this number of events before starting. Equivalent to running over this many events without performing any action, to allow starting at higher event numbers.

• skipToEvent (list(int), default=[])

  Skip events until the event with the specified (experiment, run, event number) occurs. This parameter is useful for debugging to start with a specific event.

EventLimiter

Allows you to set limits on the number of events per run passing this module. It returns True until the limit is reached, after which it returns False. basf2 conditional paths can then be used to prevent events continuing onwards from this module.

Package:

framework

Library:

libcore.so

Parameters:

• maxEventsPerRun (int, default=-1)

  Maximum number of events that will have True returned on them per run. This module returns True until the limit in a particular run is reached, it then returns False. It will only start returning True again once a new run begins. The default value (-1) means that this module always returns True regardless of how many events are processed in a run.

Gearbox

Loads the Belle II detector parameters from an XML document.

Package:

framework

Library:

libgearbox.so

Parameters:

• backends (list(str), default=[‘file:’])

  The backends to use when looking for xml data. A backend can also contain a search path after ‘:’. (If none is given, ‘/data’ will be used.)

• fileName (str, default=’geometry/Belle2.xml’)

  The filename of the main xml file

• override (list(tuple(str, str, str)), default=[])

  Override single values from the XML file. This should be a list of tuples containing an xpath expression, a value and a unit (which can be empty). The xpath expression must resolve to exactly one node in the XML tree which does not contain any children except text. The supplied value and unit will be set for this node. See framework/examples/gearbox_override.py

• overrideMultiple (list(tuple(str, str, str)), default=[])

  Same as override but the xpath expression may evaluate to more than one node in which case all occurances are set to the supplied value and unit

• overridePrefix (str, default=’/Detector’)

  Common prefix which is prepended to all overrides. Beware that ‘//’ has a special meaning meaning in xpath so be careful with leading and trailing slashes in the overrides and the prefix respectively

HistoManager

Manage histograms/Ntuples/TTrees for modules inheriting from the HistoModule class. See https://xwiki.desy.de/xwiki/rest/p/297bb for details.

Package:

framework

Library:

libhistomanager.so

Parameters:

• histoFileName (str, default=’histofile.root’)

  Name of histogram output file.

• workDirName (str, default=’.’)

  Name of working directory.

Interactive

Start an interactive (I)python shell in each call of event(). Also imports the ROOT.Belle2 namespace for convenience, allowing you to use Belle2.PyStoreArray etc. directly.

Package:

framework

Library:

libcore.so

IoVDependentCondition

Module which sets its return value based on the fact, if the event is in the given run/exp interval or not. If you set the maximal value of experiment and run to -1, there will be no upper limit for the interval. If you only set the maximal run to -1, there is no upper limit on the run number.

Package:

framework

Library:

libcore.so

Required Parameters:

• iovList (list(tuple(int, int, int, int)))

  The list of IoV to test in the format [(min exp, min run, max exp, max run), …].If multiple IoVs are given, their union will be checked against the event’s IoV.

PartialSelect

This module helps you set the interval of events to process. It returns True inside the set window and False outside.

The input parameters are fractions which can be interpretted as the fraction of leading and (1-)fraction of trailing events that will be skipped. Internally, the total number of events of the input file is used to determine the event selection window boundaries.

basf2 conditional paths can then be used to select events that pass this module for further processing.

This module can be used with GRID jobs when dataset collections are passed as input. It helps you control the range of events per file so that you can avoid processing all of the events but still cover all the files in the collection.

NOTE: This module has to be added directly after the input module so as to filter out events before any other processing. It also only works with one input file for now.

Package:

framework

Library:

libcore.so

Parameters:

• entryStart (float, default=0.0)

  The product of entryStart fraction and total number of events in each file will determine the first event to begin processing with. Module will return False for all leading events before this. By default(0.0) module will start with the first event.

• entryStop (float, default=1.0)

  The product of entryStop fraction and total number of events in each file will determine the last event to end processing with. Module will return False for all trailing events after this. By default(1.0) module will end wtih the last event.

Prescale

Returns True or False randomly for each event. Fraction of the time that True is returned is set by the ‘prescale’ parameter. You can use conditional basf2 paths to allow only the events that return True (or False) to continue.

Package:

framework

Library:

libcore.so

Parameters:

• prescale (float, default=1.0)

  Fraction of events that will return True from this module. Range(0.0 -> 1.0)

PrintBeamParameters

Print the BeamParameters everytime they change

Package:

framework

Library:

libcore.so

PrintCollections

Prints the contents of the DataStore in an event, listing all objects and arrays (including size).

Package:

framework

Library:

libcore.so

Parameters:

• printForEvent (int, default=-1)

  Print the collections only for a specific event number. If set to -1 (default) only the collections of the first event will be printed, if set to 0, the collections of all events will be printed, which might be a lot of output.

Profile

Records execution time and memory usage in ProfileInfo objects for each event. Can also graph memory usage.

Package:

framework

Library:

libprofile.so

Parameters:

• outputFileName (str, default=’’)

  File name of virtual memory usage plot.

• rssOutputFileName (str, default=’’)

  File name of rss memory usage plot.

Progress

Periodically writes the number of processed events/runs to the logging system to give a progress indication. The output is logarithmic, meaning it will output the first 10 events, then every tenth event up to 100, then every hundreth event up to 1000, etc. Output cannot be suppressed using set_log_level. If you don’t want messages, you don’t want this module

Package:

framework

Library:

libcore.so

Parameters:

• maxN (unsigned int, default=3)

  At most, 10^N events will lie between outputs

ProgressBar

Display a progress bar and an estimate of remaining time when number of events is known (e.g. reading from file, or -n switch used).

The progress bar uses stderr for its output, so it works best when stdout is piped to a file. However it should also work when printing direct to a terminal.

Changed in version release-03-00-00: the module now detects if it outputs to a terminal or into a file and will only update the bar if it has changed and not use any control characters to make log files much more readable than before.

Package:

framework

Library:

libcore.so

PruneDataStore

Clears the content of the DataStore while it keeps entries listed in the matchEntries option. The EventMetaData object will always be kept, as it is required by the framework to properly work with the DataStore.

This logic can be inverted to remove only the entries matched by the regex in the matchEntries parameter by setting the parameter to keepMatchedEntries to False.

Note:

Also all Relations will be cleared if they are not matched by one entry in the matchEntries list. You have to ensure the objects referenced by kept relations are also matched by one entry in the keepEntries list so a relation does not point to nirvana.

Package:

framework

Library:

libcore.so

Parameters:

• keepMatchedEntries (bool, default=True)

  If true, all entries matched by the regular expression are kept. If false, matched entries will be removed.

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

  name of all DataStore entries (with regular expression syntax) to match. For example, you can use ‘Raw.*’ to match all Raw-Objects.

RandomBarrier

Sets gRandom to an independent generator for the following modules. E.g. a module chain of the sort [ParticleGun -> RandomBarrier -> FullSim] would use one RNG instance for the ParticleGun, and another for FullSim and all following modules. You may find this useful if you want to change the simulation, but don’t want differences to affect the particle generation. The output is equivalent to saving the output of ParticleGun in a file, and reading it again to do the simulation. Correct separation is not provided for terminate(), don’t use random numbers there.

Package:

framework

Library:

libcore.so

RootInput

Reads objects/arrays from one or more .root files saved by the RootOutput module and makes them available through the DataStore. Files do not necessarily have to be local, http:// and root:// (for files in xrootd) URLs are supported as well.

Package:

framework

Library:

librootio.so

Parameters:

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

  Names of event durability branches to be read. Empty means all branches. (EventMetaData is always read)

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

  Names of persistent durability branches to be read. Empty means all branches. (FileMetaData is always read)

• cacheSize (int, default=0)

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

• collectStatistics (bool, default=False)

  Collect statistics on amount of data read and print statistics (seperate for input & parent files) after processing. Data is collected from TFile using GetBytesRead(), GetBytesReadExtra(), GetReadCalls()

• discardErrorEvents (bool, default=True)

  Discard events with an error flag != 0

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

  The number sequences (e.g. 23:42,101) defining the entries which are processed for each inputFileName.Must be specified exactly once for each file to be opened.The first event has the entry number 0.

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

  Names of event durability branches NOT to be read. Takes precedence over branchNames.

• excludeBranchNamesPersistent (list(str), default=[‘ProcessStatistics’])

  Names of persistent durability branches NOT to be read. Takes precedence over branchNamesPersistent.

• ignoreCommandLineOverride (bool, default=False)

  Ignore override of file name via command line argument -i.

• inputFileName (str, default=’’)

  Input file name. For multiple files, use inputFileNames or wildcards instead. Can be overridden using the -i argument to basf2.

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

  List of input files. You may use shell-like expansions to specify multiple files, e.g. ‘somePrefix_*.root’ or ‘file_[a,b]_[1-15].root’. Can be overridden using the -i argument to basf2.

• isSecondaryInput (bool, default=False)

  When using a second RootInputModule in an independent path [usually if you are using add_independent_merge_path(…)] this has to be set to true

• parentLevel (int, default=0)

  Number of generations of parent files (files used as input when creating a file) to be read. This can be useful if a file is missing some information available in its parent. See https://xwiki.desy.de/xwiki/rest/p/077a2 for details.

• silentErrrorDiscardMask (unsigned int, default=16)

  Bitmask of error flags to silently discard without raising a WARNING. Should be a combination of the ErrorFlags defined in the EventMetaData. No Warning will be issued when discarding an event if the error flag consists exclusively of flags present in this mask

• skipNEvents (unsigned int, default=0)

  Skip this number of events before starting.

• skipToEvent (list(int), default=[])

  Skip events until the event with the specified (experiment, run, event number) occurs. This parameter is useful for debugging to start with a specific event.

RootOutput

Writes DataStore objects into a .root file. Data is stored in a TTree ‘tree’ for event-dependent and in ‘persistent’ for peristent data. You can use RootInput to read the files back into basf2.

Package:

framework

Library:

librootio.so

Parameters:

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

  Add additional event branch names without the need to specify all branchnames.

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

  Add additional persistent branch names without the need to specify all branchnames.

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

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

• autoFlushSize (int, default=-10000000)

  Value for TTree SetAutoFlush(): a positive value tells ROOT to flush all baskets to disk after n entries, a negative value to flush after -n bytes

• autoSaveSize (int, default=-10000000)

  Value for TTree SetAutoSave(): a positive value tells ROOT to write the TTree metadata after n entries, a negative value to write the metadata after -n bytes

• basketSize (int, default=32000)

  Basketsize for Branches in the Tree in bytes

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

  Names of event durability branches to be saved. Empty means all branches. Objects with c_DontWriteOut flag added here will also be saved. (EventMetaData is always saved)

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

  Names of persistent durability branches to be saved. Empty means all branches. Objects with c_DontWriteOut flag added here will also be saved. (FileMetaData is always saved)

• buildIndex (bool, default=False)

  Build Event Index for faster finding of events by exp/run/event number

• compressionAlgorithm (int, default=0)

  Set the Compression algorithm. Recommended values are 0 for default, 1 for zlib and 4 for lz4

  Added in version release-03-00-00.

• compressionLevel (int, default=1)

  0 for no, 1 for low, 9 for high compression. Level 1 usually reduces size by >50%, higher levels have no noticeable effect. On typical hard disks, disabling compression reduces write time by 10-20 %, but almost doubles read time, so you probably should leave this turned on.

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

  Names of event durability branches NOT to be saved. Branches also in branchNames are not saved.

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

  Names of persistent durability branches NOT to be saved. Branches also in branchNamesPersistent are not saved.

• ignoreCommandLineOverride (bool, default=False)

  Ignore override of file name via command line argument -o. Useful if you have multiple output modules in one path.

• keepParents (bool, default=False)

  Keep parents files of input files, input files will not be added as output file’s parents

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

  Name of the output file. Can be overridden using the -o argument to basf2.

• outputSplitSize (unsigned long int or None, default=None)

  If given split the output file once the file has reached the given size in MB. If set the filename will end in .f{index:05d}.root. So if for example outputFileName is set to “RootOutput.root” then the files will be named RootOutput.f00000.root, RootOutput.f00001.root, RootOutput.f00002.root, …

  All created output files are complete and independent files and can subsequently processed completely independent.

  Note

  The output files will be approximately of the size given by outputSplitSize but they will be slightly larger since additional information has to be written at the end of the file. If necessary please account for this. Also, using buildIndex=False might be beneficial to reduce the overshoot.

  Warning

  This will set the amount of generated events stored in the file metadata to zero as it is not possible to determine which fraction ends up in which output file.

  Added in version release-03-00-00.

• splitLevel (int, default=99)

  Branch split level: determines up to which depth object members will be saved in separate sub-branches in the tree. For arrays or objects with custom streamers, -1 is used instead to ensure the streamers are used. The default (99) usually gives the highest read performance with RootInput.

• updateFileCatalog (bool, default=False)

  Flag that specifies whether the file metadata catalog is updated or created. This is only necessary in special cases and can always be done afterwards using b2file-catalog-add filename.root”

  (You can also set the BELLE2_FILECATALOG environment variable to NONE to get the same effect as setting this to false)

SeqRootInput

Read .sroot files produced by SeqRootOutput.

Package:

framework

Library:

librootio.so

Parameters:

• declareRealData (bool, default=False)

  Declare the input to be real, not generated data

• fileNameIsPattern (bool, default=False)

  If true interpret the output filename as a boost::format pattern instead of the standard where subsequent files are named .sroot-N. For example ‘myfile-f%08d.sroot’

• inputFileName (str, default=’’)

  Input file name. Can also be a gzip-compressed file (with suffix .gz). Parameter can be overridden using the -i argument to basf2.

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

  List of input files

SeqRootOutput

Save a sequential ROOT file (non-standard I/O format used in DAQ). See https://xwiki.desy.de/xwiki/rest/p/401e7 for further information and a comparison with the .root format.

Package:

framework

Library:

librootio.so

Parameters:

• compressionLevel (int, default=0)

  Compression Level: 0 for no, 1 for low, 9 for high compression. Level 1 usually reduces size by 50%, higher levels have no noticable effect. NOTE: Because of a ROOT bug ( https://sft.its.cern.ch/jira/browse/ROOT-4550 ), this option currently causes memory leaks and is disabled.

• fileNameIsPattern (bool, default=False)

  If true interpret the output filename as a boost::format pattern instead of the standard where subsequent files are named .sroot-N. For example ‘myfile-f%08d.sroot’

• outputFileName (str, default=’SeqRootOutput.sroot’)

  Output file name. Add a .gz suffix to save a gzip-compressed file. Parameter can be overridden using the -o argument to basf2.

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

  List of objects/arrays to be saved

StatisticsSummary

Sums up the statistics of preceeding modules. All modules until the first module or another StatisticsSummary module in the module statistics are included.

Package:

framework

Library:

libprofile.so

TheKiller

This Modules kills basf2 as horribly as possible (or as selected)

With this module you can kill basf2 in a variety of ways to test what happens if processing is interrupted by

• std::abort()

• std::terminate()

• std::quick_exit()

• std::exit(N)

• uncaught exception

• signal

• segfault

• bus error

This error can occur in a selected event to test behavior during processing.

Package:

framework

Library:

libcore.so

Required Parameters:

• event (int)

  In which event to kill the processing

Parameters:

• method (str, default=’abort’)

  How to kill the event, one of (abort, terminate, quick_exit, exit, exception, signal, segfault, buserror)

• parameter (unsigned int, default=0)

  Optional parameter for the kill method: for quick_exit and exit it is the return code, for signal it is the signal number