ORCA User Guide. November 27, 2002

Transcription

1 ORCA User Guide November 27, 2002

2

3 Contents I Introduction 1 1 Welcome to ORCA About this document What is ORCA The basic structure of ORCA Required software Supported platforms Exportability Getting Started Recipe for the impatient USER Accessing ORCA Using the predefined Workspace Building and running ORCA Setting the.orcarc parameters Populating a database - the full chain A simple example analysis Overview of BuildFile options Shallow copies, UserCollections and deep copies of a UserFederation Adding new Digis Tags II Sub-System Descriptions 31 3 CommonDet Introduction Detector view iii

4 4 Calorimetry Introduction Configuration Ecal Realistic Digitization Hcal Realistic Digitization Preshower Realistic Digitization Ecal Realistic Calorimeter Hit Reconstruction Hcal Realistic Hit Reconstruction Preshower Realistic Hit Reconstruction Detailed digitization of ECAL hits EcalSelectiveReadoutTower Tracker Introduction Overview of the object model Geometrical layout Detector response simulation CommonStripDet: Does something Pixel detector SiStripDet: Silicon Strip Detectors: digitisation and cluster reconstruction Interface to Geant3/cmsim data CommonReco Track Reconstruction Track finding and fitting The Muon Subsystem Muon reconstruction in barrel region The Endcap Muon CSC system Digi-SimHit associations Trigger code in ORCA Introduction Calorimeter Trigger Muon Trigger Global Trigger

5 9 JetFinders, design, implementation, and usage Noun List Requirements Responsibilities and mapping to design elements Object Oriented Design Concrete Algorithms Usage of the Package Conclusions TrackerReco Track reconstruction Pixel Reconstruction Tracker Alignment Tools in ORCA TkRecHitValidation: Reconstructed Hit Validation Electron and Photon Reconstruction Introduction ElectronPhoton modular reconstruction and analysis Calorimetric clustering and position reconstruction Energy reconstruction and brem recovery Candidate identification and selection Analysis helpers and toolkit Examples Histograms, Ntuples and Tags Accessing MC generator information and GEANT tracks and vertices Simple matching between tracks and clusters Comparing MC particles with their reconstructed equivalents The prototyping library III COBRA Sub-System Descriptions GeneratorInterface HEP particle properties and identification numbers Classes to handle particles Classes to handle HEPEVENTS

6 13.4 Utility classes orcarc parameters Magnetic Field Magnetic Field with 2D map Magnetic Field Examples CARF: CMS Analysis & Reconstruction Framework Reconstruction Persistency Service CMS Service and Utility Toolkit User Inerface IV Appendices 157 A Using Objectivity commands (Examples) 159 B Changing from ORCA 3 to ORCA B.1 General changes C.orcarc Parameters 167 V Glossary 177 Bibliography 181

7 Part I Introduction 1

8

9 Chapter 1 Welcome to ORCA 1.1 About this document This UserGuide is supposed to give general information about the CMS reconstruction program: ORCA. It consists of two major parts, an introduction into the usage of ORCA for beginners and a part giving general information about the different subsystems of the program like Calorimetry, Tracker, GeneratorInterface, CARF or Examples. The information is completed by appendices on related technicalities like Objecitiviy/DB commands. Complementary to this UserGuide a ReferenceManual is created for each version of ORCA that contains more techincal details of the program like a list of all classes, the methods of each class, the inheritance structure and relations between different classes. All information about ORCA can be found from the main WWW page at CERN: This page contains links to the Manuals of all important releases, to talks and tutorials, to the remedy feedback system, information on how to install ORCA and how to subscribe to the existing mailing lists. 1.2 What is ORCA ORCA is a framework for reconstruction and is intended to be used for final detector optimisations, trigger studies or global detector performance evaluation [3]. It is an object oriented system for which C++ has been chosen as programming language. The acronym ORCA stands for Object Oriented Reconstruction for CMS Analysis. ORCA is a work in progress. The development takes place on a roughly four month schedule. Its design is based on CARF, the CMS Analysis and Reconstruction Framework, which was developed to prototype reconstruction methods, initially for testbeam applications. It is still a prototype, but one that is already usable by CMS physicists. This causes inevitably accidental conflicts between developers, who need to correct their prototypes sometimes and users who expect them to remain valid for a long period of time. It is hoped that both these groups adopt a respect for the others problems, the developers trying to avoid rapid fluctuations and the users accepting the occasional changes that can result in them having to modify their code. Nevertheless, there is a system of code versions in use so it should always be possible for users to work with a fixed version - however of course with the rapid devlopment taking place at the moment they will soon get out of date. 3

10 4 CHAPTER 1. WELCOME TO ORCA 1.3 The basic structure of ORCA ORCA has two logical layers, subsystems and then within a subsystem packages. For an overview of the currently available subsystems see Figure 1.1. ORCA CommonDet Jets ElectronPhoton TestBeams Calorimetry TrackerReco btauanalysis DAQ CommonReco Visualisation MuonAnalysis H4Ecal Tracker Vertex JetMetAnalysis Data Muon Workspace Examples Trigger MuonReco Documentation Figure 1.1: Subsystems of ORCA. The packages within a subsystem typically produce a single library dedicated to cope with a certain aspect of the corresponding sub-detector (e.g. for Calorimetry: G3EcalDigits, G3HcalDigits, EcalCluster,...) or reconstruction utility. For this note the subsystem Examples is of special interest. There the packages correspond to typical analysis tasks performed by normal users. The subsystem Workspace has the same task, only that it is ment as a working environment for the users private code. For each standard package at least the following four sub-directories are present, where only the first two are of interest for external users of the packages: doc The documentation related to the package. interface The C++ header files that can be referenced from other packages in the same or in different subsystems. In case of missing documentation these header files reveal the implemented functionality of the package. src The actual source code and C++ header files local to the package. test Source code of test programs for quality control of the package. Besides the individual packages a subsystem has a directory domain containing files and documentation which are common to the packages of the subsystem. 1.4 Required software 1.5 Supported platforms It has been agreed to support ORCA on SUN and Linux (currently CERN Redhat 6.1) machines. With most of the developers working on Linux PCs usually ORCA is better tested on that platform. Running on any other Linux

11 1.6. EXPORTABILITY 5 FAMOS OSCAR ORCA COBRA IGUANA Figure 1.2: Relation with other CMS OO projects. flavour (e.g. Redhat 7.2 or Suse 7.x/8.0) is probably not covered by the Objectivity licenses of CERN. Versions starting with ORCA use for Linux gcc Solaris Workshop 6.2 with CC 5.3 (not yet for ORCA 5.1.0) 1.6 Exportability Version 1 of ORCA was in practice usable only on CERN machines and not exportable. The architectures SUN (e.g. cms.cern.ch) and Linux are supported, a special version for Windows NT is available. Version 2 has been successfully exported to Fermilab and Dubna machines. There will be a special chapter on how to install ORCA on a remote site. Starting with Version 3 ORCA is exported to a multitude of different sites. The tool scram can be used to access the different versions of ORCA. To run ORCA on a non-cern machine a lot of additional software is needed. In particular, the CERN libraries (2001), LHC++ (3.6.6), doxygen, dot and various CMS utilities as well as the cmsim (v125) Simulation program and the SCRAM configuration management tool (V0.19.3). ORCA 6 uses the basic CMS OO tools and framework from COBRA (6.1.0). If you intend to use the visualisation options of ORCA also IGUANA (2.7.6) is needed with OpenInventor and OpenGL.

12 6 CHAPTER 1. WELCOME TO ORCA

13 Chapter 2 Getting Started This chapter gives an introduction in the usage of ORCA. The intended audience are normal users who want to do physics analysis or detector studies things they did in the past with CMSIM [2]. People participating in code development for ORCA itself need a deeper understanding of the framework; they may however also profit from this document. The general layout of the system and some technical or slang expressions used will be discussed. Also a step by step instruction on how to use the Workspace and Examples subsystems will be given. Special emphasis is put on the predefined Workspace for private programs of the users. Finally an example application is discussed in detail. As for the other CMS offline software projects, the tool SCRAM is used to build, configure and even distribute the ORCA code. The recipe section is ment just as such. You should in any case read the rest of this introduction. When using the recipe execute every single step one by one, unless you have read the detailed explanation and know what you are doing. The recipe applies only to users on CMS machines at CERN. Everybody else: check the details! The commands in the recipies are given for csh/tcsh only, since this is the default for CMS. The detailed explanation gives the commands for sh/bash/zsh as well. 2.1 Recipe for the impatient USER 1. Prepare the ORCA environment: scram project ORCA ORCA cd ORCA 6 3 0/src 2. Initialise the environment (PATH and path to search shared libraries): eval scram runtime -csh The apostrophes in this command are the backward-single-quotes. On PC keyboards the key is located left of the 1-key, on SUN keyboards it is the rightmost key on the line with the numbers. Make sure you issue this command before any scram b to avoid problems! 3. Checkout the Workspace from the CVS server: 7

14 8 CHAPTER 2. GETTING STARTED cmscvsroot ORCA cvs login When prompted for the password, enter 98passwd cvs co -r ORCA Workspace cd Workspace You should always specify the name of the release you are using when checking code out of the CVS repository. 4. Copy your source code to this directory. The directory already contains a simple Example program ExRun- Event.cpp printing run and event number. 5. Edit the BuildFile to make your executables known. (The BuildFile is setup to compile ExRunEvent. 6. Build the stuff, first the library, then the executables. (To simply try this, please do touch ExRun- EventInfo.cc first.) scram b shared scram b bin 7. Rescan your path for new executables rehash 8. Setup the ORCA environment (OO FD BOOT, DETINPUT, GEANEUSED) eval scram runtime -csh examples.env (*) (*) This works at CERN only. This sets the environment to read from an Objectivity database. If you want to read from a different database, change the environment variable OO FD BOOT correspondingly. See Section on how to access the official production databases. For more details on ORCA environment variables see Section Run your program by simply typing its name, e.g. ExRunEvent. The first 10 events will be analysed. The program simply prints run end event numbers for the trigger events and event numbers for pileup events 2.2 Accessing ORCA Where to find the code The CVS server ORCA is available from a dedicated CVS 1 server running at CERN. Standard cvs commands have to be used to get files from the repository, or, as an authorised developer, store the files in the repository. The public checkout area A public checkout area (/afs/cern.ch/cms/releases/orca) contains the most important versions available. There one has easy access to the full source code, e.g. of the header files and the examples. A snapshot version of the HEAD of the ORCA repository updated approximatly every four hours can be found in /afs/cern.ch/cms/oo/software/snapshots/orca. 1 Concurrent Versioning System, [4]

15 2.2. ACCESSING ORCA Versions of ORCA The versions of ORCA follow a special naming scheme, containing three numbers, e.g. ORCA The numbers indicate the major release number (5), changes in interfaces within a minor release (4) and bug-fixes within the release (2). Releases of ORCA are announced in the CMS news system. A list of all releases and their release notes (a brief description of what changed with respect to the last version) can be found at It is recommended to always use the latest release and the latest interface version. If unaffected by the bugs fixed in bugfixes (check the release notes!) older version with the same interface can be used. But since a bug is a bug it is certainly a good idea to use the release including the fix. Using cvs tags Developers have also the possibility to tag code with names to their liking. This tagging can be done on package or subsystem level. In principal any meaningful tagname is allowed, e.g. dbioworks. Some tag names are reserved and can only be used by the CMS librarien (those containing ORCA for example). In addition during the release phase of a new major or minor version tags with names like ORCA pre6 are used to tag code that is fully tested and integrated for the new release. These pre-releases contain mostly only a subset of all ORCA code. The tags will be put by the CMS librarien and their use is prohibited for everybody else. The same applies to the official release tags like ORCA Only developers may want to access the HEAD version of the code. This version contains the latest changes done by the developers and does not necessarily work. Caution: When checking code out of the repository the default is to get the HEAD version. Unless beeing a developer working on your own code you always want to specify a tag using the -r tagname flag Access to the ORCA CVS server Users and developers access the CVS server in different ways. Normal users In a CMS environment you can simply type cmscvsroot ORCA to set the CVSROOT shell variable. If this doesn t work, try it by hand: CSH-style: setenv CVSROOT :pserver:anonymous@cmscvs.cern.ch:/cvs_server/repositories/orca SH-style: export CVSROOT=:pserver:anonymous@cmscvs.cern.ch:/cvs_server/repositories/ORCA Then type cvs login and give 98passwd as password. Developers have three different ways to access the CVS server. At CERN and as member of the CMS group (ZH) they can use the command project ORCA to preset their environment for work with ORCA. Alternativly, they can use kerberos tickets or the secure shell (ssh) to access the server. For more information on accessing the CVS server see server.html The CVSROOT variable has to be set every time you login and want to use the CVS server.

16 10 CHAPTER 2. GETTING STARTED Setup the private working environment To actually build ORCA the tool SCRAM [8] is used 2. This introduction will not discuss all details of SCRAM. A powerful online help is available with the command scram help. The first thing to do is to choose a directory which will contain source files, libraries and executables. Again there is a difference between regular users of ORCA and ORCA developers. A normal user will check out only a few files from the CVS server, since everything else is present in the central installation. Typically the only thing to get is the subsystem Workspace, where then the private code is put. For users the setup should be somewhere in the users home directory structure, where regularly backups are made. For CERN/CMS users their AFS directory is recommended. You can ask for 500 MByte of AFS scratch space with an to afs.support@cern.ch. A developer will typically check out a larger amount of code, but this code is only taken from the CVS server and modifications to it can (and should) be saved there frequently. Therefore they should work in some scratch space. To perpare to work with ORCA, 1. go to the directory where you want to create your local copy 2. Type scram project ORCA release. A subdirectory with the name ORCA release will be created. The command scram list will print a list of valid releases. The name of the subdirectory can be choosen with the -n NAME option of the scram project command. 3. Go into src subdirectory of the directory that has just been created (cd ORCA release/src). 4. Use eval `scram runtime [-csh -sh]` to initialise the shell environment variables. The apostrophes in this command are the backward-single-quotes. On the keyboard the key is located left of the 1-key or on SUN keyboards it is the rightmost key on the line with the numbers. This sets the PATH and initialise the search path for shared libraries. It is important to execute this command before trying to build any binary. 5. Add the subsystems/packages you want to work on using standard cvs commands. A normal user should normally only get the subsystem Workspace: cvs co -r ORCA 6 3 0Workspace. A developer may check out whole subsystems: cvs co -r tag subsystemname, e.g. cvs co -r dbioworks CARF. It is also possible to get only a single package from a subsystem, e.g. cvs co -r ORCA Examples/MCinfo. This command can be used in several ways. You can choose the HEAD version with cvs co Examples or any other valid tag. If you have checked out a tagged version you need to use cvs update -A to move to the HEAD version to be able to commit the changes Using the predefined Workspace Setup the user files The subsystem Workspace is provided to allow the user to easily compile his private analysis code and link it against the central ORCA libraries. The Workspace has no specific structure like the other subsystems, it contains only a default BuildFile. BuildFiles are used to tell SCRAM what libraries to use and what executables to build. 2 For ORCA version 1 another tool, SRT, was used. Since it is no longer supported it will not be described in this and future version of this document. 3 When working with branches you need to update to the head of the branch with -r branchname instead of -A.

17 2.4. BUILDING AND RUNNING ORCA 11 Then copy your source files i.e. your own C++ analysis code to the new subsystem Workspace and define the (executable) targets in the Buildfile by adding lines like <bin file=myprogram.cpp></bin> The BuildFile is setup to use only libraries CARF and Utilities for a SimReader application by default. If you need additional libraries, e.g. because you want to use Calorimetry, you have to uncomment the corresponding lines. For a brief introduction to BuildFiles see Section 2.8. Source files that are not defined as bin targets will be compiled and put into a library. The convention is to have the extension.cpp for bin targets and.cc for classes that should go into the library. RULE: Every.cc and.cpp file must have the line #include "Utilities/Configuration/interface/Architecture.h" as first line Build and run the programs To build your executable and library you can use the commands discussed in Subsection Building and running ORCA Building libraries and executables Once you have checked out some code from the repository or added your code to the Workspace you will want to build the libraries and programs you got. For this a single command scram build is sufficient. This command can be given at any level of the checkout area, starting in the directory.../orca release/src and below. Only code that has changed with respect to the central installation in /afs/cern.ch/cms/releases/orca/... will be recompiled. For the compilation step the debug options are enabled by default. A package in a standard subsystem like Calorimetry or Tracker usually contains a test suite to verify the correct functioning of the corresponding library. The source code for these executables are located in the test subdirectory of the package. They are created when a scram build (or simply scram b) is issued in that particlular test directory. Executables in the Example and Workspace subsystems are created by default. The command scram b clean can be used to delete all dependency files, object files, libraries and executables related to the level where you give it. Typing it in.../orca release/src will delete all created files and you can restart like after the cvs co command Running an executable Starting from ORCA 4 we distiguish between different types of ORCA applications. To start with there exist G3Reader to read a CMSIM FZ-file and populate an Objectivity database with the simulated hits for the different subdetectors,

18 12 CHAPTER 2. GETTING STARTED SimReader to reads that database and to do the digitization and reconstruction of higher level objects if asked for. In this step signal (trigger) and minimum bias (pileup) events are added corresponding to the required luminosity. It is possible to store some of the objects back into the database, RecReader to read Digis and RecHits from the database that have been stored by the SimReader. These names correspond to CARF group names that can be used in BuildFiles. Most users will run RecReader applications. Currently ORCA G3Reader applications read the detector geometry from RZ files created with CMSIM. The geometry is stored in the database and SimReader and RecReader read it from there. Configuring the application In addition to the scram runtime command one needs to define additional environment variables. ORCA programs need to know where to find the Objectivity federation (the collection of databases) to use. This is specified with the variable OO FD BOOT or with the.orcarc paramenter BootFile. For a G3Reader - the RZ-file that contains the CMSIM geometry needs to be specified with the DETINPUT variable. Finally, to successfully reconstruct muon tracks GEANE is required to trace particles through the magnet yoke. This is enabled by setting the variable GEANEUSED to the value TRUE. Everything else, i.e. the selection of input files or databases to read or to write and all parameters to algorithms are specified in.orcarc files. For that purpose simple scripts are provided with the various packages, choosing reasonable values and linking to existing example input files. To read from the central test federeation at CERN only one environment variable has to be set: Variable OO FD BOOT Value suncmsc.cern.ch::/data/valid/orca 6 0 2/VALIDATION.boot Table 2.1: The most important ORCA environment variable In addition the data to read from this federation has to be specified in a.orcarc file in the local directory. MaxEvents = 10 InputCollections = /System/SimHits/single_mu_pt50/single_mu_pt50 This example specifies (to an ORCA SimReader application) to use the dataset single mu pt50 with the owner name SimHits. The dataset name specifies normally the kind of events (here single muons with 50 GeV transvers momentum) and has to be repeated. The owner name indicates how the events have been treated. Here for example it is just the simulated hits. Other examples are NoPileup or Lumi1034 for data that has been digitised for no pileup or for pileup corresponding to a luminosity of cm 2 s 1. For SimReader applications the information on pileup treatment can be given 4. Pileup can be switched off by setting PUGenerator:AverageEvents to zero. 4 Only up-to For later versions no Pileup is used if no PUGenerator: datacard is given.

19 2.5. SETTING THE.ORCARC PARAMETERS 13 RecApplication:MaxEvents = -1 PUGenerator:Collection = /System/SimHits/minbias/minbias PUGenerator:AverageEvents = 4.67 PUGenerator:MinBunch = -5 PUGenerator:MaxBunch = 3 PUGenerator:FirstEvent = -2 Selecting runs and events The selection of a specific run is done with the InputCollections parameter. For example InputCollections = /System/NoPileup/single_mu_pt50/EvC_Run2 selects run number 2 in the dataset single mu pt50. Individual events can be selected with SelectEvents or rejected with RejectEvents. They are identified in the form run:event SelectEvents = 1:3 1:9 2:39 RejectEvents = 1:111 2:6 And execution... Finally one can run the program by just typing its name. This works because the PATH has been adopted by the scram runtime command. Eventually the unix command rehash is needed to make the shell find the executable. 2.5 Setting the.orcarc parameters Some of the most important.orcarc parameters from COBRA are given in Table 2.2. More details on the.orcarc parameters defined in ORCA are given in Appendix C and in the ReferenceManual. 2.6 Populating a database - the full chain Even with many important dataset available from the official HLT UserFederations, a physicist may want to study his own private set of events. This chapter tries to explain how to create an Objectivity/DB federation on a local disk and store the events in it From the event Generator to a cmsim FZ file Most people are familiar with this step. For details please check the cmsim documentation. Here only a few reminders. Examples of geometry and FZ-event files are available in /afs/cern.ch/cms/oo/reconstruction/datafiles. There also the datacards used for the production of the FZ files are stored. They can be used as examples for private

20 14 CHAPTER 2. GETTING STARTED TYPE NAME DEFAULT Vector<int> CMSRandom:Seeds bool Verbose:info true bool Verbose:test false bool Verbose:debug false Vector<string> FZInputFiles int G3FZ:SkipEv 0 float DBPopulator:MaxDBSize 1.0 int DBPopulator:CommitInterval 200 bool DBPopulator:UseMutex true bool DBPopulator:UnNamedContainers false int DataSet:JobsPerDB 4 int DataSet:DBPoolIncrement 1 string EDLocation::EventDB Events Vector<string> EDLocation::OtherDBs bool GoPersistent false bool Digi:Update false string InputCollections string OutputDataset unsigned int InputRun 0 unsigned int FirstEvent 0 int MaxEvents -1 bool MemoryDebug false Enum<PUGenType> PUGenerator:Type Poisson (Auto, Fixed, Poisson, HIC) bool PUGenerator:NoReuse bool PUGenerator:AllEvents false string PUGenerator:xxx int PUGenerator:FirstEvent -1 float PUGenerator:MaxRange 10. float PUGenerator:AverageEvents 0. int PUGenerator:MinBunch 999 int PUGenerator:MaxBunch -999 Table 2.2: Some CARF parameters for the.orcarc files. For more check the sections of the different subdetectors.

21 2.6. POPULATING A DATABASE - THE FULL CHAIN 15 simulation jobs. One hint: Make sure to give enough arguments (1.0 as last) to the KINE datacard to store the Monte-Carlo generator information to the FZ file. A geometry file can be created with the datacards CFIL DETO xxxx.rz RSAV INIT in the CMSIM run How to create and initialise your own federation First thing to do is to create a new federation if one doesn t have one. To do so 1. Go to the directory where you want to store your database. It should have some enough disk space, e.g. $SCRATCH, but careful! On central machines files in $SCRATCH may (and will) be removed. 2. Create the federation with one of makefd scripts (in the PATH after a scram runtime) makefd.central 5. If you are using bash, ksh or zsh, you should give -sh as argument. It will create a subdirectoy call myoofd. 3. Execute the script fdinit.csh (or fdinit.sh in the myoofd directory, using source or. (dot), respectivly. Make sure you don t have the OO FD BOOT environment variable set when you run this script! If you already have a federation, just execute the fdinit.(c)sh script. This script will set the neccessary environment variables. Databases corresponding to different versions of ORCA are a priori not compatible. It is technically possible to upgrade databases, but for time beeing it is recommended to create a new database for each major and minor ORCA release. Running private lockservers and ams When working on a private PC or workstation, we recommend to run on this machine a private lockserver and a private ams. This increases the performance (when contacting the lockserver, it s only a local access) and makes it easier to recover from some problems that can happen when an ORCA program is aborted at inappropriate times. Do NOT run ams on the central machines! First thing to do is to initialise our shell for Objectivity/DB if you have not yet done so. Type: eval scram runtime -csh Then start the lockserver and the ams: oolockserver oostartams These commands have to be executed once and repeated only after a reboot of the machine. To use the private lockserver, the makefd.local script needs to be modified. Copy it from the bin/system directory of the central 5 Several versions of makefd scripts exist. On machines in the CMS cluster at CERN makefd.central should be used. For private machines use makefd.local. To use a laptop, make sure the hostname is constant. This can be insured by specifying the line myhost myhost.mydomain localhost localhost.localdomain in the file /etc/hosts.

22 16 CHAPTER 2. GETTING STARTED release area you use and change the lockserver mentioned in that file to your local machine. Every federation created after that with the script will use your lockserver. Running the ams will allow you to access your federation from different machines, setting the OO FD BOOT variable to host::/localpath/orcatest.boot Storing the SimHits from FZ file to Objectivity The first thing to store in an ORCA database are the simulated GEANT hits from the FZ files. An example program to do this is Examples/ExProduction/writeHits.cpp. This file is empty - choosing the correct libraries when linking the application is the crucial point. This piece of code obviously doesn t do much the secret is in the BuildFile. Here the relevant part: <environment> <External ref=cmsim> <External ref=objectivity> <External ref=hepodbms> <Group name=g3> <Group name=g3reader> <external ref=cobra Use=CARF></Use> <ignore> To produce all Ecal, Hcal and Preshower hits </ignore> <Group name=calohitwriter> <Use name=calorimetry> <ignore> To produce Muon barrel, endcap and RPC hits </ignore> <Group name=muonhitwriter> <Use name=muon> <ignore> To produce all Tracker hits </ignore> <Group name=tkhitwriter> <Use name=tracker> <lib name=pbasicdet></lib> <Use name=commondet></use> <external ref=cobra Use=Utilities></Use> <bin file=writehits.cpp></bin> </environment> Before running the program several environment variables have to be set and a database has to be created and initialised (makefd, fdinit). Mandatory environment variables are: Variable OO FD BOOT DETINPUT Description bootfile of the federation Input geometry Table 2.3: the remaining ORCA 5 environment variables for writing SimHits into a database

23 2.6. POPULATING A DATABASE - THE FULL CHAIN 17 In addition some entries have to be made in the.orcarc file: # where is the CMSIM input file? FZInputFiles=/afs/cern.ch/cms/oo/reconstruction/datafiles/cms125/single_mu_pt50.fz # configure the number of events to process (-1 means everything) MaxEvents = 1000 # specify the output owner and dataset name OutputDataSet = /System/SimHits/single_mu_pt50 # we certainly want to store the hits GoPersistent = Mixing signal and pileup events and storing RecHits into the database To read the SimHits from a database one needs not only the correct code, but also a different set of libraries. Most importantly instead of using G3Reader one needs SimReader from CARF. Again, private source code is not needed.here is an Example (Examples/ExProduction/writeDigis): <environment> <External ref=objectivity> <External ref=hepodbms> <Group name=g3> <Group name=simreader> <external ref=cobra Use=CARF> <ignore> To produce Calorimetry digis</ignore> <Group name=calohitreader> <Group name=calorhitwriter> <Group name=calorhitreader> <Group name=triggerprimitivewriter> <Use name=calorimetry> <ignore> To produce all Muon digis </ignore> <Group name=muondigiwriter> <Use name=muon> <ignore> To produce Tracker digis </ignore> <Group name=tkdigiwriter> <Use name=tracker> <Use name=commondet> <external ref=cobra Use=Utilities></Use> <bin file=writedigis.cpp></bin> </environment> The only environment variable to set is this time OO FD BOOT. Everything else is specified in the.orcarc file: Where to read the pileup, the number of events to process and/or to skip and many parameters for the digitisation are defined in the.orcarc file:

24 18 CHAPTER 2. GETTING STARTED # This will skip the first 10 events and process 5 signal events in total. FirstEvent = 10 MaxEvents = 5 InputCollections = /System/SimHits/single_mu_pt50/single_mu_pt50 # general pile-up specifications PUGenerator:Collection = /System/SimHits/minbias/minbias PUGenerator:AverageEvents = 4.67 PUGenerator:MinBunch = -5 PUGenerator:MaxBunch = 3 #owner and dataset name for the output OutputDataSet = /System/Lumi1033/single_mu_pt50 # and to really save it GoPersistent = 1 # parameters for calorimeter code CaloRecHit:EcalBarrel = 1 CaloRecHit:EcalEndcap = 1 CaloRecHit:HcalBarrel = 1 CaloRecHit:Preshower = 1 Ecal:Barrel:noise = 0.03 Ecal:Barrel:threshold = 0.06 Ecal:Endcap:noise = 0.15 Ecal:Endcap:threshold = 0.30 Hcal:noise = Hcal:threshold = Presh:noise = Presh:threshold = Calo:Preshower:MinBunch=-2 Calo:Preshower:MaxBunch=1 # parameters for muon code Muon:Barrel:MinBunch = 0 Muon:Barrel:MaxBunch = 0 Muon:EndCap:MinBunch = 0 Muon:EndCap:MaxBunch = 0 Muon:Rpc:MinBunch = 0 Muon:Rpc:MaxBunch = 0 # parameters for trigger code EcalTrigPrim:Threshold = 0.3 HcalTrigPrim:Threshold = 0.3 # how often to save DBPopulator:MaxDBSize=1.0 DBPopulator:CommitInterval=50 In principal it is possible to run this step without saving the RecHits/Digis database. But since the digitisation step is where a lot of CPU time is needed storing the RecHits/Digis is probably what you want.

25 2.6. POPULATING A DATABASE - THE FULL CHAIN Reading RecHits from database Finally the database is nicely populated and you want to read from it. This corresponds to a CARF/RecReader application. Again here is the BuildFile as taken from Examples/Statistics: <environment> <Group name=g3> <Group name=recreader> <external ref=cobra Use=CARF> <lib name=calohititr></lib> <lib name=calohit></lib> <lib name=calorechit></lib> <lib name=caloreadout></lib> <lib name=calodetector></lib> <lib name=calocommon></lib> <lib name=mrpc> <Group name=muonb> <Group name=muone> <Group name=muonrpc> <Use name=muon> <Group name=tkdigireader> <Use name=tracker> <Use name=commondet> <external ref=cobra use=magneticfield> <external ref=cobra Use=Utilities> <bin file=exrechitstatistics.cpp></bin> </environment> Again, only the OO FD BOOT environment variable has to be set. The.orcarc needs less options, actually it s only needed to specify what data to read: # This will skip the first 10 events and process 5 signal events in total. FirstEvent = 10 MaxEvents = 5 InputCollections=/System/Lumi1033/single_mu_pt50/single_mu_pt Upgrading a private database to a new schema Populating a private database is timeconsuming and means some work. Logically one wants to avoid this. New ORCA versions may have a different schema that prevents parts of the new code to use the an older database. Often the database can be upgraded to the new schema - this means makeing the new additional or modified objects known to the database. To do so simply type

26 20 CHAPTER 2. GETTING STARTED ooschemaupgrade -infile.../data/domain/orcaschema.dmp \\.../myoofd/orcatest.boot where the dots obviously need to be replaced with the correct paths. ORCAchema.dmp is the schema dump of the new version of ORCA, ORCATEST.boot is the boot file of the old federation. Warning: It is not possible to upgrade an ORCA5 federation to ORCA Reading from the official production databases in the UserFederation To read from the official production databases that have been created for the Jet/missing E t and Muon groups, please use the command setenv OO_FD_BOOT xxxxxx to specify the userfederation you need. To access specific datasets it is necessary to specify the correct values in the.orcarc file. The HLT groups maintain tables with the corresponding information. Follow the link on the ORCA web page to access information about the official UserFederations. 2.7 A simple example analysis In this subsection a simple example analysis will be discussed. The example demonstrates how to tell ORCA to build clusters in the electro-magnetic calorimeter, how to access the information (E, η, φ) of the clusters and how to fill some histograms. The source code is contained in five files in the directory Examples/ExCalorimetry: ExClusterHistograms.cpp, ExClusterHistos.cc, interface/exclusterhistos.h, ExClusterInfo.cc and interface/exclusterinfo.h. The first file contains the minimal required code for an ORCA application, in the next two a histogram class is defined and the last two contain the code and definition of the analysis class. The reason to split the code into several source files is to minimise compile and link time to make fast development possible. Haveing the analysis code which is more likely to change in a shared library makes it possible to avoid the very time consuming linking step to a large extend. To understand the examples the user should have some basic familiarity with the C++ programming language [6] Basic building blocks of an ORCA application The way to register a private analysis class, i.e. usually a class that inherits from ActiveObserver or Lazy- Observer is largly simplified in ORCA 4. Here what is in ExClusterHistogramss.cpp: #include "Utilities/Configuration/interface/Architecture.h" #include "Utilities/Notification/interface/PackageInitializer.h" #include "Examples/Histograms/interface/ExClusterInfo.h" PKBuilder<ExClusterInfo> mybuilder("exclusterinfobuilder"); The small file consists of three include directives, Architecture.h which is mandatory for all.cc and.cpp files, PackageInitializer.h for definition of the package builder and finally the header file for the user analysis class. Then an object of class PKBuilder, templated with the user analysis class is declared. Several objects are possible, corresponding to several analyses. They have to be distinguished by the name given as argument (here ExClusterInfoBuilder).

27 2.7. A SIMPLE EXAMPLE ANALYSIS User-provided classes In addition, to do any kind of analysis one needs an observer class (that does the analysis) and a histogramming class (to define, fill and to save histograms or ntuples). An observer is an object that will be automatically notified if certain things happen. Here, the analysis class inherits from the class ActiveObserver to become an observer. ActiveObserver is templated 6 and here precisely it will be an observer of objects G3EventProxy, i.e. events produced by GEANT3. This results in the analysis class being notified when ORCA has read a new event and handed over a pointer to this event. Here is the class definition (from ExClusterInfo.h): class ExClusterInfo : private ActiveObserver<G3EventProxy *> { public: /// default constructor ExClusterInfo(); /// default destructor ExClusterInfo(); /// this method will do the user analysis void myanalysis(g3eventproxy * ev); private: /// don t change the name "update" - this method is mandatory. void update(g3eventproxy * ev) { if (ev!=0) myanalysis(ev);} private: unsigned int eventsanalysed; //!< just to count events that have been analysed unsigned int runsanalysed; //!< count the runs unsigned int lastrun; //!< number of the last run analysed ExClusterHistos * UserHists; //!< pointer to the Histogram class }; The class has a constructor, a destructor and a public method myanalysis. This method will actually do the analysis. Furthermore there is a private method update. This method is mandatory for ActiveObervers and will be called if a new event is processed by ORCA. Here it will then just call the analysis method of the class, provided the pointer to the event is not the NULL pointer. To do some statistic of the events processed some private data members are defined. Since they are private they can only be modified by methods of our analysis class. Finally a pointer to an instance of a histogram class is available. Let s now look at the implementation of the methods (in the file ExClusterInfo.cc) - first the constructor. It is automatically called when a new instance of the class is created. Therefore one can do here the necessary initialisations. Since we want to fill some histograms here the histogram class is instantiated. ExClusterInfo::ExClusterInfo() { cout << "===========================================================" << endl; cout << "=== Start create new ExClusterInfo ===" << endl; eventsanalysed = 0; runsanalysed = 0; lastrun = 0; // Instantiate the user histogram (capitals in filenames are ignored by ZEBRA) UserHists = new ExClusterHistos("exhistogram.hbook"); // UserHists = new ExClusterHistos(); // an alternative, // default filename is calohistos.hbook cout << "=== Done create new ExClusterInfo ===" << endl; 6 C++ terminus. If something is templated it works with different types or objects in the same way. E.g. it works with int, float or like here with pointers to different kinds of classes.

28 22 CHAPTER 2. GETTING STARTED } cout << "===========================================================" << endl; Similarly the destructor is automatically called whenever an instance of the class is deleted. Consequently one can do here some final calculations and print a summary. ExClusterInfo:: ExClusterInfo() { cout << "===========================================================" << endl; cout << "=== Start delete ExClusterInfo ===" << endl; cout << " Number of events analysed: " << eventsanalysed << endl; cout << " Number of runs analysed: " << runsanalysed << endl; UserHists->FillEventStat(eventsAnalysed,runsAnalysed); // Cleanup the Histograms - here they will be saved to file delete UserHists; cout << "=== Done delete ExClusterInfo ===" << endl; cout << "===========================================================" << endl; } Some of the summary information is filled into a histogram in this case. To avoid a crash of a program the histogram object must still exist at that point. Only then the instance of our histogram class is deleted (and during its deletion the histograms are saved to file). Finally follows the method where the analysis is done: void ExClusterInfo::myAnalysis(G3EventProxy * ev) { int nclusters=0; // just to count the clusters // We want to loop over all calorimetric clusters -> get an iterator. // The iterator needs to know about the event to use. // What kind of clusters we use is determined by the libraries specified in // the BuildFile, here:<lib name=ecalfixedwindow> RecItr<CaloCluster> MyCluster(ev->recEvent()); // Just print the event number (see CARF/G3Event/interface/G3EventHeader.h) cout << "===========================================================" << endl; cout << "=== Private analysis of event #"<< ev->id().eventinrun() << " in run #" << ev->id().runnumber() << endl; eventsanalysed++; // some statistics: count events and runs processed if (ev->id().runnumber()!= lastrun) { lastrun = (unsigned int) ev->id().runnumber(); runsanalysed++; } // Here is the loop over all clusters while (MyCluster.next()) { nclusters++; // count the clusters // Print some of the cluster properties // see Calorimetry/CaloCommon/interface/CaloCluster.h cout << "Cluster " << nclusters <<": E=" << MyCluster->Energy() << ", eta="<< MyCluster->Eta() << ", phi="<< MyCluster->Phi() << endl; // Fill them to (our) histograms. Defined in ExClusterHistos.h UserHists->FillEepCluster(MyCluster->Energy(), MyCluster->Eta(),

29 2.7. A SIMPLE EXAMPLE ANALYSIS 23 MyCluster->Phi()); } // Fill (our) histogram for statistics UserHists->FillNCluster(nClusters); cout << "===========================================================" << endl; }; The important point here is the use of an iterator, RecItr. Again this is a template - here it is used for objects of the class CaloCluster. It reduces loops over all clusters to the simple statement while (MyCluster.next()) {}. Then member functions of the CaloCluster class are used to access information about the current cluster, like its energy, E, (Energy()), its pseudo-rapidity, η, (Eta()) and its azimuthal angle, φ, (Phi()). This information is filled into histograms with member functions of the EcalHisto class. The last missing part is the histogramming class. Here the definition from the file ExClusterHistos.h: class ExClusterHistos : private HB4Histogrammer { public: /** The default constructor with the default arguments. * Missing arguments will be added automatically with the value given here. */ ExClusterHistos(const char * filename = "calohistos.hbook", int lun=10) : HB4Histogrammer(filename, lun) { BaseInit(); } /// The destructor. Here the final cleanup is done. ExClusterHistos() { BaseEnd();} // Public methods to access the user histograms /** Fill histograms for the energy \a e, the pseudorapidity \a eta and * the azimuthal angle \a phi.*/ void FillEepCluster(float e, float eta, float phi); /** Fill histograms for the number of clusters \a n. */ void FillNCluster(int n); /** Fill histograms for statistics with the number of events * \a events and runs \a runs analysed. */ void FillEventStat(unsigned int events, unsigned int runs); private: // private methods both are mandatory virtual void book(); //!< book the histograms virtual void hend(); //!< save the histograms to file public: // public data is forbidden by CMS coding rules private: // Define some abbreviation. These are pointers to one and // two-dimensional histograms. Put these into the class. This // avoids conflicts in the global namespace, which you should not // pollute anyway. typedef auto_ptr<chbookhisto> HP1; typedef auto_ptr<chbookhisto2> HP2; typedef auto_ptr<chbookhistoprof> HPP; private: // private data // Since they are private, histograms are accessable only via public methods HP1 hcalo1,hcalo1b, hcalo2, hcalo3, hcalo4, hglobal; HP2 hcalo5;

30 24 CHAPTER 2. GETTING STARTED HPP }; hcalo6; The class inherits its general functionality from the HB4Histogrammer class. This is taking care of the ZEBRA bookkeeping (no more hlimit) and the file handling. The constructor of ExClusterHistos has as arguments a filename and a unit where to open the file. Sensible default values are provided. These are automatically used when the constructor is called with one or both arguments left out. Three public methods are defined to provide access to the (private) user histograms. The use of public class data is prohibited by the CMS coding rules [7], so one cannot fill histograms directly. Another good reason for this is to avoid changes to the analysis class. If you for instance decide to fill the cluster information to Ntuples instead of histograms the analysis class need not change. It s only using the public Fill... methods and does not care if these methods fill histograms or ntuples. There are two mandatory private methods: book() and hend(). They are required by HB4Histogrammer and called in the constructor and destructor of the class, respectively. Finally a number of pointers to histograms are defined. HP1 and HP2 are abbreviations for pointers to one- and two-dimensional histograms, defined in ExClusterHistos.h. The source code for the methods is located in ExClusterHistos.cc. Here is the booking of the histograms done: void ExClusterHistos::book() { cout << "===========================================================" << endl; cout << "=== Start booking user histograms ===" << endl; // ID Name Nbins Min Max hcalo1 = HP1(new CHBookHisto (100, "Calo:E(cluster) ", 100, 0., 100. )); hcalo1b = HP1(new CHBookHisto (101, "Calo:E(cluster) ", 50, 0., 500. )); hcalo2 = HP1(new CHBookHisto (200, "Calo:n cluster", 101, -0.5, )); hcalo3 = HP1(new CHBookHisto (300, "Calo:eta(cluster)", 100, -2.5, 2.5 )); hcalo4 = HP1(new CHBookHisto (400, "Calo:phi(cluster)", 100, 0., 3.15 )); hcalo5 = HP2(new CHBookHisto2(500, "Calo:eta_vs_phi (cluster)", 100, -2.5, 2.5, 100, 0., 3.15 )); hcalo6 = HPP(new CHBookHistoProf(600,"Calo",100,-2.5,2.5,0.,3.2, " ")); hglobal = HP1(new CHBookHisto ( 1, "Events/Runs", 2, 0.5, 2.5 )); } cout << "=== Done booking user histograms ===" << endl; cout << "===========================================================" << endl; The arguments needed to define a histogram are the same as in FORTRAN/HBOOK commands. If the histogram ID is omitted an ID will be generated automatically. From the destructor of the class hend() will be called. Here one can do some printout or final manipulations of the histograms. void ExClusterHistos::hend() { cout << "===========================================================" << endl; cout << "=== Start cleanup user histograms ===" << endl; hcalo1->print(); hcalo1b->print(); hcalo2->print(); cout << "=== Done cleanup user histograms ===" << endl;