Hands On 1: Setting Up the Environmnet

Introduction slides

Back to Agenda


In this first hands on you will learn:

There is no additional exercise tar-ball for this first hands on since we use Geant4 code base.
We are going to use Geant4 Version 10.0.p01 (Geant4 version numbers are expressed with the triplet of numbers: Major.Minor.PatchLevel).
You should have already installed Geant4 on your machine, however we review here some options and give some details. Geant4 code can be downloaded from download are on Geant4 website: http://www.geant4.org.

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

With its basic installation Geant4 Version 10.0 series does not have external dependicies, but to configure the installation process cmake is needed. The role of cmake is to automatically create Makfiles (or project files for IDEs) from a set of configurable options. 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.0 requires cmake version 2.6.4 or more recent.

In the following 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 4 (Geant4 supports Qt version 5 only experimentally). Many Linux distributions already come with Qt4 installed. It is relatively easy to manually install Qt4 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 requires GUI interfaces to be completed.

Geant4 Version 10.0 introduces 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. To enable MT you need a recent compiler (on Linux we recommend at least gcc 4.2, on Mac OS X you need clang at least version 3.0, sorry no WIN support yet).
Note for virtual machine users: if you are using a VM for this tutorial, even if you have a multi-core laptop it is probable 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.


In the Hands On we will use the following conventions:

Geant4 Installation

After downloading and un-packing Geant4 tarball (geant4.10.00.p01.tar.gz) in an empty working directory, we need to create a build directory where the compilation of Geant4 is performed: cmake uses out of source builds.

Step 1: Configuration
Let's configure Geant4:
  $ cd <tutorial>
  #Copy in this directory Geant4 tarball
  $ tar -xz geant4.*.tar.gz
  $ ls
 geant4.10.00.p01 geant4.10.00.p01.tar.gz
  $ mkdir build
  $ cd build

If everything works as expected cmake will work few seconds producing some output, the last lines should read:

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

If you do not want to use Qt, remove the -DGEANT4_USE_QT=ON option. If you do not want multi-threaded support remove also the corresponding option.
If you disable Qt it is recommended to enable OpenGL with: -DGEANT4_USE_OPENGL_X11=ON. If neither Qt or OpenGL work for you contact us.

Some notes:

Step 2: Compilation
Compile Geant4, on a multi-core system with N cores you can substantially speedup compilation with:
  $ #cd into <tutorial>/build if needed
  $ make -j N #or gmake
  $ make install

Hint: you can have a verbose compilation (for example to see the exact compilation options) using make VERBOSE=1 -jN.

After Geant4 has been compiled and installed the content of the <tutorial> directory should look like:
  $ cd ../ #Needed to go back to <tutorial> if you are in build directory
  $ ls
 bingeant4.10.00.p01.tar.gz share build include geant4.10.00.p01 lib

Note: In some linux systems instead of lib you may have lib64. In such a case for the rest of tutorial use lib64 instead of lib when appropriate.

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.0.1 that contains cmake files specific to Geant4 (they are used to compile an application via cmake that uses Geant4).

Note: If you are not using Geant4 Version 10.0.p01 (patch released February 28th) directory names may be slightly different; for example you will find: lib/Geant4-10.0, remember this difference for the rest of the tutorials.

Step 3: Setup runtime environemnt
Every time you want to use or compile an application using Geant4 remember to (select appropriate script extension depending on your shell type):
  $ source <tutorial>/bin/geant4.[c]sh

For this tutorial you will need to do this step evry time a new terminal window is open.

Compiling the first example

Assuming you have installed Geant4 we will now compile the basic example B1 using cmake to configure it.

Exercise 1

Compile Example basic B1.

Example code can be found under: geant4-soruce-dir/examples/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 you have installed it. Do not compile the example in the same build directory where you compiled Geant4, create a new clean one (use a clean directory for each exercise of this tutorial).


  $ cd <tutorial>
  $ source bin/geant4.[c]sh
  $ mkdir build-exB1
  $ cd build-exB1
  $ cmake -DGeant4_DIR=<tutorial>/lib/Geant4-10.0.1 <tutorial>/geant4.10.00.p01/examples/basic/B1
  $ [g]make -jN
  $ ls
  ... lots of stuff ...
  ... note the file exampleB1: the application binary ...

There is no need to make install; if you want to do that, add -DCMAKE_INSTALL_PREFIX=<tutorial> to cmake line and type make install after compilation. Your binary will be placed under <tutorial>/bin

Important notes:

Familiarizing with a Geant4 application

Start the application built from the previous exercise. For this very first test, we disable graphics.
  $ export G4UI_USE_TCSH=1 #Or setenv G4UI_USE_TCSH 1 cor tcsh shell
  $ unset G4UI_USE_QT #Or unsetenv G4UI_USE_QT on tcsh shell
  Edit vis.mac file and comment line /vis/open OGL
  $ ./exampleB1

Geant4 will initialize and will greet you with lots of output, the first lines should read:
  Geant4 version Name: geant4-10-00-ref-00 [MT] (6-December-2013)
  << in Multi-threaded mode >>
  Copyright : Geant4 Collaboration
  Reference : NIM A 506 (2003), 250-303
  WWW : http://cern.ch/geant4

If you reveive error messages like ERROR: G4VisCommandsViewerSet::SetNewValue: no current viewer you can safely ignore them: they are there since you are forcing to run Geant4 without graphcis.

After quite some verbose output, you will see Geant4 prompt Idle>, at which you can issue Geant4 commands.
For example:
  Idle> /run/beamOn 10
  Idle> help
  Idle> exit

Refer to the presentaitons today for UI interactivity.
Take your time to familiarise with the Geant4 prompt (for example note that the prompt has auto-complete, history, like a system shell).

Now start again the application but with visualization enabled:
  $ unset G4UI_USE_TCSH #Or unsetenv G4UI_USE_TCSH cor tcsh shell
  $ ./exampleB1

A visualization windows will appear with the geometry displayed:

If you have compiled Geant4 with Qt support the graphic windows will be embedded in the GUI. Play with the interface, in particular take a look at the help menu.

Exercise 2

Compile a second exercise.

Browse the geant4/examples directory and try out compilation of few exercises. Compile following the instructions of the previous exercise. Refering to the presentation about exercises, try out the exercise that most is relevant for your field. Imprtant: some exercises may require additional components of Geant4 (e.g. GDML), thus will not compile in this setup.

Tutorial by:
Andrea Dotti (adotti AT slac DOT stanford DOT edu)

3 March 2014