Auger Software Run Control. More...

#include <RunController.h>

Inheritance diagram for fwk::RunController:

Public Types
enum	BreakStatus { eNoBreak, eBreak, eContinue }

Public Member Functions
virtual void	Finish ()

evt::Event &	GetCurrentEvent () const
	Get Event currently being processed. More...

const std::string &	GetCurrentModule () const
	Get the name of the currently running module. More...

VModule &	GetModule (const std::string &moduleName) const
	Get module by name. More...

int	GetNumberOfRegisteredModules () const
	Return number of registered modules. More...

std::string	GetRegisteredModuleNames () const
	Get list of all module builder names and module versions in the registry. More...

RunData &	GetRunData () const

const std::set< std::string > &	GetUsedModuleNames () const
	Get a set of the names of all modules accessed thus far in the run. More...

bool	HasModule (const std::string &moduleName) const

virtual void	Init ()

virtual void	Run ()

Public Attributes
static T &return	instance

Protected Member Functions
void	FinishBranch (utl::Branch &currentB)

void	InitBranch (utl::Branch &currentB)

void	RunBranch (utl::Branch &currentB)

	RunController ()

virtual	~RunController ()

Private Member Functions
BreakStatus	DoNextInSequence (utl::Branch &currentB)

void	DoRunSequence (utl::Branch &currentB)

void	GetNextModuleName (utl::Branch &currentB)

Static Private Member Functions
static std::string	GetBreakStatusByName (const BreakStatus status)

Private Attributes
evt::Event *	fCurEvent = nullptr

std::string	fCurrentModule

utl::RealTimeStopwatch	fRealTimeStopwatch

RunData	fRunData

utl::Stopwatch	fStopwatch

std::set< std::string >	fUniqueModuleNames

std::set< std::string >	fUsedModuleNames

Friends
class	utl::Singleton< RunController >

Detailed Description

Auger Software Run Control.

Author: T. Paul

Date: 30 Jan 2003

Performs module sequencing under direction of an external XML file. Creates the Event(s) and manages them on a stack according to looping instructions.

The simplest example

The RunController performs physics module sequencing under directions from an external XML file, which we call a sequence file. Here is a trivial example of a sequence file:

<!-- Sequence file that loops over the MyModule Run method twice -->

<sequenceFile>
  <moduleControl>
    <loop numTimes="2">
      <module> MyModule </module>
    </loop>
  </moduleControl>
</sequenceFile>

For this sequence, the RunController will first invoke the Init method of MyModule, then invoke the Run method of MyModule twice, and finally invoke the Finish method of MyModule. For More details on the Init, Run, Finish methods, see the documentation for fwk::VModule.

Communicating between RunController and Modules

In addition to giving directions to the RunController from an XML file, individual Modules individual modules can send instructions via the fwk::VModule::ResultFlag return code telling the RunController to break a loop, continue a loop, or abort altogether. In addition to controlling module sequences, the RunController is responsible for passing the Event reference to the

  fwk::VModule::ResultFlag Run(evt::Event &)

method of each module. The module sequence file can also be use to control the state of the Event when it is passed to a module. We illustrate each of these points below.

First, to illustrate basic looping instructions as well as the fwk::VModule::ResultFlag return code, assume we run the module sequence shown below:

<loop numTimes="unbounded">
  <module> ModuleA </module>
  <loop numTimes="10">
    <module> ModuleB </module>
    <module> ModuleC </module> <!-- returns a ResultFlag -->
    <module> ModuleD </module>
  </loop>
</loop>

Let's consider the effect of ModuleC returning various values of fwk::VModule::ResultFlag from its Run(Event &) method. The ResultFlag is simply an enumeration which can take four possible values:eSuccess, eFailure, eContinueLoop, eBreakLoop. For the case eSuccess, nothing interesting happens; it is assumed that all went well for ModuleC, and the RunController carries on to ModuleD. In contrast, if Module returns eFailure, it is assumed that a catastrophic error occurred, and execution is immediately terminated by the RunController. If ModuleC returns eBreakLoop, then the control is returned to the loop level outside of the current level, or, if there is no such outer loop, execution is terminated. In the example above, an eBreakLoop returned by ModuleC would cause the RunController to jump out of the inner loop and run ModuleA. (Notice also that in the example above, the outermost loop happens an "unbounded" number of times; this implies a never-ending loop unless ModuleA returns eBreakLoop or unless any of the modules returns eFailure). Finally, if ModuleC returns eContinue, all subsequent modules at the current loop level are skipped and control returns to the beginning of that loop. In the example above, this would imply ModuleD would be skipped and ModuleB would be the next one executed. This sort of behavior is useful when, for example, you are looping on events and applying selection criteria as a condition for continued processing of the event.

The event stack : how to use the pushEventToStack attribute

Now we describe how to use the pushEventToStack attribute of the loop tag. This attribute allows you to tell the RunController to push the current Event to a stack when it encounters a loop tag, and pop an Event from the top of the stack just after passing that loop tag. Whether or not to set pushEventToStack = "yes" or pushEventToStack = "no" depends on the kind of looping behavior you want. Consider the following two examples

First suppose you write an FD reconstruction sequence in which Cerenkov light subtraction is carried out through an iterative procedure. A module sequence for such an application might look something like:

<loop numTimes="unbounded" pushEventToStack="yes">

  <module> EventFileReader </module>
  <module> GeometryFinder  </module>
  <module> ProfileFinder   </module>
  <module> EnergyFinder    </module>  <!-- position 1 -->

  <loop numTimes="10" pushEventToStack="no">  <!-- iterative Cherenkov subtraction -->
    <module> CherenkovFinder     </module>
    <module> CherenkovSubtracter </module>
    <module> ProfileFinder      </module>
    <module> EnergyFinder       </module>  <!-- position 2 -->
  </loop>

  <module> Analysis </module>
</loop>

Note the pushEventToStack = "no" in the inner loop. The behavior in the inner loop is as follows. The first time the CherenkovFinder module is run, the Event will be in the state that the EnergyFinder left it at position 1. The subsequent 9 times the CherenkovFinder is run, the Event will be in the state that the second EnergyFinder left it at position 2. Since we do not push the event to a stack when starting the loop, the modules within the <loop> tags simply modify the state of the same event on each pass through the inner loop. Note that, in contrast, the outermost loop has a pushEventToStack="yes" attribute. This causes the RunController to push an (empty) event to the stack before descending into the loop, and pop this empty event when passing the first <loop> tag. So, each time the RunController returns to the top of the outermost loop, it gets a fresh, empty event structure.

Next consider a SD simulation example. A module sequence to generate 10 fully simulated showers (including the detector response) from a single Aires or Corsika shower might look something like:

<loop numTimes="unbounded" pushEventToStack="yes">
  <module> EventFileReader </module>     <!-- reads in an Aires or Corsika shower -->
  <loop numTimes="10" pushEventToStack="yes">
    <module> EventGenerator    </module> <!-- throws sim shower somewhere on array -->
    <module> SimulatorModules  </module> <!-- actually involves several modules -->
    <module> EventFileExporter </module>
  </loop>
</loop>

In this sequence, there is an outer loop which reads in several Aires or Corsika showers from one or more files. For each shower, there is an inner loop in which we want a fully simulated shower to be generated using the Aires or Corsika shower, with the EventGenerator placing the core in a different location each time through the loop. Thus, the EventGenerator module expects to always see an Event which is in the state the EventFileReader left it (not in the state that the the EventFileExporter left it!). To produce this sort of behavior, we add the pushEventToStack="yes" attribute to the inner <loop> tag.

Two very important notes:

Some modules (such as EventFileReaderOG) clear the event. This means that if you begin a loop with EventFileReaderOG, the event will be cleared even if you set pushEventToStack = "no" for that loop.
By default, pushEventToStack is set to "no". If you leave out the pushEventToStack attribute, the event will not be saved at the loop.

Because of these two points, you may see occasionally (lazily) written sequences that look something like:

<loop numTimes="41">
  <module> EventFileReaderOG </module>
  <module> myReconstruction  </module>
</loop>

This will work, but only because the EventFileReaderOG clears the event as part of its job. Generally, if you want to be certain the event is cleared at the outermost loop, you should expend the extra energy required to type pushEventToStack = "yes".

The try tag

As described above, modules may send a VModule::eContinueLoop flag to the RunController in case they cannot continue processing. In such cases, subsequent modules are skipped up to the next <loop> tag or the next <try> tag. The <try> tag is equivalent to <loop numTimes="1">, but is given a special name to help make it clear that it is meant only to set the place at which the RunController stops skipping moduels. For example, consider the following (hypothetical) sequence fragment:

<loop numTimes="unbounded">
...
  <module> FdReconstruction </module>
  <module> SdReconstruction </module>
  <module> WriteOutEvent </module>
</loop>

In this case, if FdReconstruction returns eContinueLoop (eg. because the reconstruction fails), then the subsequent modules will be skipped. This may not be desirable; one may wish to run SdReconstruction despite an eContinue from FdReconstruction. This behavior can be achieved by surround the relevant modules with a <try> tag (or equivalently a <loop numTimes="1"> tag) :

<loop numTimes="unbounded">
...
  <try>
    <module> FdReconstruction </module>
  </try>
  <try>
    <module> SdReconstruction </module>
  </try>
  <module> WriteOutEvent </moudle>
</loop>

Writing your own run control

Note finally that if the program steering functionality of the RunController is not sufficient for a particular application, the user can provide an empty <moduleControl> element to disable the RunController entirely, and provide his own custom sequencing as a C++ program the AugerOfflineUser() function.

Definition at line 26 of file RunController.h.