DragonRoot Documentation

Version 1.3

Introduction

DragonRoot is...

...a framework with which experimenters can access DRAGON data through a C++ interface. This interface is designed to be used in conjunction with the CERN ROOT data analysis environment utilising the MySQL database. The basic idea behind DragonRoot is that the user should be able to take a raw data-file and use ROOT (and TTree::MakeSelector(), for example) in order to generate histograms and to aid data analysis. Use the links at the top of this page to navigate the code documentation. Included below are other package documentation files which also may be of use.

What does this code do?

This code takes and decodes raw data from a TMidasEvent. The MIDAS event is filled by either reading data from file or by setting online data into an instance of the TMidasEvent class. The data is placed into subevents by methods in the TDragonRun class. The subevents are bundled into a TDragonEvent (and by default written out to a root file when used offline). Other events that are written are scaler events (TScalerEvent) and EPICS events (TEpicsEvent). Once this is done then everything else that is or is not performed on the data is up to the user. You can work with basic unpacked data if you like by retrieving it from the TDragonEvent, or you can be more complex and create some detectors and fill them with appropriate data, calibrate this data and create hits from each of the detector. The only other point to note is that most of this code is now only being added as I need it, so if you want a feature (such as filling in all items in a hit) then feel free to add it to the source code and recompile following the instructions below. If it's well written, send a patch and I'll merge it into CVS.

Using this Manual

These pages document the DragonRoot code and the user interfaces to the classes within the package. The code reference is intended for use when more information on a particular DragonRoot class, which is probably being used in an analysis code, is needed. For example, if you have an instance of a TDragonEvent object and you want to know what information can be retrieved from it and the methods you can use to get that information, then you would look at the TDragonEvent documentation. Taking this example further, this class contains a data member which is a vector containing HMEM subevents:

 vector<TSubEvent> fHmemSubEvents; 

To retrieve this data from the class, it can be seen that the GetHmemSubEvents() method is the one to use:

 const vector<TSubEvent> & GetHmemSubEvents() const 

So your code would look like this to grab the HMEM subevents:

  const vector<TSubEvent> &subs = GetHmemSubEvents(); 

And you can then find out what you can do with each of the subevents in the vector by looking at the TSubEvent class.

Installation

This package creates three useful things:

• makeDragonTree
• DragonTree.so (DragonTree.a)
• libdr.so (libdr.a)

All these programs are created using libtool, and is the reason why the package takes so long to compile (because it's creating more than just one program or library). Anyhow, makeDragonTree is used for just that: it creates a tree containing TDragonEvents, TScalerEvents and TEpicsEvents from a MIDAS .mid data file. DragonTree.so is the ROOT plugin library that you need to play back the data in ROOT (using TTree::MakeSelector() for example). The libdr.so library is linked against for online use of the DragonRoot code.

Obtaining DragonRoot

The latest DragonRoot code can be found here. Navigate to the bottom of the page and use the "Download tarball" link. Save the package to your desired location. Use a terminal and navigate to where the package is located. Follow the instructions below, or if you have unpacked the package look at the base-directory README or INSTALL files for generic instructions. If the package is already installed, jump straight to the examples located in the DragonRoot example directory.

Basic instructions:

From the README file:

README
======

May 2004 - original version.
August 2004 - updated to include ROOT tree stuff.
November 2004 - small updates.
December 2004 - moved example to example/README + updates.
January 2006 - updated MySql instructions.
January 2007 - added WARNING.

WARNING
=======

This software is no longer maintained by the principal author (JEP).
For whoever takes maintainership: a lot of this code is junk, and was
written to work around bad design decisions in the DRAGON hardware.
With a sensible hardware design, at least 1/3 of this code can be
removed.  There is still a lot that could be done with dragonroot to
make it really useful, but with crap tools such as roody, the nasty
widgets in ROOT (what is that GUI builder about?), I really just gave
up in the end.

To install this package:

1. # tar xvfz dragonroot-version.tar.gz
This unpacks the source into dragonroot-version directory.

2. # cd dragonroot-version
The default installation directory is /usr/local.  If the package
should be installed elsewhere, or it is not possible to use the
default location because of root access issues, then choose a suitable
location and pass it to configure (this is likely).
For example:
   # ./configure --prefix=/home/jonty/online/dragonroot
Otherwise, for the default, just issue:
   # ./configure
Make sure the checks for and root-config, rootcint and MySql are OK.
If they aren't then either of ROOT or MySql will need to be installed
for this package to compile.  This step is important and you basically
want almost everything configure looks for to say "yes".  ROOT must be
installed correctly, either system wide or with ROOTSYS and all paths
set correctly in your environment.  This is especially important if
you have multiple versions of ROOT installed.

3. Possible source file alterations.
The account name and password for MySql database access have default
values of username "dragon" and password "dragonTail".  If they need
changing, edit the TDragonRun.cxx, TGrCalibration.cxx and
THiCalibration.cxx files in the src directory so they are correct.

4. # make install-strip
This will compile everything if the needed dependencies are found and
install by default in /usr/local OR wherever --prefix above points to.
If you want to install with debugging information in the libraries,
instead do:
   # make install
To view html documentation point your browser at the
(path in --prefix)/html/index.html file.  This will provide comments
and a few code snippets from the source files.  The install will place
files in the following places:
	headers -------> (path in --prefix)/include
	libraries -----> (path in --prefix)/lib
	executables ---> (path in --prefix)/bin
	documentation -> (path in --prefix)/html

5. Add the correct paths to your profile.
If the installation is not system wide (there is no real reason for it
to be) the correct PATH variable will need to be modified.  For
example, using the above --prefix directory in bash execute:
   # PATH=$PATH:/home/jonty/online/dragonroot/bin
   # export PATH
If you want to link against the dragonroot library for online sorting
then LD_LIBRARY_PATH will also need modifying (or /etc/ld.so.conf):
   # LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/jonty/online/dragonroot/lib
   # export LD_LIBRARY_PATH
To make these changes permanent add them to your .bash_profile file
(or equivalent in .cshrc file if using tcsh).

   That's it regarding installation!  You should now checkout the
README files in the sql directory (to set up the database entries),
and then in the example directory (to see how to run the examples).
To change the output of makeDragonTree, first edit the source files in
the src directory, then repeat instruction 4 to regenerate the
makeDragonTree DragonTree.so binaries.  For more information on how to
sort the data using ROOT, have a look in the example directory.  If
you want to develop this package then you could also use kdevelop or
anjuta if you like flowery interfaces to the GNU tools :)

Jonty.

Things still to be done:

From the TODO file:

TODO
====

May 2004 - original version.
August 2004 - updated.
November 2004 - updated.
January 2006 - updated.

This stuff has now been running online for some time.  Offline
analysis seems to be going OK, so a good place for continued work is
the examples.

Other todo's can be found in the Doxygen documentation under "Related
pages".  These are todo's that I add into the source code to remind me
that they will need doing eventually.

Jonty.

DragonRoot Authors

From the AUTHORS file:

AUTHORS
=======

The initial author and instigator in the summer of 2003 was Joe Chuma
<chuma@triumf.ca>.  Since then it's been me (Jonty Pearson)
<jonty@triumf.ca>; any questions should probably come to me.

Author:

JEP, J. Chuma.

Version:

1.2.

Date:

December 2003.

---