Skip to content

README.md

Latest commit

 

History

History
399 lines (317 loc) · 14.5 KB

README.md

File metadata and controls

399 lines (317 loc) · 14.5 KB
Raw

GEMC

Quality Deploy Docs
Test
Sanitize
CodeQL
Thread Scaling
Valgrind Profile 		Deploy
Binary Tarballs
Release Tarballs
macOS Tarball
Nightly Dev Release
pygemc PyPI
Docker Pulls 		GEMC documentation
Doxygen

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.

GEMC architecture


Highlights

  • Python-first detector definitions through pygemc
  • Geometry and material storage in SQLite or ASCII databases
  • Geometry imports from GDML, CAD meshes
  • Run-number and geometry variations
  • Built-in sensitive types: flux, gPhotonDetector, dosimeter, particle_counter
  • C++ plugin infrastructure for custom digitization, fields, generators, and output streamers
  • Event generation from command-line/YAML particle definitions and LUND files
  • Supported output formats: ASCII, CSV, JSON, ROOT
  • Magnetic-field support, including multipoles field and ascii maps
  • Interactive Geant4/Qt visualization and off-screen image generation
  • PyVista geometry preview, VTK export
  • Python analyzer CSV and ROOT formats
  • Meson-based C++ build with CI-tested Docker images for Linux amd64 and arm64

Quickstart

The fastest way to try GEMC is through the 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 50

The 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.


Installation

For installation instructions see the installation guide


pygemc

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.25

PyVista Visualization

PyVista 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:

B2 PyVista
Geant4 basic/b2 		Materials PyVista
Materials
Scintillator Barrel PyVista
Scintillator Barrel 		Materials PyVista
CLAS12 DC
Boolean Solids PyVista
Boolean Solids 		CAD Import PyVista
CAD Import

Open the linked interactive PyVista scenes generated from the GEMC examples.


Running Simulations

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_AIR

Run in batch mode:

gemc counter.yaml

Run with the Geant4 GUI:

gemc counter.yaml -gui

Execute a Geant4 macro text file (upcoming in the next release):

gemc counter.yaml -geant4_macro=run.mac
gemc counter.yaml -gui -geant4_macro=vis.mac

The equivalent YAML setting is geant4_macro: run.mac. GEMC executes the macro after initialization and visualization setup, before entering the GUI or interactive terminal. Relative paths use the working directory; Geant4 handles comments, aliases, and nested /control/execute commands. Missing files and failed commands produce a nonzero exit status.

In batch mode, the macro controls event generation with commands such as /run/beamOn 100; GEMC does not automatically run the -n events or the -run_weights allocation afterward. Detector conditions are prepared using -run. A visualization-only macro generates no events unless it contains a beam-on command. Without geant4_macro, the usual event processing is unchanged.

Generate 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}]"

Output and Analysis

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

Upcoming in the next release, track provenance can be enabled for event output:

gemc counter.yaml -save_original_track
gemc counter.yaml -save_all_ancestors

-save_original_track populates otid in each true-information hit. -save_all_ancestors also enables original-track IDs and writes a deduplicated ancestors bank containing each hit-producing track and its complete parent chain. CSV output uses a separate _ancestors.csv file; ASCII, JSON, and ROOT include the bank in their event output.

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.png

For 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

Documentation


Contributing

Contributions are welcome through normal pull requests. Before opening a pull request, run the relevant Meson tests and keep changes focused. See:


Citation

If you use GEMC in scientific work, cite:

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

BibTeX and additional citation formats are in CITATION.md.


License

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.


Roadmap

See the project roadmap for the current development plans.