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.

Features

• Single small C++ file, easy to manage, fast to compile (a few second on a regular PC)
• Easy switching between well maintained Geant4 reference physics lists without recompilation
  • Individual processes can be turned on/off without recompilation
  • Fast implementation of optical properties without recompilation
  • Optional radioactive decay simulation with the possibility to save the parent and daughter decays into different events if the later happens after a user specified time interval
• Frequently used source spectra (AmBe, Am-241, etc.) in addition to GPS
• Output in multiple data format
  • ROOT TTree format (default, no ROOT installation is needed)
    • Build-in data compression, well suitable for large data processing
    • Fast access to independent data members
    • Flat tree (no nested branches or arrays) with short leaf names
      • Easy to use in TTree::Draw
      • No need to load extra library to open
  • HDF5, universal data format, easy to read by different tools
  • CSV or XML, Human readable ASCII file, capable of dealing with multiple dimensional arrays
• Record information of step 0 (initStep), which is not available through G4UserSteppingAction
• simple text or GDML geometry I/O
  • Fast implementation of detector geometry without C++ programming
  • Create/Change geometry without re-compilation
  • Turn off data saving in a volume by assigning it a non-positive copy number
  • Turn any volume to a sensitive detector by adding "(S)" in its name
  • Assign optical properties in Geant4 plain text geometry description, which is not available in the official Geant4 release.
• Doxygen documentation
• Many sample macros and geometry descriptions for feature demonstration

Getting started

Prerequisites

• Geant4, version above 9 is requested due to the following inconvenience in version 9: http://hypernews.slac.stanford.edu/HyperNews/geant4/get/hadronprocess/1242.html.
• (Optional) Xerces-C++, to use or export detector geometries in GDML format.
• (Optional) HDF5, to save simulation results in HDF5 format.

After an successful installation of Geant4, there should be a command line tool geant4-config available, which can be used to query some basic information of your Geant4 installation. GEARS relies on it to find the installed Geant4 libraries and header files.Please run the following command to make sure that you have it available:

$ which geant4-config

If you get a null result, please contact the person who installed Geant4 in your system for help.

Get GEARS

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 gears-master.zip # 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 https://github.com/jintonic/gears.git

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. An easy way to check if there is any local change that may block git pull is:

$ git status

Compilation

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

$ cd /path/to/gears
$ make # compile gears.cc to generate executable: gears
$ source gears.sh # setup environment for using gears
$ gears # run gears in current terminal

You should also add the source gears.sh line to your ~/.bashrc so that you can use gears in any newly opened terminal. For Mac users, you need to source ~/.bashrc in your ~/.bash_profile in addition. Please check this article for explanation.

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 [email protected]:yourGitHubAccount/gears.git # get forked repository
$ git remote add upstream [email protected]:jintonic/gears.git # 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.

Indentation

Two spaces instead of a tab are used to indent a line in gears.cc to insure a consistent appearance in different text editors, and to avoid wasting space in front of deeply nested code blocks. The following mode lines are added to the end of gears.cc 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

To-do's

• examples
  • add an example to show how QE can be implemented
  • add an example to show how one can use uproot to load ROOT file
  • add examples to show how one can distribute source in a volume or surface
• installation
  • an executable for Windows