View on GitHub

GEARS | 齿轮组

Geant4 Example Application with Rich features and Small footprints

Download this project as a .zip file Download this project as a tar.gz file

YouTube tutorials visualization boolen scripts optical syntax

Detector construction


Instead of using geometry written in C++ as described in detail in the Geant4 manual, GEARS accepts two types of detector geometry descriptions in pure ASCII format as input:

Their difference is similar to that between markdown and HTML. The simpler text geometry description provided by Geant4 is recommended to be used as GEARS’s input given its simplicity and readability. For example, an experimental hall filled with air and of a dimension of 10 x 10 x 10 meters can be easily implemented using the following line:

:volu hall BOX 5*m 5*m 5*m G4_AIR

For more examples, please check *.tg files in the tutorials/detector directory, such as tutorials/detector/ and tutorials/detector/ The suffix of .tg indicates that they are text geometry description files. A Geant4 macro command /geometry/source is added to load geometry files:


You can utilize Boolean operation or shell scripts to construct more complicated geometries.

Alternatively, you can read a GDML file:

/geometry/source file.gdml

The command must be used before /run/initialize, otherwise GEARS will construct a simple experimental hall automatically to prevent crashing.

GEARS provides the following command to export constructed detector geometry to a GDML file:

/geometry/export output.gdml

This can only be used after the macro command /run/initialize, which constructs the detector geometry before exporting. While the simpler text geometry description can only be understood by Geant4, GDML can be understood by many other tools. For example, ROOT provides functions to read and visualize GDML geometries. On the other hand, it is not that easy to write a valid GDML file manually. This functionality is provided to enable the following usage:

 # describe the detector using simple text geometry description
 # construct the detector
 # export detector geometry as GDML for analysis/visualization in other tools
 /geometry/export output.gdml

You can find a concrete example in tutorials/detector/GDML.

Sensitive volume

Total energy deposited in a sensitive volume is recorded in an array in a GEARS output file. You can turn any volume to a sensitive one by simply adding the string “(S)” at the end of its name. The copy number of the volume is used as the array index to retrieve the total energy deposited in that volume. Note that hits in any volume that has a copy number less than 1 won’t be recorded. Consequently, the copy number of a sensitive volume must be larger than 0. If there are multiple sensitive volumes, their copy numbers do not have to be continuous.


The NIST material table provided by Geant4 contains all elements (C, H, O, for example) and a lot of commonly used materials (start with “G4_”). One can run /material/nist/listMaterials at any Geant4 state to print the list locally. These materials can be used directly in a text geometry description, for example

// use Geant4 elements, C and H to define TPB
:MIXT_BY_NATOMS TPB 1.079 2 C 28 H 22
// use NIST material G4_AIR to define vacuum
:mixt vacuum 1e-9 1 G4_AIR 1

To construct more complicated material please refer to the manual of the text geometry description.