Hands On 1: Setting Up the Environment


Introduction

In this first hands on you will learn:

There is no exercise tar-ball for this first hands on since we use Geant4 code base.
We are going to use Geant4 Version 10.5.p01 (Geant4 version numbers are expressed with the triplet of numbers: Major.Minor.PatchLevel).
We are going to use Geant4 and related libraries pre-installed on the CNL central computer farm. You do not need to manually install Geant4 during this tutorial, however we review here some options and give some details on the installation process. Geant4 code can be found in the download area on Geant4 website: http://www.geant4.org.

During the next days we will develop a Geant4 application that will use installed Geant4 libraries. Geant4 is a toolkit, thus a Geant4 installation consists of a set of library files and header files (plus resource files: the data-base data and examples source code). You create an application compiled against a Geant4 installation.


Conventions

In the Hands On we will use the following conventions:


Geant4 Installation (OPTIONAL)

Given you are using Geant4 libraries pre-installed to the CNL central computing farm, you may skip this section. However you can follow the instructions here and install Geant4 to your local machine.

Code compilation dependencies

With its basic installation options Geant4 Version 10.5 does not have external dependencies, but to configure the compilation and installation process cmake is needed. The role of cmake is to automatically create Makfiles (or project files for IDEs) based on options that can be specified based on your own environments. We will show how to use cmake via command line options, but a menu-based version of cmake exists (type ccmake instad of cmake) and for some platforms also a GUI is avialble (cmake-gui). Geant4 Version 10.5 requires cmake version at least 3.3.
Geant4 version 10.5 contains c++11 code, this mean that the compiler needs to support this standard. With recent versions of Linux this is the default, but you may need to manually install and setup a compiler in some cases.
Refer to the Geant4 installation guide for additional information, including the list of supported compilers.

Visualization and GUI

We will also describe how to setup and use the interactive graphical user interface (GUI) based on Qt. This is an optional component. We use Qt version 5.6 (Geant4 still supports Qt version 4). Many Linux distributions already have a pre-installed version of Qt. It is relatively easy to manually install Qt on a Linux or Mac system, but we will not cover this step in this tutorial. This component is optional, if you do not want to use Qt simply skip the Qt options during configuration. None of exercises require GUI interfaces to be completed.
If you do not have Qt or do not want to use it, the examples in this tutorial will fall back to simple OpenGL graphics. In such a case to enable OpenGL graphics, use -DGEANT_USE_OPENGL_X11=ON when configuring G4 with cmake. While for Linux this should not be a problem, it could have issues on Mac systems. If this fail, contact us.

Multi-threading

Starting with Geant4 Version 10 series, we introduced event level parallelism via multi-threading. This means that we will develop a parallel application that will simulate events using all available cores of your machine. This is an optional component: we will show here how to turn it on, but if you do not want to enable MT you can still follow the exercises as they are, since the code is also compatible with the sequential version of Geant4.
Note for virtual machine users: if you are using a VM, even if you have a multi-core laptop it is possible that the VM sees only one CPU core. It is usually just a matter of VM configuration to allow more than one CPU in the guest OS.

Instructions: step-by-step installation guide

Step 0: Obtain the Geant4 code

After downloading and un-packing Geant4 tarball (geant4.10.05.p01.tar.gz) in an empty working directory, you need to create build and install directories where the compilation of Geant4 is performed, and resulted Geant4 libraries and related scripts are installed, respectively: cmake uses out of source builds.

Step 1: Configuration


In the following we assume you are using a Linux machine. For Mac users there are little differences, except that you will rely on the system compiler (clang) and cannot set an alternative compiler (in an easy way).
Let's configure Geant4:

  $ cd <tutorial>
  $ wget http://cern.ch/geant4-data/releases/geant4.10.05.p01.tar.gz
  $ tar xf geant4.*.tar.gz
  $ ls
  geant4.10.05.p01 geant4.10.05.p01.tar.gz
  $ mkdir build install
  $ cd build
  $ cmake -DCMAKE_INSTALL_PREFIX=../install -DGEANT4_BUILD_MULTITHREADED=ON -DGEANT4_INSTALL_DATA=ON -DGEANT4_USE_QT=ON -DGEANT4_USE_OPENGL_X11=ON ../geant4.10.05.p01

If you have an old version of Linux with a default compiler with a version <4.8.2, type gcc --version to get the compiler version, you need to have installed an alternative more recent compiler. For example if you have a CentOS 6 or Scientific Linux 6 distributions you need to manually install a recent compiler. After doing that you need to prepend to the cmake line: CC=gcc CXX=g++ and make sure that gcc and g++ binaries are the correct one.
Replace gcc and g++ with your alternative compiler if you have one and you want to use it (e.g. icc and icpc for Intel C compiler).
If everything goes as expected cmake will work few seconds on the configuration. The last lines should read:

-- Configuring done
-- Generating done
-- Build files have been written to: <some-directory>/build


Some notes:

Step 2: Compilation

Compile Geant4, on a multi-core system with N cores you can substantially speedup compilation. For this tutorial we use 2 threads due to the limitation of Minerva devnode.

  $ #cd into <tutorial>/build if needed
  $ make -j 2 #or gmake -j 2
  $ make install

Note: replace 2 with the integer representing the number of cores of your machine. If not sure use 2.
Note: you can have a verbose compilation (for example to see the exact compilation options) using make VERBOSE=1 -j 2.

After Geant4 has been compiled and installed the content of the <tutorial>/install directory should contain the directories: bin share include lib[64].

The include directory contains a sub-directory (Geant4) where all the .hh files are located. The directory lib[64] contains all Geant4 libraries and a sub-directory: Geant4-10.5.1, this contains cmake files specific to Geant4 (they are used to compile an application via cmake that uses Geant4).


Compiling the first example

For this tutorial Geant4 10.5.p01 is centrally installed, and the SHELL environment G4INSTALL points to the top directory of this Geant4 installation.

Every time you want to use an application using Geant4, remember to set up run-time environment variables. Use the appropriate script extension depending on your shell type, .sh for bash family, .csh for tcsh family:

  $ source $G4INSTALL/bin/geant4.[c]sh
  $ printenv | grep G4

Exercise 1

Compile Example basic B1 provided with Geant4.

Example code can be found at: $G4EXAMPLES/basic/B1. This is an application that needs Geant4 libraries and headers to be compiled correctly, thus you will need to instruct cmake to use Geant4 from the location where it is installed.

Solution

  $ cd <tutorial>
  $ mkdir HandsOn1
  $ cd HandsOn1
  $ cp -r $G4EXAMPLES/basic/B1 .
  $ cd B1
  $ cmake .
  $ make -j 2 -f Makefile
  $ ls
  ... some lines of output ...

Note : If you get the line: [100%] Built target exampleB1 everything worked as expected.


Familiarizing with a Geant4 application

Exercise 2

Start the application built in the previous exercise. For this very first test, we disable Qt interface.

Solution

  $ ./exampleB1

Geant4 will initialize and will greet you with some output, the first lines should read:

 *************************************************************
  Geant4 version Name: geant4-10-05-patch-01 [MT] (17-April-2019)
  << in Multi-threaded mode >>
  Copyright : Geant4 Collaboration
  Reference : NIM A 506 (2003), 250-303
  WWW : http://cern.ch/geant4
 *************************************************************

Note: G4 can be quite verbose, especially if you have enabled MT support.
If you receive error messages like ERROR: G4VisCommandsViewerSet::SetNewValue: no current viewer you can safely ignore them.

If you use Qt, a GUI window should pop up.



You can type your command in the Session: field at the right-bottom of the window. You may also pick a command from the left side menu.
Try 10 events and see trajectories.
  /run/beamOn 10

If you do not use Qt but use OpenGL visualization, a visualization window will appear with the geometry displayed.



You will see Geant4 prompt on your terminal screen, where you can issue Geant4 commands.

Try 10 events and see trajectories.
  Idle> /run/beamOn 10

Refer to the presentations at this tutorial for UI interactivity.
Take your time to familiarize with the Geant4 prompt (for example note that the prompt has auto-complete, the tab key; history, with up-down arrow keys).
Try navigating the GUI help panel.
Familiarize with the help menu and its sub-menu levels. Can you find where the /run/beamOn command is located? What is the UI command to change the primary particle type?

Exercise 3

Compile a second exercise.

Browse the $G4EXAMPLES directory and try a few examples.
Compile/run them following the instructions of the previous exercises.
Note: Move to an appropriate directory before copying the second example.
Imprtant: some examples may require additional libraries (e.g. GDML), thus may not compile in this setup.


Created by: Andrea Dotti (adotti AT slac DOT stanford DOT edu) May 2018
Updated by: Makoto Asai (asai AT slac DOT stanford DOT edu) August 2019