License

See the license conditions.


Release Notes


Note

Use the most recent GEMC release to ensure you are taking advantage of the latest bug fixes and new features. This also helps the developers to provide the best support.



Table of Contents

Appendix:



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 install 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:

Download the latest release:

cd /path/to/gemc/0.1
git clone -c advice.detachedHead=false --recurse-submodules --branch 0.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 source:

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


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

OS GEMC Version Registry address arm64 amd64
AlmaLinux 9.4 dev ghcr.io/gemc/src:dev-almalinux-9.4 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 42 dev ghcr.io/gemc/src:dev-fedora-42 true true
Ubuntu 24.04 dev ghcr.io/gemc/src:dev-ubuntu-24.04 true true

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.

archlinux amd64 images.


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 (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-9.4 bash

Then:

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


Warning

The graphical interface, in particular OpenGL windows, may not work properly in apptainer if connecting to a remote host


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




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



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 ↩