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

Doxygen License:MIT Examples Get Started Get Involved

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, built-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 local copy from time to time using

$ cd /path/to/gears
$ git pull

Note that if you change some files in your local copy, the git pull command will fail since Git does not want to overwrite your local modification with the updated GEARS. To avoid this, please copy example macros to somewhere outside of the gears/ directory. You can then modify them as you like without worry.


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

$ cd /path/to/gears
$ make # compile
$ export PATH=/path/to/gears:$PATH # so that you can use gears everywhere
$ 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 somewhere:

$ env |grep G4UI

If yes, run export G4UI_USE_QT=1 to overwrite the G4UI_USE_TCSH setting, and run gears again. It is optional to delete the latter, because if both variables are set, the latter will be ignored.

Now, if you want to go back to the command-line UI, you need to unset G4UI_USE_QT and keep the G4UI_USE_TCSH setting unchanged. export G4UI_USE_QT=0 or export G4UI_USE_QT=false does not do what you intend to do. In fact, you can set G4UI_USE_QT to any value. It will take effect as long as it is not empty. The only way to completely get rid of it is to unset it.

If none of the environment variables is set, you can use ~/.g4session to select your UI:

qt # the first line is for all Geant4 applications
gears tcsh # just for gears

Session mode

Without any argument, gears will start an interactive session. It accepts commands you type in the UI.

You can also put a set of commands into a macro file, which can be used as an argument of gears. For example,

$ cd gears/examples/detector/visualization
$ gears RayTracer.mac # run gears in batch mode

This way, gears will run in the batch mode. It executes commands in the macro file one by one, and quit once it finishes.

How to contribute

Please fork GEARS on GitHub. Run the following to get a local copy of the forked repository and link it to the original GEARS repository:

$ git clone # get forked repository
$ git remote add upstream # link to original repository
$ git remote -v # run a check

Run the following to keep your local repository updated with the original GEARS repository:

$ git fetch upstream # updates are saved in a new branch upstream/master
$ git merge upstream/master # merge 2 branches: upstream/master and master

If the merge is successful, run git push to update your forked GEARS repository on GitHub.

You can initiate a pull request on GitHub if you’d like to have your update being absorbed in the original GEARS repository.

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.


Two spaces instead of a tab are used to indent a line in to insure a consistent appearance in different text editors, and to avoid wasting space in font of deeply nested code blocks. The following mode lines are added to the end of to insure that in Vim and Emacs:

// -*- C++; indent-tabs-mode:nil; tab-width:2 -*-
// vim: ft=cpp:ts=2:sts=2:sw=2:et