GEARS -- A Fully Run-Time Configurable Geant4 Application

The Geant4 toolkit is the standard for simulating the passage of particles through matter, but its conventional architecture often requires users to modify and recompile C++ code to alter fundamental simulation parameters such as geometry, physics list, and primary particle source. This architectural constraint introduces significant friction for new users and slows down the experimental iteration cycle. This paper introduces GEARS (Geant4 Example Application with Rich features yet Small footprint), a universally applicable Geant4 application that fundamentally addresses this issue. GEARS achieves complete simulation configurability without C++ recompilation by strictly utilizing external configuration methods: Geometry is defined via simple text-based configuration, the Physics List is selected via the standard PHYSLIST environment variable, and the Primary Source is defined through the General Particle Source (GPS) macro commands. Furthermore, regarding GEARS as an application instead of a framework, key features include a flat ntuple structure with short variable names for highly efficient analysis and a solution for capturing vital initial step data. Output creation is also fully managed via run-time macro commands and volume properties. The project is distributed as a ready-to-use Docker container to eliminate compilation barriers. Through these design considerations, GEARS transforms Geant4 into a practical, ready-to-use tool, enabling users to rapidly prototype and execute simulations for diverse experiments solely through simple text configuration files, without ever needing to modify or compile the underlying C++ source code.

💡 Research Summary

The paper presents GEARS (Geant4 Example Application with Rich features yet Small footprint), a minimalist yet fully functional Geant4‑based Monte‑Carlo simulation tool that eliminates the need for any C++ source modification or recompilation. The entire application resides in a single C++ file of roughly 555 lines (about 300 lines dedicated to an optional optical‑properties extension), and all experiment‑specific definitions are supplied at run time through external configuration files and macro commands.

Geometry can be described either by standard GDML files or by a very simple plain‑text format (".tg") that resembles Markdown. The latter allows users to define volumes with one‑line commands such as “:volume hall BOX 5m 5m 5*m G4_AIR”. During the initialization phase Geant4 parses the text file and builds the same internal C++ objects as a hand‑coded detector, so there is no measurable performance penalty during the actual simulation. The text format is deliberately kept hierarchical‑free, making it easy to generate programmatically with Python or shell scripts for large, complex detector models. GEARS also provides macro commands to import and export geometry, effectively acting as a conversion utility between GDML and the simple text format.

Physics list selection is handled exclusively through the environment variable PHYSLIST, a feature already supported by Geant4. If the variable is unset, the default list FTFP_BERT is used; otherwise any validated reference list (e.g., QGSP_BERT) can be chosen without recompilation. Individual processes can be toggled on or off with the usual Geant4 macro commands (/physics_list/factory/addXXX, /process/activate, etc.). A dedicated macro (/grdm/setTimeWindow) enables event separation for radioactive decay chains, allowing users to split a decay chain into separate events when the daughter’s decay time exceeds a user‑defined window—crucial for delayed‑coincidence studies.

The primary particle source is defined entirely through the General Particle Source (GPS) macro language. Users can specify particle type, energy spectrum, spatial distribution, and timing in a GPS macro file, enabling rapid parameter sweeps and reproducible source definitions without touching C++ code.

Output data are stored in a flat ROOT ntuple with short variable names, optimized for fast analysis via TTree::Draw(). Initial step information (first interaction point, time, energy) can be turned on or off through macro options, which is especially useful for optical simulations where the first photon interaction is of interest.

From a software‑engineering perspective, GEARS deliberately avoids namespaces, complex directory hierarchies, and multiple separate header/source files. It uses multiple inheritance (e.g., Detector inherits from both G4VUserDetectorConstruction and G4UImessenger) to combine geometry construction with custom macro handling, thereby reducing the total number of classes and source lines. Build is performed with CMake; the process is fast because only one source file is compiled. Post‑build scripts (gears.sh for Unix‑like systems, gears.bat for Windows) automatically adjust the user’s PATH, relocate the executable to the project root, and set required Geant4 environment variables, eliminating the typical “where is the binary?” confusion for newcomers.

Distribution is further simplified by providing a ready‑to‑run Docker image that contains the compiled executable, all required Geant4 libraries, and the helper scripts. This removes any platform‑specific installation hurdles and makes the tool instantly usable on any system with Docker installed.

In summary, GEARS transforms Geant4 from a development framework that traditionally demands C++ coding expertise into a ready‑to‑use application. By moving all experiment‑specific configuration to external files and macros, it dramatically lowers the learning curve, accelerates the iteration cycle, and makes Monte‑Carlo simulation accessible to beginners, educators, and small research groups. Limitations remain for cases that require custom physics models or deep extensions, which still necessitate C++ changes, but for the vast majority of standard detector simulations GEARS offers a compelling, highly portable, and efficient solution.