License

See the license conditions.

Release Notes

• development - released nightly
• 0.1 - Released on 04/29/2026
• All Releases

Table of Contents

• Build and Install GEMC from source code
• [Optional] Install Pyvista
• GEMC using Docker
• GEMC using Apptainer

Build and Install GEMC from Source

Please see the Software Prerequisites and Geant4 Installation in the appendix for the requirements.

1. Obtain the source

For illustration, we will use /path/to/gemc as the installation location, 0.1 as the version to be installed, source as where to place the source code. Replace 0.1 with dev if you want to instal the development release.

Create the paths and cd to the version directory:

mkdir -p /path/to/gemc/0.1/source
cd /path/to/gemc/0.1

Download the code:

cd /path/to/gemc/0.1
git clone -c advice.detachedHead=false --recurse-submodules --branch 0.1 https://github.com/gemc/src source

cd /path/to/gemc/dev
git clone --depth=1 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 ssource:

cd /path/to/gemc/0.1/source
meson setup build --native-file=core.ini --prefix=/path/to/gemc/0.1

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, meson test -v will run several tests of various components of GEMC.

Build Options

• The setup option -Droot=enabled will add ROOT support (needs ROOT installed on your system).
• The setup option -Di_test=true will enable the GUI interfaces in the tests.
• Use -v at build time for verbose output.
• To wipe out the build directory and start over, use rm -rf build and then re-run setup.
• Use -jN to set the number of threads during compilation

Post Installation

You can add the lines below to your shell configuration file (e.g. ~/.bashrc or ~/.zshrc).

export GEMC_VERSION=0.1
export PATH=/path/to/gemc/$GEMC_VERSION/bin:$PATH
export PYTHONPATH=/path/to/gemc/$GEMC_VERSION/api:$PYTHONPATH

Here with GEMC_VERSION we control the version of GEMC to use.

[Optional] Install Pyvista

While pyvista is not necessary to build the detectors, it provides a nice visual feedback without the need to run GEMC to visualize the geometry.

To install pyvista, including the qt modules, use a python environment:

python3 -m venv ~/venv/pyvista/
source ~/venv/pyvista/bin/activate
pip install pyvista vtk 
pip install pyqt6 pyvistaqt

To use it with the Python API, remember to activate the environment first:

source ~/venv/pyvista/bin/activate

Then pass either -pv (native pyvista) or -pvb (for a qt GUI) to the python scripts that build the databases.

GEMC using Docker

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 ¹).

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

Batch mode

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

Use a browser for the graphical interface:

Set these convenience variables for the interactive (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-9.4

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

GEMC using Apptainer

Linux hosts can use apptainer (formally 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 source explicitly:

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

Then:

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

Note

Apptainer uses a default cache directory to store the images. If that becomes full, one can use environment variables to point 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 and Geant4 Installation

• Builders and compilers:

  • C++ Compiler and Standard Library supporting the C++17 Standard
  • CMake 3.16 or later
  • Meson 1.10.1 or later

• Packages installed with your system package manager:

  • expat: 2.0.1 or higher
  • zlib: 1.2.3 or higher
  • Qt6: 6.5 or higher (required for GUI
  • ROOT: 6.36.04 or higher (optional, required for ROOT output)

One liners installation of basic packages and dependencies on some popular Linux distributions:

dnf install -y --allowerasing git make cmake gcc-c++ gdb valgrind expat-devel mariadb-devel \
sqlite-devel python3-devel ninja-build 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 xterm x11vnc openbox lxqt-panel dejavu-sans-mono-fonts qt6-qtbase-devel root liblsan \
libasan libubsan libtsan tbb 

dnf install -y --allowerasing git make cmake gcc-c++ gdb valgrind expat-devel mariadb-devel \
sqlite-devel python3-devel ninja-build 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 xterm x11vnc openbox tint2 dejavu-sans-mono-fonts qt6-qtbase-devel root liblsan \
libasan libubsan libtsan tbb

DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends tzdata git make cmake \
g++ gdb valgrind libexpat1-dev libmysqlclient-dev libsqlite3-dev python3-dev ninja-build \
libglu1-mesa-dev libx11-dev libxpm-dev libxft-dev libxt-dev libxmu-dev libxrender-dev \
xvfb x11-xserver-utils bzip2 wget curl nano bash zsh hostname gedit environment-modules pv \
which ca-certificates psmisc procps mailcap net-tools rsync patch bash-completion xterm \
x11vnc openbox tint2 dbus-x11 fonts-dejavu-core qt6-base-dev libqt6opengl6t64 \
libqt6openglwidgets6t64 qt6-base-dev-tools liblsan0 libasan8 libubsan1 libtsan2 libtbb12

DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends tzdata git make cmake \
g++ gdb valgrind libexpat1-dev libmariadb-dev libsqlite3-dev python3-dev ninja-build \
libglu1-mesa-dev libx11-dev libxpm-dev libxft-dev libxt-dev libxmu-dev libxrender-dev \
xvfb x11-xserver-utils bzip2 wget curl nano bash zsh hostname gedit environment-modules pv \
which ca-certificates psmisc procps mailcap net-tools rsync patch bash-completion xterm \
x11vnc openbox tint2 dbus-x11 fonts-dejavu-core qt6-base-dev libqt6opengl6 libqt6openglwidgets6 \
qt6-base-dev-tools liblsan0 libasan8 libubsan1 libtsan2 libtbb12 

pacman-key --init && pacman-key --populate
pacman -Sy --noconfirm archlinux-keyring
pacman -Syu --noconfirm --needed git make cmake gcc gdb valgrind expat mariadb mariadb-libs \
sqlite python python-pip ninja mesa glu libx11 libxpm libxft libxt libxmu libxrender \
xorg-server-xvfb xorg-xrandr bzip2 wget curl nano bash zsh inetutils gedit pv which fakeroot \
psmisc procps mailcap net-tools rsync patch bash-completion ncurses xterm tigervnc openbox \
ttf-dejavu qt6-base root gcc-libs tbb 

• Packages, compiled from source against the same C++ Standard as GEMC (C++17 by default):

  • Geant4: 11.3.2 or higher
  • CLHEP: 2.4.6.0 or higher
  • Xerces-C: 3.2 or higher

Supported and tested platforms

• macOS: 26

• AlmaLinux: 9.4

• ArchLinux: latest

• Debian: 13

• Fedora: 42

• Ubuntu: 24.04