README.md

Note The latest GEARS require Geant4.11. If you are still using Geant4.10, please download v1.5.1 of GEARS from the Release page.

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 550 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
      • Can be easily analyzed in Python through Uproot
  • 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
  • Syntax highlighting of the simple text geometry description files in Emacs, Vim, Micro, and Sublime Text
• Creating 3D mesh to record and visualize physical variables in it without any change of the C++ code
• Doxygen documentation
• Many simple tutorials to demonstrate the usage of Geant4

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

• tutorials
  • add tutorials to show how one can distribute source in a volume or surface