D0 GROUP LEVEL3
ONLINE LESSONS

Episode XI
Writing Tools

All Level 3 basic packages are released, and the interface is stable.  We don't anticipate any further major changes to the tool interface although there will certainly be  disruptions as other parts of the system come into existance.
The base utility packages which are relevent for tool development are

l3utility
l3exceptions
l3ftoolbase
l3fregistry

You can use addpkg if you wish to examine these packages more closely.

PhysicsTool

 If you are writing a high level object tool, it will be a physicsTool, which uses the L3*** results classes. (Review Episode IX)

Code example
A representative example of a PhysicsTool is given by L3TauHadronic (which doesn't quite adhere to our naming convention--it should be L3TTauHadronic) :

          Source Code

• l3fTauTool/l3fTauTool/L3TauHadronic.hpp    //the header file
•  l3fTauTools/src/L3TauHadronic.cpp    //the source code for the tool
•  l3fTauTools/l3fTauTools/L3TauPhysicsResults.hpp
•  l3fTauTools/src/L3TauPhysicsResults.cpp

 

 

Component Testing
 

•  l3fTauTools/testfiles/L3TauHadronic.lst  //trigger list for the component test
• l3fTauTools/src/L3TauHadronic.sh   //shell script for the component test
• l3fTauTools/rcp/L3TauHadronic_t.rcp   //rcp parameters
•  l3fTauTools/src/L3TauHadronic_t.cpp   //component test

 

 

Integrated testing

•  l3fTauTools/test/L3TauHadronicTestPkg.cpp
•  l3fTauTools/test/L3TauHadronicTestPkg.sh
•  l3fTauTools/test/L3TauHadronic_itest.rcp

• If you want to make an physicsTool, a way to start is by copying the files from L3TauHadronic

L3TXXXX (where XXXX is the name of your tool).
• Then edit L3TXXXXTool_*.* --change all the internals to reflect your names.
• Fix up the type of data that the tool stores and returns.
• Change MakeMe to read in your parameters.
• Make DoThisTool do what you want it to do.
• Register with the database (  )have your tool and its parameters defined.

Be sure in the tool implementation file to include:

#ifndef L3REG_H
  #include "l3fregistry/L3TRegistry.hpp"
#endif

At global scope:
L3_TOOL_REGISTRY(tool_class, "tool_class:version")
 

In addition all Tools must have their parameters registered with the database.  See Episode XV.

Tools Calling other Tools

For Tools to call other tools they must take as a parameter the identification of the tool that they wish to call, and use the registration to get the pointer to the instance.  Of course, you should hold the pointers to  any tools you need.  See l3fTauTool/l3fTauTool/L3TauHadronic.hpp  l3fTauTools/src/L3TauHadronic.cpp for a full example.

In brief:
The MakeMe method will include

#ifndef DYNLOAD_H
  #include "l3fregisty/dynload.hpp"
#endif
 

DynLoad dl;

l3string _refxxx;
toolpar.get_par("TOOL", _refxxx);

_refxxx = dynamic_cast<L3Tool *>(dl.ToolInstance(_ref1));
 

Be sure to drop any tools that you are using when your destructor is called.  ScriptRunner reference counts tools so it knows when they should be deleted so if your tools is deleted without dropping the tool it uses, that tool will hang out until SR ends.

DynLoad dl;
dl.Drop(_refxxx);
 

Component Testing

Now for the component test--much of it is boilerplate--especially the part that acts like ScriptRunner.
But you'll have to change the rcp file name. If you can't make a little test chunk, then you won't be able to exercise DoThisTool at the component test level. Myself, I like using a test chunk when possible since it's a controlled enviroment.

Don't forget that you'll have to include all of the tools that you will be calling in your trigger list for your component testing.

Most of the work of reading in a trigger list and making the tools is handled for you by the function  instantiate_tools  This function takes an rcp file and a package name, and by reading in the trigger list and tools file specified, it will initialize all the tools in the trigger list.  This is one of the functions performed by ScriptRunner.

Your component tests should declare the tools that you will be using:
L3_TOOL_DECL(L3ErrHandle)

NOTE:  Orginally, we suggested that only tools which were not explicitly casted needed to be declared.  It turns out this is linker dependent, so now we know that you must declare all tools.
 

Integrated Testing

The difference between component tests and integrated tests will typically be that Integrated test have an offline batch framework interface which will allow you to read in events to exercise more fully DoThisTool.  Integrated tests also use  instatiate_tools  and again, the tools must be declared.   For the release, the integrated tests should use datafiles in $TESTDATA_DIR and should only go through a handful of events.  For your own testing and verification, use whatever best suits your needs.
 

UnpackTool

If you are responsible for taking RawData and unpacking it for use by
higher level tools, you will need to write an unpackTool which can talk to the event.

Remember that only unpackTools can talk to the event so if you need information out of any chunk, the access must be through an unpackTool.
Until RawData is simulated out of the Monte Carlo, you might have to use an unpackTool as a temporary way of accessing some event data.  The unpackTools that use offline chunks will have to be replaced by unpackTools that deal with raw data so it would be unwise to tangle up your tool's calculation with chunk access.  Additionally, the same unpacked data might be used by several higher algorithms so it makes sense to isolate the unpacking algorithms.

An example of an unpackTool can be seen in the package l3tCalUnpTool which contains the tool L3TCalUnp.hpp

DataTool
An example of a data tools is in the package l3fvertex.
 

Main Page

Next Episode