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

Documentation License: MIT Code size

GEARS is a Geant4 Example Application with Rich features yet Small footprint. The entire C++ coding is minimized down to a single file with about 600 SLOC. This is achieved mainly by utilizing Geant4 plain text geometry description, build-in UI commands (macros), and C++ inheritance. It is ideal for student training and fast implementation of small to medium-sized experiments.


Getting started



You can download GEARS as a .tar.gz or *.zip file from its homepage or GitHub page, and run the following to unzip it:

$ unzip # if you downloaded the zip file
$ tar xfvz jintonic-gears-commitID.tar.gz # if you download the tar.gz file
$ mv jintonic-gears-commitID gears # rename the directory

If you know how to use Git, you can download the whole GEARS repository from GitHub:

$ git clone

This way, you can update your GEARS using

$ cd /path/to/gears
$ git pull


GEARS is shipped with a simple makefile. Simply type make to compile to generate the executable gears:

$ git clone
$ cd gears
$ make # compile
$ export PATH=/path/to/gears:$PATH
$ export LD_LIBRARY_PATH=/path/to/geant4/libs:$LD_LIBRARY_PATH # for Linux
$ export DYLD_LIBRARY_PATH=/path/to/geant4/libs:$DYLD_LIBRARY_PATH # for MAC
$ gears # run gears

User interface

GEARS relies on G4UIExecutive to select a user interface (UI). Without any specific setup, GEARS will try to run a graphic user interface (GUI) based on Qt. If your Geant4 is not compiled with Qt support, GEARS will try to use a command-line UI that behaves like a tcsh. Run the following command to check if your Geant4 is compiled with Qt

$ geant4-config --help | grep qt

If the output is qt[yes], then you should be able to use the Qt based GUI. If you can’t, please check if you set the environment variable G4UI_USE_TCSH to 1 somewhere:

$ env |grep G4UI

If yes, change it to G4UI_USE_QT=1 instead, and run gears again.

If none of the G4UI_USE_XXX variables is set, check if you have ~/.g4session with the following line in it:


If yes, add one more line to it:

gears qt

so that you can use Qt based GUI with GEARS, while run other Geant4 applications with command-line based UI.


Physics list

Since it requires a lot of knowledge to set up a correct physics list, Geant4 provides some pre-packaged physics lists. Three are enabled by default in GEARS:

Three optional lists (G4OpticalPhysics, G4HadronElasticPhysicsHP, G4HadronPhysicsFTFP_BERT_HP) can be enabled using Geant4 macros:

  # has to be called before /run/initialize
  /physics_lists/enable Optical
  /physics_lists/enable HadronElastic
  /physics_lists/enable HadronInelastic

Physics processes

Run /process/list after /run/initialize, and you will get

     Transportation,              Decay,   RadioactiveDecay,                msc
              hIoni,            ionIoni,             hBrems,          hPairProd
        CoulombScat,              eIoni,              eBrem,            annihil
               phot,              compt,               conv,             muIoni
            muBrems,         muPairProd,         hadElastic,   neutronInelastic
           nCapture,           nFission,    protonInelastic,       pi+Inelastic
       pi-Inelastic,     kaon+Inelastic,     kaon-Inelastic,    kaon0LInelastic
    kaon0SInelastic,    lambdaInelastic,anti-lambdaInelastic,   sigma-Inelastic
anti_sigma-Inelastic,    sigma+Inelastic,anti_sigma+Inelastic,     xi-Inelastic
  anti_xi-Inelastic,       xi0Inelastic,  anti_xi0Inelastic,    omega-Inelastic
anti_tritonInelastic,  anti_He3Inelastic,anti_alphaInelastic

Now you can use, for example, /process/inactivate nCapture to disable neutron capture process in your simulation. And you can use, for example, /process/setVerbose 20 RadioactiveDecay to change the verbosity of the radioactive decay process.

Individual optical processes can be toggled by the following commands:

/process/optical/processActivation Cerenkov true/false
/process/optical/processActivation Scintillation true/false
/process/optical/processActivation OpAbsorption true/false
/process/optical/processActivation OpRayleigh true/false
/process/optical/processActivation OpMieHG true/false
/process/optical/processActivation OpBoundary true/false
/process/optical/processActivation OpWLS true/false

Detailed control of radioactive decay is provided by the /grdm/ command, for example,

/grdm/deselectVolume chamber # disabled radioactive decay in volume "chamber"
/grdm/nucleusLimits 1 80 # enabled radioactive decay only when z in [1, 80]


Output format

GEARS utilizes Geant4 analysis managers to provide 4 output formats: ROOT (default), HDF5, CSV, and XML. The output file format can be chosen using the following command:

make hdf5 # create from
make # compile

The output file name can be chosen using macro command:

/analysis/setFileName output

No suffix is needed for the file name.


ROOT use TTree to save data. TTree have entry and branch to build their data structure. Each branch is a variable listed in Track Points, and each entry is a event. ROOT will compress the data, so it will cost less disk space. ROOT can load part of data, which can save time when it get large.

Track point

A track point is a concept introduced in GEARS. It is a point where a track is generated or changed. It records the following information:

Process id

The physics process generating each track point is saved in a variable pro[n], where n is the index of the track point. It equals to (process type) * 1000 + (sub type). The Process types are defined in G4ProcessType.hh, sub types are defined in G4HadronicProcessType.hh, G4DecayProcessType.hh, G4EmProcessSubType.hh, G4TransportationProcessType.hh, G4FastSimulationProcessType.hh, G4OpProcessSubType.hh, etc. They can be found at

Particle id

The type of particle related to a track point is saved in a variable pdg[n]. It is the same as the PDG encoding of the particle. A Google search will give more information about it.

Record information of step 0

One cannot get access to step 0 (initStep printed on screen if /tracking/verbose is set to be more than 0) through G4UserSteppingAction, which only provides access to step 1 and afterwards. However, step 0 contains some very important information that is constantly requested by the user. For example, the energy of a gamma ray from a radioactive decay is only available from step 0. Such information can be easily displayed using the following ROOT command with the Output ROOT tree, t:

  // draw kinetic energy, "k", of a gamma (pdg==22)
  // created by radioactive decay process (pro==6210)
  t->Draw("k","pro==6210 && pdg==22")

This is achieved by using G4SteppingVerbose instead of G4UserSteppingAction for data recording. The former provides a function called TrackingStarted() to print verbose information about step 0 on screen if /tracking/verbose is set to be more than 0. It also provides a function called StepInfo() to print verbose information about steps after step 0 on screen if /tracking/verbose is more than 0. G4SteppingVerbose::StepInfo() is called right before G4UserSteppingAction::UserSteppingAction(G4Step) is called in G4SteppingManager::Stepping(), it hence can be used to fully replace the functionality of G4UserSteppingAction::UserSteppingAction(G4Step).

In fact, G4UserSteppingAction::UserSteppingAction(G4Step*) is not used at all in GEARS. The Output class inherits TrackingStarted() and StepInfo() from G4SteppingVerbose to record data from all steps. There is another advantage of using G4SteppingVerbose instead of G4UserSteppingAction for recording, that is, G4SteppingVerbose is provided as a globally available singleton, which can be easily accessed at different places in the codes using:


This is used in G4UserRunAction to open and close a TFile, in G4UserEventAction to fill a TTree.

The catch is that functions in G4SteppingVerbose will not be called in G4SteppingManager unless /tracking/verbose is set, which will print too much information on screen for a long run. This is solved in EventAction::BeginOfEventAction by turning on tracking verbose all the time so that all functions in G4SteppingVerbose will be called, while at the same time, turning on G4SteppingVerbose local verbose flag Silent to run them in silent mode.

Coding convention

G4cout VS std::cout

G4cout and G4endl is preferred over std:cout and std:endl because the former handle the output in Geant4 GUI correctly, while the later can only output to terminal.