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 as event viewers and processors.

Installation of 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:

ilcsoft/ilcinstall-v01-16/releases/v01-16/release-versions.py

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/init_ilcsoft.sh

env

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

Note!! You will need to source the init_ilcsoft.sh 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?

Ced2go is a simple program for displaying events. To run the program simply source the init_ilcsoft.sh 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

Marlin is a useful tool for analysing data 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 an xml 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 >>mysteer.xml."

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

MarlinGUI mysteer.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 mysteer.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. When doing this we recommend creating a new work area for all your Marlin related work e.g. called myMarlin. Within this you can run all your Marlin scripts and create an area to house and build your custom processors e.g. myMarlin/processors. Within the processors directory you want the following subdirectories- build, src, include and lib. You will also need a CMakeLists? .txt file for cmake to read when compiling your library. Once you have your cmake lists and have placed your processor code into the src and include files the code can be compiled by running the following commands:

rm -r build
mkdir build
cd build
cmake -C $ILCSOFT/ILCCSoft.cmake ..
make
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.

The library produced will then need to be added to the MarlinDLL? in order to be used in any Marlin job

export MARLIN_DLL="/home/myMarlin/processors/lib/yourLibraryName.so:$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:

#!/bin/bash

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

# adds user generated processors to MARLIN_DLL export MARLIN_DLL="/home/myMarlin/processors/lib/yourLibraryName.so:$MARLIN_DLL

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

Getting LCIO Files from DIRAC

DIRAC is the main source for data files to be used in linear collider simulations. In order to use the system you will need to register as a DIRAC user- details of how this are done can be found here: https://twiki.cern.ch/twiki/bin/view/CLIC/IlcdiracRegistration

DIRAC can be used to run jobs directly on the grid however for the purposes of debugging and doing quick analysis jobs it is usually quicker to download files from DIRAC to your local system and run them there. A full list of available files (for CLIC) can be seen here: https://twiki.cern.ch/twiki/bin/view/CLIC/MonteCarloSamplesForTheHiggsPaper . The important number to look at when browsing these files is the ProdID? as this is what you will need if you want to download any files.

The actual download process is relatively easy requiring only a few comands:

source /afs/cern.ch/eng/clic/software/DIRAC/bashrc (or source WHERE_YOU_STORED_DIRAC/bashrc)

dirac-proxy-init --group ilc_user <- this will only work if you have registered with Dirac. All being well you should be asked for your Grid password at this point

dirac-ilc-find-in-FC /ilc/prod/clic/1.4tev/h_nunu/ILD/DST ProdID? =2022 <-this outputs a list of all files i the area /ilc/prod/clic/..... with the Production ID 2022

dirac-dms-get-file file1, file2, file3 ... <-downloads a list of file1, file2 ... into the local directory you run it from (Note! It's useful to feed the output from the above command into this one)

These commands alone should allow you to download and use any file form DIRAC

General Useful Commands

anajob - lists all the collections present in an lcio file

dirac-dms-filecatalog-cli - opens the dirac file catalog and allows you to browse itusing regular commands such as cd, ls etc

Available Information

• CALICE home
• MAPS wiki
• CosmicsTests
• Link to CalId or to Calice s/w on grid

GUINEAPIG-test

• C Rimbault, P.Bambade, K.Mönig, D.Schulte, Impact of beam-beam effects on precision luminosity measurements at the ILC, 2007 JINST 2 P09001 doi: 10.1088/1748-0221/2/09/P09001
• C.Rimbault, P.Bambade, K.Mönig, D.Schulte, Incoherent pair generation in a beam-beam interaction simulation, Phys. Rev. ST Accel. Beams 9, 034402 (2006)
• C.Rimbault et al, GUINEA-PIG++ : An Upgraded Version of the Linear Collider Beam-Beam Interaction Simulation Code GUINEA-PIG, http://accelconf.web.cern.ch/AccelConf/p07/PAPERS/THPMN010.PDF[Proc. PAC07, Albuquerque, New Mexico, USA]]

• GUINEAPIG web site (LAL) - http://flc-mdi.lal.in2p3.fr/spip.php?rubrique40

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

• SensorsRT110708.pdf: To upload to arxiv