This page is obsolete. Please report the refering page

DaVinci tutorials are now at https://twiki.cern.ch/twiki/bin/view/LHCb/DaVinciTutorial

This page explains the basic steps necessary to run DaVinci and to write some code. It is intended for newcomers to LHCb or analysis and hence nothing is assumed, except some unix and C++ basics.

First steps

These are the basic steps to run it under linux. I think this is a good start.  This section is written as a list of magic incantations, more details are below. The following assumes you want to use DaVinci v12r0 or later.

1. Go to the LHCb secretariat and ask for an LHCb computer account.
2. Logon to lxplus. You should get a message of the type "WELCOME to the gcc3.X on XXX system" and some more output. If you don't get this (which might be because you are opening a terminal and not actually logging in) type
   > lbcmt
   If this does not work, either you don't have a LHCb (z5 group) computer account (which you can check with the command xwho), so go back to point 1. Or something else is wrong and you should ask the LHCb helpdesk.
3. The LHCb software is organized in four main applications: Gauss (simulation), Boole (digitization), Brunel (reconstruction) and DaVinci (analysis).
   Determine from the DaVinci webpage which DaVinci version you want to use. It will be of the type vXrY where X and Y are some numbers. Type
   > DaVinciEnv vXrY
   which will set up the correct path and environment variables to look for code.
4. You should also have a directory in your home called cmtuser. If not, go back to point 1 or ask the LHCb helpdesk. Go there
   > cd cmtuser
   and get your private copy of the package containing the DaVinci main code and most useful option files to run it.
   > getpack Phys/DaVinci vXrY
   This will install the code in a directory ~/cmtuser/Phys/DaVinci/vXrY/
5. Go to the cmt directory of DaVinci
   > cd ~/cmtuser/Phys/DaVinci/vXrY/cmt/
   and do
   > cmt config
   which tells cmt to read the file called requirements and to look for all the dependencies of DaVinci. This has actually already been done by getpack, but it is a good idea to redo it and check for warnings.
6. Build the executable
   > make
   This will not only compile the source code in ../src/ but also make links to necessary libraries. Compiled stuff goes into a directory called ../slc3_ia32_gcc323/ or similar (actually $CMTCONFIG).
7. > source setup.csh
   This will define environment variables pointing to all paths necessary to load the shared libraries needed by DaVinci. For instance
   > echo $DAVINCIROOT
   will print something equivalent to ~/cmtuser/Phys/DaVinci/vXrY/
   It is a good idea to redo cmt config and source setup.csh when something goes wrong, as it will allow to recover possible changes of code. Many common errors in DaVinci can be solved by doing this.
8. Run DaVinci. Finally! In any directory type
   > DaVinci
   And wait... it's not always very fast...

And when I already did this and come back the next day?
You don't have to recompile every day. What you need to do each time you start over is
> DaVinciEnv vXrY
and
> source setup.csh

What does it do actually?
Well, that was not very useful. When you type DaVinci alone, it executes DaVinci using a set of options defined in a file called $DAVINCIROOT/options/DaVinci.opts. Have a look at it (best with emacs, that will show you all in colour): It executes some default initializations you don't need to care about, then tells DaVinci how to make "protoparticles" (i.e. almost particles) from tracks and calorimeter clusters. Then it defines some input and output data. To make something interesting, you need to edit this file. Or you can also look in the various packages in DaVinci for files called options/DV*.opts. They are all option files that can be given as input to DaVinci. Like in the next section...

Some more information about these commands

CVS

The getpack command will actually get the code from the CVS repository. CVS manages all revisions of all code written in LHCb. More details are here. You can have a look at the content of the repository here.

 

CMT

cmt is a configuration tool documented here. It helps you to resolve all the dependencies of your code reading recursively the cmt/requirement files. If you get a warning when you do this, do
> cmt show uses
( or  cmt show uses | less  )
and have a look at the output. It tells you which package requires which and allows you to trace back where the error comes from. Most code will come from the release area where all packages are stored and compiled. Your private versions of the packages you have in ~/cmtuser have precedence. The order in which the packages are looked for is defined in $CMTPATH.

 

$DaVinci_release_area/DAVINCI/DAVINCI_vXrY/

The DaVinci release area is the place where all code of all 'useful' versions is available. You can browse through this packages in this place to look at the source code (in src/), read the release notes (in doc/). But it's main use is to store the compiled shared libraries needed by DaVinci.
The main packages of DaVinci are in Phys/ and PhysSel/ (selections).

Making something real

Let's have a look at how well DaVinci reconstructs the primary vertex. There is an algorithm that does this in the Phys/DaVinciTest package. But you don't need to get it. All you need to do is to tell DaVinci to use it.

1. Edit options/DaVinci.opts.
   Add the following lines
     ApplicationMgr.DLLs += { "DaVinciTest" };
     ApplicationMgr.TopAlg += { "PrimVertAnalysis" };
   anywhere after #include "$DAVINCIROOT/options/DaVinciNeutrals.opts" (at the end of the file is fine). The second line will add the algorithm PrimVertAnalysis" to the list of executed algorithms and the first tells where to look for this algorithm. This is documented in the Gaudi user guide.

2. You may also want to specify the number of events editing the line
      ApplicationMgr.EvtMax = XXX ;
   or change the events read in, by editing the file DaVinciTestData.opts. You can generate such a file from the Bookkeeping database.

3. Run DaVinci as usual. You can also go to the job directory and execute DaVinci.job, or send it to a batch queue.

4. You'll get a file called DVNtuples.hbook that you can open using paw. If you prefer root, edit options/DaVinci.opts accordingly.

5. The output ntuple is in the hbook directory primvertanalysis (do you know the command ldir in paw?) Running over 5000 BB events, I get the distribution shown on the side.

There's a lot DaVinci can do only via options. Read the file options/DaVinci.opts and let it guide you... Also a general convention is that all files called options/DV*.opts are self-containing option files. For instance in $DAVINCICHECKSROOT/options/ there is a file called DVChargedProtoP.opts that executes an algorithm checking the reconstruction of the protoparticles. You can force the use if any such file instead of DaVinci.opts by typing
> DaVinci $DAVINCICHECKSROOT/options/DVChargedProtoP.opts

There are for instance such files in all PhysSel/ packages. They steer the preselections.

Another interesting place to look into is the Phys/DaVinciEff package. In there you will find three option files controlling analyses and the corresponding efficiency monitors.

Writing your own code

Just follow the latest example for the DaVinci tutorial.

Debugging

How to run the debugger on lxplus:

1. compile all you have in cmtuser with
   > make tags=$CMTDEB

2. source setup in DaVinci/vXrX/cmt with
   > source setup.csh -tag=$CMTDEB

3. Make sure you don't limit the core dump size ("limit" command).

4. Run DaVinci as usual. Don't interrupt even it seems to be doing nothing...

5. start the debugger with
   > gvd $DAVINCIROOT/slc3_ia32_gcc322_dbg/DaVinci.exe &
   (this can take some time, ignore the two warnings)

6. File -> open core dump. Load the latest core dump. Go and get a coffee... your computer is useless while you do this.

7. Data -> Call stack. Be patient (or get another coffee). Expand the upper window and navigate in the stack. What is interesting for you is most probably in MyApplication::Execute...

Modify your code and start over. There are some features of gvd like breakpoints, but...

Don't forget the tags=$CMTDEB when you recompile, or your source code would not be in sync with your executable anymore...

More Documentation

I am in the process of compiling some documentation. In the meantime what exists is:

• The Gaudi user guide. Quite complete but somewhat obsolete.
• The DaVinci Tutorial slides. Refer to DaVinci v12r3.
• The doxigen code documentation. Contains everything. Use the alphabetical list...
• Finally, have a look at the release.notes of each package.
• CVS
• CMT
• DaVinci (or anything else) under Windows
• To facilitate discussion and sharing of information a mailing list is available (previous mail exchanges can be accessed via its archive). To subscribe to the mailing list send a request to the LHCb secretariat.
• You can also ask me.
• If you choose to use LoKi, read this documentation and your questions at this mailing list.