Path Class Reference

Implements a path consisting of Module and/or Path objects. More...

#include <Path.h>

Inheritance diagram for Path:

Public Member Functions
	Path ()
	Constructor.
	~Path ()
	Destructor.
void	addModule (const std::shared_ptr< Module > &module)
	Adds a module to the path.
bool	isEmpty () const
	Returns true if this Path doesn't contain any elements.
std::list< std::shared_ptr< Module > >	getModules () const override
	Returns a list of the modules in this path.
std::list< std::shared_ptr< Module > >	buildModulePathList (bool unique=true) const
	Builds a list of all modules which could be executed during the data processing.
void	putModules (const std::list< std::shared_ptr< Module > > &mlist)
	Replaces all Modules and sub-Paths with the specified Module list.
bool	contains (const std::string &moduleType) const
	Does this Path contain a module of the given type?
std::shared_ptr< PathElement >	clone () const override
	Create an independent copy of this path, recreating all contained modules with the same parameters.
void	addPath (const PathPtr &path)
	See 'pydoc3 basf2.Path'.
void	forEach (const std::string &loopObjectName, const std::string &arrayName, PathPtr path)
	See 'pydoc3 basf2.Path'.
void	doWhile (PathPtr path, const std::string &condition, unsigned int maxIterations)
	See 'pydoc3 basf2.Path'.
void	addIndependentPath (const PathPtr &independent_path, std::string ds_ID, const boost::python::list &merge_back)
	See 'pydoc3 basf2.Path'.
void	addIndependentMergePath (const PathPtr &independent_path, std::string ds_ID, const boost::python::list &merge_back, std::string consistency_check, bool event_mixing, bool mergeSameFile)
	See 'pydoc3 basf2.Path'.
std::string	getPathString () const override
	return a string of the form [module a -> module b -> [another path]]

Static Public Member Functions
static void	exposePythonAPI ()
	Exposes methods of the Path class to Python.

Private Attributes
std::list< std::shared_ptr< PathElement > >	m_elements
	The list of path elements (Modules and sub-Paths)

Friends
class	PathIterator

Detailed Description

Implements a path consisting of Module and/or Path objects.

The modules are arranged in a linear order.

Definition at line 38 of file Path.h.

Member Function Documentation

addIndependentMergePath()

void addIndependentMergePath	(	const PathPtr &	independent_path,
		std::string	ds_ID,
		const boost::python::list &	merge_back,
		std::string	consistency_check,
		bool	event_mixing,
		bool	mergeSameFile
	)

See 'pydoc3 basf2.Path'.

Definition at line 135 of file Path.cc.

{
  if (ds_ID.empty()) {
    static int dscount = 1;
    ds_ID = "DS " + std::to_string(dscount++);
  }
  auto mergeBack = PyObjConvUtils::convertPythonObject(merge_back, std::vector<std::string>());
  ModulePtr switchStart = ModuleManager::Instance().registerModule("MergeDataStore");
  static_cast<MergeDataStoreModule&>(*switchStart).init(ds_ID, true, mergeBack);
  ModulePtr switchEnd = ModuleManager::Instance().registerModule("MergeDataStore");
  static_cast<MergeDataStoreModule&>(*switchEnd).init("", false, mergeBack);
  switchStart->setName("MergeDataStore ('' -> '" + ds_ID + "')");
  switchEnd->setName("MergeDataStore ('' <- '" + ds_ID + "')");
 
  ModulePtr fillConsistencyInfo = ModuleManager::Instance().registerModule("CreateConsistencyInfo");
  static_cast<CreateConsistencyInfoModule&>(*fillConsistencyInfo).init(consistency_check, event_mixing);
 
  ModulePtr steerInput = ModuleManager::Instance().registerModule("SteerRootInput");
  static_cast<SteerRootInputModule&>(*steerInput).init(event_mixing, merge_same_file);
 
  //set c_ParallelProcessingCertified flag if _all_ modules have it set
  auto flag = Module::c_ParallelProcessingCertified;
  if (ModuleManager::allModulesHaveFlag(buildModulePathList(), flag)) {
    switchStart->setPropertyFlags(flag);
    switchEnd->setPropertyFlags(flag);
  }
 
  // switch to the second (empty) data store
  addModule(switchStart);
  // execute independent path
  addPath(independent_path);
  // do the merging
  addModule(switchEnd);
  // check events to be merged is consistent (typically charge)
  addModule(fillConsistencyInfo);
  // decide which events have to be processed next
  addModule(steerInput);
  // the current combination of events might not be sensible or unphysical
  // in this case end path and try next combination
  steerInput->if_value("==0", std::make_shared<Path>());
}

addIndependentPath()

void addIndependentPath	(	const PathPtr &	independent_path,
		std::string	ds_ID,
		const boost::python::list &	merge_back
	)

See 'pydoc3 basf2.Path'.

Definition at line 109 of file Path.cc.

{
  if (ds_ID.empty()) {
    static int dscount = 1;
    ds_ID = "DS " + std::to_string(dscount++);
  }
  auto mergeBack = PyObjConvUtils::convertPythonObject(merge_back, std::vector<std::string>());
  ModulePtr switchStart = ModuleManager::Instance().registerModule("SwitchDataStore");
  static_cast<SwitchDataStoreModule&>(*switchStart).init(ds_ID, true, mergeBack);
  ModulePtr switchEnd = ModuleManager::Instance().registerModule("SwitchDataStore");
  static_cast<SwitchDataStoreModule&>(*switchEnd).init("", false, mergeBack);
  switchStart->setName("SwitchDataStore ('' -> '" + ds_ID + "')");
  switchEnd->setName("SwitchDataStore ('' <- '" + ds_ID + "')");
 
  //set c_ParallelProcessingCertified flag if _all_ modules have it set
  auto flag = Module::c_ParallelProcessingCertified;
  if (ModuleManager::allModulesHaveFlag(buildModulePathList(), flag)) {
    switchStart->setPropertyFlags(flag);
    switchEnd->setPropertyFlags(flag);
  }
 
  addModule(switchStart);
  addPath(independent_path);
  addModule(switchEnd);
}

addModule()

void addModule

(

const std::shared_ptr< Module > &

module

)

Adds a module to the path.

The module is added to the path by inserting it to the end of the list of modules.

See 'pydoc3 basf2.Path' for the complete documentation.

Parameters

module

Module that should be added to the path.

Definition at line 32 of file Path.cc.

{
  m_elements.push_back(module);
}

addPath()

void addPath

(

const PathPtr &

path

)

See 'pydoc3 basf2.Path'.

Definition at line 37 of file Path.cc.

{
  if (path.get() == this) {
    B2FATAL("Attempting to add a path to itself!");
  }
  m_elements.push_back(path);
}

buildModulePathList()

ModulePtrList buildModulePathList

(

bool

unique = true

)

const

Builds a list of all modules which could be executed during the data processing.

The method starts with the current path, iterates over the modules in the path and follows recursively module conditions to make sure the final list contains all modules which could be executed while preserving their correct order.

Parameters

unique

If true, the list will be unique.

Returns

A list containing all modules which could be executed during the data processing.

Definition at line 67 of file Path.cc.

{
  ModulePtrList modList;
  for (const ModulePtr& module : getModules()) {
    if (!unique or find(modList.begin(), modList.end(), module) == modList.end()) {
      modList.push_back(module);
 
      //If the module has a condition, call the method recursively
      if (module->hasCondition()) {
        for (const auto& conditionPath : module->getAllConditionPaths()) {
          // Avoid loops in path conditions
          if (conditionPath.get() == this) B2FATAL("Found recursion in conditional path");
          const std::list<ModulePtr>& modulesInElem = conditionPath->buildModulePathList(unique);
          modList.insert(modList.end(), modulesInElem.begin(), modulesInElem.end());
        }
      }
    }
  }
 
  return modList;
}

clone()

std::shared_ptr< PathElement > clone ( ) const

overridevirtual

Create an independent copy of this path, recreating all contained modules with the same parameters.

Note that parameters are shared, so changing them on a module in the cloned path will also affect the module in the original path.

Implements PathElement.

Definition at line 186 of file Path.cc.

{
  PathPtr path(new Path);
  for (const auto& elem : m_elements) {
    const auto* m = dynamic_cast<const Module*>(elem.get());
    if (m and m->getType() == "PyModule") {
      //B2WARNING("Python module " << m->getName() << " encountered, please make sure it correctly reinitialises itself to ensure multiple process() calls work.");
      path->addModule(std::static_pointer_cast<Module>(elem));
    } else {
      path->m_elements.push_back(elem->clone());
    }
  }
  return path;
}

contains()

bool contains

(

const std::string &

moduleType

)

const

Does this Path contain a module of the given type?

Useable in Python via '"ModuleType" in path' syntax.

Definition at line 178 of file Path.cc.

{
  const std::list<ModulePtr>& modules = getModules();
 
  auto sameTypeFunc = [moduleType](const ModulePtr & m) -> bool { return m->getType() == moduleType; };
  return std::find_if(modules.begin(), modules.end(), sameTypeFunc) != modules.end();
}

doWhile()

void doWhile	(	PathPtr	path,
		const std::string &	condition,
		unsigned int	maxIterations
	)

See 'pydoc3 basf2.Path'.

Definition at line 102 of file Path.cc.

{
  ModulePtr module = ModuleManager::Instance().registerModule("SubEvent");
  static_cast<SubEventModule&>(*module).initSubLoop(std::move(path), condition, maxIterations);
  addModule(module);
}

exposePythonAPI()

void exposePythonAPI ( )

static

Exposes methods of the Path class to Python.

Definition at line 238 of file Path.cc.

{
  docstring_options options(true, false, false); //userdef, py sigs, c++ sigs
  using bparg = boost::python::arg;
 
  class_<Path>("Path",
               R"(Implements a path consisting of Module and/or Path objects (arranged in a linear order).
 
.. seealso:: :func:`basf2.process`)")
  .def("__str__", &Path::getPathString)
  .def("_add_module_object", &Path::addModule) // actual add_module() is found in basf2.py
  .def("add_path", &Path::addPath, args("path"), R"(add_path(path)
 
Insert another path at the end of this one.
For example,
 
    >>> path.add_module('A')
    >>> path.add_path(otherPath)
    >>> path.add_module('B')
 
would create a path [ A -> [ contents of otherPath ] -> B ].)
 
Parameters:
  path (Path): path to add to this path)")
  .def("modules", &_getModulesPython, R"(modules()
 
Returns an ordered list of all modules in this path.)")
  .def("for_each", &Path::forEach, R"(for_each(loop_object_name, array_name, path)
 
Similar to `add_path()`, this will
execute the given ``path`` at the current position, but in each event it will
execute it once for each object in the given StoreArray ``arrayName``. It will
create a StoreObject named ``loop_object_name``  of same type as array which will
point to each element in turn for each execution.
 
This has the effect of calling the ``event()`` methods of modules in ``path``
for each entry in ``arrayName``.
 
The main use case is to use it after using the `RestOfEventBuilder` on a
``ParticeList``, where you can use this feature to perform actions on only a part
of the event for a given list of candidates:
 
    >>> path.for_each('RestOfEvent', 'RestOfEvents', roe_path)
 
You can read this as
 
  "for each ``RestOfEvent`` in the array of "RestOfEvents", execute ``roe_path``"
 
For example, if 'RestOfEvents' contains two elements then ``roe_path`` will be
executed twice and during the execution a StoreObjectPtr 'RestOfEvent' will be
available, which will point to the first element in the first execution, and
the second element in the second execution.
 
.. seealso::
    A working example of this `for_each` RestOfEvent is to build a veto against
    photons from :math:`\pi^0\to\gamma\gamma`. It is described in `HowToVeto`.
 
.. note:: This feature is used by both the `FlavorTagger` and :ref:`FullEventInterpretation` algorithms.
 
Changes to existing arrays / objects will be available to all modules after the
`for_each()`, including those made to the loop object itself (it will simply modify
the i'th item in the array looped over.)
 
StoreArrays / StoreObjects (of event durability) *created* inside the loop will
be removed at the end of each iteration. So if you create a new particle list
inside a `for_each()` path execution the particle list will not exist for the
next iteration or after the `for_each()` is complete.
 
Parameters:
  loop_object_name (str): The name of the object in the datastore during each execution
  array_name (str): The name of the StoreArray to loop over where the i-th
    element will be available as ``loop_object_name`` during the i-th execution
    of ``path``
  path (basf2.Path): The path to execute for each element in ``array_name``)",
       args("loop_object_name", "array_name", "path"))
  .def("do_while", &Path::doWhile, R"(do_while(path, condition='<1', max_iterations=10000)
 
Similar to `add_path()` this will execute a path at the current position but it
will repeat execution of this path as long as the return value of the last
module in the path fulfills the given ``condition``.
 
This is useful for event generation with special cuts like inclusive particle generation.
 
See Also:
  `Module.if_value` for an explanation of the condition expression.
 
Parameters:
  path (basf2.Path): sub path to execute repeatedly
  condition (str): condition on the return value of the last module in ``path``.
    The execution will be repeated as long as this condition is fulfilled.
  max_iterations (int): Maximum number of iterations per event. If this number is exceeded
    the execution is aborted.
       )", (bparg("path"), bparg("condition") = "<1", bparg("max_iterations") = 10000))
  .def("_add_independent_path", &Path::addIndependentPath)
  .def("_add_independent_merge_path", &Path::addIndependentMergePath)
  .def("__contains__", &Path::contains, R"(Does this Path contain a module of the given type?
 
    >>> path = basf2.Path()
    >>> 'RootInput' in path
    False
    >>> path.add_module('RootInput')
    >>> 'RootInput' in path
    True)", args("moduleType"))
  ;
 

forEach()

void forEach	(	const std::string &	loopObjectName,
		const std::string &	arrayName,
		PathPtr	path
	)

See 'pydoc3 basf2.Path'.

Definition at line 95 of file Path.cc.

{
  ModulePtr module = ModuleManager::Instance().registerModule("SubEvent");
  static_cast<SubEventModule&>(*module).initSubEvent(loopObjectName, arrayName, std::move(path));
  addModule(module);
}

getModules()

std::list< ModulePtr > getModules ( ) const

overridevirtual

Returns a list of the modules in this path.

(Recursively searches sub-paths)

Implements PathElement.

Definition at line 50 of file Path.cc.

{
  std::list<ModulePtr> modules;
  for (const std::shared_ptr<PathElement>& elem : m_elements) {
    if (dynamic_cast<Module*>(elem.get()) != nullptr) {
      //this path element is a Module, create a ModulePtr that shares ownership with 'elem'
      modules.push_back(std::static_pointer_cast<Module>(elem));
    } else {
      //some PathElement with submodules
      const std::list<ModulePtr>& modulesInElem = elem->getModules();
      modules.insert(modules.end(), modulesInElem.begin(), modulesInElem.end());
    }
  }
  return modules;
}

getPathString()

std::string getPathString ( ) const

overridevirtual

return a string of the form [module a -> module b -> [another path]]

can be used to 'print' a path in a steering file.

Implements PathElement.

Definition at line 206 of file Path.cc.

{
  std::string out("");
  bool firstElem = true;
  for (const std::shared_ptr<PathElement>& elem : m_elements) {
    if (!firstElem) {
      out += " -> ";
    } else {
      firstElem = false;
    }
 
    out += elem->getPathString();
  }
  return "[" + out + "]";
}

isEmpty()

bool isEmpty

(

)

const

Returns true if this Path doesn't contain any elements.

Definition at line 45 of file Path.cc.

{
  return m_elements.empty();
}

putModules()

void putModules

(

const std::list< std::shared_ptr< Module > > &

mlist

)

Replaces all Modules and sub-Paths with the specified Module list.

Definition at line 89 of file Path.cc.

{
  m_elements.assign(mlist.begin(), mlist.end());
}

Friends And Related Function Documentation

PathIterator

friend class PathIterator

friend

Definition at line 139 of file Path.h.

Member Data Documentation

m_elements

std::list<std::shared_ptr<PathElement> > m_elements

private

The list of path elements (Modules and sub-Paths)

Definition at line 137 of file Path.h.

---

The documentation for this class was generated from the following files:

• framework/core/include/Path.h
• framework/core/src/Path.cc