[Paper Review] MinGLE: A Minimalist, Configurable, and Pedagogical Geant4 Application Template

Jing Liu|arXiv (Cornell University)|Jan 13, 2026

Scientific Computing and Data Management0 citations

TL;DR

MinGLE provides a minimalist, fully functional Geant4 simulation template in under 70 C++ lines, with a pedagogical, Git-driven, stepwise development roadmap to teach Geant4 concepts from UI to physics and geometry.

ABSTRACT

The Geant4 toolkit is the leading software for the simulation of particle transport through matter, widely used in nuclear physics, high-energy physics, and medical physics. However, the initial learning curve for new developers can be steep, often due to the complexity and experiment-specific nature of many introductory examples. This paper introduces MinGLE (Mini Geant4 Learning Example), a dedicated application template designed to be a universal, flexible, and educational starting point for Geant4 projects. MinGLE achieves a complete, functional simulation kernel using fewer than 70 lines of core C++ code. This minimalism is realized by leveraging contemporary Geant4 features, including factory classes for run management and physics, and the Text Geometry format for detector definition. Furthermore, MinGLE employs a unique pedagogical structure, using Git tags to document the incremental development of eleven core Geant4 components, with each tagged version being fully compilable, executable, and testable, providing a clear, step-by-step learning resource.

Motivation & Objective

• Lower the entry barrier to Geant4 by providing a minimal, extensible application core.
• Offer a step-by-step learning path that builds Geant4 components incrementally through Git branches and tags.
• Enable runtime configurability via text geometry and macro commands to reduce C++ boilerplate.
• Demonstrate how modern Geant4 factory classes and standard interfaces can compose a complete simulation kernel.
• Provide deployment aids (CMake, Docker) and tooling (compile commands) to streamline learning and development.

Proposed method

• Present a single-file mingle.cc containing core Geant4 components and showing how to load detector geometry from a text file detector.tg.
• Use Geant4 factory classes and external configuration to maximize configurability while keeping C++ code minimal.
• Adopt a ten-stage Git-based roadmap (branches and tags) to incrementally introduce UI, batch mode, run manager, physics lists, detector definitions, visualization, GPS, scoring, ntuples, and magnetic fields.
• Incorporate runtime macro commands and a text-geometry detector description to decouple geometry from code.
• Provide cross-platform build via CMake, optional Docker image, and JSON compilation database for IDE integration.

Figure 1: Screenshot of the Geant4 GUI with a customized menu, visualized detector geometry, and accumulated particle trajectories.

Experimental results

Research questions

• RQ1 Can a Geant4 application be taught and learned incrementally using a minimal core plus text-based configuration?
• RQ2 How does a Git-based, stage-by-stage roadmap affect learning, code quality, and debugging in Geant4 development?
• RQ3 What minimal set of components is required to achieve a functional Geant4 simulation kernel suitable for teaching?
• RQ4 Does text geometry loading (detector.tg) effectively decouple geometry from C++ and accelerate experimentation?
• RQ5 Can the template be compiled and run across Windows, macOS, and Linux with a simple CMake workflow and optional Docker image?

Key findings

• MinGLE delivers a complete Geant4 simulation kernel in under 70 lines of C++ in mingle.cc.
• A ten-stage Git-based roadmap isolates concepts, enabling incremental learning and easy rollback to stable milestones (tags).
• Detector geometry can be defined in a text file (detector.tg) and loaded via G4tgbVolumeMgr, decoupling geometry from code.
• The template demonstrates modern Geant4 components (run manager, physics lists via G4PhysListFactory, UI, visualization, GPS) through minimal additions per stage.
• Build and deployment are cross-platform via CMake, with optional Docker image and support for JSON compile commands to aid IDE integration.
• The approach emphasizes hands-on, just-in-time learning by evolving the codebase with minimal boilerplate at each stage.

Figure 2: Dose distribution behind Shape2 recorded by the scoring manager shown as 2D histograms in color.