Detector simulation general note

From Electron Ion Collider Wiki
Revision as of 13:55, 28 February 2018 by Zwzhao (Talk | contribs)

Jump to: navigation, search



This is a general description how to use GEMC to do Geant4 simulation

  • How it works
    • parameters used to defined a detector are in Delimiter-separated_values format and can be stored in simple text file or in a database also. They can be edited by hand.


GEMC tries to be a wrapper around Geant4, you need to know some basic of geant4, refer to Geant4 like here

Documentation on GEMC website

Introductory talks

[1] Zhiwen Zhao, 2015/03/26
[2] Zhiwen Zhao, 2015/09/11
[3] Maurizio Ungaro,2015/09/24


example of full detector including many subsystems


example of a standalone simulation

This is an example of SoLID EC simulation with customized hit processing. It's ready to be included into full SoLID simulation without any change needed

refer to the general information about standalone simulation for SoLID here

detector description files are at
Here is how to build this simulation
first source env like this one
edit solid_PVDIS_ec_forwardangle__parameters_Original.txt to modify parameter
edit to modify geometry
edit to modify material
edit to modify bank
edit to modify hit
edit * to modify mirror (not applicable to this EC simulation)
edit to include all other perl script
edit config_solid_PVDIS_ec_forwardangle.dat to make sure detector name is correct
run "./ config_solid_PVDIS_ec_forwardangle.dat" to generate all text files
edit $SoLID_GEMC/source/$GEMC_VERSION/hitprocess/ like [this one to match entries in
recompile solid_gemc by "cd $SoLID_GEMC/source/$GEMC_VERSION" and "scons OPT=1"
Then you can run simulation according to

building simulation

introduction and format

By building simulation, it means building the experiment setup in simulation.

It includes defining geometry with material or mirror property and choosing which geometry be sensitive to record output with what kind of hit processing

All things including geometry,material,mirror,bank,hit are defined in a table format with fixed entries.

It can be stored first in a txt file, then user can choose to put it into a table in a database. GEMC can read both txt file and database as input

GEMC uses a set of perl tools to generate the text file, but it can be edit directly by hand

Only the hit process routine is in C++ code, which will be compiled and linked to GEMC library.


an example here [4]

There is no general perl script to produce it yet, just edit by hand

use "our %parameters = get_parameters(%configuration);" in [5] so that the parameters can be called and used in [6]


define it


See geometry tutorial on GEMC website.


  • Here are entry names and an example
 name           name of the volume
 description    description of the volume, doesn't have impact on actual simulation
 pos            position relative to mother in x y z
 rotation       rotation relative to mother along axis of x y z
 color          HEX color coding, refer to and
 type           geant4 solids name
 dimensions     geant4 solids dimensions
 mfield         local magnet field file name only applies to the volume
 ncopy          copy number
 pMany          1 or 0, needed by geant4 at G4PVPlacement time
 exist          1 or 0, active it or not in simulation
 visible        1 or 0, view it or not in graphic mode 
  • The mother volume of all is called "root" which is a big box with customized size at run time

see more details below

define type and dimensions

In standard Geant4 source code
G4double StartPhi=0;
G4double DeltaPhi=360;
In GEMC perl script
$detector{"type"}       = "Polycone";
  • Polyhedra (PGON) type, its parameter arrangement are little different from G4Polyhedra, it's "StartPhi,DeltaPhi,numSide*counts,numZPlanes*counts,rmin1,rmin2,...rminn,rmax1,rmax2,...rmaxn,z1,z2,...zn" in GEMC
In standard Geant4 source code
G4double StartPhi=0;
G4double DeltaPhi=360;
G4double poly_rmin[2] = {40.0*mm, 40.0*mm}; //this is inner radius of polyhedron side line, not corner 
G4double poly_rmax[2] = {50.0*mm, 40.001*mm}; //this is inner radius of polyhedron side line, not corner
G4Polycone *solidGroove1 = new G4Polyhedra("Groove1",StartPhi,DeltaPhi,6, 2, poly_z, poly_rmin, poly_rmax);
In GEMC perl script
$detector{"type"}       = "Pgon";
$detector{"dimensions"} = "0*deg 360*deg 6*counts 2*counts 40*mm 40*mm 50*mm 40.001*mm 0*mm 1*mm";
  • geant4 volume boolean operation in gemc
3. See examples in the
  • geant4 volume copy in gemc
2. See examples in [7][8]

link material

 > Option DEFAULT_MATERIAL: Default material for missing material field
 > Option HALL_MATERIAL: Composition of the Experimental Hall. 
           Air normal simulation
           Air_Opt Simulation with Optical Physics (default)

link local magnetic field

local magnetic field to the geometry is defined by "mfield"



all daughter geometry will inherent mother field

link sensitivity

This is closely linked to hit processing

 For a non-sensitive geometry
 $detector{"sensitivity"} = "no";
 $detector{"hit_type"}    = "no";
 $detector{"identifiers"} = "no";
 $detector{"sensitivity"} = "flux";
 $detector{"hit_type"}    = "flux";

link mirror


  $detector{"hit_type"}    = "mirror";

check overlap

   GEMC Option CHECK_OVERLAPS: Checks Overlapping Volumes:
     1.  Check Overlaps at Construction Time
     2.  Check Overlaps based on standard lines grid setup
     3.  Check Overlaps by shooting lines according to a cylindrical pattern



convert geometry file from GEMC 1 to GEMC 2 format

The changes are small and here is a summary

1. header changes because IO engine changes

easy to see by comparing a old file and new file


field is defined in map file with name like field_name.dat

It's a text file including a header and the actual map


see examples at


See material tutorial on GEMC website.



See mirror tutorial on GEMC website.


hit processing


First understand what is a "GEMC Hit"

hit processing need 3 things to work together







hit definition

built in type "flux"

The built-in "flux" type has timeWindow as "0" and thus it sums all steps with a sensitive volume with same ID from one track into a hit. One particular situation this won't work well is if you have a track passing through one detector more than once, (for example a low energy charge particle got bend backward in magnetic field), flux will average the multiple hits and give nonphysical results like hit positions etc

signalThreshold = 0;
timeWindow      = 0;
prodThreshold   = 1*mm (for GEMC >=2.3) or 0.001*mm (for GEMC <2.3)
maxStep         = 1*mm;

customized type


$hit{"name"}            = "solid_hgc";
$hit{"identifiers"}     = "id";
$hit{"mvToMeV"}         = 100;
$hit{"pedestal"}        = -20;
  • meaning of the entries

bank definition

built in type "flux"



customized type





Additional entries can't have same name what "true info" has (see below), otherwise, it create conflict when "true info" is recorded for the bank

true info

"true info" records particles in a sensitive volume

By default, it's off.

It can be turned on for flux and any customized bank by option like <option name="INTEGRATEDRAW" value="flux,solid_gem"/>

Then additional entries here will be added into the bank output

The "Process Names / ID Table" on the webpage is not correct for all version of code and it changes. To check the version you used, open the source file at "source/sensitivity/" and search for "procName"

hit process routine


All entries defined in bank definition should be filled one by one

The source code has same matching version with GEMC version

see examples here

generating experiment setup

Once parameter, geometry, materiel, mirror, bank, hit are all defined, we are ready to generating experiment setup by commands like

"./ config_solid_PVDIS_ec_forwardangle.dat"

the perl script set up some env variable and call all other perl scripts,

the config file defines some features like detector name and if use text file or database.

A serial of text files will be produced and loaded into database if decided, ready for simulation to run.

running simulation

running option and gcard file

run "gemc -help" to see all running option

run "gemc -help-html" will produce a file options.html showing all running options, see gemc 2.3 options gemc 2.2 options and gemc 2.1 options (save the file to your local machine and view it with a browser to see it in right format)

All options can be used at command line with a dash

All options can be put in a XML format gcard file, one example here [12]. And you can call gcard without a dash


Please note gcard file can't recognize env variable, so the detector file and field map location need to be either relative to current running path or have absolute path. If not being careful, a job on a computer farm can fail due to this

Some special options

<detector name="detector_name" factory="TEXT" variation="Original"/>  include this detector with many files like geometry,materials,mirrors,hit,bank
<detector name="volume_name">  <existence exist="no" />    </detector> turn off a volume and its daughter volume at run time
<option name="PHYSICS" value="QGSP_BERT+STD+Optical"/>  combined physics list 
<option name="INTEGRATEDRAW" value="flux"/>   activates true info output for the built-in flux bank
<option name="ALLRAWS"  value="flux,ec"/>     activates step-by-step output for the built-in flux bank and user defined ec bank


option "HALL_FIELD" is the global magnetic field

local field is defined in a particular volume definition and only live within the volume and covers its daughter volume.


When local and global field overlaps, local field always win because field in daughter volume will always supersede the one in the mother volume, as in geant4.

Both global and local field will try to find map files with "dat" as file extension at the location defined by "FIELD_DIR"

"SCALE_FIELD" scales a field by a factor and it works on both local and global field


particle color

Particle   Color
neutrons   black 
photons    blue 
e-         cyan 
protons    orange 
pion+      magenta 
pion-      yellow 
q=+1       red 
q= 0       white 
q=-1       green

hit color

red: hit for which the first step Edep is above threshold

blue: hit for which the first step Edep is below threshold

green: hit for which the first step Edep zero

using macro

geant4 command can be used directly in GUI window



macro examples here

particle ID

the standard geant4 pid, follows PDG defination

To see all pids, run this 'gemc -BEAM_P="show_all"' to get this list GMEC pid


input format

GEMC take two kinds of input

1. particle guns directly from options

a particle gun for a single particle

2. from an external input file pointed by an option



passing information into output

The information from input are completely passed into output in two banks




Direct output are txt or evio which is JLab DAQ data format

use text output to debug

convert evio to xml by

evio2xml output.evio

covert evio to root by

for built-in flux bank only
evio2root -INPUTF=output.evio  
for customized bank

see evio2root option by

evio2root -help-all


GEMC can output many detailed information for debugging if VERBOSITY options are used as show in help message, for example "-GEO_VERBOSITY=100" will give more info about geometry

If you see a warning like this "Error: directory /group/solid/apps/jlab_root/noarch/data/ could not be opened.", just ignore it.

note for 3D display file

example result

pngpdfwrl JLEIC beamline

wrl file

run simulation with this macro to generate a wrl file

This VRML file ending with wrl can be opened by many CAD program, for example, "3D builder" preinstalled in window8 and 10, meshlab, freecad

pdf file

we can convert wrl to pdf with a paid version of acrobat




	toolbar, %same as `controls'

