Writing Your Own Package



This page explains how to create your own analysis package and how to use Atlfast output entities in your analysis.

Stage 1: The basics (Creating a package and writing a simple Algorithm)
Stage 2: Adding to your Algorithm


Stage 1: The basics

As always you will use the TestRelease Package to control your work. So as usual, if you have not already got the TestRelease package you will need to check it out.

cmt co TestRelease

Now, in the same directory you will need to Create your own analysis package. You will need to give your package a version number, if it is your first version, 00-00-01 is the usual value.

cmt create MyAnalysis MyAnalysis-00-00-01

This will create a directory structure with the following branches:

MyAnalysis/MyAnalysis-00-00-01/cmt
MyAnalysis/MyAnalysis-00-00-01/src

the src directory is empty. The cmt directory contains the following files; cleanup.csh, cleanup.sh, Makefile, requirements, setup.csh and setup.sh. The only one of real interest should be the requirements file. We will come back to this once we have written our first analysis algorithm.

We are ready to make our analysis algorithm. Firstly you need a directory to put your header files in, this is traditionally given the same name a the package, in our case MyAnalysis, but it can have any name you wish.

cd MyAnalysis/MyAnalysis-00-00-01
mkdir MyAnalysis
cd MyAnalysis

In here we will put the header file for your analysis algorithm, which I have called TheAnalysis.h. The example shown here in the minimum skeleton needed for an athena algorithm. It has the #include for the required Gaudi files and it has been put in a namespace MyAnalysis to avoid any clashes with other packages. The actual class has the required Gaudi Constructor and destructor and the Three Mandatory methods that all athena algorithms need:

StatusCode initialize();
StatusCode execute();
StatusCode finalize();

And that's it! Now we need a cxx file to contain the actual code. This needs to be put in the src directory and will be called TheAnalysis.cxx

cd ../src
emacs TheAnalysis.cxx

This file first includes some prerequisite headers, TheAnalysis.h and the header for MsgStream so we can print out messages.

Now comes namespace MyAnalysis and then the methods code. At the moment the constructor here does no extra work, it only runs the Athena Algorithm constructor. The destructor and three methods only have one simple instruction, to print a message out when they are run. They all use the messageService to do this, so must instanciate a MsgStream log( messageService(), name() ) object. All messages are set to the level of DEBUG, so are only printed if the user defines TheAnalysis.OutputLevel = 2. And that is our first Analysis Algorithm.

However, to tell Athena to load our package and algorithms when it runs, we need two further .cxx files. These need to be put in a src/components directory.

mkdir components
cd components

They are called MyAnalysis_load.cxx, which defines which factory to load (MyAnalysis), and MyAnalysis_entries.cxx which declares the factory entries and its associated algorithms (at this stage we only have one Algorithm, TheAnalysis).

we are now ready to build the code. Firstly we have to tell cmt which code to build and which external packages it will need to build and run. Thus, we have to edit the requirements, in the cmt directory.

cd ../../cmt
emacs requirements

In here i have firstly defined the author, me

author Jon Couchman

Then i tell it which packages will be needed by my code

use AtlasPolicy AtlasPolicy-01-*
use GaudiInterface GaudiInterface-01-* External

Next the cmt command apply_pattern dual_use_library files=*.cxx is used to tell cmt that we are making a athena library and which files need to be compiled. *.cxx means all the files in the src directory and the src/components directory

apply_pattern dual_use_library files=*.cxx

Finally there is some cmt jiggery-pokery put at the end of the requirements file that tells cmt which files to copy to the run directory.

apply_pattern declare_runtime extras=MyJobOptions.txt

The private section of the requirements file is left empty at this stage.

Now, before you build, it is a good idea to write a jobOptions.txt file. This is traditionally put in a directory called share and i have named my file MyJobOptions.txt

cd ..
mkdir share
cd share
emacs MyJobOptions.txt

MyJobOptions.txt first includes a file needed by athena so it knows what it is doing:

#include "Atlas_Gen.UnixStandardJob.txt"

It then tells athena which shared libraries should be loaded:

ApplicationMgr.DLLs += { "GaudiAlg"};
ApplicationMgr.DLLs += { "MyAnalysis" };
ApplicationMgr.DLLs += { "GaudiAud" };
AuditorSvc.Auditors = { "ChronoAuditor" };

The GaudiAlg is required whenever you run an athena algorithm and The MyAnalysis is your own packages library.The GaudiAud is an Auditor library, this is used by Auditor service ChronoAuditor. ChronoAuditor prints out a report at the end of the athena job detailing the time used to execute each algorithm. The number of events to run over and the output level of your job is set by the following:

ApplicationMgr.EvtMax = 1000;
MessageSvc.OutputLevel = 3;

Finally you have to tell athena to run your algorithm and optionally, you can set it's output level to a different value to the global value already set.:

ApplicationMgr.TopAlg = {"Sequencer/TopSequence"};
TopSequence.Members += {"Sequencer/MyAnalysis"};
MyAnalysis.Members += {"MyAnalysis::TheAnalysis/TheAnalysis"};
TheAnalysis.OutputLevel = 2;

You are now ready to build the code, this envolves going to the TestRelease directory and editing the requirements file there.

cd ../../../TestRelease/TestRelease-00-00-14/cmt
emacs requirements

The requirements file needs the following lines:

use MyAnalysis MyAnalysis-00-00-01
use Control Control-*
use Event Event-*
use Generators Generators-*
use Simulation Simulation-*

Now you can configure and build

cmt broadcast cmt config
source setup.sh
cmt broadcast gmake

To run the code you just need to change to the run directory and issue the athena run command and tell athena which jobOptions file to use. Your MyJobOptions.txt should have been copied to the run directory already by cmt.

cd ../run/
athena MyJobOptions.txt

Now you are ready to edit your TheAnalysis to do some proper analysis. If you are ready learn how to do this move onto stage 2