What we want to do :

     We want to see ORCA reconstruct some particles and then add a toy class.  We are all about using ROOT, so we will 'rootify' our class and see why they (whoever they are) say that using ROOT is so much better than PAW ...
 

How To generate a bunch of particles for the ORCA Analysis :

     Follow the instructions for making particles and turning on the CMSIM detector simulation package as described in "How To Simulate CMS Detector Response to Particles in CMSIM".  Setup ORCA, make a Federation/Database, and write your particle hits and digis to that Database as shown in "How To Setup ORCA v5_x_x at Fermilab".
 
 

Let's See A Sample Application :

    Hans Wenzel has preparded a sample program which takes a simple ORCA based application (to access and loop over Calorimeter data) and incorporates Root as well as add a second Root-based class to it.  The example is immediately extendable to the other Example included with the ORCA distributions.
 
 

    Download the Example here.  (It's called ExRoot1.tar)

    Check out the 'Root' sample program - there is nothing in here, but we want to take the CVS directory structure.  Untar the ExRoot1.tar file into this directory structure,

    cd ORCA_5_3_1/src/Examples
    cvs co -r ORCA_5_3_1 Examples/Root/
    tar xvf RootEx1.tar
    cd Examples/Root/

     Now build the shared libraries and the executable ...

     scram b shared
     scram b bin
     rehash

     Now we have an executable called 'ExRoot'.  Like the writeHits and writeDigis programs, all applications in ORCA have an .orcarc file.  You need to make sure that the OO_FD_BOOT variable is set to point to the database where your particles are and that your .orcarc exists and contains the correct information specifying what in the database you want to look at.  The .orcarc file for this example should have a designation for the InputCollections and MaxEvents.

     This program knows about ROOT and has an extra ROOT-based class attached to it, Atom.cc.  Look in the ExSimpleCaloAnalysis_Root.cc file.

     You can see where a root file and tree is created with a few lines like following :

     hfile=new TFile("hsimple.root","RECREATE","Demo ROOT file with histograms");
     ...
     ...
     ntuple = new TNtuple("testntuple", "Test Ntuple","run:event:pythia");

    And you can see there is also this :

  //  Atom * U240;
  U240  = new Atom("U240","Uranium 240 ",240,92);
  U240->PrintAtom();

    This is the implementation of the "toy" Atom class.  This class allows you to make a Atom object with a name, title, number of neutrons, and number of protons.  There is one method immediately employed here, the PrintAtom() method.  If you look at the Atom.cc file, you can see that this method simple prints some information about the things you entered for the name, title, number of neutrons, and number of protons.

   There's one more important thing thats done in ExSimpleCaloAnalysis_Root.cc program.  Look at where the line of code (in the destructor for the ExSimpleCaloAnalysis_Root class) :

     U240->Write();

   Since you looked at the Atom.cc file, you probably realize that this method is not defined there.  This method is inherited from ROOT.  It writes the object out to the Rootfile just like the method available for the ROOT TNtuple object created earlier.

    Let's execute the program ...

     ExRoot

   In the huge amount of text generated, you can see the output of the Atom->Print() method as well as the search for particles in the Calorimeter (what the ExSimpleCaloAnalysis_Root class is all about).

Result of the Atom->Print() method :

                     === now creating atom   ===
                    Name:   U240
                    Title:  Uranium 240
                    Number of of Nucleons:  240
                    Number of of Neutrons:  148
                    Charge:                 92
 

Notice it created the following root file:  hsimple.root

Let's look inside the Rootfiles and see whats going on.

Start up root, and do the following at the CINT command prompt:

root [0] .L Atom.so
root [1] TFile *f = new TFile("hsimple.root")
root [2] .ls

     You should see a list of everything in the Rootfile, a ntuple, a ttree, and Atom.  We had to load the shared library for Atom first, because this contains the information about the methods and class definitions for the Atom object.  This is exactly what we did when creating after creating a Root class from CINT in the "Using ROOT For Analysis of HEPEVT Ntuples" example.  When you looked in the Atom.cc file, you probably saw a couple other methods available for the Atom object.  We called this object 'U240' (you can see that after the .ls command in root as well).  These objects are available to us on the ROOT CINT command line as well.

root [3] U240->stable()
root [4] U240->PrintAtom()

     If you start a new TBrowser in root (ie root [5] new TBrowser()), double click on the hsimple.root file you see under the root files in now open, right click on the U240 object, and select 'DrawClass' from the menu that pops up, you will see all of the methods available to you for the U240 Atom object.  This is what makes Root so worthwhile - you can save a complete class and all its methods for later use with your data (ie its persistant).

     It might be hard to see with the Atom example, but imagine if we made a class which holds not just a few integers like the number of protons and neutrons, but a class which accepts arrays (or better yet, vectors from the STL), TTrees, ntuples, or even other classes (a sophiticated measurement class for example).  Rather than just a Print method, we could write more useful methods to sort or histogram the data.

   The ExRoot example is also nice because it shows you how the data which was at first stored in a PAW style ntuple (this example is derived from the 'ExSimpleCaloAnalysis' example which can be checked out with cvs) can be written directly to TTrees and Rootfiles.  Poke around the source code to get the general idea.
 

Some Details on How to Create Your Own ROOT Based Classes:

Pre-Requisite:  You have to know how to use ROOT.  It sounds obvious, but if you don't know what ROOT can do, or more importantly what ROOT classes/objects do what, this example is not really going to be very helpful to you.

The important things to do:

  Take a look at the following files: root_3.2.6 and /interface/AtomLinkDef.h.  The root_3.2.6 file is sort of like the BuildFile, it tells scram about ROOT.  The AtomLinkDef.h file is needed by any class which uses ROOT.  If you make a class that uses ROOT, you need to make a file which mimics this one.

   Now notice that you have two other suspicous files: AtomDict.cc and AtomDict.h.  These are intermediatary files generaed by ROOT for your class.  You can make them by using the command 'scram b rootdict'.   You will never want to edit the contents of these files, only regenerate them via scram.

     Like most C++ classes, we have a header .h file and a .cc implementation file for out Atom class.  Look at the ./interface/Atom.h file.  As you can see it's pretty standard C++ stuff where we have included some Root libraries.  The funny 'Int_t' and items that begin with a 'T' (like TNamed) are Root things, but you've probably seen this if you have played with root for awhile.  Notice one very important line in here -- the 'ClassDef(Atom,1)'.  You will need that line to get things compiled smoothly (it's another ROOT thing).

     In the Atom.cc file, we have an analog to the 'ClassDef(Atom,1)' line in the header file -- You will need to put the equivelent of 'ClassImp(Atom)' in any root root based class you create.  The rest of this file is standard C++.

     There is also a Makefile, which makes the shared libraries for the Atom class.  It's a pretty standard makefile, but I do not really understand how to make them very well, so I have to confess I've been copying and modifying this one when making my own classes.

   Finally, there is the all important BuildFile.  If you are new to programming ORCA stuff, let me just say the BuildFile is absolutely crucial and putting the right things in it makes all the difference.  You can see there are numerous references to ROOT, you will need the same if you make your own BuildFile for a new application and want to make rootified classes.

    That's about it.  I learned the most by playing with the Atom class and then trying to make a second class within this example.  After that, I made a program from scratch and had some success getting it to run.
 

Things You Want To Know:
 

     To completely clean out an area (Root stuff included) for a completely new recompilation of libraries and executables, do the following :

scram b clean
scram b cleanroot
rm *.so
rehash

     To build it all again :

scram b rootdict
make
scram b shared
scram b bin
rehash

     Notice that we have a new command in here, 'scram b rootdict' and 'scram b rootclean' -- these build and clean the Root Dict files.

     Sometimes, scram does not seem to catch that you have done someting new (ie it does not reflect changes or links against old libraries).  Try to do a 'touch *' command or look in the temp directories (in ORCA_5_3_1/tmp/Linux__2.2/src/Examples/Root).  You might try deleting all to files in this temp directory to force scram into making them again.
 

Whats Next ?

   I guess your on you own now.  I am interested in reconstructing muons, but there isn't any sort of program which accepts a nice datacard and supplies ntuples (let alone rootfiles), so I am trying to write my own analysis program.  I found the examples included with the releases to be helpful (check out what's available by going to the ORCA website, under the Examples section).

     Unfortunately, even though the snippets of code are very helpful, I have not see very much documentation for exactly what they do (like what fitting algorithms (and what constraints) are used when reconstructing tracks, is this the momentim returned the momentum at the innermost chamber of the subsystem or at the vertex, and other details like that).  The ORCA world seems very much for software people and developers right now, not people with modest C++ knowledge who want to use ORCA strctly as a user.

   These simple help pages were generated after getting a whole lot of help from Hans Wenzel, who also wrote the scripts and code necessary to get most of these things running here at FNAL.  Any comments or corrections about the web pages should be sent to me.  Any comments about bugs or the code being run should be sent to the appropriate people who manage the ORCA code (see the ORCA Users Manual)