How to use the HCAL software

1. Some Introduction

1.1. Who or what is this Marlin?

Marlin stands for Modular Analysis & Reconstruction for the Linear Collider and is a C++ software framework based on LCIO. The official Marlin web site , the documentation and (hopefully) this little introduction might help to understand its purpose and maybe even how to use it.

1.2. Who or what is LCIO?

LCIO is a persistency framework that defines a data model for linear collider detector studies. For now this should be enough information: LCIO is a definition how to access data (in C++, JAVA and Fortran). Event data is represented by LCEvent objects that are stored in collections, that are in turn represented by LCCollection objects. Via these objects and their methods you can access the data.

If you one day need more information see the LCIO web site where you also find the documentation. A good introduction is this paper.

1.3. Idea

The purpose of Marlin is to provide a falice way to write reconstruction and analysis code using LCIO. Since some tasks in analysis and reconstruction are always the same, it is a waste of time if everybody working with the data develops its own solution for them. Those things should be implemented once in a correct way and should be maintained in a single place. An example are IO tasks, i.e. opening the data source, reading/writing event data and closing the data source.

Marlin handles all IO and loops over the event data for you. To process the data you develop a module, so called processor that is then linked to Marlin. How this is done will be explained below. As things get complicated not only one single processor will do all the calculations. A chain of processors will be used, each doing more generic and simpler tasks (and can also be reused by others...). Marlin then must be told which processors to use and in which order to execute them, which is done via steering files. You then execute the marlin binary and tell him which steering file to use. The steering files not only contain the processor names but also which data to process and parameters for each processor to use.

... to be continued...

2. A quick guide for stupid users like me

All official CALICE software can be run anywhere with:

 $ flcini caliceSoft
 $ caliceMarlin mySteeringFile.steer 

You can get an overview of all existing processors and their default settings

 $ caliceMarlin -l > defaultSettings.steer
 $ emacs defaultSettings.steer


To add private processors one should use the calice_torso package:

 $ mkdir calice_devel
 $ cd calice_devel
 $ flcini git
 $ git clone /afs/desy.de/group/flc/hcal/calice_soft/git_repo/calice_torso

In calice_torso you will find a README, so read it, and a calicebuild-v01-03-04.cmake. It is useful to copy it into your calice_devel directory. This allows you to use the same file for all further calice packages you may want to add and modify later on. If you do not move the calicebuild.cmake file, adopt the following paths accordingly.

 $ mkdir build; mkdir install
 $ cd build
 $ mkdir calice_torso
 $ cd calice_torso
 $ flcini cmake 

Now you can start to build and install the torso package:

 $ cmake -C ../../calicebuild.cmake ../../calice_torso
 $ gmake -j2 && gmake install  

In case you don't have a dual core processor just leave away -j2.

All source code should be written to calice_torso/src, all header files have to be added to calice_torso/include. Then the processors have to be introduced in calice_torso/src/CMakeLists.txt like:

> ################################
> # sources                      #
> ################################
> SET( ${lib1name}_srcs HelloWorldProcessor.cc
>                    myNewProcessor.cc ) 

And of course one has to build, make and install again.

In addition one has to write a private version of caliceMarlin, e.g. ~/bin/myMarlin that has to include all the new libraries:

> #!/bin/sh
> 
> export LD_PRELOAD=/opt/products/lib/libpdcap.so
> 
> export MARLIN_DLL="/data/nwattime/calice_devel/install/lib/libPrivate.so"
> 
> /afs/desy.de/group/it/ilcsoft/v01-03/Marlin/v00-09-10/bin/Marlin $@

You can find out the name of your new library from

$ cd calice_devel/install/lib
$ ls -lrt


Any other code that has been changed by your colleages, or is in the official package, but need slight modifications can be installed in the same way:

$ cd calice_devel
$ flcini git
$ git clone ssh://flc45/scratch/data/richters/calice-devel/calice_userlib
$ cd build
$ mkdir calice_userlib
$ cd calice_userlib
$ cmake -C ../../calicebuild.cmake ../../calice_userlib
$ gmake -j2 && install

Modify the calice_devel/calicebuild-v01-03-04.cmake if necessary, e.g. adding new path:

> SET( CALICE_USERLIB_DIR "/data/nwattime/calice_devel/install/cmake"
>     CACHE PATH "Path to calice_userlib" FORCE )

And introduce the new libraries to ~/bin/myMarlin-v01-03:

> export MARLIN_DLL="/data/nwattime/calice_devel/install/lib/libuserlib.so:/data/nwattime/calice_devel/install/lib/libPrivate.so"


The most difficult thing to set in your steering files is usually the database folders, since they (at least up to now) change from run periode to run periode. Here it might be useful to visualize what is available.


An example steering file for the recontruction of 2007 HCAL data is dumpRootTree.steer . It is using the RootTreeWriter as an output of the reconstructed data. So if you want to use it, you will also have to fetch, build, make and install this one. Just like all the other processors metioned above.

Nevertheless, here are some differences with respect to e.g. calice_torso. The RootTreeWriter as such should not be touched, but it is allowed to add engines. The header files and source code are stored in the very same directory: calice_devel/RootTreeWriter/engines And instead of modifying a CMakeLists.txt, one has to adopt the calice_devel/RootTreeWriter/engines/EnginesAdd.icc

> // Add new engines here
>    _writeEngineList.push_back( new HcalHitWriteEngine( this )    );
> //***********************************************************

and calice_devel/RootTreeWriter/engines/EnginesInclude.icc:

> // Add header files for new write engines here
> #include "HcalHitWriteEngine.hh"
//****************************************************

afterwards recompile the RootTreeWriter in the calice_devel/build/RootTreeWriter directory

<!> NOTE: It is important to use the correct Root version. At the moment this is 5.16.00. You can get it by

 $ ini ROOT516


This page is more or less my personal summary of other sources like:

http://www-flc.desy.de/flc/flcwiki/HCAL_Calice_How_to_use_the_new_software

http://www-flc.desy.de/flc/flcwiki/HCAL_Calice_Quickstart

HCAL SoftwareForDummies (last edited 2009-06-16 18:32:14 by localhost)