D0 GROUP LEVEL3
ONLINE LESSONS

Episode VIII
Tool and Die* --An Overview for Machinists

We have working on the interface for tools--this is the interface to which all of us will adhere when writing tools. That interface is not yet complete, but is far enough along that people can start tool development. This is the first in a series of episodes that will include tool examples, the tool parameters, ScriptRunner and coding guidelines.

All tools are instantiated at the request of ScriptRunner via the map of tools. Period. No one else is allowed to request a tool instantiation. The tools can be called from other tools or directly from a filter.

The fundamental tool base class is called bTool and bTool contains everything that is common to all tools. Deriving from bTool are two other dies (base classes) dataTool, and triggerTool. You need not worry about triggerTools, they are used for trigger utility fuctions like MarkandPass and prescale.
dataTool further breaks into unpackTool and physicsTool. These are the types of tools that you will be writing. A class diagram is shown at
http://www-pat.fnal.gov/personal/cope/level3/Tools.ps

unpackTool is the only tool base class that provides access to the event data model. The raw data will be wrapped into a chunk and ScriptRunner will be told by Brown the location of the data, information that ScriptRunner will pass on to the unpackTools, and only the unpackTools. An implication of this is that as you are developing now, prior to raw data being available, you will still have to segregate any dealings with edm to a tool that has unpackTool type. There are other ramifications. You will not making chunks inside level3 tools, nor insert chunks into the event. You will not be inheriting from d0_Object. You locally are responsible for managing the results of your tool until ScriptRunner asks for them. You will not be talking directly to the offline framework in simulation mode. You will not be talking directly to the online framework during data collection. Your component tests will look a little funny since it takes some machinery just to instantiate the tools.

physicsTools contain a templated physics results class. This is to provide a standard interface to another class of tools called relational tools, tools that rely on, typically, multiple physics objects.

Currently the dataTool interface supports the following functionality:

void MakeMe()

This is the pseudo-constructor which is called from the map on request from the parsing of the L3 reference sets in the trigger list. That mechanism is the only way to make an instance of the tool.

MakeMe should do several things:

1. Read in the tool parameters from the trigger list and store those parameters.
2. Read in any calibration constants or needed data
3. Preallocate a reasonable amount of space to the hold the tools results --lots of news / deletes are definitely frowned on L3. That's not to say you can't realloc once in a great while on highly unusual events--but no news / deletes on every event you see.
4. Have the tool prepared to run.

The constructor (which should be private) should, as usual, leave the class in a healthy state.

bool DoThisTool()

This is the guts of the tool where the work is done.

DoThisTool has several responsibilities as well as doing the calculations.

1. Guarding against repeated work. Depending on the trigger programming a single instance of a tool can be called multiple times during an event. But we only want it to do the work once. Thus the tools make use of a flag _IHaveData.
2. The tools are called by other tools and by filters. They have to let their callers know if something went wrong. Currently, DoThisTool returns a bool that lets the caller know if everything is ok or not. Depending on the level of "wrong", you might have to throw an exception, which Gustaaf will be explaining in a separate episode. The bool return might change to a status class, in the future.

void PrintTool()

The next method is for debugging, both on and offline. My current implementations just use iostream--that probably isn't going to cut it online. But for now it's fine.

void Write()

Since we throw away most of the events that we see in Level 3, we figure that we'll copy out the information that we want to save for verification, debugging and analysis purposes on passed/unbiased events. So ScriptRunner will specify when it wants you to write. Write again uses a flag to set the status (we aren't much interested in writing the results of one tool multiple times). At this time, just set the flag and we'll provide further direction as we settle on it.

void ToolReset()

as mentioned, ScriptRunner will let you know that it is done with an event. At the time of ToolReset, your tools should prepare itself for accepting the next event. Whatever results you have should be reset in some fashion. Again, delete is frowned--grap your memory and hang on to it. Gustaaf's recommendation is to set some field to some non-physical value and zero out your candidate pointer.

What you have to add to the interface:

For unpackTools and dataTools which are not physicsTools, you'll have to add methods that return your data. You will need to keep your data and any counter and timer information that might need. For example, you might want to know how many times your tool has been called, how many times those calls have required calculation, how long it takes to make the calculation, stuff like that.

What's obviously missing from the interface:

Check out the Level 3 interactions link from

http://www-d0.fnal.gov/~moacyr/l3/l3filter.html
That will tell you what functionality has to be in ScriptRunner --You might think from there what that implies for your tool. ScriptRunner used to handle an end-of-job summary, but we seem somehow to have lost it. Rest assured that it will be back. It will probably come in several flavors, end of run and dump summary. In addition, at end of run, there will have to be some sort of global tool reset to clear out the counters. Online, we will start and stop runs without stopping the execution of ScriptRunner. Likewise there will have to be a begin run method. And think about any monitoring information that you might need to supply.