Using Geant4 in Containers

You can install Geant4 inside containers like Docker or Singularity. Containers can help make your application build and run setup reproducible, simplify installing software, and work well on HPC systems.

Singularity

This section shows you how to build a Singularity container with Geant4, including GDML support and Qt5 visualization.

  1. Create a file named, for example, G4_gdml_vis.def, and copy the following code into it:

Bootstrap: docker
From: ubuntu:22.04

%labels
    Author Geant4 collaboration
    Version Geant4-GDML-Qt5

%environment
    export G4INSTALL=/opt/geant4
    export G4DATA_DIR=$G4INSTALL/share/Geant4/data
    export G4LIB_DIR=$G4INSTALL/lib
    export PATH=$G4INSTALL/bin:$PATH
    export LD_LIBRARY_PATH=$G4INSTALL/lib:$LD_LIBRARY_PATH

%post
    apt-get update && apt-get install -y \
        build-essential \
        cmake \
        wget \
        libxerces-c-dev \
        libexpat1-dev \
        qtbase5-dev \
        mesa-utils libglu1-mesa-dev \
    freeglut3-dev mesa-common-dev

    # Install Geant4
    cd /opt
    G4_VERSION=11.2.2
    wget https://github.com/Geant4/geant4/archive/refs/tags/v${G4_VERSION}.tar.gz
    tar -xf v${G4_VERSION}.tar.gz

    cmake -S geant4-${G4_VERSION} -B geant4-build \
        -DCMAKE_INSTALL_PREFIX=/opt/geant4 \
        -DGEANT4_BUILD_MULTITHREADED=ON \
        -DGEANT4_USE_GDML=ON \
        -DGEANT4_USE_SYSTEM_EXPAT=ON \
        -DGEANT4_INSTALL_DATA=ON \
        -DGEANT4_INSTALL_EXAMPLES=OFF \
        -DGEANT4_USE_QT=ON

    cmake --build geant4-build -- -j$(nproc) install

    # Clean up
    apt-get clean && rm -rf /var/lib/apt/lists/* /opt/v${G4_VERSION}.tar.gz /opt/geant4-${G4_VERSION} /opt/geant4-build

%runscript
    echo "Geant4 with GDML and Qt5 is ready."
    exec "$@"

  1. Build the Singularity image

Run this command to build the container image from the definition file. This can take several minutes.

singularity build G4_gdml_vis.sif G4_gdml_vis.def

After it finishes, you will have a file called G4_gdml_vis.sif in your directory.

  1. Use the image

You can now compile and run your Geant4 projects inside the container. Your current directory . is automatically available inside the container.

If you have Geant4 environment variables set on your host system, either unset them or run with --cleanenv to avoid conflicts.

singularity exec G4_gdml_vis.sif cmake -S ./MyProject -B build -D CMAKE_INSTALL_PREFIX=install
singularity exec G4_gdml_vis.sif cmake --build build -- -j install
singularity exec G4_gdml_vis.sif ./install/bin/MyApp -m run.mac -g geo.gdml -o outputFile.root

For more detailed information about building and running Singularity (now Apptainer) containers, including managing permissions and enabling graphical applications, please refer to the official Apptainer documentation

Docker

This section shows you how to build a Docker container with Geant4, including GDML support and Qt5 visualization.

  1. Create a file named Dockerfile and copy the following code into it:

FROM ubuntu:22.04

# Labels (optional but good for metadata)
LABEL author="Geant4 collaboration"
LABEL version="Geant4-GDML-Qt5"

# Set environment variables
ENV G4INSTALL=/opt/geant4
ENV G4DATA_DIR=$G4INSTALL/share/Geant4/data
ENV G4LIB_DIR=$G4INSTALL/lib
ENV PATH=$G4INSTALL/bin:$PATH
ENV LD_LIBRARY_PATH=$G4INSTALL/lib:$LD_LIBRARY_PATH
ENV G4GDMLROOT=$G4INSTALL

# Install dependencies and build Geant4
RUN apt-get update && apt-get install -y \
        build-essential \
        cmake \
        wget \
        libxerces-c-dev \
        libexpat1-dev \
        qtbase5-dev \
        mesa-utils \
        libglu1-mesa-dev \
        freeglut3-dev \
        mesa-common-dev && \
    cd /opt && \
    G4_VERSION=11.3.0 && \
    wget https://github.com/Geant4/geant4/archive/refs/tags/v${G4_VERSION}.tar.gz && \
    tar -xf v${G4_VERSION}.tar.gz && \
    mv geant4-${G4_VERSION} geant4-source && \
    mkdir -p geant4-build geant4-install && \
    cd geant4-build && \
    cmake ../geant4-source \
        -DCMAKE_INSTALL_PREFIX=/opt/geant4 \
        -DGEANT4_BUILD_MULTITHREADED=ON \
        -DGEANT4_USE_GDML=ON \
        -DGEANT4_USE_SYSTEM_EXPAT=ON \
        -DGEANT4_USE_SYSTEM_XERCESC=ON \
        -DGEANT4_INSTALL_DATA=ON \
        -DGEANT4_INSTALL_EXAMPLES=OFF \
        -DGEANT4_USE_OPENGL_X11=OFF \
        -DGEANT4_USE_QT=ON \
        -DGEANT4_USE_XM=OFF \
        -DGEANT4_USE_RAYTRACER_X11=OFF && \
    make -j$(nproc) && \
    make install && \
    apt-get clean && rm -rf /var/lib/apt/lists/* /opt/v${G4_VERSION}.tar.gz /opt/geant4-source /opt/geant4-build

# Set default command / entrypoint
CMD ["bash"]

  1. Build the Docker image

Run this command to build the container image from the Dockerfile. This can take several minutes.

docker build -t G4_gdml_vis .

After it finishes, the image is stored by Docker, and it can be listed by using the following command:

docker images

The output should look like this:

REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
G4_gdml_vis         latest    9479e0632429   2 seconds ago   3.13GB

  1. Use the image

Docker does not automatically mount your local directory like Singularity does. To work with files on your computer, you need to mount a volume. It is also good practice to remove the container after it stops (using the --rm option). Use -it to interact with the container.

You can create an alias to simplify running your container:

alias g4run='docker run --rm -it -v "$(pwd):/workspace" -w /workspace localhost/G4_gdml_vis'

Warning

If you’re using Podman (an alternative to Docker on systems like Fedora or RHEL), add :Z to the volume option like this:

-v "$(pwd):/workspace:Z"

The :Z tells Podman to adjust file permissions, so it can access your files even if your system uses SELinux (a security feature).

Then, you can use the image to build and run your Geant4 projects like this:

g4run cmake -S ./MyProject -B build -D CMAKE_INSTALL_PREFIX=install
g4run cmake --build build -- -j install
g4run ./install/bin/MyApp -m run.mac -g geo.gdml -o outputFile.root

For more details about building and running Docker containers, managing permissions, and enabling graphical applications, please see the official Docker documentation