This site refers to the latest GEMC project (version 3 and above). For CLAS12 simulations refer to this page.

GEMC Logo gemc GEANT4 SIMULATION FRAMEWORK


A database-driven Geant4 simulation application with Python geometry workflows

GEMC is a Python-friendly wrapper around Geant4 that eliminates the C++/Geant4 learning curve. Users define geometry in Python, store it in a database, and GEMC handles the full simulation pipeline.

The goal is to lower the entry barrier for Geant4-based simulations, especially for users who want to prototype detector or radiation-transport setups without writing C++ code.

Highlights:

  • Python API to create geometry and materials
  • ASCII, SQLite GDML, CAD meshes volume imports
  • Built-in dosimeter, flux, particle_counter sensitive types
  • ASCII, CSV, JSON, ROOT output formats
  • pyvista geometry visualization
  • Geometry variations and run-number-dependent configurations
  • CI-tested builds and Docker deployment

Latest News

News

GEMC Analyzer is available

GEMC now includes analyzer, a small Python package for reading GEMC output files and plotting variables by name.

News

Roadmap to GEMC 0.2

New features, improvements, and issue resolutions planned for the next release.

All news · RSS Feed



Try GEMC in Your Browser

No installation needed. Click the badge to launch a live JupyterLab session:

quickstart codespaces Creates a system with a simple detector and a target

Other examples:

Binder Codespaces Example
Simple Flux Simple Flux Codespaces Record track information using the flux digitization
b1 b1 Codespaces Reproduces the Geant4 basic B1 example
b2 b2 Codespaces Reproduces the Geant4 basic B2 example
Materials Materials Codespaces Demonstrates Geant4 built-in materials, custom compositions, and optical properties
Cherenkov Cherenkov Codespaces Showcases the activation of the Cherenkov radiation in a GEMC detector



Python API

Python is used to create and fill databases with the geometry, materials and mirrors definitions. GEMC uses these databases to create the Geant4 world and does not need to be re-compiled when the geometry is changed. The API supports pyvista visualization of the geometry.

Python API example
The code that fills the database with the world volume, a liquid hydrogen target and a flux plane.
The pyvista option allows immediate visualization of the geometry.
In the GEMC simulation, hits are created from particles generated by a beam of protons impinging on the liquid hydrogen target.
flux_z = 50
flux_dx = 1
flux_dim = world_size * 0.8
gvolume = GVolume("FluxPlane")
gvolume.mother = "root"
gvolume.description = "Flux Scoring Plane"
gvolume.make_box(flux_dim * 0.5, flux_dim * 0.5, flux_dx * 0.5)
gvolume.material = "G4_AIR"
gvolume.color = "FAFAD2"
gvolume.set_position(0, 0, flux_z)
gvolume.digitization = "flux"
gvolume.set_identifier("flux_plane", 1)
gvolume.publish(cfg)

The code used to create the flux plane shown above, showcasing the Python API.



Databases

Detector definitions are stored in databases. A typical workflow looks like this:

Database-driven architecture
Using the Python API, users fill databases with detector definitions (Step 1). The rest of the steps are executed by GEMC.


Note

Running simulations does not require previous knowledge of C++ or Geant4. Basic Python knowledge helps organize complex setups. Users can also define their own hardware emulation routines - in this case basic C++ knowledge helps for complex digitizations.



Geometry Variations

A detector can be re-used in multiple experiments, with configuration changes such as component shifts, changes of materials, addition or removal of certain volumes. GEMC supports these geometry versions using variations and/or run numbers to adapt to different simulation setups

Python API example
In the above animation two variations of the CLAS12 Central Detector are shown. The geometries are identical except for the position of the target. They can be selected by specifying a variation string or a run number in the configuration file or command line options.



Continuous Integration

GEMC is built, tested, and deployed as Docker images by GitHub CI on several platforms and on both arm64 and amd64 architectures.

Deployment and Testing CI
Doxygen Docs
Nightly Release Nightly
Homepage Site
Sanitizer Sanitize
Code QL CodeQL



Reference

Please make sure to cite the following paper if you use GEMC:

| M. Ungaro, Geant4 Monte-Carlo (GEMC) A database-driven simulation program, *EPJ Web of Conferences* 295, 05005 ( 2024) |

Bibtex:

@INPROCEEDINGS{2024EPJWC.29505005U,
author = { {Ungaro}, Maurizio,
 title = "{Geant4 Monte-Carlo (GEMC) A database-driven simulation program}",
 booktitle = {European Physical Journal Web of Conferences},
 year = 2024,
 series = {European Physical Journal Web of Conferences},
 volume = {295},
 month = may,
 eid = {05005},
 pages = {05005},
 doi = {10.1051/epjconf/202429505005},
 adsurl = {https://ui.adsabs.harvard.edu/abs/2024EPJWC.29505005U},
 adsnote = {Provided by the SAO/NASA Astrophysics Data System} }
}

Bibitem:

\bibitem{2024EPJWC.29505005U}
{Ungaro}, M.: Geant4 Monte-Carlo (GEMC) A database-driven simulation program.
\newblock European Physical Journal Web of Conferences \textbf{295}, 05005 (2024).
\newblock \doi{10.1051/epjconf/202429505005}



Source Code and License

The GEMC source code on GitHub is distributed under an open source license.