License

See the license conditions.


Release Notes


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

Set the versioned installation prefix once, so you can copy and paste the commands below. Change gprefix to the GEMC version and location you want to install.

gprefix=/path/to/gemc/0.2

The source code will be cloned into $gprefix/source, and GEMC will be installed into $gprefix. For the development release, set gprefix=/path/to/gemc/dev and use the development tab.

Download the code:

Download the latest release:

mkdir -p "$gprefix"
cd "$gprefix"
git clone -c advice.detachedHead=false --branch 0.2 https://github.com/gemc/src source


2. Compile 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 inside source:

cd "$gprefix/source"
meson setup build --native-file=core.ini --prefix="$gprefix"

The compile phase will build the code and external libraries. The install phase will copy the binaries, libraries, and python modules to the installation directory.

meson compile -C build
meson install -C build

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


Build Options


Post installation

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

export gprefix=/path/to/gemc/0.2
export PATH=$gprefix/bin:$gprefix/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 without any activation step or separate pip install. It also exposes the gemc-analyzer and gemc-system-template command-line tools.

Check the installed simulator and Python tools with:

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



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 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 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 ↩