pygemc

pygemc is the Python API used by GEMC to define detector geometry, materials, optical properties, mirrors, and lightweight output-analysis workflows. It lets users build GEMC databases with Python scripts, preview geometry with PyVista, and inspect GEMC CSV or ROOT output without writing C++.

The package is installed with pip or as part of the GEMC source build. It also ships preinstalled in the GEMC Docker images on Docker Hub (and ghcr.io/gemc/src).

Features

• Python classes for GEMC geometry and material databases
• GVolume helpers for common Geant4 solids such as boxes, tubes, cones, and trapezoids
• GVolume.g4placement_type to select the G4Transform3D active or passive constructor
• GMaterial helpers for chemical formulas, fractional-mass mixtures, and optical/scintillation properties
• GConfiguration run, variation, factory, SQLite, ASCII, and PyVista configuration handling
• autogeometry() convenience setup for detector scripts
• SQLite and ASCII database output
• PyVista rendering, interactive Qt display, and VTK.js .vtksz export for geometry inspection and documentation
• gemc-system-template CLI for generating ready-to-run detector systems
• Python code snippets for supported Geant4 solid constructors
• gemc-sqlite CLI for creating and inspecting GEMC SQLite database files
• gemc-cure-mesh CLI for simplifying and repairing CAD meshes (STL/PLY/OBJ) for Geant4 tessellated solids
• gemc-analyzer CLI for summarizing and plotting GEMC CSV or ROOT output
• Unit conversion helpers for length, angle, time, and energy strings
• Pytest suite that does not require a compiled gemc binary

Installation

Stable PyPI Install

Use a Python virtual environment for direct pip installs. On macOS with Homebrew use /opt/homebrew/bin/python3 to ensure the correct interpreter is used:

/opt/homebrew/bin/python3 -m venv ~/venv/pygemc
source ~/venv/pygemc/bin/activate
python -m pip install --upgrade pip

Install pygemc from PyPI with:

python -m pip install pygemc

Optional ROOT-file analysis dependencies:

python -m pip install "pygemc[root]"

Install with GEMC

When GEMC is built from source, pygemc available in your scripts without any activation step or separate pip install and gemc and Python tools are available:

gemc -v
gemc-system-template --help
gemc-sqlite --help
gemc-analyzer --help

Quickstart

Create a detector template:

gemc-system-template -s counter
cd counter
./counter.py

The generated system contains:

Run with PyVista visualization:

./counter.py -pv

Export a VTK.js scene:

./counter.py -pvvtk counter -pvz 0.25

Use a light flat background for documentation exports:

./counter.py -pvvtk counter -pvbg "0.92 0.92 0.98" -pvbgt none

Run the generated simulation with GEMC when the compiled gemc executable is available:

gemc counter.yaml

Analyze output:

gemc-analyzer counter_t0_digitized.csv totEdep --bins 50

The quantities available to plot are the numeric columns of the loaded file, so they are only known after the data is read — they do not appear in --help. Run the analyzer with just a file name to print the summary, including row and event counts where available, plus the plottable <stream>: ... list for each stream. The explicit --list option prints the same summary:

gemc-analyzer counter_t0_digitized.csv
gemc-analyzer counter_t0_digitized.csv --list

Upcoming in the next release: true-information CSV files containing pid, opid, and the current and original momentum components expose delta_p, delta_theta, and delta_phi. Only rows whose pid matches opid enter these plots; delta_phi is wrapped to the interval [-pi, pi]. Select one particle species with --pid, for example gemc-analyzer hits_true_info.csv delta_p --pid 11.

Geometry API

Typical geometry scripts create a configuration and publish volumes/materials to it:

from pygemc import GMaterial, GVolume, autogeometry

cfg = autogeometry("examples", "counter")

gas = GMaterial("methaneGas")
gas.description = "methane gas CH4 0.000667 g/cm3"
gas.density = 0.000667
gas.addNAtoms("C", 1)
gas.addNAtoms("H", 4)
gas.publish(cfg)

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.style = 1
flux.digitization = "flux"
flux.set_identifier("box", 2)
flux.publish(cfg)

Placement convention

GVolume.g4placement_type selects which Geant4 placement convention GEMC should use for a volume:

Most new GEMC3 geometry can use the default active convention. Detector systems ported from GEMC2 that rely on frame rotations should set:

gvolume.g4placement_type = "passive"

This field is written to SQLite geometry databases. Existing SQLite databases are upgraded with the missing column when a geometry script publishes new rows.

Common command-line options accepted by geometry scripts:

PyVista Visualization

PyVista support is central to pygemc: geometry scripts can display the detector as they build it, open an interactive Qt viewer, or export a .vtksz scene that can be published in documentation.

B1	B2
Materials	Scintillator Barrel

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

GitHub README pages cannot embed .vtksz files directly, so the preview image links to the hosted VTK.js viewer.

Command-Line Tools

Tests

Run the standalone Python tests:

pytest
pytest tests/test_analyzer.py
pytest tests/test_cli.py
pytest tests/test_gconfiguration_yaml.py
pytest tests/test_geometry.py
pytest -v
pytest -k "sqlite"

The tests cover analyzer plotting, CLI behavior, YAML-driven PyVista configuration, and geometry database generation. They intentionally do not require Geant4 or a compiled gemc executable; full simulation tests live in the parent GEMC Meson build.

Project Layout

Documentation

• GEMC homepage
• Python API overview
• Quickstart
• Examples
• GEMC source repository
• CLAS12 GEMC systems repository
• Documentation website repository
• GEMC2 / CLAS12 repository

Contributing

Keep patches focused and run the relevant pytest targets before opening a pull request. If a change affects the integrated GEMC build, also run the parent repository Meson tests for the affected examples or modules.

License

pygemc is licensed under the Apache License, Version 2.0 — the same license used by the main GEMC source repository. See NOTICE for attribution.