Babar logo
HEPIC E,S & H Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Workbook Home Introduction Account Setup QuickTour Packages Modules Unwrap page!
Event Information Tcl Commands Editing Compile and Link Run the Job Debugging
Check this page with the
W3C Validator
(More checks...)
Parameters Tcl Files Find Data Batch Analysis ROOT Tutorial

Modules and the BaBar Framework



BaBar code is built from objects called modules. Each module uses the data to perform one well-defined task.

There are many types of modules. There are modules to manage histograms, load detector conditions, read the data from the database, reconstruct particles, perform particle identification, get Monte Carlo simulation information, perform a user analysis, and much more. In addition, there are special-purpose modules: input modules and output modules to control the input and output of data, and filter modules to control subsequent data processing. Whenever there is an analysis task to be done, a module is created to do that task.

The modules are strung together into an ordered analysis path, Whenever you run an analysis job, your application creates ("instatiates") an object called the Framework. The Framework passes data from module to module, until it reaches the last module of the analysis path. Each module uses the data to perform its own task.

Modules in an analysis job

The above diagram shows an analysis job. As you can see, the organization is really quite simple: the modules take turns using the data. Currently, it is module C's turn to use the data to perform task C. Once it is finished, the Framework will pass the data on to module D. The analysis job will finally end when the Framework reaches module E, the output module.

Note that this diagram is unrealistic because it has only five modules. A typical analysis job involves hundreds of modules.

There is more than one possible analysis path - that is, there is more than one way to put the modules together to make an analysis path. The analysis path is set up by the Tcl scripts in a BaBar package.

BaBar code already comes with all of the modules that you need to run an analysis. But in addition to the "ready made" modules, users often write their own analysis modules. User-defined modules are made in a user's private test release.

In the QuickTour analysis, the BetaMiniUser package came with several of its own modules: MyDstarAnalysis, MyK0Analysis, MyMiniAnalysis, MyReadList, and MyTimePointAnalysis. But you also added your own user-defined module, QExample, into the BetaMiniUser package directory.

The BetaMiniUser package also came with its own Tcl scripts to set up the analysis path. Your Quicktour job used MyMiniAnalysis.tcl as its main Tcl file. Some of the other Tcl files in the package also played a role.

AppModule: the C++ class

So what exactly is a module? Technically, a module is a member of the C++ class AppModule. You can look up the code in $BFDIST/releases/analysis-41/Framework/AppModule.hh or .cc. Writing or modifying a user analysis module involves writing or modifying C++ code. If this is unfamiliar, don't worry (yet). This topic will be covered with example exercises in the Workbook's Editing Code section.

For now, the important thing to know about a module is that every module comes with three important member functions:

The beginJob() function is executed once, at the very beginning of a job. Similarly, the endJob() function is executed once, at the end of a job.

The most important function is the event() function. The event() function is where analysis code goes. It is executed once for each event in a run.

The following figure shows the order of execution in a job with N events. The job begins with a call to the beginJob() function of each module. starting with the active input module and ending with the active output module. Then the event() function is called N times. Note that the job traverses the full analysis path N times. (That is, it does not sit at one module for N events, and then the next module for N events, and so on). Finally, after the last event, endJob() is called once for each module. And then the job is done.


The AppModule::event() function

As mentioned above, the most important module function is the event() function. In the event() function, you can:

Access to the event information comes via the event() function's AbsEvent pointer, usually called "anEvent" or just "event". For example, a module will often need to access one of the many lists of particle candidates available in BaBar's Event Store database. The syntax to access the CalorNeutral list of neutral particles is:

AppResult MyModule::event(absEvent* anEvent) {

HepAList<BtaCandidate> *neutralList = Ifd< HepAList<BtaCandidate> >::get( anEvent, "CalorNeutral");


The "get" function uses anEvent (the module's AbsEvent* pointer) to locate the event. Then it uses the name "CalorNeutral" to find the right list. Finally, it returns neutralList, a pointer to a list of neutral candidates for that event.

If this is confusing, don't worry. You will learn more about Event Store, the available particle lists, and how to access and use them in the Event Information section of the Workbook. For now, just remember: In a module, you access event information from the event() function.

BaBar analysis package

BaBar (reconstruction and simulation) software is organized into packages. A package is a self-contained piece of software intended to perform a well-defined task, eg. find calorimeter clusters, or simulate the drift chamber response. Each package has a unique name and its own library and include files. Some packages may not be usable on their own, requiring integration with others, for example the individual subsystem simulation packages which together form the Geant simulation of BaBar.

An analysis package is a package that accesses the BaBar Event Store and collects and stores information relevant to the user's analysis. The contents of a typical BaBar analysis package include:

Identifying modules

Suppose your package contains two files, and Mystery.hh. How can you determine whether this is a module or just a C++ utility class?

To see if it is really a module, look at Mystery.hh. If the file contains the line:

class Mystery : public AppModule {
then it is a module. If you look below that line, you will also see the module's three functions:
  virtual AppResult           beginJob( AbsEvent* anEvent );
  virtual AppResult           event   ( AbsEvent* anEvent );
  virtual AppResult           endJob  ( AbsEvent* anEvent );

The actual definitions of what these functions do are found in the file.

In the BetaMiniUser package, you can verify for yourself that MyMiniAnalysis, MyK0Analysis, MyDstarAnalysis, MyReadList, and MyTimePointAnalysis are all modules. You can also confirm that QExample is a module.

Module features

Modules have a number of useful features:

Future sections of the Workbook will explore these features in detail.

Back to Workbook Front Page

Send comments to Workbook Team.