pygemc

pygemc is the Python API used by GEMC to define detector geometry, materials, optical properties, mirrors, geometry variations, 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 as part of the GEMC source build and can also be developed as a standalone Python project.

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 active G4Transform3D placement or passive GEMC2-compatible placement
• 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-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

Choose the installation path based on what you need:

• Use PyPI for Python geometry building, PyVista previews, and output analysis without the compiled gemc simulator.
• Build GEMC from source for the full Geant4 simulation executable and the bundled pygemc Python environment.
• Use the development install when you are editing pygemc itself.

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

Stable PyPI Install

Install pygemc from PyPI with:

python -m pip install pygemc

Update an existing PyPI installation with:

python -m pip install --upgrade pygemc

Optional ROOT-file analysis dependencies:

python -m pip install "pygemc[root]"

Update with optional ROOT-file analysis dependencies enabled:

python -m pip install --upgrade "pygemc[root]"

Development Snapshot

Install the moving GitHub dev prerelease with:

python -m pip install "pygemc @ git+https://github.com/gemc/pygemc.git@dev"

Update the GitHub dev snapshot with:

python -m pip install --upgrade --force-reinstall "pygemc @ git+https://github.com/gemc/pygemc.git@dev"

Use this when you need the latest development version before the next stable PyPI release.

Local Clone Development Install

Use this when you are editing pygemc from a local clone:

git clone https://github.com/gemc/pygemc.git
cd pygemc
python -m pip install -e ".[dev]"

Optional ROOT-file analysis dependencies for local development:

python -m pip install -e ".[dev,root]"

The package requires Python 3.10 or newer and depends on NumPy, VTK, PyVista, PyVistaQt, PyQt6, pandas, and matplotlib.

Installed with GEMC

When GEMC is built from source, the parent Meson project installs pygemc into the GEMC Python environment at <prefix>/python_env. Activate that environment before running any pygemc tools:

source <prefix>/python_env/bin/activate

After activation, the simulator and Python tools are available:

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

All subsequent python and tool invocations in the shell session will use the GEMC environment's interpreter automatically. To deactivate, run deactivate.

Wiring a local pygemc clone into the GEMC build

By default the GEMC Meson build fetches pygemc via subprojects/pygemc.wrap into subprojects/pygemc/. That copy is independent of any local clone, so edits to the clone are not picked up by meson install until the wrap is re-fetched.

To make meson install always use your local clone, replace the fetched directory with a symlink once:

rm -rf /path/to/gemc/src/subprojects/pygemc
ln -s /path/to/pygemc /path/to/gemc/src/subprojects/pygemc

Meson resolves a plain directory before the wrap file, so it uses the symlink transparently. Every subsequent meson install picks up the latest changes from the local clone with no extra steps.

Quickstart

Create a detector template:

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

The generated system contains:

File	Purpose
counter.py	Main geometry-builder script
geometry.py	Example volumes, including a flux detector
materials.py	Example methane-gas material
counter.yaml	GEMC steering card
README.md	Placeholder notes for the generated detector

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 --kind csv --bins 50

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:

Value	Meaning
active	Default; uses G4Transform3D(rotation, translation)
passive	Uses G4PVPlacement(rotation, translation, ...), matching GEMC2/clas12Tags conventions

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:

Option	Purpose
-f, --factory	Select sqlite or ascii output
-v, --variation	Select the geometry variation
-r, --run	Select the run number
-sql, --dbhost	Select the SQLite file path
-pv	Show a PyVista window
-pvb	Show a PyVistaQt background plotter
-pvvtk	Export a VTK.js .vtksz scene
-pvz	Set the VTK.js export zoom
-pvbg	Set the PyVista background color as a name, hex string, or r g b triple
-pvbgt	Set the optional PyVista top gradient color; use none for a flat background

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	Simple Flux

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

gemc-system-template

Generate a detector skeleton:

gemc-system-template -s counter

List supported solid snippets:

gemc-system-template -sl

Print a volume-construction snippet:

gemc-system-template -gv G4Box

Write a snippet to a file:

gemc-system-template -gv G4Tubs -write_to geometry.py -geo_sub build_tube

gemc-sqlite

Create a new empty SQLite database with the GEMC geometry and materials schema:

gemc-sqlite -n mydetector.sqlite

If the file already exists it is removed and recreated. The resulting database contains two tables — geometry and materials — with all columns expected by GEMC, ready to be populated by a geometry script using factory: sqlite.

Open an existing database and list its volumes:

gemc-sqlite -sql mydetector.sqlite -sv

List materials:

gemc-sqlite -sql mydetector.sqlite -sm

Filter by experiment, variation, system, or run number:

gemc-sqlite -sql mydetector.sqlite -sv -ef examples -vf default -sf counter -rf 1

gemc-analyzer

Summarize an output file:

gemc-analyzer counter_t0_digitized.csv --kind csv

Plot a variable:

gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50

Plot hit positions in the y-vs-x plane:

gemc-analyzer counter_t0_true_info.csv --kind csv --data true_info --plot yvsx --xlim -20 20 --ylim -20 20

Save a figure without opening a GUI:

gemc-analyzer out.root E --kind root --detector flux --save energy.png

Analyzer inputs:

• CSV output files or CSV root names
• ROOT files when pygemc[root] dependencies are installed
• Digitized and true-information data streams

Tests

Run the standalone Python tests:

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

The tests cover CLI behavior 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

Path	Purpose
src/pygemc/api/	Geometry, materials, units, SQLite output, PyVista support, and templates
src/pygemc/analyzer/	CSV/ROOT readers, plotting, and analyzer CLI
tests/	Standalone pytest suite
releases/	Release notes
pyproject.toml	Python packaging metadata and console scripts
meson.build	Meson subproject integration used by GEMC

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 distributed under the GEMC Software License, the same license used by the main GEMC source repository. See LICENSE.md.