BuildTree

BuildTree is a routine in the eic-smear package that processes output from the EIC task-force Monte Carlo generators into ROOT tree files. It supercedes the ROOT macro used for the previous generation of ROOT trees.

Introduction

The output from most of the Monte Carlo generators used by the EIC task force is in the form of ASCII text files, following a common format. Specifically, PYTHIA, PEPSI, RAPGAP, MILOU, DJANGOH, gmc_trans and DPMJet generate their output in this way. The format of files produced by each is explained in the page for the corresponding generator.

The text files can be processed into a ROOT TTree for analysis by a routine named BuildTree. BuildTree is provided as part of the EIC smearing shared library, and is loaded into and run from ROOT. This library also contains an event class for each of the aforementioned generators, a common particle class shared by each event type, plus numerous other utility classes. This page describes the use of the BuildTree function itself and briefly describes event class. Documentation for the full class structure contained in the library is available here.

Running

BuildTree takes four arguments, the first of which is mandatory and the rest of which are optional:

1. A character string giving the name of the input ASCII file.
2. The directory in which to write the output file. By default this is the current directory.
3. The maximum number of events to process. The default value will cause the macro to process all events in the input file.
4. The name of a log file, from which it will attempt to extract information about the generated cross section. By default BuildTree will attempt to locate a log file automatically based on the name of the input ASCII file.

Note that you do not need to specify which Monte Carlo generators was used to generate the events; the common ASCII format specifies the generator in the input file. For example, to process the first 100,000 events in the file "myPythiaEvents.txt":

root [1] BuildTree("myPythiaEvents.txt", ".", 100000);

This will generate a ROOT file named "myPythiaEvents.root" in the current directory containing. The total number of events and particles processed and the running time are printed to the screen when the function completes. An example of running BuildTree() is included in the distribution in a macro named build.cxx.

Data Format

The output file contains a TTree named EICTree. Each entry in the TTree is a single event. The event contains two parts:

1. A collection of event-wise properties, such as event number, process ID and kinematics quantities.
2. A list of all the particles in the event.

The format of the particles is common to all the generators, while the event variables typically differ between generators, though some are common to one or more. Events from each generator are described by their own C++ class. All classes are contained in the erhic namespace to avoid clashing with other code (though the main BuildTree routine remains in the global namespace). For example, erhic::EventPythia describes a PYTHIA event, while erhic::EventDjangoh describes a DJANGOH event. Particles are described by a C++ class named erhic::ParticleMC. A simple way to view descriptions of the variables stored in an event are to create an object of the appropriate type in ROOT and call its Dump() method:

root [0] erhic::EventPythia event
root [1] event.Dump()
==> Dumping object at: 0x000000017e4bf490, name=erhic::EventPythia, class=erhic::EventPythia
nucleon                       2147483647          /< PDG code of the hadron beam,
tgtparton                     2147483647          /< PDG code of the struck parton
…

Each variable in the event is listed along with a description. Please see the class documentation for full descriptions of the classes.

Reading Trees

Simple analyses can be performed using TTree::Draw() statements. For example, to draw the polar angle distribution of all electrons in events with Q² greater than 1 GeV²:

root[1] EICTree->Draw("theta","id==11 && QSquared>1.");

More complex analyses involve reading each event into memory in a loop and performing the required processing. An example macro for doing this, named read.cxx, is included in the distribution.