License

See the license conditions.


Release Notes


Streaming readout requires GEMC 0.5’s SRO interfaces and experiment plugins rebuilt against the same GEMC installation. FT-Cal’s JLAB encoder belongs to clas12-systems; installing pygemc alone does not supply the native SRO implementation.

The vertex and angular examples include 11 steering cards and prepared Analyzer plots. Use GEMC 0.5 or later; the GUI plots require Qt Charts. Their batch simulations and CSV checks also work without Qt Charts.

Table of Contents



Install the Python API


pygemc is available from PyPI. Use a virtual environment for direct pip installs:

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

The optional Jupyter modules used by PyVista VTK export can be installed with:

python -m pip install "pygemc[jupyter]"

The optional ROOT-file analysis dependencies can be installed with:

python -m pip install "pygemc[root]"

PyPI does not install the gemc executable but can be used to create and visualize geometry or analyze results.


Download a precompiled binary distribution

Binary tarballs contain the gemc executable and the examples (but not pygemc). Linux builds are available for amd64 and arm64; the macOS build is native to Apple Silicon (arm64).

Make sure to check the Software Prerequisites for binary installation before unpacking the tarball.

Choose an installation directory first:

gemc_home=/path/to/gemc
mkdir -p "$gemc_home"
cd "$gemc_home"

Then, use the commands from the tab that matches your Linux distribution and CPU architecture. This will install GEMC and the Geant4 data files.

archive=gemc-dev-geant4-11.4.3-fedora-44-amd64.tar.gz
curl -L -o "$archive" "https://github.com/gemc/src/releases/download/dev/$archive"
tar -xzf "$archive" -C "$gemc_home" --strip-components=1
./install_geant4_data.sh


After installation, source the GEMC environment file. Add this line to .bashrc or .zshrc if you want it available in every shell:

source /path/to/gemc/gemc.env

Run a few checks to verify the installation:

gemc -v
test_gdynamic_plugin_load
test_gdata_event_verbose


Build from source

You will need Geant4 to build GEMC. Check the Software Prerequisites and Geant4 Installation for the GEMC build in the appendix for the complete list of requirements.


1. Obtain the source

Download the code:

Download the latest release:

git clone -c advice.detachedHead=false --branch 0.5 https://github.com/gemc/src
cd src


2. Configure the build and install GEMC

The Meson build system is used to compile and install GEMC.

The setup phase will check for the required dependencies and fetch external libraries. Here we use a build directory.

meson setup build --prefix=/path/to/install/gemc

The install phase will build and install GEMC. Here we use -q for a quiet build.

meson install -C build -q

Optionally, after installation, run meson test -C build to test the configured GEMC build.


Build Options


Post installation

Add these lines to your shell configuration file (e.g. ~/.bashrc or ~/.zshrc):

export PATH=/path/to/install/gemc/bin:/path/to/install/gemc/python_env/bin:$PATH

The second PATH entry adds the bundled Python virtual environment so that python3 resolves to the venv interpreter — making import pygemc available in your scripts.

Check the installed simulator and Python tools with:

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


CLAS12 detector systems from source

The CLAS12 detector systems (clas12-systems) 0.3 build with the same Meson flow and no longer require a pre-installed GEMC. On a bare Geant4 environment — for example a g4install Docker image — the build compiles GEMC automatically from the gemc subproject and installs it into the same prefix, so the detector geometry and plugins can be installed entirely from scratch. Only Geant4 must already be present (it is never built); GEMC resolution prefers, in order, an explicit -Duse-gemc-location=<dir>, an already-installed GEMC on PATH/pkg-config, and finally the from-source subproject.

git clone --depth=1 --branch 0.3 https://github.com/gemc/clas12-systems
cd clas12-systems
meson setup build --prefix="$PWD/install"   # builds GEMC too if none is installed
meson compile -C build
meson install -C build



Run in a Docker container

You can use Docker to run GEMC. The available images are listed below. Both arm64 and amd64 are supported (except on Arch Linux images which are amd64 only 1).

OS GEMC Version Registry address arm64 amd64
AlmaLinux 10 dev ghcr.io/gemc/src:dev-almalinux-10 true true
ArchLinux latest dev ghcr.io/gemc/src:dev-archlinux-latest false true
Debian 13 dev ghcr.io/gemc/src:dev-debian-13 true true
Fedora 44 dev ghcr.io/gemc/src:dev-fedora-44 true true
Ubuntu 24.04 dev ghcr.io/gemc/src:dev-ubuntu-24.04 true true
Ubuntu 26.04 dev ghcr.io/gemc/src:dev-ubuntu-26.04 true true

The addresses above are the Docker Hub images, published under the Docker-Sponsored Open Source program, which allows unlimited anonymous pulls. They are mirrored from the canonical GitHub Container Registry build: the two registries carry identical content and tags. To pull from GHCR instead, replace the docker.io/gemc/gemc: prefix with ghcr.io/gemc/src: and keep the same tag, for example ghcr.io/gemc/src:dev-ubuntu-24.04.

It is recommended to bind a local directory to save and store your work. For illustration, the commands below bind the container path /mywork to ~/mywork and use the image ghcr.io/gemc/src:dev-almalinux-10.

archlinux amd64 images.


Batch mode

docker run -it --rm -v ~/mywork:/mywork ghcr.io/gemc/src:dev-almalinux-10 bash


Browser graphical interface

Set these convenience variables for the interactive session. Choose your own password:

VPORTS=(-p 6080:6080 -p 5900:5900)
VNC_PASS=(-e X11VNC_PASSWORD=change-me)
VNC_BIND=(-e VNC_BIND=0.0.0.0)
GEO_FLAGS=(-e GEOMETRY=1920x1200)

docker run -it --rm -v ~/mywork:/mywork $VPORTS $VNC_BIND $VNC_PASS $GEO_FLAGS ghcr.io/gemc/src:dev-almalinux-10

Then point your browser to http://localhost:6080/vnc.html to access the graphical interface.


Run using Apptainer

Linux hosts can use apptainer (formerly singularity) to run Docker containers. You can use it with the Docker images above. It runs similarly to Docker, but the entrypoint needs to be sourced explicitly.

apptainer exec --cleanenv --bind ~/mywork:/mywork docker://ghcr.io/gemc/src:dev-almalinux-10 bash

Then:

source /usr/local/bin/docker-entrypoint.sh
gemc -v


Warning

The graphical interface, especially OpenGL windows, may not work properly in Apptainer when you connect through a remote host.


Note

Apptainer uses a default cache directory to store images. If it becomes full, set the cache and temporary directories to a location with enough disk space. For example, set sim_cache to somewhere with enough space:

	export sif_cache=/path/to/$USER/cache

then set these variables:

	export APPTAINER_CACHEDIR=$sif_cache/apptainer-cache
	export APPTAINER_TMPDIR=$sif_cache/apptainer-tmp
	export TMPDIR=$sif_cache/apptainer-tmp

and run apptainer again.




Appendix


Software Prerequisites for binary installation


Binary tarball installations need only the runtime packages required by the gemc executable and the tools used to download and unpack the archive. ROOT is intentionally not included in this list.


dnf install -y --allowerasing ca-certificates curl gzip tar expat sqlite-libs zlib \
libX11 libXext libXmu libXt mesa-libEGL mesa-libGL qt6-qtbase qt6-qtsvg qt6-qtcharts tbb


Software Prerequisites and Geant4 Installation for the GEMC build




One-line installation commands for basic packages and dependencies on MacOS and some popular Linux distributions:


dnf install -y --allowerasing git make cmake gcc-c++ gdb valgrind libxcrypt-devel \
expat-devel zlib zlib-devel mariadb-devel sqlite-devel python3-devel ninja-build \
mesa-libGL-devel mesa-libGLU-devel libX11-devel libXpm-devel libXft-devel \
libXt-devel libXmu-devel libXrender-devel xorg-x11-server-Xvfb xrandr \
bzip2 wget curl nano bash zsh hostname gedit environment-modules pv which \
psmisc procps mailcap net-tools rsync patch bash-completion python3-numpy \
xterm x11vnc openbox lxqt-panel dejavu-sans-mono-fonts \
qt6-qtbase-devel qt6-qtsvg qt6-qtsvg-devel qt6-qtcharts-devel \
root liblsan libasan libubsan libtsan tbb



Important

GEMC can use any custom installation of CLHEP/Xerces-C/Geant4, however we recommend using the g4install repository to install Geant4, as it provides coexistence of multiple Geant4 versions and installation scripts.


Supported and tested platforms




  1. For Apple Silicon Mac add the option --platform linux/amd64 to the docker run command if you want to use the ↩