From EIC
Jump to navigation Jump to search


The full Monte Carlo framework for detector simulation for EIC is the eicroot package. This package is an adaptation of the FairRoot framework.

Within this framework, you can do detailed detector simulations and make nice figures like the one below.


Pythia DIS eventShot eic 2.pdf

Code Documentation

The Doxygen generated documentation can be found at this link. A cronjob runs every night at midnight to update the documentation if needed, so the documentation should be at most one day out of date. The Doxygen configuration file can be found in SVN at the provided link.

Obtaining the Code

To obtain the source code, please check out from svn:

svn co http://svn.racf.bnl.gov/svn/eic/eicroot/trunk eicroot

Go to the eicroot directory and read through the README file for an overview of the code, location of "tutorials", required packages to run the eicroot package, and an example of how to run the simulation chain.

Note: if you plan to contribute to the code and commit changes to the repository, you must check out securely (use https). You will then be prompted for a password.

Compiling the Code

Assuming you are interested in detector development, you will have to install EicRoot.

Go to the eicroot directory and read through the INSTALL file for detailed instructions. This document describes how to install everything needed from scratch (including ROOT, GEANT, FairROOT, etc.). This is not necessary if you source the existing installation as described at the bottom of the INSTALL file in the "EicRoot installation" section.

To install, first get your environment ready so that you point to the proper existing packages (you can also replace the locations with the location of your local installations):

setenv SIMPATH /eic/data/FairRoot/fairsoft/apr13-build
setenv ROOTSYS /eic/data/FairRoot/fairsoft/apr13/tools/root
setenv PATH /eic/data/FairRoot/fairsoft/apr13-build/bin:${PATH}

Then follow the instructions at the bottom of the INSTALL file or the instructions below for a fresh install (for updating, see the note at the bottom of this section):

cd <eicroot-source-dir>          // go to the installation directory;
svn update                               // optional; ~cures possible 'svn co' problems with externals;
patch -p0 < eic.patch              // apply patch to several files;
mkdir build                              // create build directory;
cd build                                   // go to the build directory;
cmake -Wno-dev ..                  // configure Makefiles in 'cmake' environment;
make                                       // compiling

You may require optional component(s). cmake should be invoked with respective additional command-line switch(es):

Smearing package interface:

cmake -DEICSMEAR=/eic/data/FairRoot/eic-smear

FopiRoot TPC-related codes:

cmake -DFOPIROOT=YES -DCLHEP=/eic/data/FairRoot/clhep -DRAVEPATH=/eic/data/FairRoot/rave

AutoCAD: file import interface (STL and STEP format only; required 'cad' branch back merge at some point; does not work in trunk as of now):

cmake -DCAD2ROOT=YES -DTETGEN=/eic/data/FairRoot/tetgen

CBMROOT: If one wants to draw the existing RICH detector, the eicroot package must be built with the CBMROOT package as well. Add the option:


There is a small caveat to this. To get the RICH to display correctly in size and position, a hack needs to be introduced in the ROOT package on the file TGDMLParse.cxx, adjusting the scale. Details will be added at another time. Until then if you really want to do this, please contact Richard Petti or Alexander Kiselev.

These options can be combined when invoking cmake at the command line.

After doing 'make', a build directory will be created and filled. Inside that are configuration files, allowing easy setup of the computing environment to run eicroot. Source this config file as below and you should be up and running:

source /<yourInstallationPath>/eicroot/build/config.csh

NOTE: if you simply want to update your existing working version of the package from SVN, it is strongly recommended to use the update.com script rather than executing 'svn update' command by hand. The script takes care to re-apply eic.patch in a consistent way (if needed).

Tutorials and Examples to Get Started

Still under development…

The basic chain of the simulation is controlled by several scrips and indicated in the eicroot/README file.

  1. Detector Setup: One can implement a specific detector setup in a "detector.C" script. Some simple examples can be found in eicroot/tutorials/designer. Inside this directory, you will find a simple tracker tutorial (in the directory tracking, script named tracker.C) and a simple calorimeter example (in the directory calorimetry, script calorimeter.C). The script will generate a root file which encodes the detector geometry and must be passed on to the other scripts down the chain.
  2. Particle Simulation: In the same subdirectories listed above in which you find the detector setup scripts, you will also find the script simulation.C. This script is a simple example of single particle generation in some phase space range and shows how to call the detector setup and implement a magnetic field map. This script will create three files, FairRunInfo_simulation.root, simparams.root, and simulation.root, which encodes information from the simulation. Some of these will need to be passed on to other scripts in the simulation chain as setup. See the tutorial scripts for examples. For more detailed information on particle simulation, go to the page particleSimulationEicRoot.
  3. Event Display: An example script for the event display is again found in the same directory as above, with the script name eventDisplay.C. Some tips and tricks to navigating the event display menu can be found at the Event Display page.
  4. Digitization: An example script is digitization.C. More information on the digitization process can be found at digitization details.
  5. Reconstruction: An example script is reconstruction.C. For more details, visit the Reconstruction page.
  6. Analysis: An example script is analysis.C

Defining a Magnetic Field

Importing magnetic field maps is still in development. Currently one can define a magnetic field map in an ASCII file. The format needed in the ASCII file can be determined by looking at the source code that reads it ( eicroot/field/PndFieldMap.cxx, PndFieldMap::ReadAsciiFile() ). The format is as below:

fieldType[Dipole, Solenoid, etc…]
units[T, G]
fXmin[cm] fXmax[cm] fNx
fYmin[cm] fYmax[cm] fNy
fZmin[mc] fZmax[cm] fNz
bx1 by1 bz1
bx2 by2 bz2
bx3 by3 bz3
bxfNx byfNy bzfNz

Then run the script eicroot/macro/field/f2root.C to convert the ASCII file into a root binary used as input to the simulation and event display scripts. Note that the script automatically looks for the ASCII file in eicroot/input directory, so it needs to be placed there. (Note: still needs to be updated to support any field type other than Solendoid).

Realistic IR Magnet Setup

The beam hadron and electron beam line magnets around the IR have also been added to the framework. You can load in the desired field maps in the simulation.C script by inserting combinations of the following:

FairRunSim *fRun = new FairRunSim();  // create the simulation run manager
//some configuration calls needed and not detailed here, look in the example macro

EicMagneticField *fField = new EicMagneticField();   // create magnetic field object to hold all relevant fields
fField->AddFieldMap(new EicPndFieldMap(new PndSolenoidMap("SolenoidMap4","R")));  // add solenoid field
fField->AddBeamLineElementMaps("IR/ELECTRON/v2.1");  // add electron beam line
fField->AddBeamLineElementMaps("IR/HADRON/v2.1");    // add hadron beam line
fField->CreateYokeVolumes();   // optional call to create yoke volumes, defining the aperture 
 //optional argument kTRUE to stop particle propagation in magnet yoke

fRun->SetField(fField);    // pass the field configuration to the simulation manager

Note that these calls automatically look for maps in eicroot/input. Also note that if you do not want the particles to be propagated to through the magnet yoke (which is computationally expensive), then you can add the arguement "kTRUE" to the function call CreateYokeVolumes(). This will stop the particle propagation once it hits the magnet yoke.

Also note that the current v2.1 machine magnetic fields are implemented for 20x250GeV e+p collisions. If one wants to study collisions at a different energy, the fields can be scaled accordingly by passing a second numerical argument to the AddBeamLineElementMaps() function call. For example, for simulations of protons at 100 GeV, the above code could be modified as so:

fField->AddBeamLineElementMaps("IR/HADRON/v2.1", 0.4);

Some General Directory Structure For Detector Subsystems

This may be of some help. All of the existing subsystems that have been developed and simulated thus far are implemented through their own detector class. The source code for each of these subsystems can be found in their own subdirectories in eicroot/eic/detectors. Each subsystem also has their own set up script to create the root binary file containing the geometry information. These can also be found for each subsystem in their respective subdirectories in eicroot/geometry.