You're reading the documentation for a development version.
For the latest released version, please have a look at v0.5.1.

1. How To Run with Docker#

Automatically built Docker images are available for G4SEE in its Container Registry. G4SEE Docker image is a Debian-based image, with Geant4 installed and G4SEE compiled inside, ready to use.

1.1. Pull Docker image#

Note

Depending on your Docker installation, you may need to use sudo for docker commands.

Pull the g4see Docker image, naming the specific Docker image tag you need:

docker pull gitlab-registry.cern.ch/g4see/g4see:<TAG>

Available g4see Docker image tags:

Docker image TAG

G4SEE version

Geant4 version

Comment

master_G4-11.0.3

master

11.0.3

development

v0.5_G4-11.0.3

v0.5

11.0.3

STABLE RELEASE

v0.5_G4-11.0.2

v0.5

11.0.2

for testing only

v0.5_G4-11.0.1

v0.5

11.0.1

for testing only

v0.5_G4-11.0.0

v0.5

11.0.0

for testing only

v0.5_G4-10.7.3

v0.5

10.7.3

for testing only

v0.5_G4-10.7.2

v0.5

10.7.2

for testing only

v0.5_G4-10.7.1

v0.5

10.7.1

for testing only

v0.5_G4-10.7.0

v0.5

10.7.0

for testing only

1.2. Run Docker container#

To start a container locally based on the image:

docker run -it -h g4see gitlab-registry.cern.ch/g4see/g4see:v0.5_G4-11.0.3

To start a container with a local folder shared between host and container (mounted to container’s /home):

docker run -it -h g4see \
           -v /host/path/to/shared_folder:/home \
           gitlab-registry.cern.ch/g4see/g4see:v0.5_G4-11.0.3

To start a container with GUI/visualization forwarding:

Note

You need to have G4 visualization dependencies installed on your local computer in order to display G4 GUI and visualization locally.

  • On a Linux host:

export DISPLAY=:0.0
xhost +local:docker
docker run -it -h geant4 \ 
           -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
           gitlab-registry.cern.ch/g4see/g4see:v0.5_G4-11.0.3

  • On a Windows host:

    • Enable and use Windows Subsystem for Linux (WSL)

    • Install Xming X11 display server for Windows to run graphical applications with WSL

    • Allow WSL through Windows Firewall

    • Check IP address of your vEthernet (WSL) adapter with ipconfig, then set-variable -name DISPLAY -value <YOUR_WSL_IP>:0.0

docker run -it -h geant4 \
           -e DISPLAY=%DISPLAY% -v /tmp/.X11-unix:/tmp/.X11-unix \ 
           gitlab-registry.cern.ch/g4see/g4see:v0.5_G4-11.0.3

  • On a Mac host:

    • Install XQuartz: brew install --cask xquartz

    • Run XQuartz: open -a XQuartz

      • Open preferences, go to the “Security” tab and check “Allow connections from network clients”

      • Leave XQuartz running

    • Back in the terminal: ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}'); xhost + $ip

    • NOTE: There is a resolution limitation in XQuartz.

docker run -it -h geant4 \ 
           -e DISPLAY=$ip:0 -v /tmp/.X11-unix:/tmp/.X11-unix \
           gitlab-registry.cern.ch/g4see/g4see:v0.5_G4-11.0.3

1.3. Use Docker container#

Paths inside container:

  • G4SEE source directory: /opt/g4see/ (G4SEE_SRC environment variable)

  • G4SEE build directory: /opt/g4see/build (G4SEE_BUILD environment variable)

  • Geant4 installation: /opt/geant4/install/lib/Geant4-<version> (G4LIB environment variable)

  • Geant4 examples: /opt/geant4/install/share/Geant4-<version>/examples/

Tools available in container:

  • G4SEE

  • Geant4

  • g++, gcc, cmake, make

  • git, curl, nano, htop

  • python3.10 with numpy, pandas, matplotlib, pyYAML

See How To Run the G4SEE toolkit.

1.4. Build Docker image#

Needed:

  • Access to CERN GitLab with CERN credentials

  • Access to geant4-docker repository in CERN GitLab

To build Docker image locally (in g4see/ repository):

docker login gitlab-registry.cern.ch
docker build --build-arg G4TAG=11.0.3 \
             --build-arg MT=True \
             --build-arg N_CPU=4 \
             --tag g4see:devel .