Software/Geant4/Installation

From PBTWiki
Revision as of 11:47, 2 April 2016 by SimonJolly (talk | contribs)
Jump to navigation Jump to search

Installation of Geant4 and supporting packages in UCL PBT environment on HEP Linux servers

This document describes the steps taken to install Geant4 and related software within the PBT environment on the UCL HEP Linux servers.

  • Title: Installation of Geant4 and supporting packages in UCL PBT environment on HEP Linux servers
  • Author: Matt Easton
  • Date created: 07/08/2014
  • Version: 0.29
  • Date modified: 30/09/2014

The environment described here is the combination of files, folders, settings and user interface that allow users to make use of Geant4 and related software packages for particle beam therapy simulations.

Accessing the environment requires the following:

  • Access to the filesystem and required folders.
  • Terminal access to run simulations.
  • A visualisation engine such as OpenGL on X (optional).
  • setting environment variables to point to installed software and scripts.

Two separate environments are provide for PBT simulations: the production environment for general use and the development environment for testing changes or updates to the code.

Folder structure

Disk

There is a separate (large) disk for PBT work mounted on the Linux system at /unix/pbt.

Software

All software is enclosed in a folder at /unix/pbt/software.

Production and development environments

The production and development environments are kept in separate folders:

  • /unix/pbt/software/prod
  • /unix/pbt/software/dev

Source code

Source code for building and installing software packages is kept in a separate folder at /unix/pbt/software/src.

GNU Stow

Software is installed using the GNU Stow package for separating package code and linking to standard folders.

At installation time, each software package will be installed into a holding folder (such as /unix/pbt/software/dev/stow/geant4-10.00.p02) with subfolders under this holding folder for the usual Linux software folders such as bin and lib.

The GNU Stow package then handles linking of the software from the holding folders into the main folders of the relevant system. For example, the file /unix/pbt/software/dev/bin/geant4-config is a soft link to /unix/pbt/software/dev/stow/geant4-10.00.p02/bin/geant4-config.

Links are added by calling stow, deleted by calling stow -D, and checked by calling chkstow. See GNU Stow package documentation for more details.

Scripts

Access to the PBT production and development environments is implemented by two scripts, pbt.sh and pbt-dev.sh. These scripts are located in the bin folders of the production and development environments, respectively, and should be called directly by the user to set up all paths and environment variables required to make use of Geant4 and related packages.

Aliases can be set up by the users to simplify running the scripts, such as:

alias pbt='source /unix/pbt/software/prod/bin/pbt.sh'
alias pbt-dev='source /unix/pbt/software/dev/bin/pbt-dev.sh'

Two other scripts are required as functions used by the setup scripts.

/unix/pbt/software/prod/bin/pbt.sh

This is a simple script that launches a new shell (using the Developer Toolset 2) and calls the setup script pbt.bashrc.

The Developer Toolset 2 (devtoolset-2) is a Linux software collection providing various tools for developers, most notably including a newer version of GCC (the GNU Compiler Collection).

/unix/pbt/software/prod/bin/pbt.bashrc

This is a bash startup script that sets various environment variables and other settings so that all PBT software is available to use.

Steps taken:

  1. Run the user's own .bashrc
  2. Add locations to path variables
  3. Define colours for scripts, prompt, etc
  4. Greeting with information for users
  5. Notify user on exiting environment
  6. Modify prompt to show environment name
  7. Run Geant4 setup script and set additional settings
  8. Remove duplicates from path variables

/unix/pbt/software/prod/bin/definecolours.sh

This script defines various variables to represent colours for printing to the terminal and to file.

/unix/pbt/software/prod/bin/checkversions.sh

This script checks the versions (and optionally the paths/locations) of important software packages used in the PBT environment.

Installations

For each software package, the installation information is listed below. The basic method used is as follows:

  1. Download the source tarball latest version to the /unix/pbt/software/src folder.
  2. Extract the tarball to a subfolder within the src folder using tar -xvzf <filename>.tar.gz.
  3. Create a build folder at /unix/pbt/software/build and set the working directory here.
  4. Run the specific configure, build and install steps for the package.
  5. Remove the build folder and extracted source folder, but keep the source tarball.

The configure, build and install steps may be different for each package, and this is described per package below. However, in most cases the steps follow the general steps below:

  1. Change working directory to the build folder.
  2. Run the configuration script from the source folder to set the build options, including the customised installation prefix.
  3. Build the code.
  4. Install the code to the sandbox folder.
  5. Link to the sandboxed files using GNU Stow.

The order of installation is important, as some packages depend on having the other packages first. In some cases, installations will be successful if carried out in the wrong order, but some features will be disabled that should be enabled. The order of packages described below is the order in which these packages were installed into the PBT environment.

GNU Stow

Website
http://www.gnu.org/software/stow/
Latest version
2.2.0 (18 February 2012)
Source tarball
src/stow/stow-2.2.0.tar.gz

Installation commands:

cd /unix/pbt/software/build
../src/stow-2.2.0/configure --prefix=/unix/pbt/software/dev
make
make install prefix=/unix/pbt/software/dev/stow/stow-2.2.0

Note that as GNU Stow is not yet installed, it cannot be used to stow itself... Hence this part has to be done manually. This is much easier when no other software has yet been installed, as in the commands below.

The hidden file .stow informs GNU Stow that the stow folder is a special folder and should not be altered by the software.

Stow commands:

cd /unix/pbt/software/dev
ln -s stow/stow-2.2.0/* .
touch stow/.stow

Qt4

Website
http://qt-project.org
Latest version
4.8.6 (24 April 2014)
Source tarball
src/geant4-prerequisites/qt/qt-everywhere-opensource-src-4.8.6.tar.gz

Notes:

  • Qt5 version 5.3.1 is available but not officially supported by Geant4.
  • For installation, Qt4 does not support installation into a sandbox directory (i.e. there are no options prefix or DESTDIR defined for command make install). This has to be managed manually as can be seen in the installation and stow commands.
  • The tarball extracts to a rather long folder name. To follow the installation commands below, rename this to src/qt-4.8.6.

Installation commands:

cd /unix/pbt/software/build
../src/qt-4.8.6/configure -prefix /unix/pbt/software/dev -prefix-install -docdir /unix/pbt/software/dev/share/doc/qt4 -plugindir /unix/pbt/software/dev/share/qt-4.8.6/plugins -importdir /unix/pbt/software/dev/share/qt-4.8.6/imports -datadir /unix/pbt/software/dev/share/qt-4.8.6/data -translationdir /unix/pbt/software/dev/share/qt-4.8.6/translations -examplesdir /unix/pbt/software/dev/share/qt-4.8.6/examples -demosdir /unix/pbt/software/dev/share/qt-4.8.6/demos -release -opensource -optimized-qmake -opengl
make
make install

Stow commands:

cd /unix/pbt/software/dev
mkdir -p stow/qt-4.8.6/bin
mv bin/assistant bin/designer bin/lconvert bin/linguist bin/lrelease bin/lupdate bin/moc bin/pixeltool bin/q* bin/rcc bin/uic* bin/xml* stow/qt-4.8.6/bin/
mv include stow/qt-4.8.6/
mkdir -p stow/qt-4.8.6/lib
mv lib/libQt* lib/pkgconfig stow/qt-4.8.6/lib/
mkdir -p stow/qt-4.8.6/share/doc
mv share/doc/qt4 stow/qt-4.8.6/share/doc/
mv share/qt-4.8.6 stow/qt-4.8.6/share/
mv tests stow/qt-4.8.6/share/
cd /unix/pbt/software/dev/stow
stow qt-4.8.6

Xerces-C

Website
http://xerces.apache.org/xerces-c/
Latest version
3.1.1 (27 April 2010)
Source tarball
src/geant4-prerequisites/xerces-c/xerces-c-3.1.1.tar.gz

Notes:

  • Version 3.0 is installed on the server, but some applications need the later version.

Installation commands:

cd /unix/pbt/software/build
../src/xerces-c-3.1.1/configure --prefix=/unix/pbt/software/dev
make
make install prefix=/unix/pbt/software/dev/stow/xerces-c-3.1.1

Stow commands:

cd /unix/pbt/software/dev/stow
stow xerces-c-3.1.1

Coin3D

Website
http://bitbucket.org/Coin3D/coin/wiki/Home
Latest version
3.1.3 (13 February 2012)
Source tarball
src/geant4-prerequisites/coin3d/Coin3d-3.1.3.tar.gz

Notes:

  • There are a number of programming errors in the Coin3D code. Most can be ignored and skipped over by adding the compiler flag fpermissive at the configuration step.
  • One error needs to be fixed in the source code - the file src/fonts/freetype.cpp needs two lines inserted before the line #include fonts/freetype.h: #include <cstdlib> #include <cmath> This fix needs to be carried out (manually) using the nano editor, if the exact installation commands below are being used.

Installation commands:

cd /unix/pbt/software/build
nano ../src/Coin-3.1.3/src/fonts/freetype.cpp
../src/Coin-3.1.3/configure --prefix=/unix/pbt/software/dev CXXFLAGS=-fpermissive
make
make install prefix=/unix/pbt/software/dev/stow/coin-3.1.3

Stow commands:

cd /unix/pbt/software/dev/stow
stow coin-3.1.3

SoXt library

Website
http://bitbucket.org/Coin3D/soxt
Latest version
1.3.0 (2 March 2010)
Source tarballs
src/geant4-prerequisites/coin3d/SoXt-1.3.0.tar.gz and src/geant4-prerequisites/coin3d/sogui-2011-12-03.tar.gz

Notes:

  • This library is used by Coin3D and is in fact the link between Geant4 and Coin3D.
  • Coin3D must be installed before SoXt.
  • Geant4 must be installed after SoXt.
  • There are a number of programming errors here as well. Again, the compiler flag fpermissive is required at the configuration step.
  • The configuration tool cannot find the libraries it needs unless the environment variable LD_RUN_PATH is manually set to include /unix/pbt/software/dev/lib
  • Part of the code required for compilation has been removed to a separate project called SoGUI. This GUI code needs to incorporated into the library code before compilation. The SoGUI source code is available in a separate tarball, src/geant4-prerequisites/coin3d/sogui-2011-12-03.tar.gz.
  • Both tarballs extract to rather long folder names. To follow the installation commands below, rename these to src/soxt and src/sogui before starting the installation.

Installation commands:

cd /unix/pbt/software/build
mv ../src/sogui ../src/soxt/src/Inventor/Xt/common
export LD_RUN_PATH=/unix/pbt/software/dev/lib
../src/soxt/configure --prefix=/unix/pbt/software/dev CXXFLAGS=-fpermissive
make
make install prefix=/unix/pbt/software/dev/stow/soxt-1.3.0
unset LD_RUN_PATH

Stow commands:

cd /unix/pbt/software/dev/stow
stow soxt-1.3.0

DAWN

Website
http://geant4.kek.jp/~tanaka/DAWN/About_DAWN.html
Latest version
3.90b (1 September 2010)
Source tarball
src/geant4-addons/dawn/dawn_3_90b.tar.gz

Notes:

  • DAWN uses a different type of configure script, and it is not possible to build the software in separate directory from the source. The configure script must be run inside the source directory.
  • The configure script does not accept the installation prefix as a command-line parameter, but this can be set at the interactive prompt in the configure script.
  • The makefile also does not accept an installation prefix to give the stow directory. This means that the four files installed for DAWN need to be moved manually after installation, and then stowed properly.

Options for configure script interactive prompt:

  • Compiler name: g++
  • Optimisation option: -O2
  • Window shell name: wish
  • Directory to install executable files: /unix/pbt/software/dev/bin

Installation commands:

./configure
make
make install

Stow commands:

cd /unix/pbt/software/dev
mkdir -p stow/dawn-3.90b/bin
mv bin/dawn stow/dawn-3.90b/bin/
mv bin/DAWN_GUI stow/dawn-3.90b/bin/
mv bin/dawnunixd stow/dawn-3.90b/bin/
mv bin/dawninetd stow/dawn-3.90b/bin/
cd stow
stow dawn-3.90b

HepRApp

Website
http://www.slac.stanford.edu/~perl/HepRApp/
Latest version
3.15.0 (30 March 2007)
Source file
src/geant4-addons/heprapp/HepRApp.jar

Note that this is a Java program and is very simply installed by copying the .jar file.

Installation commands:

cd /unix/pbt/software
mkdir -p prod/stow/heprapp-3.15.0/bin
cp src/geant4-addons/heprapp/HepRApp.jar prod/stow/heprapp-3.15.0/bin

Stow commands:

cd /unix/pbt/software/dev/stow
stow heprapp-3.15.0

Java Analysis Studio 3 (Jas3)

Website
http://jas.freehep.org/jas3/
Latest version
3.0.12 (30 July 2014) Installed version: 3.0.9
Source tarball
src/geant4-addons/wired4/jas-assembly-3.0.9-distribution.tar.gz

Notes:

  • This is also a Java program, but with multiple files and a library subfolder.
  • The files jas3.* are not needed on our Linux system, and can be omitted for clarity in the bin folder.
  • As the program does not require compilation, the stowed folder can be copied directly from the development environment to the production environment.
  • Installing a new version in the development environment will simply require copying the jas3 executable and the lib folder into a new stow folder.
  • The latest version has not yet been tested, hence installing version 3.0.9 in the production environment.
  • Version 3.0.11 was tested and found to crash repeatedly, hence version 3.0.12 will need to be tested in the development environment to see if this has been fixed.

Installation commands:

cd /unix/pbt/software
cp dev/stow/jas-assembly-3.0.9 prod/stow/

Stow commands:

cd /unix/pbt/software/dev/stow
stow jas-assembly-3.0.9

WIRED 4 plugin

Website
http://wired.freehep.org
Latest version
4.3.6

This is a plugin for Java Analysis Studio 3. It is downloaded and installed through the plugin manager.

Installation instructions:

  1. From within the PBT environment, run Java Analysis Studio 3 by typing jas3.
  2. From the View menu, select Plugin Manager.
  3. If the plugin is already installed, it will be visible in the Installed tab of the plugin manager, filed in the system group.
  4. If the plugin is not installed, it can be found in the Available tab, filed under hep > visualisation.
  5. Select the WIRED 4 plugin and choose the option Install in system extension directory.
  6. Click Install selected plugins.
  7. All required dependencies will be installed automatically.

Note that installing plugins will create, or change the contents of, the extensions folder relative to the jas3 executable. These changes will normally be picked up without needing to re-stow the folder.

gMocren

Website
http://geant4.kek.jp/gMocren/
Latest version
unknown Installed version: 4.2 (29 September 2011)
Source tarball
src/geant4-addons/gmocren/gMocren4-slc5.7-64bit-20110929.tar.gz

This specialist medical physics software is only available on request from the developers. The tarball contains compiled binaries for the Scientific Linux 5 servers, rather than source code, so installation on other machines will need a different version to be requested from the developers.

As the software is already compiled, installation only requires moving these files (extracted from the tarball) to the right place.

Installation commands:

cd /unix/pbt/software
mkdir -p prod/stow/gmocren-4.2
mv src/gMocren4 prod/stow/gmocren-4.2/bin

Stow commands:

cd /unix/pbt/software/dev/stow
stow gmocren-4.2

Geant4

Website
http://geant4.web.cern.ch/geant4/
Latest version
10.0.2 (13 June 2014)
Source tarball
src/geant4/geant4.10.00.p02.tar.gz

All the required software has now been installed, and GEANT4 itself can finally be installed.

Notes:

  • There are a number of ways to configure the software before building. The simplest is cmake, where each configuration option can be seen clearly and set individually. The command below bypasses this to use an explicit set of options.
  • The makefile doesn't support make install prefix, and so DESTDIR must be used instead, and the files moved after installation.

Installation commands:

cmake -DCMAKE_INSTALL_PREFIX="/unix/pbt/software/dev" -DCMAKE_INSTALL_CONFIG_NAME="Release" -DGEANT4_BUILD_MULTITHREADED=ON -DGEANT4_INSTALL_DATA=ON -DGEANT4_BUILD_EXAMPLES=OFF -DGEANT4_BUILD_TESTS=OFF -DGEANT4_ENABLE_TESTING=OFF -DGEANT4_BUILD_STORE_TRAJECTORY=ON -DGEANT4_BUILD_VERBOSE_CODE=ON -DGEANT4_USE_G3TOG4=ON -DGEANT4_USE_GDML=ON -DGEANT4_USE_INVENTOR=ON -DGEANT4_USE_NETWORKDAWN=ON -DGEANT4_USE_NETWORKVRML=ON -DGEANT4_USE_OPENGL_X11=ON -DGEANT4_USE_QT=ON -DGEANT4_USE_RAYTRACER_X11=ON -DGEANT4_USE_SYSTEM_CLHEP=OFF -DGEANT4_USE_SYSTEM_EXPAT=ON -DGEANT4_USE_SYSTEM_ZLIB=OFF -DGEANT4_USE_USOLIDS=OFF -DGEANT4_USE_WT=OFF -DGEANT4_USE_XM=ON -DINVENTOR_INCLUDE_DIR=/unix/pbt/software/dev/include -DINVENTOR_LIBRARY=/unix/pbt/software/dev/lib/libCoin.so -DINVENTOR_SOXT_INCLUDE_DIR=/unix/pbt/software/dev/include -DINVENTOR_SOXT_LIBRARY=/unix/pbt/software/dev/lib/libSoXt.so -DQT_QMAKE_EXECUTABLE=/unix/pbt/software/dev/bin/qmake -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=OFF -DCMAKE_COLOR_MAKEFILE=ON -DCMAKE_USE_RELATIVE_PATHS=OFF -DCMAKE_VERBOSE_MAKEFILE=OFF ../src/geant4.10.00.p02
make
make install DESTDIR=/unix/pbt/software/dev/stow/geant4-10.0.2

Stow commands:

cd /unix/pbt/software/dev/stow
mv geant4-10.0.2/unix/pbt/software/dev/* geant4-10.0.2/
rm -r geant4-10.0.2/unix
stow geant4-10.0.2

Testing

Software package tests

GEANT4 built-in tests

The GEANT4 software includes some system tests, which can be included in the installation command via the options -DGEANT4_BUILD_TESTS=ON -DGEANT4_ENABLE_TESTING=ON. However, these tests are only used for testing of the system, and are not included in the distributed source tarballs, nor supported for use by end-users. Therefore, these cannot easily be used for validation of the production system installation.

GEANT4 examples

One test of the GEANT4 software after installation is to make sure that all examples can be run and produce the expected results.

Notes:

  • The examples can be built at installation time using the command -DGEANT4_BUILD_EXAMPLES=ON, but this throws up a number of problems because not all installation requirements are met. It is easier to build and run the examples after the installation is complete.
  • Environment variable G4SHARE is defined in the environment scripts pbt.bashrc and pbt-dev.bashrc, along with the variable G4VERSION. For the current installation, the location stored in this variable is /unix/pbt/software/dev/share/Geant4-10.0.2

The following errors and warnings were seen while configuring examples:

  • Cannot find AIDA package
  • Cannot find HBOOK package
  • Cannot find HepMC package
  • Cannot find Pythia6 package
  • Cannot find GCCXML These packages are optional, but some of the examples are designed to demonstrate the connection with these packages. Note that some filetypes, such as AIDA and HBOOK, do in fact have viewers installed in the PBT environments, but these are not available to the GEANT4 system. This what the errors are reporting.

Basic examples

B1
cp -r ${G4SHARE}/examples/basic/B1 . mkdir build cd build cmake ../B1 make ./exampleB1 exampleB1.in | tee exampleB1.new.out grep -B0 -A3 "End of Global Run" exampleB1.out > exampleB1.old.results grep -B0 -A3 "End of Global Run" exampleB1.new.out > exampleB1.new.results diff exampleB1.old.results exampleB1.new.results

There seem to be significant differences in the simulation results compared to the included exampleB1.out file. The reason for these differences is unclear.