TWiki> CALICE Web>WebHome (revision 17)EditAttach Welcome to the Birmingham CALICE wiki

Beginners guide to using ILC Software

This guide is intended for those who are installing and using ILC software for the first time and aims to give a brief description of how to install the software, fix any common problems and run a few of the core programs such asevent viewers and processors.

Installation ILC Software from Scratch

There are many versions of the ILC software available which can be downladed from the ILCsoft webpage- in our examples we will be using ilcsoft v01-16 in Scientific Linux 5 though they should still apply for more recent versions. Once you have downladed your copy of ilcsoft the first thing you will need to do will be to check if you can successfully install the software. This is done by moving to the ilcinstall directory within the ilcsoft file you downloaded (e.g in our case: cd /home/caldata3/software/ilcsoft/ilcinstall-v01-16 ) then using the command below. If you would prefer to preview what the installation will attempt to do before actually running it you can instead replace the option -i with -p.

Install code: ./ilcsoft-install -i releases/v01-16/release-scratch.cfg

If the installation doesn't report any errors- congratulations!! You've finished installing ilcsoft and can skip ahead to the next section. In the more likely situation that the software doesn't install correctly on your first attempt and instead you are faced with numerous error messages this will simply be because ilcsoft relies on several other packages to run such as ROOT, GEANT4 and CMAKE. To check which packages are used by ilcsoft you will need to open the release file in a text editor. The release file is found here:


This file contains the version and path names of all the packages ilcsoft will require. It is essential that all version numbers match the version currently installed on your computer and that the path names are correct for the current versions of each package.

Note!! It is worth reading the error messages you received during installation as they will give you a hint as to where the problems arise.

If after correcting the version file you find that the installation is still not working it is possible that some of the versions you are using are not compatible with ilcsoft. In this case you will see error messages letting you know at which part of the installation the problem occurred e.g. it will install all files up until Marlin. If this is the case a last resort can be to go into the following file:

ilcsoft/ilcinstall-v01-16/releases/v01-16/ release-scratch.cfg

and to comment out the sections relating to the problem (e.g. Marlin.) Obviously this is only useful if the particular package you comment out is one that you aren't going to need as this process removes the package from the installation.

Hopefully after all this you the installation should run successfully and you will be able to move on to actually using the software.

You can check that ilcsoft has successfully installed by using the following commands:

source /home/caldata3/software/ilcsoft/v01-16/


You should now see that your enviroment is populated with many packages such as Marlin and Pandora.

Note!! You will need to source the script anytime you wish to use ilcsoft so it may be worth adding it to the setup of your user area or to place it somewhere easily accessible.

Running Basic Programs

Now that you have the ilc software installed it is worth running a couple of simple programs to familiarise yourself with ilcsoft and to check that it is working correctly


Ced2go is a simple program for displaying events. To run the program simply source the script then type "ced2go". This will bring up a basic guide for how to use ced2go. Ced2go requires the following:

LCIO input file: this contains all the data relating to the particles in your collision

Gear file: this contains all the data regarding the detector used and it's geometry

Template file: this comes preinstalled with ilcsoft ->the location should have been displayed next to the option "-t" when you typed ced2go

To actually view an event type:

ced2go -d "gearfile.gear" -t "templatefile" "LCIOfile.lcio"

This will bring up a 3d viewer that allows you to view the detector and all the tracks/hits within it for multiple events. The viewer has many display tools worth exploring such as the ability to remove different sections of the detector from the display.


Marlin is a useful tool for analysing results in a simple and flexible manner. It consists of a series of processors for analysing lcio files which can be turned on or off at will and ordered to suit your needs. New processors can easily be created using the template file provided by Marlin. To run Marlin you require a steering file which will tell Marlin which lcio files to use, what gear file to use, what processors you want to run and what parameters the processor will use. An easy to follow template for the steering file can be generated using the command "Marlin -x" which will print an example steering file to stdout.

Once you have generated the steering file you can run Marlin using the simple command

MarlinGUI steering.xml

This opens the GUI for Marlin from which you can see all the input files you are using as well as a list of the processors being used and their status (on/off/broken.) From the GUI you can edit which files to use and turn off processors you don't wish to use. Once you are happy that the correct files and processors are being used you should save the file- this overwrites the input steering file with all the amendments you made in the GUI. Output can then be generated by running

Marlin steering.xml

Depending on the number of events you are processing this can take some time but will eventually output whatever files the processors are programmed to generate (usually root files) and save them into the directory from which you are working.

Creating new processors

As mentioned earlier, new processors can be created for Marlin using the template provided and by creating an appropriate header file to go with it. The processor and header file should be saved in the Marlin src and include folders respectiviely. Before the processor can be used however, it first needs to be built using cmake. This is done in the temporary build folder within Marlin/processors/ as follows:

rm -r build
mkdir build
cd build
cmake -C $ILCSOFT/ILCCSoft.cmake ..
make install

Note!! If the processor contains any mistakes the make command will fail but will generate a series of errors giving the exact lines in the code where there are problems. If the processor relies on a specific library then this must also be added to the MarlinDLL? before it can be used. This is done as follows:

export MARLIN_DLL="/home/Marlin/processors/lib/$MARLIN_DLL

As this must be added for any session in which you need your processor it is recommended that you create a script that will source ilcsoft and export the library at the same time

For example:


# sources ilcsoftware
source /home/caldata3/software/ilcsoft/v01-16/

# adds user generated processors to MARLIN_DLL
export MARLIN_DLL="/home/aw/aw_Marlin/processors/lib/$MARLIN_DLL"

Then when this script is sourced it will set up everything you need to run marlin in one command.

Available Information


There are new-ish C++ and (the original) C versions of GUINEAPIG. We had more success with the original C version that GUINEAPIG++, but note that the latter has been revised in the last 12 months, and now supports all input options of the original C version, therefore recommend using/trying GUINEAPIG++ .

  • acc.dat steering files we used for Mokka/MAPS background studies are contained in
    • acc.dat
    • Trimming the resultant pairs.dat, for very loose kinematic cuts, used modpairs6.C.

CALICE Web Utilities

Topic attachments
I Attachment Action SizeSorted ascending Date Who Comment
cC modpairs6.C manage 1.4 K 16 Jul 2008 - 10:34 NigelWatson  
docdoc DeepPwell-V4.1.doc manage 1479.0 K 11 Jul 2008 - 09:24 NigelWatson Draft version, NKW addition of email/correspondance addresses for Yoshi and Vladimir
docdoc DeepPwell-V3.doc manage 2875.0 K 10 Jul 2008 - 17:42 NigelWatson Draft version, NKW edits, for Mike/Renato
pdfpdf SensorsRT110708.pdf manage 6769.3 K 17 Jul 2008 - 16:11 NigelWatson To upload to arxiv
elsedat acc.dat manage 8.0 K 16 Jul 2008 - 10:32 NigelWatson  
Edit | Attach | Print version | History: r21 | r19 < r18 < r17 < r16 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r17 - 31 Oct 2014 - 13:18:47 - AlasdairWinter?
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback