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.
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 "$@"
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.
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.
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"]
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
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