Belle II Software development
core.py
1#!/usr/bin/env python3
2
3
10
11"""
12The core module of the Belle II Analysis Software Framework.
13"""
14
15import sys as _sys
16import signal as _signal
17
18# now let's make sure we actually run in python 3
19if _sys.version_info[0] < 3:
20 print("basf2 requires python3. Please run the steering files using basf2 "
21 "(or python3), not python")
22 _sys.exit(1)
23
24# import to override print function
25from basf2 import _override_print # noqa
26
27# import the C++ library with the exported functions
28import pybasf2 # noqa
29# and also import all of them in current scope for ease of use
30from pybasf2 import logging
31from pybasf2 import * # noqa
32
33# make sure conditions objects are read only
34from basf2 import _constwrapper # noqa
35
36
37
38basf2label = 'basf2 (Belle II Analysis Software Framework)'
39
40basf2copyright = 'Copyright(C) 2010-2024 Members of the Belle II Collaboration'
41
42basf2license = '(See "basf2 --license" for more information.)'
43
44# -----------------------------------------------
45# Prepare basf2
46# -----------------------------------------------
47
48# Reset the signal handler to allow the framework execution
49# to be stopped with Ctrl-c (Python installs own handler)
50# This will again be replaced once process() is called.
51_signal.signal(_signal.SIGINT, _signal.SIG_DFL)
52
53
54def register_module(name_or_module, shared_lib_path=None, logLevel=None, debugLevel=None, **kwargs):
55 """
56 Register the module 'name' and return it (e.g. for adding to a path). This
57 function is intended to instantiate existing modules. To find out which
58 modules exist you can run :program:`basf2 -m` and to get details about the
59 parameters for each module you can use :program:`basf2 -m {modulename}`
60
61 Parameters can be passed directly to the module as keyword parameters or can
62 be set later using `Module.param`
63
64 >>> module = basf2.register_module('EventInfoSetter', evtNumList=100, logLevel=LogLevel.ERROR)
65 >>> module.param("evtNumList", 100)
66
67 Parameters:
68 name_or_module: The name of the module type, may also be an existing
69 `Module` instance for which parameters should be set
70 shared_lib_path (str): An optional path to a shared library from which the
71 module should be loaded
72 logLevel (LogLevel): indicates the minimum severity of log messages
73 to be shown from this module. See `Module.set_log_level`
74 debugLevel (int): Number indicating the detail of debug messages, the
75 default level is 100. See `Module.set_debug_level`
76 kwargs: Additional parameters to be passed to the module.
77
78 Note:
79 You can also use `Path.add_module()` directly,
80 which accepts the same name, logging and module parameter arguments. There
81 is no need to register the module by hand if you will add it to the path in
82 any case.
83 """
84
85 if isinstance(name_or_module, pybasf2.Module):
86 module = name_or_module
87 else:
88 module_name = name_or_module
89 if shared_lib_path is not None:
90 module = pybasf2._register_module(module_name, shared_lib_path)
91 else:
92 module = pybasf2._register_module(module_name)
93
94 if kwargs:
95 module.param(kwargs)
96 if logLevel is not None:
97 module.set_log_level(logLevel)
98 if debugLevel is not None:
99 module.set_debug_level(debugLevel)
100
101 return module
102
103
104def set_module_parameters(path, name=None, type=None, recursive=False, **kwargs):
105 """Set the given set of parameters for all `modules <Module>` in a path which
106 have the given ``name`` (see `Module.set_name`)
107
108 Usage is similar to `register_module()` but this function will not create
109 new modules but just adjust parameters for modules already in a `Path`
110
111 >>> set_module_parameters(path, "Geometry", components=["PXD"], logLevel=LogLevel.WARNING)
112
113 Parameters:
114 path (basf2.Path): The path to search for the modules
115 name (str): Then name of the module to set parameters for
116 type (str): The type of the module to set parameters for.
117 recursive (bool): if True also look in paths connected by conditions or `Path.for_each()`
118 kwargs: Named parameters to be set for the module, see `register_module()`
119 """
120
121 if name is None and type is None:
122 raise ValueError("At least one of name or type has to be given")
123
124 if not kwargs:
125 raise ValueError("no module parameters given")
126
127 found = False
128 for module in path.modules():
129 if (name is None or module.name() == name) and (type is None or module.type() == type):
130 # use register_module as this automatically takes care of logLevel
131 # and debugLevel parameters
132 register_module(module, **kwargs)
133 found = True
134
135 if recursive:
136 if module.has_condition():
137 for condition_path in module.get_all_condition_paths():
138 set_module_parameters(condition_path, name, type, recursive, **kwargs)
139 if module.type() == "SubEvent":
140 for subpath in [p.values for p in module.available_params() if p.name == "path"]:
141 set_module_parameters(subpath, name, type, recursive, **kwargs)
142
143 if not found:
144 raise KeyError("No module with given name found anywhere in the path")
145
146
147def remove_module(old_path, name=None):
148 """Provides a new path with all modules that were in the ``old_path`` \
149 except the one with the given ``name`` (see `Module.set_name`)
150
151 Usage is very simple, in this example we remove Geometry the path:
152
153 >>> main = remove_module(main, "Geometry")
154
155 Parameters:
156 old_path (basf2.Path): The path to search for the module
157 name (str): Then name of the module you want to remove
158 """
159
160 if name is None:
161 raise ValueError("You should provide the module name")
162
163 new_path = create_path()
164
165 for module in old_path.modules():
166 if name != module.name():
167 new_path.add_module(module)
168
169 return new_path
170
171
172def create_path():
173 """
174 Creates a new path and returns it. You can also instantiate `basf2.Path` directly.
175 """
176 return pybasf2.Path()
177
178
179def process(path, max_event=0, calculateStatistics=False):
180 """
181 Start processing events using the modules in the given `basf2.Path` object.
182
183 Can be called multiple times in one steering file (some restrictions apply:
184 modules need to perform proper cleanup & reinitialisation, if Geometry is
185 involved this might be difficult to achieve.)
186
187 When used in a Jupyter notebook this function will automatically print a
188 nice progress bar and display the log messages in an advanced way once the
189 processing is complete.
190
191 Note:
192 This also means that in a Jupyter Notebook, modifications to class members
193 or global variables will not be visible after processing is complete as
194 the processing is performed in a subprocess.
195
196 To restore the old behavior you can use ``basf2.core.process()`` which
197 will behave exactly identical in Jupyter notebooks as it does in normal
198 python scripts ::
199
200 from basf2 import core
201 core.process(path)
202
203
204 Parameters:
205 path: The path with which the processing starts
206 max_event: The maximal number of events which will be processed,
207 0 for no limit
208 calculateStatistics: Switch to turn on calculation of processing statistics
209
210 .. versionchanged:: release-03-00-00
211 automatic Jupyter integration
212 """
213
214 # if we are running in an ipython session set the steering file to the
215 # current history
216 try:
217 ipython = get_ipython() # noqa
218 history = "\n".join(e[2] for e in ipython.history_manager.get_range())
219 from ROOT import Belle2
220 Belle2.Environment.Instance().setSteering(history)
221 except NameError:
222 pass
223
224 # If a pickle path is set via --dump-path or --execute-path we do something special
225 if pybasf2.get_pickle_path() != "":
226 from basf2.pickle_path import check_pickle_path
227 path = check_pickle_path(path)
228
229 # apparently nothing to do
230 if path is None:
231 return
232
233 pybasf2.B2INFO("Starting event processing, random seed is set to '" + pybasf2.get_random_seed() + "'")
234
235 if calculateStatistics:
236 from ROOT import Belle2
237 Belle2.Environment.Instance().setStats(True)
238 if max_event != 0:
239 pybasf2._process(path, max_event)
240 else:
241 pybasf2._process(path)
242 if calculateStatistics:
243 from basf2 import statistics
244 print(statistics)
245
246
247def set_log_level(level):
248 """
249 Sets the global log level which specifies up to which level the
250 logging messages will be shown
251
252 Parameters:
253 level (basf2.LogLevel): minimum severity of messages to be logged
254 """
255
256 logging.log_level = level
257
258
259def set_debug_level(level):
260 """
261 Sets the global debug level which specifies up to which level the
262 debug messages should be shown
263
264 Parameters:
265 level (int): The debug level. The default value is 100
266 """
267
268 logging.debug_level = level
269
270
271def log_to_console(color=False):
272 """
273 Adds the standard output stream to the list of logging destinations.
274 The shell logging destination is
275 added to the list by the framework by default.
276 """
277
278 logging.add_console(color)
279
280
281def log_to_file(filename, append=False):
282 """
283 Adds a text file to the list of logging destinations.
284
285 Parameters:
286 filename: The path and filename of the text file
287 append: Should the logging system append the messages to the end of the
288 file (True) or create a new file for each event processing session (False).
289 Default is False.
290 """
291
292 logging.add_file(filename, append)
293
294
295def reset_log():
296 """
297 Resets the logging by removing all logging destinations
298 """
299
300 logging.reset()
301
302
303def _add_module(self, module, logLevel=None, debugLevel=None, **kwargs):
304 """
305 Add given module (either object or name) at the end of this path.
306 All unknown arguments are passed as module parameters.
307
308 >>> path = create_path()
309 >>> path.add_module('EventInfoSetter', evtNumList=100, logLevel=LogLevel.ERROR)
310 <pybasf2.Module at 0x1e356e0>
311
312 >>> path = create_path()
313 >>> eventinfosetter = register_module('EventInfoSetter')
314 >>> path.add_module(eventinfosetter)
315 <pybasf2.Module at 0x2289de8>
316 """
317 module = register_module(module, logLevel=logLevel, debugLevel=debugLevel, **kwargs)
318 self._add_module_object(module)
319 return module
320
321
322def _add_independent_path(self, skim_path, ds_ID='', merge_back_event=None):
323 """
324 Add given path at the end of this path and ensure all modules there
325 do not influence the main DataStore. You can thus use modules in
326 skim_path to clean up e.g. the list of particles, save a skimmed uDST file,
327 and continue working with the unmodified DataStore contents outside of
328 skim_path.
329
330 Parameters:
331 ds_ID: can be specified to give a defined ID to the temporary DataStore,
332 otherwise, a random name will be generated.
333 merge_back_event: is a list of object/array names (of event durability)
334 that will be merged back into the main path.
335 """
336 if merge_back_event is None:
337 merge_back_event = []
338 self._add_independent_path(skim_path, ds_ID, merge_back_event)
339
340
341def _add_independent_merge_path(
342 self,
343 skim_path,
344 ds_ID='',
345 merge_back_event=None,
346 consistency_check=None,
347 event_mixing=False,
348 merge_same_file=False):
349 """
350 Merge specified content of DataStore of independent path into DataStore of main path
351 on a per event level (add tracks/cluster from both events,...).
352
353 Parameters:
354 skim_path: independent path to be merged
355 ds_ID: can be specified to give a defined ID to the temporary DataStore,
356 otherwise, a random name will be generated (option for developers).
357 merge_back_event: is a list of object/array names (of event durability)
358 that will be merged back into the main path.
359 consistency_check: perform additional consistency checks on the objects from two paths.
360 If they are not satisfied, the skim_path proceeds to the next event on the path.
361 Currently supported value is "charge" that uses EventExtraInfo "charge" of the two paths,
362 that must be specified by the user, ensuring correct configuration of the combined event.
363 See CheckMergingConsistencyModule for more details.
364 event_mixing: apply event mixing (merge each event from first path with each event of second path)
365 merge_same_file: merge events from single file (useful for mixing)
366 """
367 if merge_back_event is None:
368 merge_back_event = []
369 if consistency_check is None:
370 consistency_check = ""
371 if merge_same_file:
372 if not event_mixing:
373 pybasf2.B2INFO("add_independent_merge_path: merge_same_file requires event_mixing, setting it to True")
374 event_mixing = True
375 for module in skim_path.modules():
376 if module.type() == "RootInput":
377 module.param("isSecondaryInput", True)
378 self._add_independent_merge_path(skim_path, ds_ID, merge_back_event, consistency_check, event_mixing, merge_same_file)
379
380
381pybasf2.Path.add_module = _add_module
382pybasf2.Path.add_independent_path = _add_independent_path
383pybasf2.Path.add_independent_merge_path = _add_independent_merge_path
static Environment & Instance()
Static method to get a reference to the Environment instance.