Eicroot

Overview

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.

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:

cmake -DCBMROOT=YES

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 subdirectories of eicroot/examples. Inside these directories, you will find a simple tracker tutorial (for example 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 the file simulation.root, which encodes information from the simulation. This file can be passed on to other scripts in the simulation chain (such as displaying in the event display or running digitization and reconstruction, see the sections below). 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:

// Create simulation run manager; use GEANT3 for tracking excercises here;
EicRunSim *fRun = new EicRunSim("TGeant3");
//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);

The second argument to the function call will apply a scale factor to the field, which will scale the fields in the magnets for different beam energies.

Alternate Magnet Lattice Import

In addition to the importing of a full map, a simpler method of import has been developed and added to the code package. In this scheme, rather than supplying a full field map, one only needs to specify the location of the magnets in coordinate space, the rotational angle of the magnet (about the vertical or y-axis), the bore aperture radius, along with the field strength and field gradient across the magnet. An example of the input file format is shown below:

## protons, Draft linac-ring lattice V3.00,  E_e = n/a, E_p=249.358GeV
##  Source: 21-Apr-2016 from Brett Parker
##
## Notes: this is still a draft version with only the first few forward side magnets
##
##  magnet_name1 center_z[m] center_x[m] center_y[m] aperture_radius[m] length[m] angle[mrad]   B[T]   gradient[T/m]

      Q0HF        5.70        0.00500       0.00         0.041           1.600      -14.0      0.000     129.00
      Q1HF        8.55        0.00900       0.00         0.060           3.000      -14.0      0.000      -86.00
      B0HF        11.40       0.00500       0.00         0.066           1.600      -14.0     -4.055       0.00
      Q2HF        13.65       0.00955       0.00         0.077           1.800       7.8      0.000      59.50
      B1HF        16.35       0.02261       0.00         0.092           2.500      -4.0     -4.059       0.00

Note that there is space reserved for six header lines (this requirement is hard coded for now so the first six lines really need to be reserved for the comments), where comments associated with the lattice design can be denoted (such as version, beam energy for which the field are tuned, the author and date, etc). The last header line denotes the format for the importing of each magnet in the lattice. Each magnet element is denoted by its own line with the following information required (in this specific order):

magnet_name, magnet center in z (in meters), magnet center in x (m), magnet center in y (m), aperture radius (m), magnet length (m), rotational angle around the vertical (mrad), the magnetic field strength (Tesla) and the magnetic field gradient (T/m).

Note that an input gradient of 0 indicates a bending dipole magnet, where as if a gradient is given a non-zero value, a quadrupole field is assumed.

The field at each step in the particle's path is then calculated from the field strengths and gradients based on the relative location within the magnet volume of the particle. Note that this then represents the ideal field and no fringe field effects will be taken into account.

An example of the code used in the simulation.C macro referenced above is also shown below:

EicRunSim *fRun = new EicRunSim("TGeant4");
EicMagneticFieldFromGradients *fField = new EicMagneticFieldFromGradients();
fField->AddBeamLineElementGrads("IR/HADRON/v3.01", 1.0, kBlue)
fField->CreateYokeVolumes(kTRUE);
fRun->SetField(fField);

The above code will read all files denoted with the extension *.dat. With this in mind, the idea is to have the entire hadron beam (or electron beam) lattice in a single file with the .dat extension. The arguments in the AddBeamLineElementsGrads function call pass on the location of the directory with the field maps, a value to scale the fields if running with different beam energies, and the color of the magnets that will be assigned when viewing in the EicRoot event display.

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.