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:

• Python API to create geometry and materials
• Geometry imports from ASCII, SQLite, GDML, and CAD mesh files
• Built-in sensitive detectors: flux, dosimeter, particle_counter, and gPhotonDetector
• Output formats: ASCII, CSV, JSON, and ROOT
• Built-in Python analyzer module for reading and plotting simulation output
• pyvista geometry visualization
• Geometry variations and run-number-dependent configurations
• CI-tested builds and Docker deployment

Try GEMC

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

	Creates a system with a simple detector and a target
	Reproduces the Geant4 basic B1 example
	Reproduces the Geant4 basic B2 example
	Imports STL organ meshes with the CAD factory and records dose per organ
	Demonstrates Geant4 built-in materials, custom compositions, and optical properties
	48 trapezoidal scintillator paddles tiling a cylindrical barrel using distribute_on_circle
	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

Interactive 3D Gallery

Rotate the camera with the mouse wheel or use the arrow keys within each thumbnail. Click on the title link for the documentation.

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.

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:

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.

Latest News

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

Tests
Sanitizer
Image Deploy
Docker Hub
Binary Tarballs
CodeQL
Doxygen
Nightly Release
Homepage

pygemc

Nightly Dev Release
Publish to PyPI
Tests
PyPI	[][PyPI]

Reference

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

M. Ungaro and the CLAS Collaboration, “The CLAS12 Geant4 simulation,” Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment 959, 163422 (2020). https://doi.org/10.1016/j.nima.2020.163422

BibTeX:

@article{UNGARO2020163422,
  title = {The CLAS12 Geant4 simulation},
  journal = {Nuclear Instruments and Methods in Physics Research Section A: Accelerators,
             Spectrometers, Detectors and Associated Equipment},
  volume = {959},
  pages = {163422},
  year = {2020},
  issn = {0168-9002},
  doi = {https://doi.org/10.1016/j.nima.2020.163422},
  url = {https://www.sciencedirect.com/science/article/pii/S0168900220300279},
  author = {M. Ungaro and {CLAS Collaboration}},
  keywords = {Geant4, GEMC, Simulation, Software, Database, Monte Carlo, CAD, STL, GDML, MYSQL, C++}
}

Bibitem:

\bibitem{UNGARO2020163422}
M. Ungaro and the CLAS Collaboration,
\newblock The CLAS12 Geant4 simulation.
\newblock Nuclear Instruments and Methods in Physics Research Section A \textbf{959}, 163422 (2020).
\newblock \doi{10.1016/j.nima.2020.163422}

Source Code and License

The GEMC source code is distributed under the Apache License, Version 2.0.