Detector simulation general note

From Electron Ion Collider Wiki
Revision as of 17:32, 4 August 2016 by Zwzhao (Talk | contribs)

Jump to: navigation, search

Contents

Introduction

  • How it works
    • Geometry,material,mirror,hit processing including hit and bank definition are all external for GEMC. This allows simulate any detector without recompiling GEMC. They are defined in Delimiter-separated_values format and can be stored in simple text file or in a database. They are produced by a set of perl scripts and config files
    • 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 are edit by hand.
    • The hit process routine as a part of hit processing needs be defined in source code and compiled with GEMC as a library to form a final binary code.

Documentation and Example

see documentation on GEMC website

https://gemc.jlab.org/gemc/html/documentation/documentation.html

One example for an individual detector

SoLID Heavy Gas Cerenkov geometry https://jlabsvn.jlab.org/svnroot/solid/subsystem/hgc/hgc_solid_gemc/ 
SoLID Heavy Gas Cerenkov running script and analysis code https://jlabsvn.jlab.org/svnroot/solid/subsystem/hgc/analysis

Examples of full detector including many subsystems

CLAS12 https://phys12svn.jlab.org/repos/gemc/systems/clas12
SoLID https://jlabsvn.jlab.org/svnroot/solid/solid_gemc2
EIC   https://jlabsvn.jlab.org/svnroot/eic/eic_gemc

building simulation

By building simulation, it means defining geometry with material and mirror property and choosing which geometry be sensitive to record output with what kind of hit processing

parameters

geometry

define it

format

See geometry tutorial on GEMC website.

GEMC tries to be a wrapper around geant4, you need to know some basic of geant4, refer to http://geant4.cern.ch/G4UsersDocuments/UsersGuides/ForApplicationDeveloper/html/Detector/index.html

The final answer to all questions are in the source code building geometries "detector.cc"

  1. geometry is defined in a tabled format with fixed entries
 name  | mother | description  | pos  | rotation  | color  | Type  | dimensions  | material  | mfield  | ncopy | pMany | exist | visible  | style  |  sensitivity | hit_type | identifiers
an example
meic_det1_rich_detector_holder  | root  |meic_det1_rich_detector_holder  |  0*mm 0*mm 0*mm  |  0*deg 0*deg 0*deg  | ffffff   |  Box  | 56.25*mm 56.25*mm 12*mm  |  Air_Opt  |  no  |     1   |     1   |     1   |   1   |   0   |    no  |  no  | no 
  1. It can be stored first in a txt file with format as above, later user can choose to put it into a table in a database. GEMC can read both txt file and database as input
  2. GEMC uses a set of perl tools to generate the text file
  3. The mother volume of all is called "root" which is a big box with certain size built in GEMC.
 Here is some details about each entry
 name           name of the volume
 mother         name of its mother volume, has to be existing one or "root" which is a big box with certain size built in GEMC
 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 http://www.webmonkey.com/2010/02/color_charts/ and http://en.wikipedia.org/wiki/Web_colors
 type           geant4 solids name
 dimensions     geant4 solids dimensions
 material       geant4 defined material or GEMC built-in material or your customized material
 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 
 style          1 or 0, display it by solid or wire frame in in graphic mode
 sensitivity    any string not "no" or "no", active sensitivity or not
 hit_type       hit_type name string or "no", its hit type defined by hit process routine if it's sensitive
 identifiers    its identifiers string or "no", its identifiers if it's sensitive

see more details below

define type and dimensions

  • Polycons type, its parameter arrangement are little different from G4Polycone, it's "StartPhi,DeltaPhi,n*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_z[2] = {0*mm, 1.*mm};
G4double poly_rmin[2] = {40.0*mm, 40.0*mm};
G4double poly_rmax[2] = {50.0*mm, 40.001*mm};
G4Polycone *solidGroove1 = new G4Polycone("Groove1",StartPhi,DeltaPhi, 2, poly_z, poly_rmin, poly_rmax);
In GEMC perl script
$detector{"type"}       = "Polycone";
$detector{"dimensions"} = "0*deg 360*deg 2*counts 40*mm 40*mm 50*mm 40.001*mm 0*mm 1*mm";
  • geant4 volume boolean operation in gemc
1. On the "type" you can put : "operation:  volumeA + VolumeB","operation:  volumeA - VolumeB","operation:  volumeA * VolumeB" or "operation:@  volumeA + VolumeB","operation:@  volumeA - VolumeB","operation:@  volumeA * VolumeB" where "@" means that position of second object is given in the common mother volume of both objects
2. Define the volume A and B's material as "Component", so that these volumes won't be built
3. See examples in the https://phys12svn.jlab.org/repos/gemc/systems/clas12/htcc/geo/mirrors.pl
  • geant4 volume copy in gemc
1. On the "type" you can put: "CopyOf volumeA"
2. See examples in [4][5]

link material

  • empty materiel "" field can be filled with run time option
 > Option DEFAULT_MATERIAL: Default material for missing material field
  • the hall "root" material can be set as run time
 > Option HALL_MATERIAL: Composition of the Experimental Hall. 
           Air normal simulation
           Air_Opt Simulation with Optical Physics (default)
           Vacuum
  • total absorber, "Kryptonite". Anything touching it will be killed.
(It ends the track in step action, but because the physics comes in before step action. so it could still in principal have  
secondary which are very close the primary particles. use mother pid "mpid" in true info to veto them. Kryptonite is 
realized in code Mmaterial.cc as a very very low density material, so now the secondary is almost impossible. Another thing to 
note is the hit in a detector made of "Kryptonite" can be at the detector front or back on track path)

link local magnetic field

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

It uses the same field map file like the global field which is defined in running option "HALL_FIELD"

It lives within the geometry or its field map, whichever is smaller

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";
 For a sensitive geometry using built-in "flux" hit processing
 $detector{"sensitivity"} = "flux";
 $detector{"hit_type"}    = "flux";
 $detector{"identifiers"} = "id manual 1"; // for flux, a simple and unique integer called id is used to identify the geometry
 For a sensitive geometry using a customized "wire" hit processing as an example
 $detector{"sensitivity"} = "wire";   // match name in "wire" hit and bank definition
 $detector{"hit_type"}    = "wire";   // match name in "wire" customized hit and bank definition
 $detector{"identifiers"} = "sector ncopy 0 stack manual 3 view manual 6 strip manual 36"; 
 // match "identifiers" defined in "wire" hit definition, 
 //"ncopy 0" means number will be filled at run time, "manual" mean a number explicit here
 "identifier" has to be unique for any geometry, otherwise, hits can be averaged over different geometry and give nonphysical result

link mirror

If a volume is a mirror, we use sensitivity for now to link to its reflectivity in mirror defined here Detector_simulation_general_note#mirror

  $detector{"sensitivity"} = "mirror: SL_HGC_mirror";
  $detector{"hit_type"}    = "mirror";

check overlap

  • volume overlap will cause gemc to crash after beam on. You can check it with
   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

please note the option to check overlap only work in batch mode, NOT in graphic mode. This means it need to run with option "USE_GUI=0"

if you want a "envelope volume" to enclose some geometry (eg. a EC volume with vacuum to enclose all parts of calorimeter), you can do that. then you can set those envelope volumes' mother volume as "root". One catch here is that those envelope volume overlap won't cause crash if they are not sensitive. However gemc tracking will totally messed up if they overlap. Basically, gemc can't take any volume overlap and this is also true for geant4. So please try to avoid overlap in design.

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
2. add "my %detector=init_det();" 
3. replace "print_det(\%detector, $file);" with "print_det(\%configuration, \%detector);"
4. doesn't allow "" entry anymore, you can put "no" instead
5. only lower case "flux" works, "FLUX" won't
6. add "*counts" for any pure number in "dimensions"

easy to see by comparing a old file and new file

field

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

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

Its coordinate is absolute and in the same lab frame of the detector

see examples at

https://jlabsvn.jlab.org/svnroot/solid/solid_gemc2/field/

https://jlabsvn.jlab.org/svnroot/eic/eic_gemc/field/

material

See material tutorial on GEMC website.

materials are defined by its density,composition,optical properties, see example here

https://jlabsvn.jlab.org/svnroot/solid/subsystem/hgc/hgc_solid_gemc/solid_SIDIS_hgc_materials.pl

mirror

See mirror tutorial on GEMC website.

mirror is defined by its type, reflectivity and efficiency, see example here https://jlabsvn.jlab.org/svnroot/solid/subsystem/hgc/hgc_solid_gemc/solid_SIDIS_hgc_mirror.pl

hit processing

Intro

First understand what is a "GEMC Hit" https://gemc.jlab.org/gemc/html/documentation/hitDefinition.html

hit processing need 3 things to work together

1. "hit definition", gives run time control to fine tune hit processing

2. "bank definition", gives what info to store and define exact entries in output file

3. "hit process routine", do the actual processing to fill banks with control by hit definition

For built-in type "flux", they are all inside GEMC code and can't be modified

One can build fully customized hit processing for any special detector after supply the three items and use it as "sensitivity" and "hit_type" in a piece of geometry with a "identifier"

The way to link them together is by a unique hit processing name in all three places, for example "solid_hgc" or "eic_ec"

hit definition

built in type "flux"

The built-in "flux" type has timeWindow as "0" and thus it recorded every individual hit within the same detector. 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), 0.001*mm for (GEMC <2.3)
maxStep         = 1*mm;

customized type

a "*_hit.pl" script is used to produce a text file "*__hit_*.txt" which define some parameters relevant to hit processing and it has entries similar to the following

$hit{"name"}            = "solid_hgc";
$hit{"description"}     = "solid hgc hit definition";
$hit{"identifiers"}     = "id";
$hit{"signalThreshold"} = "0.*MeV";
$hit{"timeWindow"}      = "0*ns";
$hit{"prodThreshold"}   = "1*mm";
$hit{"maxStep"}         = "1*mm";
$hit{"delay"}           = "10*ns";
$hit{"riseTime"}        = "1*ns";
$hit{"fallTime"}        = "1*ns";
$hit{"mvToMeV"}         = 100;
$hit{"pedestal"}        = -20;
  • meaning of the entries
    • name -- the same name as bank definition and hit process routine
    • identifiers -- how to distinguish individual detector component, this determine format used in geometry. eg. "sector stack view strip"
    • signalThreshold -- Minimum Energy Cut for processing the hit (not used)
    • timeWindow -- try to match ADC integration time window or TDC windows. Within the time windows, all hits within a detector component (defined by "identifiers") are combined into one. "0*ns" will have every individual hit as used in "flux" hit type, but this will slow down processing time a lot.
    • prodThreshold -- any track with energy smaller than this will not be tracked further, all energy get deposited in current volume. Too large value will give you too few tracks and being unphysical. This was defined in energy unit in Geant4, but Geant4 used a length unit to make material independent. the conversion is within Geant4. Geant4 define this globally with default 1mm, but also can be set for individual volumes. here gemc makes it to set with individual hit process type. (refer to [6] [7] [8])
    • maxStep -- Geant4 calculate step size according to material property. for gas, it can be too large if you need more steps, eg in drift chamber. gemc will take smaller one between this value and Geant4 suggested value. It can't be 0, otherwise, mem overflow
  • The built-in "flux" type has timeWindow as "0*ns" and thus it recorded every individual hit within the same detector. 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

bank definition

built in type "flux"

The built-in "flux" type has the basics entries below to all record hits on a sensitive detector identified by an integer number id

insert_bank_variable(\%configuration, $bankname, "bankid", $bankId, "Di", "$bankname bank ID");
insert_bank_variable(\%configuration, $bankname, "hitn",        99, "Di", "hit number");
insert_bank_variable(\%configuration, $bankname, "id",           1, "Di", "id");

customized type

a "*_bank.pl" script is used to produce a text file "*__hit_*.txt" which define some parameters relevant to hit processing and it has entries similar to the following

It should have at least three entries unique "bankid", "hitn" for number of hit number, and identifier

identifier format can be customized,like "sector manual 1 layer manual 2" and it has to match what is in hit definition and hit process routine

Additional entries can be defined and should be filled in hit process routine

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

hit process routine

All quantity should be in "MeV,mm,ns" units as geant4 default and it's important to follow the convention because the output banks doesn't carry any unit

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

https://jlabsvn.jlab.org/svnroot/solid/solid_gemc2/source/
https://jlabsvn.jlab.org/svnroot/eic/eic_gemc/source/

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.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 [9]. Please note gcard file can't recognize env variable and you call gcard without a dash

You can combine both, for example "gemc a.gcard -USE_GUI=1"

Some special options

<option name="RECORD_PASSBY" value="1"/>      record hit with no energy deposition
<option name="SAVE_ALL_MOTHERS" value="1"/>   save all mother particles info, may slow things down
<option name="INTEGRATEDRAW" value="flux"/>   activates true info output for systems
<option name="ALLRAWS"  value="flux,ec"/>     activates step-by-step output for systems
<option name="USE_GUI"  value="0"/>           run in batch model

particle ID

the standard geant4 pid, follows PDG defination

http://geant4.cern.ch/G4UsersDocuments/UsersGuides/ForApplicationDeveloper/html/TrackingAndPhysics/particle.html

https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=4&ved=0ahUKEwiSuJnT0qnKAhVHwj4KHZKDC60QFggwMAM&url=http%3A%2F%2Fpdg.lbl.gov%2F2007%2Freviews%2Fmontecarlorpp.pdf&usg=AFQjCNHWMg78Kz3AKzk3Mt-61ZCOE18EZA&sig2=LJ4Cz-rqdcJVayMJLZTgdg&cad=rja

physics list

It can take combined physics list

<option name="PHYSICS" value="QGSP_BERT+STD+Optical"/>

field

running option "HALL_FIELD" is the global magnetic field

only one global field is allowed while local field can be be many and linked to individual geometry

"FIELD_DIR" tells where to find the field map file for both local and global field

"SCALE_FIELD" scales either local or global field

color

particle color

https://gemc.jlab.org/gemc/Documentation/Entries/2011/1/26_Particle_Color_Codes.html

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

They can also be group in macro and loaded from gcard or command line option like

<option name="EXEC_MACRO" value="meic_slice_tilt.vis"/>

macro examples here https://clas12svn.jlab.org/repos/clas12/gemc/tags/1.8/macros/

input

input format

GEMC take two kinds of input

1. particle guns directly from options

a particle gun for a single particle
<option name="BEAM_P"   value="e-, 5*GeV, 0*deg, 0*deg"/>
<option name="SPREAD_P" value="0*GeV,0*deg,0*deg"/>
<option name="BEAM_V"   value="(0, 0, 0)m"/>
<option name="SPREAD_V" value="(0.,0)cm"/>
and up to two more additional particle gun with multiple particles, which can be used to add background
<option name="LUMI_EVENT"   value="1, 1*ns, 1*ns"/>
<option name="LUMI_P"   value="e-, 5*GeV, 180*deg, 0*deg"/>
<option name="LUMI_SPREAD_P" value="0*GeV,0*deg,0*deg"/>
<option name="LUMI_V"   value="(0, 0, 80)m"/>
<option name="LUMI_SPREAD_V" value="(0.,0)cm"/>
<option name="LUMI2_EVENT"   value="1, 1*ns, 1*ns"/>
<option name="LUMI2_P"   value="neutron, 5*GeV, 50e-3*rad, 180*deg"/>
<option name="LUMI2_SPREAD_P" value="0*GeV,0*deg,0*deg"/>
<option name="LUMI2_V"   value="(0, 0, 0)m"/>
<option name="LUMI2_SPREAD_V" value="(0.,0)cm"/>
 

2. from an external input file pointed by an option

 <option name="INPUT_GEN_FILE" value="LUND, input.dat"/>  an example for the option

 The LUND format txt file as defined here) can be fully customized for its header part to allow 8 arbitrary variables passing into output

passing information into output

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

"header" bank has entries "evn,evn_type,var1,var2,var3,beamPol,var4,var5,var6,var7,var8" where evn is for event number, evn_type=-1 for simulated event, beamPol for beam polarization, and all other variables are 0 from a particle gun as input or customized from an input file.

"generated" bank has entries "pid,px,py,pz,vx,vy,vz" and unit are MeV and mm

output

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
evio2root -INPUTF=output.evio -B="dir1/bank1 dir2/bank2 ..." 
it will look for files dir1/bank1__bank.txt and dir2/bank2__bank.txt and more to convert the banks
use this option if the evio file produced with ALLRAWS turned on for certain banks, the default is "yes" 
-WRITE_RAWS="no"

see evio2root option by

evio2root -help-all

note for 3D display file

example result

pngpdfwrl JLEIC beamline

wrl file

run simulation with this macro https://jlabsvn.jlab.org/svnroot/eic/eic_gemc/script/vrml.vis to generate a wrl file

This VRML file ending with wrl can be opened by many CAD program, for example, meshlab

pdf file

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

Or a free way here by using meshlab and pdflatex to embed a U3D file in a tex file

go to a windows computer, open the wrl file in meshlab and export a U3D file with "color" selected. a U3D file and a tex file are generated accordingly.

edit the tex file to add line "\usepackage[a4paper,landscape,top=0mm, bottom=0mm, left=0mm, right=0mm]{geometry}" and change "{\linewidth}{\linewidth}" to "{297mm}{210mm}", so the final tex file looks like this

\documentclass[a4paper]{article}
\usepackage[3D]{movie15}
\usepackage[a4paper,landscape,top=0mm, bottom=0mm, left=0mm, right=0mm]{geometry}
\usepackage{hyperref}
\usepackage[UKenglish]{babel}
\begin{document}
\includemovie[
	poster,
	toolbar, %same as `controls'
	label=det1beamline20160316.u3d,
	text=(det1beamline20160316.u3d),
	3Daac=60.000000, 3Droll=0.000000, 3Dc2c=-641.099976 -86745.000000 320.000000, 3Droo=86747.960938, 3Dcoo=-641.114990 5064.898438 -319.960022,
	3Dlights=CAD,
]{297mm}{210mm}{det1_beamline_20160316.u3d}
\end{document}

then you can run pdflatex with the tex and u3d file to produce the pdf and then view the pdf in latest acrobat reader and choose to trust the file for 3D content, then you can rotate,zoom,cut,shed light on the 3D object

note: 
movie15 and some other packages are for pdflatex to handle u3d file correctly
If you want to use miktex on windows, it needs to be installed on default location, then movie15 and other packages will be installed at run time
this has been verified with meshlab 1.3.3 (http://meshlab.sourceforge.net) and miktex 2.9 (http://miktex.org/) on 2016/02
resources:
http://nj.riotdowntown.com/2011/04/u3d-2-pdf/ (this can in principal auto the process, but its current version 0.0.3.0 doesn't work well with the meshlab 1.3.3 for color)
http://www.cadforum.cz/cadforum_en/create-free-3d-pdf-output-from-any-cad-software-tip9972
http://www.astrobetter.com/blog/2012/03/07/tutorial-for-embedding-3d-interactive-graphics-into-pdf/
http://astrobetter.com/wiki/tiki-index.php?page=Tutorial%20on%203D%20Interactive%20Graphics%20in%20PDF&offset=&sort_mode=comment_desc&atts_show=y
http://www.tetra4d.com/pdf-samples/