How to Run Geant4 Simulator for GLAST Balloon Test Flight 1 Introduction

How to Run Geant4 Simulator for GLAST Balloon
Test Flight
Tsunefumi Mizuno (Hiroshima University)
[email protected]
August 18, 2001
– update log of this document –
August 18, 2001 written by T. Mizuno
Here we describe how to setup/run Geant4 simulator for the GLAST Balloon Flight.
This memo is intended for Balloon Flight Simulator version 1.3, i.e., balloonsim package
of v13r1p* available from SLAC CVS repositly. There are some separate reports related
to the simulator.
• Detector geometry:
“Detector Geometry used for Geant4 Balloon Test Simulator (BalloonTestV13)”˜mizuno/Geant4/BalloonGeometry 2001-08-18.pdf
• Validation of the simulator:
“Validation of Geant4 Balloon Test simulator (BalloonTestV13)”
• Cosmic-ray proton and electron generator:
“Cosmic Ray Generator for GLAST Geant4 Simulation – BFEM Version– ”˜mizuno/Geant4/CRGene 2001-06-30.pdf
• Description of digitization scripts:
“Digitization and Conversion Scripts for GLAST G4 Balloon Sim”
• Validation of scripts/simulator:
“Validation of Geant4 Simulator for GLAST Balloon Test Flight”˜mizuno/Geant4/Validation 2001-08-18.pdf
Install on Your Own Machine
The programs are stored in SLAC CVS, and can be checked out as
cmt checkout balloonsim
The latest version at the moment (July 28, 2001) is v13r1p1, and requires packages of
LHCbCMT, EXTLIB, CLHEP, and Geant4 (see “requirements” file in “cmt” directory).
After modifying “requirements” file of this and related packages to meet your environment,
you can compile programs as follows;
cd balloonsim/v13r1p1/cmt
cmt config
The directory structures are shown below, where “balloonsim” is the parent directory
of this package. Note that directory names are given in brackets. Also note that this
example is for a linux machine. In “Run” directory, execute macros and analysis perl
scripts are stored, and you are expected to run the simulator here. In the next section,
we describe how to run the simulator in detail.
header files
source files
configuration files of cmt
changelog and old readme are stored
objects and execute file are stored
execute macros are stored
sample startup macro
default startup macro
sample execute script
changelog before importing to SLAC CVS
simulation outputs are stored here
digitization/conversion scripts
How to Setup/Run Programs
Composition of the simulator
The basic structure of our simulator is described in “src/BalloonTestV13.cxx” as summarized in Figure 1. If you need to modify the simulator, you have to know this structure.
Therefore we describe the structure in detail below.
The flow of the simulation is controlled by G4RunManager class, the Geant4 toolkit
class we have to construct first in a main() function. This class handles three mandatory
classes (classes we have to define to make Geant4 execute), i.e., DetectorConstruction
class, PhysicsList class, and PrimaryGeneratorAction class, and all of them are derived
from the abstract base class provided by Geant4. DetectorConstruction class describes
the detector setup. This class is written in “src/DetectorConstruction.cxx”. In PhysicsList class, all particles and physics processes are specified. This class is written in
“src/PhysicsList.cxx”. PrimaryGeneratorAction class gives the way of generating a primary event (here, “primary” means not the primary component of cosmic-ray, but the
primary event of the simulation), and is written in “src/CosmicRayGeneratorAction.cxx”
or “src/TestBeamGeneratorAction.cxx”. The former generates the particles that obey
cosmic proton/electron spectra, and the latter allows you to shoot any particle you want.
G4RunManager first constructs the detector geometry as described by DetectorConstruction class and prepares numerical tables for PhysicsList class. Then it generates the
primary particle as described by PrimaryGeneratorAction class and do the monte-carlo
In addition of these three mandatory classes, three optional classes are handles by
G4RunManager class in our simulator. The first class is RunAction class written in
“src/RunAction.cxx”, and the second one is EventAction class written in “src/EventAction.cxx”,
and the last one is TrackingAction class written in “src/TrackingAction.cxx”. In Geant4
simulator, one “Run” consists of one or more “Events”, as specified by “/run/beamOn
number of events” command (see § 3.5). And RunAction class is activated for each “Run”,
whereas EventAction class for each “Event”. In our simulator, RunAction class prints out
the run number in standard output, EventAction class stores the simulation outputs into
ASCII files (see § 3.6), and TrackingAction class stores the particle trajectory necessary
for visualization. The visualization is handles by VisManager class that is initialized also
in the main() function. We expect that users use DAWN to visualize the events.
(control the flow)
these classes are first initialized
then these classes work for each run/evnet
(CosmicRayGeneratorAction or TestBeamGeneratorAction)
RunAction.................printout run number
EventAction..............output the simulation results trajectory for visualization
(event visualization)
Figure 1: A basic structure of our Geant4 simulator for the balloon flight.
Detector Sensitivity and Production Cutoff
In Geant4, user can give sensitivity to arbitrary materials, and we attached sensitivity to
ACD, Si-strip detectors, CsI crystals, and plastic scintillators for XGTs. Energy deposited
in these materials are recorded in output ASCII files, and their format are described in
§ 3.6.
User can also set the cut value for particle production; a particle having range below
this value is not generated in simulation, and the energy of this “suppressed particle” is
deposited locally in the material. To avoid having too-much trajectories of knocked-out δrays, we set the cut value for electron 0.4 mm, whereas set 0.1 mm for others. If you want
to change this value by yourself, modify “src/PhysicsList.cxx” (see below) and recompile
the program.
// default cut value
defaultCutValue = 0.1*mm;
// cut for electron
electronCutValue = 0.4*mm;
// cut for gamma
gammaCutValue = defaultCutValue;
How to Shoot Particles
User can choose two methods to shoot particles. One is to shoot proton or electrons aimed
at four XGTs, and the other is to shoot particle aimed at Pressure Vessel.
In order to shoot particle on XGTs, edit “src/CosmicRayGeneratorAction.cxx” as
follows and re-compile the program.
#define onTarget 1
#define onPV
Then program randomly selects one of four XGTs and chooses a landing point of the
particle on a disk with minimum radius to contain the selected XGT (the disk radius is
6.123 cm). This disk is then rotated to be perpendicular to the particle direction. Note
that this procedure would not distort the original angular distribution and there would
not be double counting of flux for this method.
On the contrary, if you would like to shoot particle on Pressure Vessel, please edit
“src/CosmicRayGeneratorAction.cxx” as follows and re-compile the program.
#define onTarget 0
#define onPV
This time a landing point is chosen randomly on a disk of 140.293 cm radius. The disk is
centered on (0, 0, -11.82 cm), i.e., a center of the Pressure Vessel.
You can also shoot an arbitrary kind of particle of energy and direction you desire. To
do this, you have to edit src/BalloonTestV13.cxx as follows (i.e., activate the TestBeamGeneratorAction class instead of the CosmicRayGeneratorAction class) and re-compile
the program.
runManager->SetUserAction(new TestBeamGeneratorAction(detector));
// runManager->SetUserAction(new CosmicRayGeneratorAction(detector));
Then you can set particle kind, energy, initial position, and direction as you want by
typing the following commands in Geant4 prompt (see § 3.5).
/gun/particle mu/gun/energy 10 MeV
/gun/position 0 0 100 cm
/gun/direction 0 0 -1
In this sample, µ− of kinetic energy = 10 MeV appears at (0, 0, 100) cm, and goes
downward vertically. For more detail of these commands, see § 3.5.
We suppose you use DAWN, i.e., “Drawer for Academic WritiNgs”, to visualize events of
Geant4 simulator. To do this, you need to declare that you will use DAWN in balloonsim’s
requirements file (“cmt/requirements”) as follows
# Geant4 Visualization
macro_append balloonsim_cppflags " -DG4VIS_USE=1"
macro_append balloonsim_cppflags " -DG4VIS_USE_DAWNFILE=1"
macro_append balloonsim_cppflags " -DG4VIS_USE_DAWN=1"
and specify link option in Geant4’s requirements file (e.g., “Geant4/v3r0p1/mgr/requirements”)
like below.
## User Interface
macro_append Geant4_linkopts
‘‘ -lG4FR’’
After modifying requirements files as above, and including directory of DAWN in your
path like below, you can use DAWN for event visualization.
setenv PATH ${PATH}:/afs/
If you do not want to use DAWN, comment-out dawn-related macros in requirements
Once you succeed to re-compile the program, a DAWN file (that have .prim suffix)
will be generated when you run the simulator, and a DAWN control window will appear.
Figure 2 and 3 show the page 1 and 4 of the DAWN control panel. You can tune viewing
angle and position in page 1, and select a device (EPS file or X-Window) in page 4. These
configurations can be saved by pressing “Save Default” button. Press the “OK” button
and a 3D rendering of the detector will be shown. A sample of this drawing is shown in
Figire 4 A click of the right button on your mouse kills the plot.
After you run the events (“/run/beamOn number of events” command described in
§ 3.5), another DAWN panel will apear. This time you will see particle tracks. There,
green lines indicate neutrals, blue lines positively charged particles, and red lines negatively charged particles. If you would like to change the viewing angles, press the right
and left buttons simultaneously and you get a new control panel. Press “exit” to finish
the visualization.
Figure 2: The first page of a DAWN control panel, where you can tune the viewing angle
and position.
Figure 3: The fourth page of a DAWN control panel, where you can select output device
(EPS file or X-window).
Figure 4: A sample of DAWN drawing. Detector geometries of GLAST Balloon Flight is
How to Execute Programs
There are two ways to run Geant4 simulator. One is to run program interactively by
typing “../i386 linux22/balloonsim.exe” in “Run” directory without arguments. In this
mode, prerun1.mac is used as a start-up macro. After executing commands in this
macro file, Geant4 prompt Idle> will be displayed and you can run the simulator interactively. The other way is to run by using macro file: edit run1.mac as you want and
type “../i386 linux22/balloonsim.exe run1.mac”. If you want to save standard output to
a log file, type “../i386 linux22/balloonsim.exe run1.mac > logfilename”. The simulation
output files (see § 3.6) are stored in “Output” directory, so you have to make this directory if you do not have it yet. Below we list up useful commands for our BalloonTest
• /tracking/verbose [0–5]
Set verbose level for tracking information, which is useful for studying detector
response in detail. We recommend you to set this level 0 in case you simulate a lot
of events and save standard output to a log file.
– 0: No output
– 1: Minimum information, of each step
– 2: Information of secondary particles is added
– 3–5: more detailed information will be displayed
• /tracking/storeTrajectory [0 or 1]
Store trajectories (1) or not (0). To visualize particle trajectory, set the level 1.
Then after you ran the simulator (“/run/beamOn”), a DAWN window will appear
(see § 3.4). If you do not need to store trajectory, set the level 0 and the simulator
runs faster.
• /run/storeRandomNumberStatus [0-2]
Determine how to store random number seed files. Size of each random number
seed files is about 2 kbytes, so we do not recommend to set a level 2 (store files for
each event) when you run vast quantity of events.
– 0: no output
– 1: store random number seed files at beginning of each run
– 2: store at beginning of each event
• /run/restoreRandomNumberStatus directoryname/filename
By reading the stored random number seed file, you can reproduce any events.
• /gun/particle [proton, e-, gamma, etc...]
Determine what particle to be shot. When you activate CosmicRayGeneratorAction
class, only proton and electron (e-) can be selected, and the program will fall off
when you try to shoot other kind of particle.
• /gun/energy 1 GeV
Set kinetic energy of primary particle at 1 GeV. You can also choose another unit,
such as MeV, keV, and so on. Note that this option is effective only when you activated a TestBeamGeneratorAction class, not a CosmicRayGeneratorAction class.
• /gun/position 0 0 100 cm
Set initial position of primary particle at (0, 0, 100 cm). You can also choose
another unit. Note that this option is effective also only when you activated a
TestBeamGeneratorAction class, not a CosmicRayGeneratorAction class.
• /gun/direction 0 0 -1
Set the direction of the particle to (0, 0, -1). Again, this option is available only
when the TestBeamGeneratorAction class is activated.
• /run/beamOn 1000
Start a Run and simulate 1000 events
If you want to get description for other commands, type /control/manual in Geant4
When you set storeRandomNumberStatus 1 or 2, random number seed files are stored
in current directory. If you want to delete files that you may not be interested in, type
“scripts/”, then random number seed files of the events where
there is no hit in active detectors will be removed. Typing “scripts/”
move random number files in subdirectory you want. These two scripts are automatically called by using, a sample execute script. Link the Geant4 execute as
name of “BalloonTestV13.exe” and type “./” for interactive run or “./
run1.mac” for batch run.
Format for the Simulation Output
There are four simulator output files of BalloonTest program; a file recording the tracker
hists (TrackerOut.dat), a file recording the calorimeter hits (CalOut.dat), a file recording
the anti-coincidence detector hits (AntiOut.dat), and a file recording the active target hits
(TargetOut.dat). We explain the file format below. In all of these four files, “EventNo=”
identifies event number (start from 1), and primary particle information is stored in two
lines started “BEAM=”, where you can get the particle kind (“BEAM=”), the rest mass of
the particle (“Mass=”), the three momentum vector (“PXYZ=”), and the initial position
of the particle (“XYZi=”). To reduce file size and save disk space, these information are
not recorded if there are no hit in the sensitive detector.
Format of TrackerOut.dat
G4 chops up a particle track into contiguous segments bounded by either interaction
(including delta-ray knock-outs) or sampling distance close the one mean free path of the
particle. So a proton track will be broken out whenever a delta-ray is knocked out and
a delta-ray will be broken up into short segments because a low energy electron have a
much shorter mean-free path. “NoTrackerHit=” in TrackerOut.dat (see a sample shown
below) denotes the number of this segments of particle that deposited energy in Si-strip
detector (note that a threshold level is set 0 MeV, and digitization will be applied by perl
scripts). “ID=” identifies the detector component (a tracker plane; 0–25), “ParSpc=” tells
a particle species, “TkrLen=” gives a length of the segment, “XYZi=” and “XYZo=” give
the input/output points (entrance/exit or appearance/disappearance) of a particle track
within a Si layer, “DepE=” gives the energy deposition, and “ParE=” the total energy
of the particle at the input point. All linear dimensions are in unit of millimeter and all
energy values are in MeV in TrackerOut.dat (and also, in AntiOut.dat, TargetOut.dat,
and CalOut.dat).
EventNo= 1
BEAM= proton Mass= 938.272
PXYZ= -7013.11 -16700.4 -3379.47 XYZi= 526.583 1803.74 932.62
NoTrackerHit= 0
EventNo= 6
BEAM= proton Mass= 938.272
PXYZ= -3537.32 -2983.71 -356.919 XYZi= 1595.27 1146.32 860.904
NoTrackerHit= 0
EventNo= 9
BEAM= proton Mass= 938.272
PXYZ= 542.76 119.759 -972.743 XYZi= -889.39 -62.4939 1713.57
NoTrackerHit= 21
ID= 25 ParSpc= proton TrkLen= 0.461746 XYZi= -147.557 100.269 388.108
XYZo= -147.332 100.317 387.708
DepE= 0.227764 ParE= 1451.74
ID= 22 ParSpc= proton TrkLen= 0.461696 XYZi= -127.733 104.566 352.926
XYZo= -127.508 104.615 352.526
DepE= 0.194183 ParE= 1451.27
Format of AntiOut.dat/TargetOut.dat
In AntiOut.dat and TargetOut.dat, “No(Anti/Target)Hit=” gives the number of tiles or
targets hit, “ID=” denotes a ACD tile or Target scintillator ID number, and “DepE=”
the sum of energy deposited in the ACD tile (or target). Below we show a sample of
EventNo= 1
BEAM= proton Mass= 938.272
PXYZ= -7013.11 -16700.4 -3379.47 XYZi= 526.583 1803.74 932.62
NoAntiHit= 2
ID= 9
DepE= 2.5366
ID= 13
DepE= 5.67245
EventNo= 6
BEAM= proton Mass= 938.272
PXYZ= -3537.32 -2983.71 -356.919 XYZi= 1595.27 1146.32 860.904
NoAntiHit= 0
EventNo= 9
BEAM= proton Mass= 938.272
PXYZ= 542.76 119.759 -972.743 XYZi= -889.39 -62.4939 1713.57
NoAntiHit= 1
ID= 9
DepE= 5.16403
And below we give a sample of TargetOut.dat.
EventNo= 1
BEAM= proton Mass= 938.272
PXYZ= -7013.11 -16700.4 -3379.47 XYZi= 526.583 1803.74 932.62
NoTargetHit= 0
EventNo= 6
BEAM= proton Mass= 938.272
PXYZ= -3537.32 -2983.71 -356.919 XYZi= 1595.27 1146.32 860.904
NoTargetHit= 1
ID= 1
DepE= 8.61282
EventNo= 9
BEAM= proton Mass= 938.272
PXYZ= 542.76 119.759 -972.743 XYZi= -889.39 -62.4939 1713.57
NoTargetHit= 0
Format of CalOut.dat
As for Calorimeter, we need to simulate the double-side read-out. In order to do this, we
virtually divided each log into 10 blocks, and record the energy deposition in each of this
blocks in CalOut.dat. Digitization scripts read this block ID and simulate the double-side
read-out. A sample of CalOut.dat is given below. There, “LogID=” gives an ID number
of each log (from 0 to 79 with decreasing z value, see Figure 4 in the geometry descriptin
document), and “LayerID=” gives an ID of layer (from 0 to 7, where 0 means the layer
closest to the Tracker). As already described, we divided each log into 10 blocks in order
to record the position of the energy deposition, and this is shown as “LogDID=” (from
0 to 9 with increasing coordinate value of the principle axis). “DepE=” gives a energy
deposition in each block and “TotCalE=” means the summation of DepE.
EventNo= 1
BEAM= proton Mass= 938.272
PXYZ= -7013.11 -16700.4 -3379.47 XYZi= 526.583 1803.74 932.62
NoCalHit= 0
TotCalE= 0
EventNo= 6
BEAM= proton Mass= 938.272
PXYZ= -3537.32 -2983.71 -356.919 XYZi= 1595.27 1146.32 860.904
NoCalHit= 0
TotCalE= 0
EventNo= 9
BEAM= proton Mass= 938.272
PXYZ= 542.76 119.759 -972.743 XYZi= -889.39 -62.4939 1713.57
NoCalHit= 0
TotCalE= 0
EventNo= 34
BEAM= proton Mass= 938.272
PXYZ= -1649.4 9422.07 -4229.66 XYZi= 487.689 -1799.46 697.8
NoCalHit= 3
LogDID= 9 LogID= 28 LayerID= 2 DepE= 8.9184
LogDID= 8 LogID= 39 LayerID= 3 DepE= 1.53371
LogDID= 9 LogID= 39 LayerID= 3
TotCalE= 35.962
DepE= 25.5098
Analysis scripts
Perl scritps are prepared to convert Geant4 outputs described in previous section into one
file, called “G4Sim.irf”. To do this, just go to “scripts” directory and type “./”.
Then, detector outputs are digitized and summarized in G4Sim.irf, where only events that
satisfy L1T condition are recorded. For more detail, see “Digitization and Conversion
Scripts for GLAST G4 Balloon Sim”.