Contents

Installation of necessary packages

This section describes how to install and run the packages needed by CDER. All packages should be compiled and installed in 32-bit mode for compatibility with Lepton.

ROOT

Go to http://root.cern.ch/drupal/content/downloading-root and select the Pro (production) ROOT version. You can always try fetching a 32-bit binary, but ROOT is the most troublesome to have running in 32-bit. I would recommend installing from source. The ROOT website provides instructions to do so. Be sure that python is enabled.

To test if ROOT is installed correctly, try to run the python interpreter in 32-bit mode:

python-32

and then try

>>> import ROOT

If everything is installed correctly, the prompt should be returned to you without any further messages.

Pyglet

Pyglet is a gaming framework making use of openGL graphics that provides crucial functionalities to deal with keyboard and mouse inputs. Go to http://www.pyglet.org/download.html and either download the binary or follow the instructions to install from source. I would strongly recommend checking out the head of the package. The current stable version of pyglet on the website (1.1.4) has a few known issues that have been fixed recently. Pyglet is in itself architecture-independent so you shouldn't have anything special to do to run it in 32-bit. Once it is installed, try:

python-32

>>> import pyglet

to make sure that it is installed properly.

Lepton

Lepton (or py-lepton) is a super-fast particle generator that is easily integrated in a pyglet program. It relies on random number generators that are not architecture-independent (at least, in the way they are written at the moment). Go to http://code.google.com/p/py-lepton/downloads/list and download the binary or install from source (only windows binaries are available). Once it is installed, try:

python-32

>>> import lepton

to make sure that it is installed properly. You can also try the examples provided with the package under examples/.

Basics

This section describes the basic CDER controls.

Launching CDER

python-32 CDER.py

Camera controls

The camera in CDER is always fixated on the collision point, although the point of view may be changed. Click-and-drag to navigate around the scene and scroll up/down to zoom in/out. Pressing a will bring you directly to a view of the transverse plane and pressing s will bring you directly to a longitudinal view.

When you launch CDER, you will find that the camera is rotating around the scene. Clicking-and-dragging will not interrupt that rotation. However, pressing either a, s or d will stop the rotation. You may press d to start/stop the rotation at will.

The movement speed, minimum and maximum yaw, minimum and maximum zoom may be changed in config.ini.

Event navigation

Navigating the events in the ROOT file provided is done via the arrow keys. Pressing the right arrow brings you the next event in the ROOT file while pressing the left arrow brings you the previous event. Pressing the up/down arrow keys will summon a random event.

Terminal printout

By default, tthe basic kinematics of the objects displayed in the CDER calorimeter are also shown in the terminal. Extra information can also be displayed if desired (see section on making your own reader).

Cuts

The events that can be selected via navigation can be restrained by applying cuts. Pressing c will summon a one-line text editor to define a cut to be applied. The editor has basic shell-like functionalities, including:

CTRL-a : go to beginning of line
CTRL-e : go to end of line
CTRL-k : put the text after the cursor in the kill-ring
CTRL-y : yank back the text in the kill ring at the cursor position

The text editor keeps a history of the previous cuts entered. It can be navigated by pressing the up/down arrow keys. When the text editor is on, the other CDER controls are disabled.

The syntax to specify a cut should be the same as when defining a cut in ROOT. The cut is applied by using the TTree::CopyTree function. Press Enter to apply the cut and get back to camera controls and event navigation. If the cut passed is not valid, nothing will be done. If the cut is valid, a random event within the new selection will be chosen and displayed. You may resume ordinary event navigation and camera control at this point.

The current cut applied should be displayed in the terminal from which CDER has been launched.

To remove the currently applied cut, press r.

Information on objects

Only a finite collection of high-level objects can be displayed in CDER. These objects are chosen based on the high-level objects reconstructed in the ATLAS experiment. The list may be extended in the future to accomodate other experiments.

Jets

Jets in CDER are specified only from 3 parameters: transverse momentum (pt), pseudorapidity (eta) and azimuthal angle (phi). In the CDER display, they are shown as being collimated showers of neutral (orange) and charged (white) particles. These particles are randomly generated around the jet momentum only to reproduce the generic appearance of jets. The goal is not accuracy, but ease of visual identification.

A jet can accept a 4th parameter: b-tagging. A b-tagged jet with be shown as having a teal aura, and it will also have a different color from an ordinary jet in the terminal printout.

Photons

Photons are illustrated by a single white particle that deposits all its energy in the EM calorimeter. They are specified using only pt, eta and phi.

Electrons

Electrons are illustrated by a single blue particle that deposits all its energy into the EM calorimeter. They are specified using only pt, eta and phi.

Muons

Muons are illustrated by a single red particle that crosses the calorimeter. They are specified using only pt, eta and phi.

Taus

Taus here refer to the visible part of hadronic tau decays. The hadronic decay products illustrated are only emulated to reproduce the branching fractions. The charged particles are given a yellow color to differentiate hadronic taus from jets. They are also made narrower than jets. Taus are specified using only pt, eta and phi.

Missing transverse energy

Missing transverse energy (MET) is illustrated as a fuzzy green line. Only the magnitude and phi needs to be specified.

Reading your own ROOT files

In order to enable CDER to interpret your own ROOT files, you must write your own custom reader class. The process is made as simple as possible by hiding all of the complex operations in the Reader base class. All you have to do is to specify how to extract the basic kinematics from your own trees, and provide CDER with simple tuples.

Making a customized Reader class

First, make a new file in core/reader/ with the name of your choice:

touch core/reader/yourfile_reader.py

Then edit the file. If your ROOT files contain standard C++ vectors, you should begin with the lines:

from ROOT import gROOT
gROOT.ProcessLine('.L core/reader/addVectorToROOT.C+')

This will enable ROOT to interpret C++ vectors of floats, integers, and TLorentzVectors. Then, import the Reader base class:

from reader import Reader

and start a class that is named Custom_Reader which inherits from Reader:

class Custom_Reader(Reader):

Kinematics access functions

Then, define the kinematics access functions for each object type. The access functions must be named:

get_jets()
get_photons()
get_electrons()
get_muons()
get_taus()
get_met()

The Reader base class has predefined containers for each type of object, and these should be filled according to the following specifications:

The btag parameter is optional for jets. Only self.event_met is not a python list. It cannot hold many entries but only the one. For a concrete example on how to define a customized Reader class, see core/reader/example_reader.py.

Using the customized reader class

In order to put your customized reader class to use, go into config.ini and set the following keys:

filename=yourfile.root
treename=yourtreename
filereader=yourfile_reader

and just start CDER as usual.

Printing out extra information

You can also add information to be printed out to the terminal by defining the get_extra_information() function. This function should fill a python dictionary called self.extra_information. For examples, see core/reader/example_reader.py and core/reader/lhprocessor_reader.py.