Difference between revisions of "HOWTO install and run HDGeant4"

Revision as of 20:23, 10 October 2016

Download the package sources

The HDGeant4 simulation is still in alpha release. During the present active development phase, it is currently being maintained in a read-only public git repository under the ownership of Richard Jones. The repository is being updated frequently as new features are being added and bugs corrected. Every effort is being made to ensure that the package can be successfully checked out and built after every commit that gets pushed to the master branch on github.

To check out the HDGeant source with the latest updates, go to a work directory where you would like to build the package and type the following command.

$ git clone git@github.com:rjones30/HDGeant4.git
$ cd HDGeant4 && ls
GNUmakefile  INSTALL  README.md  SConstruct  VERSIONS  g4py  src  test  vis

The README file gives an overview of the purpose and function of the HDGeant4 physics simulation package, and gives a bit of history regarding its design and early development. The VERSIONS file contains that release notes and dates for each major release of the HDGeant4 package. The INSTALL file contains the same information as conveyed on this wiki page concerning how to download, build, and run hdgeant4 and associated python modules. The GNUmakefile and SConstruct files contain the instructions for building package executables from source files; see below for further details. The g4py directory contains the python sources that comprise the python modules that are a part of HDGeant4. The src directory contains the C++ sources. The test directory contains a sample control.in file that is useful for initial tests that the hdgeant4 executable functions correctly after it is built. It also contains a suite of eps image files showing various cutaway views of the GlueX detector geometry, which are useful for comparison with the same views that can be generated using hdgeant4 once it is built. The vis directory contains a suite of graphics macros that can be invoked from the interactive command line in hdgeant4 to produce these same cutaway views. These images take a few minutes each to create, but it is worthwhile to take the time to make them because they provide a sensitive test that the GlueX geometry is faithfully represented within the Geant4 release against which you are building hdgeant4.

Supported platforms

The build instructions in this document have been developed for the Linux platform, running a 2.6 kernel. They have only been extensively tested on machines running the Centos 6 distribution, but they should work pretty much without modification on a host running a flavor of Debian, Scientific Linux, Gentoo, Ubuntu, or even Raspian, should anyone want to try such a thing. The code has been compiled and tested with the gnu c++ 4.9.2 compiler/linker suite. It should also work with more recent releases of the gnu compiler, and may even work with version 4.8.2 that is the default release for Centos 7. The only requirement is that it support the commandline option -std=c++11 which enables most of the features included in the C++11 standard.

The default gnu compiler that comes with Centos 6 is gcc-4.4.7 which does not support -std=c++11. Before attempting the instructions below to install an updated compiler version, you can check the currently installed version on your system by typing "gcc -v". If the version reported by this command is older than 4.8 then you will need to upgrade. Version 4.9.2 of the gcc compiler suite can be installed on a Centos 6 machine as a part of the bundle package "devtoolset-3". This package is not available from the standard Centos rpm repositories. I can be found by direct search on the internet, but the simplest means to obtain it is to enable the SCL repositories in your supported yum repositories, and then install devtoolset-3 using yum.

$ yum install centos-release-scl
$ yum install centos-release-scl-rh
$ yum install devtoolset-3

After this completes successfully, all you need to do in order to switch from the base gnu compiler to version 4.9.2 is to type the following from within your working shell,

$ scl enable devtoolset-3 bash

where "bash" can be replaced with the name of your working shell, eg. tcsh or zsh. This command cannot easily be embedded in a script because it results in adding a shell layer to the working environment. To see this, type the command in an interactive shell and then type "ps" to see the additional shell has been introduced. After this, any invocations of the gcc/g++ compilers will bring up the version 4.9.2 compiler (eg. try "g++ -v") until the user types "exit" to return to the original shell; once the exit from the daughter shell completes, the compiler resets automatically back to the default system version.

External package dependencies

1. sim-recon - The core components of the GlueX software stack are distributed in a single unified bundle called "sim-recon". This package has a number of external packages upon which it depends. Users who want to build and use HDGeant4 should already be familiar with sim-recon. Installation instructions for sim-recon can be found on the page Getting started with GlueX Software.
2. python - The current releases of Geant4 supports python 2.6 or 2.7, and in the near future will be extended to support version 3 as well. Normally one of these versions of python 2 should be already installed on any up-to-date Linux system. If not, you will need to install packages python-devel and python-libs in addition to python-runtime.
3. geant4 - The Geant4 simulation toolkit is maintained separately from the HDGeant4 sources. It should be downloaded from the main geant4 download site, and installed using the instructions provided by the distributors. The minimum recommended version of Geant4 that is supported by HDGeant4 is 4.9.6, although only version numbers starting with 4.10 provide multi-threading capability. Whatever version you decide to use, it must be one of those listed in the HDGeant4/src directory, in the form of a folder named G4.VV.RR-pPPfixes corresponding to version Geant4.VV.RR-pPP. You may try to build and run hdgeant4 against any other patch release of the Geant4 libraries, but it is not guaranteed to build without errors nor to run without crashing. The software dependencies of the Geant4 libraries are described in detail in the Installation Guide, but the key dependencies are listed below for convenience.
   • cmake 3.3 - This is the recommended build system for compiling the geant4 libraries from sources. On RH/Centos systems, this utility is available from the standard repositories as package "cmake3".
   • CLHEP - Prior to version 4.9, one needed to download and install CLHEP on the build host before attempting to build Geant4, but lately they have begun distributing a compatible CLHEP release inside the Geant4 sources tree at source/externals/clhep. Unless you have a specific reason to do so, you should not define any of the CLHEP_*** environment variables when you build Geant4, and instead let the cmake system discover the built-in version that is distributed with Geant4. This tends to be a relatively recent release, and is guaranteed to be compatible with the Geant4 release you are installing.
   • xerces-c 3 - This is a general xml parser library distributed under the apache license. It is also a dependency of sim-recon, so if you have already installed sim-recon you should already have xerces-c installed. If your sim-recon is an old one, you may have the older version 2 of xerces-c installed, in which case you should upgrade to one of the version 3 releases before attempting to build Geant4.
   • boost libraries - The boost libraries are widely-used extensions to the c++ standard that provide classes and macros for a variety of purposes. Geant4 uses boost to provide a python interface to the Geant4 toolkit. Building the python interface to Geant4 requires a special build step after the cmake build of the G4 libraries has completed successfully. Instructions for building the python extensions to Geant4 are found in an appendix of the Geant4 User's Guide for Application Developers.
   • Motif and Qt libraries - These packages are not required for building a production-ready executable, but if you might ever be interested in using the geometry and event visualization facilities of Geant4 to run the simulation interactively, generate dynamic views of tracks as they traverse the detector, and make on-the-fly adjustments to the simulation parameters, these packages will be useful. Up to date releases of the Motif and Qt libraries are available for all of the common flavors of Linux, and can be installed using the package manager that goes with your system, eg. yum for RH/Centos, apt for Debian, etc.
   • X11/Qt with OpenGL extensions - These packages are basic to the visualization package in Geant4. Generally you will want to build Geant4 with at least one of these two visualization facilities turned on, and probably both. OpenGL is a high-level 3D graphics package that provides efficient means to generate 2D views of a 3D geometry, and zoom/rotate/pan within that geometry in response to mouse input. Both X11 and Qt graphics drivers support OpenGL operations whenever the output display has hardware graphics acceleration available. This is generally the case on modern Intel workstations, provided that you are working on the main console. If you want to work over a remote desktop graphics screen (eg. vnc) then you will need to find a way to associate your virtual display with the console graphics device so that its hardware accelerator can be used to implement the OpenGL calls. See below for a practical means to do this while working remotely using a vncserver on a Linux host.

There are many options not listed above that can be selected during the cmake step of building the Geant4 libraries, most of which are optional as far as HDGeant4 is concerned. The following example shows the cmake command that I used to build a 4.10.02-p02 release of Geant4 for use with HDGeant4.

cmake3 -DCMAKE_INSTALL_PREFIX=/nfs/cern.ch/asis/geant4.10.02.p02/x86_64-debug \
       -DCMAKE_INSTALL_DATADIR=/nfs/cern.ch/asis/geant4.10.02.p02/data \
       -DXERCESC_ROOT_DIR=/usr/local/xerces \
       -DGEANT4_USE_QT=ON \
       -DQT_QMAKE_EXECUTABLE=/usr/lib64/qt4/bin/qmake \
       -DGEANT4_USE_XM=ON \
       -DGEANT4_USE_OPENGL_X11=ON \
       -DGEANT4_USE_RAYTRACER_X11=ON \
       -DGEANT4_USE_NETWORKDAWN=ON \
       -DGEANT4_BUILD_MULTITHREADED=ON \
       -DCMAKE_BUILD_TYPE=DEBUG \
../src

The above command was executed from within a directory /nfs/cern.ch/asis/geant4.10.02.p02/x86_64-debug-build, which is located in a top-level installation directory together with src which contains the complete G4 source tree that is unzipped from the distribution tar.gz file.

Note added by the author: I found that I was unable to build the python extensions to Geant4 if I had GEANT4_USE_MULTITHREADED set to ON. Because of this, I made a separate build in a directory called geant4.10.02.p02/x86_64-noMT and then built the python extensions within that install. After this, whenever I need the python extensions I switch my environment to point to the noMT library, and whenever I want to run production I switch back to the default build that was done with GEANT4_USE_MULTITHREADED=ON.

Building binaries from sources

Once you have downloaded the HDGeant4 sources from git and verified that you have installed all of the necessary external packages, you are ready to build the executables. Building consists of 3 steps: configure, setup, and make. For the configure step, go into the HDGeant4 directory that resulted from the "git clone" command described above, and look for GNUmakefile. Edit this file with your favorite text editor, and look for a list of symbols defined near the top of the file. These are the options that define the user-selectable features in the build. The CPPFLAGS settings that can be customized are found in a sequence of lines beginning with CPPFLAGS += -D<symbol>. The only settings that you will normally need to customize are G4MULTITHREADED and G4DEBUG, whose meanings are obvious. Once you are satisfied with the settings in GNUmakefile, the following steps will complete the build of hdgeant4. Before you execute the following commands, do what is necessary (see above) to make sure that when you type "g++ -v" you see a compiler version string that is 4.8.2 or greater.

$ source <your_sim-recon_environment_setup_script>
$ unset CLHEP_INCLUDE_DIR
$ make

The unset step (unsetenv if you use csh) makes sure that you do not have a standalone version of CLHEP in your setup script that might override the version that is distributed with the G4 libraries. Only the one that comes with the G4 libraries is needed for building HDGeant4.

Testing the build

Visualizing the geometry and fields

Performance and benchmarks