GEMC is now developed along the standalone pygemc Python package, the engine containing the Python API and analysis tools.

This version includes:

  • GUI generator tabs, theme-aware display controls, and improved geometry-tree inspection
  • Optical photon detection
  • External plugin discovery
  • Linux binary gemc tarballs from CI, with smoke tests and Geant4 data setup helpers
  • Fixes in gstreamer output, geometry reloads, batch screenshots, event handling, and JSON/CSV output

See also the Project Roadmap


Release notes

  • The Python API and analyzer have moved into pygemc. GEMC examples and tests now use that package, while normal Python workflows only need the gemc executable in PATH.
  • gparticle steering cards now attach units directly to values, such as p: 4*GeV, theta: 23*deg, and vz: -10*cm. Plain numbers are still accepted with the historical MeV / deg / cm defaults.
  • External detector and streamer plugins are easier to deploy. GEMC now searches GEMC_PLUGIN_PATH and -plugin_path, and plugins can register detector-specific options before command-line parsing.
  • The GUI received a broad usability pass: generator controls are available in tabs, the geometry-tree right panel is cleaner, volume inspection opens in a dedicated viewer, and display toggles follow the active Qt theme.
  • Optical workflows are more visible. Optical photon trajectories render in cyan, and the Cherenkov example now includes y-vs-x photon hit-position maps generated by the analyzer.
  • The ROOT gstreamer plugin is isolated from the main executable, so ROOT libraries are no longer required to start gemc unless ROOT output is requested.
  • CI now produces Linux binary tarballs for development releases. The archives include the installed executable, support files, smoke tests, gemc.env, and a generated Geant4 data installer.
  • Several correctness issues were fixed in run weighting, gstreamer output, CSV/JSON streamers, multipole unit parsing, geometry reloads, offscreen screenshots, and event-action handling.


New developments

  • pygemc is now the place to build detector geometry in Python, create GEMC SQLite databases, preview volumes with PyVista, export VTK.js scenes for documentation, and analyze CSV or ROOT output.
  • The analyzer can now make y-vs-x hit-position maps with plot_y_vs_x() or gemc-analyzer --plot yvsx, including coordinate selection, axis limits, and position-unit control.
  • Analyzer input handling now includes the generated-particle kinematics stream, so generated p, theta, and phi plots work without extra stream selection in common cases.
  • GVolume.distribute_on_circle() replicates volumes around a circle and can keep them radially aligned. The new scintillator_barrel example uses it to build a 48-paddle G4Trap ring.
  • GVolume.g4placement_type records whether a volume should use the active Geant4 placement convention or the passive GEMC2 / CLAS12Tags convention. This matters for ported CLAS12 detector geometry.
  • PyVista support now covers G4Trap, G4Sphere, and G4Polycone, and rendering backgrounds can be configured from the command line.
  • gemc-sqlite -n <filename> creates a new empty GEMC SQLite database with the full geometry and materials schema.
  • GConfiguration now tracks all variations used in a run, which makes multi-variation geometry generation easier to inspect.


CLAS12 systems highlights

The accompanying clas12-systems 0.1 release is the first development release of the GEMC3 CLAS12 systems repository. It establishes the repository layout and provides the first working CLAS12 detector port.

  • The DC geometry is generated in geometry_src/dc from the CLAS12 coatjava geometry service.
  • The DC digitization plugin registers its own GEMC options, including the configurable dc_timeWindow, and publishes detector-specific readout variables.
  • CLAS12 HIPO output can write detector ADC, TDC, and waveform banks from digitized GEMC hits.
  • hipo-histos provides DC validation plots and two-file comparisons with CI-friendly difference checks.
  • The repository now has top-level Meson integration for detector systems, plugins, tests, installation metadata, and local coatjava setup.
  • Geometry validation includes semantic ASCII comparisons against CLAS12Tags reference geometry.


Documentation and examples

  • Added binary-tarball installation instructions, including platform prerequisites, Geant4 data setup, and smoke-test commands.
  • Added custom GDynamicDigitization plugin documentation for detector-specific digitization modules.
  • Added documentation for structure helpers, including distribute_on_circle() and the scintillator-barrel chord-sizing formula.
  • Added the scintillator_barrel example with an interactive VTK.js viewer and analyzer plots.
  • Updated the Cherenkov documentation with neutral radiator variation names and a shorter one-electron analyzer workflow.
  • Added analyzer plot tests for digitizing-sensitive-detector examples and Cherenkov photon hit maps.


Compatibility notes

The main user-facing steering-card change is the removal of the separate punit, aunit, and vunit fields in gparticle. Attach the unit directly to each value instead:

# before
gparticle:
  - name: e-
    p: 2300
    punit: MeV
    theta: 23.0
    aunit: deg
    vz: -10.0
    vunit: cm

# after
gparticle:
  - name: e-
    p: 2300*MeV
    theta: 23*deg
    vz: -10*cm

For CLAS12 detector geometry ported from GEMC2 or CLAS12Tags, use g4placement_type = "passive" in GVolume so Geant4 uses the same frame-rotation placement convention as the original geometry.


Supported platforms

Both x86_64 and ARM64 platforms are supported.

  • macOS: 26
  • Ubuntu: 24.04, 26.04
  • AlmaLinux: 10
  • Fedora: 44
  • Debian: 13
  • Arch Linux: latest


Dependencies

  • Geant4: 11.4.1 or higher
  • CLHEP: 2.4.6.0 or higher
  • Xerces-C: 3.2 or higher
  • Python: 3.10 or higher for pygemc


Detailed release notes