Monte Carlo and Smearing

From EIC
Jump to navigation Jump to search


The Monte Carlo smearing package eic-smear is a collection of classes and routines for analysing Monte Carlo events and performing fast smearing to study the effects of detector resolution. It is designed for use with the ROOT analysis framework.


There are two main elements to eic-smear:

  1. Monte Carlo: A collection of classes describing events produced by various EIC Monte Carlo generators, and routines for building ROOT trees of these events from ASCII input.
  2. Smearing: Classes and routines for applying fast detector smearing to the events produced by the Monte Carlo portion of the package.

Being closely related, they are distributed as a single package.

Please see the links above for details of how to use each portion of the package. There is also a summary talk here. The remainder of this page will deal primarily with installing the software.


Full class documentation is provided here.

The scripts subdirectory of the distribution contains a number of examples of how to use the code, including:

  • Building ROOT trees from generator output.
  • Reading trees for analysis.

Class documentation for the out-of-date original version of the code is preserved here. This version does not provide fast smearing functionality.

Obtaining the code

There are three ways to access the smearing package.

  1. For those with an EIC RCF account, it can be accessed via the EIC AFS region. The code is located at /afs/
  2. Download a source distribution (see below) and build it yourself.
  3. For those wanting to develop the code themselves, check out the a version from svn. Stable releases can be found under tags, while the latest developments (albeit with the possibility of instabilities) are located under trunk.

If using the EIC AFS version, make sure to run it with the correct EIC ROOT installation. The simplest way to ensure this is to use the standard EIC logon scripts to configure your environment. It can then be run immediately with no further setup. If you want to run with a different version of ROOT you should compile your own version of the library.

Source distributions


The package can be built using either configure/make or (as of version 1.0.3) CMake. The most up-to-date build instructions and other information can be found in the accompanying README. Out-of-source builds are recommended to avoid polluting your source directory e.g. from the eic-smear directory:

mkdir build
cd build

Create a Makefile using either configure:

../configure [arguments]

or CMake:

cmake [arguments] ..

See the README for relevant arguments. Finally make and, optionally, install:

make install

If you don't do an install then the generated library can be found in the .libs directory (note the '.') in the build directory.

PYTHIA 6 support

For most generators eic-smear only accepts ASCII files as input for tree generation (see the generator pages for an explanation of the format). However it is possible to run PYTHIA 6 from within ROOT and directly process the output into a tree, without the intermediate step of an ASCII file. This can save significant time and disk space associated with storing and reading the ASCII files, as well as allowing user-defined manipulation (such as event filtering) between generation and writing of events. For this, one must have

  • PYTHIA 6 compiled as a shared library named
  • A version of ROOT compiled against PYTHIA 6 (see the ROOT installation instructions)

To enable PYTHIA 6 support in eic-smear, the user must pass the following option to configure:

../configure --with-pythia6-libdir=/path/to/pythia6dir

or to CMake:

cmake -DPYTHIA6_LIBDIR=/path/to/pythia6dir ..

where pythia6dir is the directory containing To run PYTHIA 6 from within ROOT, the erhic::Pythia6 utility class is provided. All PYTHIA configuration is done via ROOT's own TPythia6 class. See the documentation for that class for details of how to use it.


Load the shared library into ROOT via

root [0] gSystem->Load("/path/to/eic-smear/.libs/libeicsmear");

or whatever library path was used if it was installed in another location. If you include this path in your (DY)LD_LIBRARY_PATH you can just do

root [0] gSystem->Load("libeicsmear");

Note that if you are an EIC RCF user, and follow the EIC logon instructions, the package is automatically loaded when you start ROOT. Depending on what is loaded already, you may need to load other ROOT libraries before loading eic-smear. Specifically, if you compile without PYTHIA 6 support you may need to load libEGPythia6 first, followed by eic-smear:

root [0] gSystem->Load("libEGPythia6");
root [1] gSystem->Load("libeicsmear");

A note to Mac users

Depending on the version of ROOT you use, it may not recognise the libeicsmear.dylib file produced by make. A simple workaround is to create a symbolic link to the .dylib with suffix .so:

cd /path/to/eic-smear/librarydir
ln -s libeicsmear.dylib

Recent versions of ROOT recognise and accept .dylib files without issue.


Converting ASCII output from the EIC event generators to ROOT events is handled by the routine BuildTree.

The first step to smearing is to write a script defining the detector volumes one wants to use. The routine SmearTree() is then used to apply the smearing defined by this script to a Monte Carlo tree. A detailed overview of how to perform both these steps can be found here.