View on GitHub


Geant4 Example Application with Rich features and Small footprints

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

home examples visualization boolen scripts

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:

:volume hall BOX 5*m 5*m 5*m G4_AIR

For more examples, please check *.tg files in the examples/detector directory, such as examples/detector/ and examples/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 examples/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

Optical properties of a material or a surface

There is no tag to define the optical properties of a material or a surface in the default Geant4 text geometry description. The following two tags are added in GEARS to enable definition of optical materials and surfaces using Geant4 text geometry description syntax:

Define optical properties of a material

//:prop <material>
//  <wavelength-independent_property> <value>
:prop pureCsIat77K

//:prop <material> photon_energies <int(array size)> <energy array>
//  <wavelength-dependent_property> <property values>
:prop pureCsIat77K
  photon_energies 2 2.034*eV, 3.025*eV, 4.136*eV
  RINDEX 1.34, 1.35, 1.36
  ABSLENGTH 1.0*meter, 1.1*meter, 1.2*meter

Define optical properties of a surface

First of all, there is no need to define a surface for polished interfaces between two media. As long as the two media have an index of refraction stored in their respective G4MaterialPropertiesTable, the G4OpBoundaryProcess::PostStepDoIt will handle the refraction and reflection correctly.

One can use the following syntax to define a G4LogicalBorderSurface in case that there is a real need to specify the optical properties of the interface:

//:surf v12v2 v1:copyNo1 v2:copyNo2
:surf CsI2Teflon CsI:1 Teflon:1
  type dielectric_dielectric
  model unified
  finish ground
  sigma_alpha 0.1
  property photon_energies 2 2.5*eV 5.0*eV
    REFLECTIVITY 0.9 0.9
//property must be the last setting due to the current coding method

Note that physics volumes from the same logical volume created by the text geometry processor share the same name as their logical volume. Since G4LogicalBorderSurface requires pointers to the two physical volumes beside, a unique copy number has to be attached to the volume name to uniquely identify the physics volume.