To see a list of the available Geant4 constructors:
gemc -showPhysics
Generator
The default kinematics is a 3 GeV proton generated along the z-axis just before the target.
This is defined in the YAML file:
gparticle:-name:protonp:3000*MeVvz:-250*cm
gparticle
The gparticle option controls the Geant4 particle gun.
For the complete list of parameters: gemc help gparticle.
Common parameters:
name: particle name (mandatory), e.g. proton or e-
multiplicity: number of copies generated per event;
copies are independently randomized when spread parameters such as delta_p or delta_theta are set
p: particle momentum with unit, e.g. 4*GeV or 4000*MeV
delta_p: momentum spread, centered on p
theta: polar angle with unit, e.g. 23*deg or 0.4*rad
delta_theta: polar-angle spread, centered on theta
phi: azimuthal angle with unit, e.g. 90*deg
Kinematic values accept an explicit Geant4 unit (value*unit). A plain number without
a unit falls back to MeV for momentum, deg for angles, and cm for vertex coordinates,
with a logged warning.
For example, to define a particle gun with one electron along z plus one proton at θ = 30° and φ = 90°:
The chamber volume sensitivities are specified with the flux digitization (one of the available GEMC prebuilt routines)
in b2.py. The copy number identifies each chamber:
The flux digitization collects all G4Step objects into hits by using the track ID: all steps within a
sensitive element produced by the same track define a single hit. Different tracks’ steps in the
same sensitive element are collected in separate hits.
This digitization can be used to count and analyze the tracks passing through a volume.
Flux hit definition example: three tracks goes through two sensitive cells.
Track 1 creates two hits: < cell2, hit #1 > and < cell1, hit #1 >.
Track 2 creates two hits: < cell1, hit #2 > and < cell2, hit #2 >.
Track 3 creates one hit: < cell2, hit #3 >.
The digitized variables below, resulting from the flux digitization, are stored in the output.
the sensitive element identifier, assigned by the user. For example:
sector
layer
hitn: hit number
pid: particle ID
tid: track ID
E: track energy
time: time of the hit
totEdep: total energy deposited by the track
In this case, the identifier contains only one name: mychamber.
In addition to the digitized variables, the true information is saved on the output stream.
True Information
The true information is processed by GEMC and, in some cases, averaged and weighted by the energy deposition.
For variables like pid, tid, or processName, the data come from the first step in the hit.
The complete list of variables is:
the sensitive element identifier, assigned by the user. For example:
sector
layer
hitn: hit number
pid: particle ID
tid: track ID
avgTime: average time
avglx: average local x position
avgly: average local y position
avglz: average local z position
avgx: average global x position
avgy: average global y position
avgz: average global z position
totalEDeposited: total energy deposited
processName: process name creating the first step of this hit
Usage
Building the detector
Use the Python script b2.py to build the detector. By default, the setup is stored in a SQLite file
named gemc.db. Command-line options can define the database type, variations, and run number.
python API
Pass -h for additional command line options:
options:
-h, --help show this help message and exit
-f, --factory FACTORY
ascii, sqlite
-v, --variation VARIATION
Set variation name
-r, --run RUN Set run number
-sql, --dbhost DBHOST
SQLite filename or MYSQL host
-pv, --pyvista Show geometry using pyvista (needs pyvista)
-pvb, --pvb, --pyvista-background
Use PyVista BackgroundPlotter (needs pyqt6 pyvistaqt)
-pvw, --width WIDTH Set plotter width
-pvh, --height HEIGHT
Set plotter height
-pvx, --x X Set plotter x position
-pvy, --y Y Set plotter y position
-axes, --add_axes_at_zero
If you have pyvista (see also install pyvista),
you can use the -pv and -pvb options to display the setup without having to run GEMC
Running gemc
The file b2.yaml can be used to run the setup. Add -gui to run interactively:
gemc b2.yaml -gui
Modify b2.yaml as needed, in particular to add particles, control the number of threads, or change the output.
Output
The gstreamer option selects the output name and format. Two simultaneous streams are selected:
CSV and ROOT.
Because flux is a per-event digitization, GEMC will produce one output file per thread.
For ROOT files, you can use hadd to merge the files.
gstreamer
The gstreamer option selects the output name and format.
Run gemc help gstreamer to check its documentation:
-gstreamer=<sequence> ......: define a gstreamer output
• filename: name of output file. Default value: NODFLT
• format: format of output file. Default value: NODFLT
• type: type of output fileDefault value: event
Define output formats and filenames.
It can be used to select <events> or <frame> streams.
The file extension is added automatically based on the format.
Supported formats:
- jlabsro
- root
- ascii
- csv
- json
Output types:
- event: write events
- stream: write frame time snapshots
Example that defines two gstreamer outputs:
-gstreamer="[{format: root, filename: out}, {format: csv, filename: out}]"
The produced files structure depends on the accumulation method used:
- event-based digitization (like <flux>) will have one file per
thread, with "_t<thread#>" appended to the filename
- run-based digitization (like <dosimeter>) will have one output file
Plotting with the GEMC Analyzer
Run GEMC with 1,000 events first. The default YAML file writes CO2_t0_digitized.csv and CO2_t0_true_info.csv.
