SLAC PEP-II
BABAR
SLACRAL
Babar logo
SPIRES E S & H Databases PDG arXiv
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Home
Workbook
 1. Introduction
 2. Accnt. Setup
 3. QuickTour
 4. Packages
 5. Modules
 6. Event Info.
 7. Tcl Cmds.
 8. Editing
 9. Comp.+Link
 10. Run the Job
 11. Debugging
 12. Parameters
 13. Tcl Files
 14. Find Data
 15. Batch
 16. Analysis
 17. ROOT I
 18. Kanga
Additional Info.
 Other Resources
 BABAR
 Unix
 C++
 SRT/CVS Cmds.
 SRT/CVS Dev.
 Sim/Reco
 CM2 NTuples
 Root II, III
 PAW I, II
 tcsh Script
 perl Script
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator

(More checks...)

Modules and the BaBar Framework

Contents:


Modules

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 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-42/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:

  • beginJob ( AbsEvent *)
  • event ( AbsEvent * )
  • endJob ( AbsEvent * )
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.


runorder.gif

The AppModule::event() function

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

  • Access lists of particle candidates in the event
  • Obtain kinematic, particle ID, and other physics information about each particle candidate
  • Get and use information about the overall event, such as the event shape, number of tracks, highest-energy particle, and more
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:

  • Modules - The building blocks of the analysis job. A module named MyModule consists of two files: MyModule.cc and MyModule.hh.
  • AppUserBuild.cc - Provides the Framework with a list of modules to work with.
  • Tcl files - For run-time control of the analysis job. Tcl files can be used to add/remove or enable/disable modules, or to set the run-time parameters of a job. Tcl files end in ".tcl".
  • GNUmakefile, link_*.mk, bin_*.mk - Files needed to compile and link the code.
  • Utility classes - C++ classes that are not modules, but that are used by modules for analysis. A class named MyClass consists of two files: MyClass.cc and MyClass.hh.

Identifying Modules

Suppose your package contains two files, Mystery.cc 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 Mystery.cc 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:

  • Run-time parameters - Modules come with run-time parameters, paramters that can be reset whenever you run an analysis job. This is a gret advantage over normal C++ parameters, which can be changed only by recompiling and relinking the code (that is, by re-doing all the "gmake"s).
  • Paths and Sequences - To keep the code organized and easy to manage, modules can be organized into a sequence, an ordered list of related modules (and sometimes other sequences) that perform a defined task that is too big for just one module. Similarly, a path is an ordered list of modules and sequences. The complete analysis path is then built from smaller paths, sequences, and modules.
  • Enable/Disable - Modules can easily be enabled or disabled (turned on or off) at run-time. By default, all modules are enabled.
  • Self-contained - Modules are independent. Although a module may need input from previous modules, once it has the input it works independently to perform its task.
Future sections of the Workbook will explore these features in detail.

Back to Workbook Front Page


[Workbook Author List] [Old Workbook] [BaBar Physics Book]

Valid HTML 4.01! Page maintained by Adam Edwards

Last modified: January 2008