GEMC, the GEant Monte-Carlo, is a database-driven Geant4 application for detector and radiation-transport simulations. It keeps detector descriptions outside the compiled C++ application:
- users builds setups in Python
- GEMC loads those definitions at run time and executes the Geant4 simulation pipeline
The goal is to make Geant4-based simulation accessible to users who want to prototype detector systems without writing a custom Geant4 application, while still preserving C++ extension points for advanced detector response and output workflows.
- Python-first detector definition through
pygemc - Geometry and material storage in SQLite or ASCII databases
- Geometry imports from databases, GDML, and CAD meshes
- Run-number and geometry variation support for detector configurations
- Built-in sensitive detector digitizations:
flux,gPhotonDetector,dosimeter, andparticle_counter - Dynamic C++ plugin infrastructure for custom digitization, fields, generators, and output streamers
- Event generation from command-line/YAML particle definitions and Lund files
- Output streamers for ASCII, CSV, JSON, JLAB SRO, and optional ROOT output
- Magnetic-field support, including a built-in multipole field plugin and ascii maps
- Interactive Geant4/Qt visualization and off-screen image generation
- PyVista geometry preview, interactive Qt display, and VTK.js export
- Python analyzer for plotting CSV and ROOT output
- Meson-based C++ build with CI-tested Docker images for Linux
amd64andarm64
The fastest way to try GEMC is through the hosted examples:
A minimal local workflow that creates a counter detector and runs 1000 events throught it:
gemc-system-template -s counter
cd counter
./counter.py
gemc counter.yaml -n=1000
gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50The template command creates a counter system,
the Python script builds the geometry and stores it in a SQLite file gemc.db,
gemc runs the simulation, and gemc-analyzer plots a variable from the CSV output.
For installation instructions see the installation guide
Detector systems are build and written to databases using pygemc.
An example of definiting a sensitive flux box:
from pygemc import GVolume, autogeometry
cfg = autogeometry("examples", "counter")
flux = GVolume("flux_box")
flux.description = "air flux box"
flux.make_box(40.0, 40.0, 2.0)
flux.set_position(0, 0, 100)
flux.material = "G4_AIR"
flux.color = "3399FF"
flux.digitization = "flux"
flux.set_identifier("box", 2)
flux.publish(cfg)Geometry scripts can write SQLite or ASCII databases, display geometry with PyVista, or export VTK.js files:
./counter.py --factory sqlite
./counter.py -pv
./counter.py -pvvtk counter -pvz 0.25PyVista is part of the normal GEMC geometry workflow. It lets users inspect detector geometry before running Geant4, export portable VTK.js scenes for documentation, and catch placement or rotation mistakes while editing Python geometry scripts. Some examples:
 Geant4 basic/b2 |
 Materials |
 Scintillator Barrel |
 CLAS12 DC |
Open the linked interactive PyVista scenes generated from the GEMC examples.
GEMC is configured with YAML files and equivalent command-line options. A compact steering file can define the run number, event count, generator, geometry systems, output streamers, and world volume:
runno: 1
n: 100
nthreads: 1
gparticle:
- name: proton
p: 1500
vz: -5.0
gsystem:
- name: counter
factory: sqlite
gstreamer:
- filename: counter
format: csv
- filename: counter
format: root
root: G4Box, 15*cm, 15*cm, 15*cm, G4_AIRRun in batch mode:
gemc counter.yamlRun with the Geant4 GUI:
gemc counter.yaml -guiGenerate an off-screen Geant4 image:
gemc counter.yaml -n=10 \
-g4view="[{driver: TOOLSSG_OFFSCREEN, segsPerCircle: 200}]" \
-g4camera="[{phi: -10*deg, theta: 250*deg}]" \
-g4light="[{phi: 160*deg, theta: 120*deg}]"The output layer is plugin-based. Built-in streamer formats include:
| Format | Notes |
|---|---|
ascii |
Human-readable text output |
csv |
Per-thread CSV tables for digitized hits, true information, generated particles, and tracked generated particles |
json |
Structured event output |
root |
ROOT TTrees, available when GEMC is built with ROOT |
pygemc provides some utitlities to analyze CSV or ROOT output. For example:
gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50
gemc-analyzer out.root E --kind root --detector flux --save energy.pngFor example, after running the b2 example with
gemc b2.yaml -n=1000, the analyzer produces:
gemc-analyzer b2_t0_digitized.csv totEdep --kind csv
|
gemc-analyzer b2_t0_true_info.csv E --kind csv --data true_info
|
Contributions are welcome through normal pull requests. Before opening a pull request, run the relevant Meson tests and keep changes focused. See:
If you use GEMC in scientific work, cite:
M. Ungaro, "Geant4 Monte-Carlo (GEMC) A database-driven simulation program," EPJ Web of Conferences 295, 05005 ( 2024). https://doi.org/10.1051/epjconf/202429505005
BibTeX and additional citation formats are in CITATION.md.
GEMC is licensed under the Apache License, Version 2.0; see NOTICE for attribution and
third-party acknowledgments. The software also depends on separately licensed third-party components, including
Geant4, CLHEP, Qt, ROOT, SQLite, and Assimp.
See the project roadmap for the current development plans.