GEMC Logo gemc GEANT4 SIMULATION FRAMEWORK

This site documents GEMC version 3 and later. For CLAS12 simulations, use the GEMC2 clas12Tags repository.


Database-driven Geant4 simulations with a Python API

GEMC is a Python-friendly wrapper around Geant4 that eliminates the C++/Geant4 learning curve. Users build complete detector systems in Python: geometry, materials, and digitization. The API automatically populates the databases that GEMC uses to run the full simulation pipeline.

Highlights:



Try GEMC

No installation needed. Click a badge to launch a live JupyterLab session in your browser:

MyBinder Codespaces Example
Quickstart Quickstart Codespaces Creates a system with a simple detector and a target
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


Container image

For a local or HPC JupyterLab session, use the prebuilt multi-architecture image:

# Docker
docker run --rm -p 8888:8888 ghcr.io/gemc/binder-tutorials:latest

# Apptainer
apptainer pull gemc-binder-tutorials.sif docker://ghcr.io/gemc/binder-tutorials:latest
apptainer exec gemc-binder-tutorials.sif jupyter lab --ip=0.0.0.0 --no-browser





pygemc: the Python API

The GEMC Python API, pygemc, provides geometry and material database builders, pyvista geometry visualization, gemc-system-template, and gemc-analyzer. The analyzer can read GEMC CSV and ROOT output and plot histograms from selected variables.

Python API example
The code fills the database with the world volume, a liquid hydrogen target, and a flux plane.
The `pyvista` option gives immediate geometry visualization.
In the GEMC simulation, hits are created from particles generated by a beam of protons impinging on the liquid hydrogen target.
The total deposited energy is plotted with the `analyzer` module.

The excerpt below defines the sensitive flux plane downstream of the target. GEMC records a flux hit each time a generated track crosses this volume.

# Place a thin scoring plane downstream of the target.
flux_z = 50
flux_dx = 1
flux_dim = world_size * 0.8

# Define the plane as an air box inside the world volume.
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)

# Turn the volume into a GEMC flux detector and tag its output column.
gvolume.digitization = "flux"
gvolume.set_identifier("flux_plane", 1)
gvolume.publish(cfg)



Databases

Detector definitions are stored in databases. A typical workflow has one user-authored step:

Database-driven architecture
Users define detector databases through the Python API (Step 1). GEMC then builds Geant4 objects, transports particles to create hits, applies digitization and electronics emulation, and streams the output data (Steps 2–5).


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 reused across experiments, with configuration changes such as component shifts, material changes, or volume additions and removals. GEMC supports these geometry versions using variation strings and/or run numbers to adapt to different simulation setups.

Python API example
The animation shows two variations of the CLAS12 Central Detector. The geometries are identical except for the target position. Users select them with a variation string or run number in the configuration file or command-line options.



Latest News

Release

GEMC 0.2

This announcement corresponds to the 0.2 GEMC release.

News

GEMC Analyzer is available

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

All news · RSS Feed



Continuous Integration

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

gemc

Deployment and Testing CI
Sanitizer Sanitize
Binary Tarballs Binary Tarballs
CodeQL CodeQL
Doxygen Docs
Nightly Release Nightly
Homepage Site

pygemc

Nightly Dev Release Nightly Dev Release
Publish to PyPI Publish PyPI
Tests pygemc tests
PyPI pygemc PyPI



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 is distributed under an open source license.