Table Of Contents

Previous topic

Gnomon: NuSTORM Detector Simulation

Next topic

Creating a new Processor

This Page


Want to cheat? Cheat Sheet

Software Prerequisites

Gnomon and its dependencies depends on several software packages:

  • Python 2.7.X
  • Boost::Python
  • CMake >= 2.8 (for Geant4 fetching data)
  • Matplotlib
  • xerces C++ 3.1.1 (for GDML)
  • GEANT4.9.5
  • g4py
  • ROOT 5.34
  • Genie (optional)

For development, we also recommend:

  • nose (to run unit tests)
  • coverage (to measure the source coverage of the tests)
  • pylint (to check for common problems in Python code)
  • sphinx 1.1 dev or later (to generate the documentation with mathjax support)

We will explain how to install all of these packages in the following section.

Step-by-Step Installation

Although Gnomon should run on any Linux distribution or Mac OS X, we recommend the use of Ubuntu Server 12.04 LTS or Mac OS X for Gnomon testing and development. For these instructions, we will assume you are starting with a fresh Ubuntu 12.04. Notes about using Mac OS X 10.8.1 or Scientific Linux can be found in the Frequently Asked Questions.

Steps 1 will require root privileges, but the remaining steps will be done in your home directory without administrator intervention.

Step 1: Prerequisites

The installation instructions diverge depending on which operating system you are using. Please find your package manager and distribution below. If you do not see your distribution, then please notify the developers if you are successful in installing gnomon on your unsupported distribution and any changes to the instructions you had to make.

apt-get packages from Ubuntu package manager

Many packages are required to setup your build environment to compile GEANT4 and ROOT. Fortunately, they can be installed with one very long apt-get line. Although this line may wrap in your browser, it should be executed as one line:

sudo apt-get update
sudo apt-get -y install build-essential xorg-dev \
  python-dev python-virtualenv python-numpy \
  python-pygame libglu1-mesa-dev cmake uuid-dev \
  liblapack-dev mercurial libboost-all-dev \
  libatlas-base-dev subversion gfortran libxml2-dev\
  liblog4cpp5-dev python-numpy python-scipy

easy_install msrflux virtualenv

To be able to generate the documentation, we also need these tools:

sudo apt-get install texlive dvipng

Step 2: virtualenv

The excellent virtualenv tool allows you to create an isolated Python environment, independent from your system environment. We will keep all of the python modules for Gnomon (with a few exceptions) and libraries compiled from source inside of a virtualenv in your $HOME directory:

virtualenv -p `which python` --system-site-packages $HOME/env/gnomon
cd $HOME/env/gnomon
source $HOME/env/gnomon/bin/activate

Where the last line setup the environment.

You’ll want to find the Python shared library associated with the installation referneced above with which python and make a symbolic link in $HOME/env/gnomon/lib by running:

ln -s  /usr/lib/ $VIRTUAL_ENV/lib  # Ubuntu
# ln -s /opt/local/lib/libpython2.7.dylib $VIRTUAL_ENV/lib # Mac, if in /opt
# ln -s ~/gnomon/local/lib/ $VIRTUAL_ENV/lib # SL, if install by self

Next, append the following lines to the end of $HOME/env/gnomon/bin/activate to allow codes to see locally installed libraries:

echo export LD_LIBRARY_PATH=\$VIRTUAL_ENV/lib:\$LD_LIBRARY_PATH >> $HOME/env/gnomon/bin/activate
echo export PYTHONPATH=\$VIRTUAL_ENV/lib:\$PYTHONPATH >> $HOME/env/gnomon/bin/activate
echo export EXTRAS="--with-python-incdir=\$VIRTUAL_ENV/include/python2.7 --with-python-libdir=\$VIRTUAL_ENV/lib" >> $HOME/env/gnomon/bin/activate

This will put the appropriate version of python in the path and also set the $VIRTUAL_ENV environment variable we will use in the remainder of the directions.

And create a directory where all the source codes will go:

mkdir $VIRTUAL_ENV/src/

where the instructions below will tell you where the files can be located. At the time of writing, one should just be able to run the following commands to fetch some of the various files:



easy_install couchdb # possible output
easy_install nose # for running tests
easy_install validictory # For Schema checking
easy_install python-graph-core # track extraction

Step almost 3: Pythia6

cd $VIRTUAL_ENV/src/
mkdir pythia6
cd pythia6
chmod +x

Step 3: ROOT

Gnomon uses the ROOT I/O system to record event information to disk for access later. In addition, we expect many Gnomon users will want to use ROOT to analyze the output of Gnomon.

Begin by downloading the ROOT 5.34 tarball from the ROOT download page. As of this writing, the latest version is 5.34.00. Then, from the download directory, execute the following commands:

tar xvf root_v5.34.00.source.tar.gz
mv root $VIRTUAL_ENV/src/root-5.34.00
cd $VIRTUAL_ENV/src/root-5.34.00
./configure ${EXTRAS} --with-pythia6-libdir=../pythia6/v6_424/lib --enable-gdml


When running the command make above, one can multithread the build by doing make -jN for an N-core machine. For example, in a four core laptop, one could do make -j4. This is true for all the make commands on this page.

We also need to append a source line to $VIRTUAL_ENV/bin/activate and setup ROOT:

echo source \$VIRTUAL_ENV/src/root-5.34.00/bin/ >> $VIRTUAL_ENV/bin/activate
source $VIRTUAL_ENV/src/root-5.34.00/bin/

Step 4: xerces c++

Gnomon uses xerces to help Geant4 with parsing XML that is used in our GDML geometry representation. Proceed to the xerces C++ download page and get version 3.1.1.

Proceed to your download directory then run the following commands:

tar xvf xerces-c-3.1.1.tar.gz
mv xerces-c-3.1.1 $VIRTUAL_ENV/src/
cd $VIRTUAL_ENV/src/xerces-c-3.1.1
./configure --prefix=$VIRTUAL_ENV
make install


Mac users: xerces gets confused about the architecture. It may be necessary to append CFLAGS="-arch x86_64" CXXFLAGS="-arch x86_64" to the configure command. This is only relevant if the output of ./configure does not agree with the output of uname -m.

Step 5: GEANT4

Gnomon uses GEANT4 to model particle interactions with matter. These instructions describe how to compile GEANT4 using the new CMake-based build system. As of GEANT4.9.5, CLHEP is shipped within GEANT4 along with various data files which means it is no longer necessary to download these on one’s own.

Now go to the GEANT4 Download Page and download the source code.

Next go to your download directory, run the following commands, and append to the activate script:

tar xvf geant4.9.5.tar.gz
mv geant4.9.5 $VIRTUAL_ENV/src/
cd $VIRTUAL_ENV/src/
mkdir geant4.9.5-build
cd geant4.9.5-build
make install

source $VIRTUAL_ENV/src/geant4.9.5-build/
echo source \$VIRTUAL_ENV/src/geant4.9.5-build/ >> $VIRTUAL_ENV/bin/activate

Step 6: g4py

To access GEANT4 from Python, Gnomon uses the g4py wrappers. We have had to fix a few bugs and add wrapper a few additional classes for Gnomon, so for now you will need to use our fork of g4py:

hg clone
cd g4py

export G4FLAGS="--with-g4-incdir=$VIRTUAL_ENV/include/Geant4 --with-g4-libdir=$VIRTUAL_ENV/lib"
export XERCESFLAGS="--with-xercesc-incdir=$VIRTUAL_ENV/include --with-xercesc-libdir=$VIRTUAL_ENV/lib"
export BOOSTFLAGS="--with-boost-libdir=/usr/lib"

# Mac OS X users need to uncomment this line below:
#export BOOSTFLAGS="--with-boost-incdir=/opt/local/include --with-boost-libdir=/opt/local/lib"

# select system name from linux, linux64, macosx as appropriate
./configure linux64 ${G4FLAGS} ${XERCESFLAGS} ${BOOSTFLAGS} --prefix=$VIRTUAL_ENV ${EXTRAS} --with-python-incdir=$VIRTUAL_ENV/include/python2.7 --with-python-libdir=$VIRTUAL_ENV/lib
make install

source $HOME/env/gnomon/bin/activate


If one is not careful and the python headers g4py finds, python libraries g4py finds, and python executable used to import g4py are not of the same version, then very obscure fatal errors will arise. This is the purpose of the ${EXTRAS} flag.

Now you can enable the Gnomon environment whenever you want by typing source $HOME/env/gnomon/bin/activate, or by placing that line in the .bashrc login script equivalent.

Step almost 7: Genie

Please install Genie per the directions on their website. At the time writing, only version 2.7.1 has been tested with gnomon. However, there is no svn tag for this release so you might want to try the trunk. The gnomon software will only expect a file in the GST file format so it should be independent of Genie version.

Install Genie:

svn co --non-interactive --trust-server-cert genie
cd genie

echo export GENIE=\$VIRTUAL_ENV/src/genie >> $VIRTUAL_ENV/bin/activate
echo export PYTHIA6=\$VIRTUAL_ENV/src/pythia6/v6_424/lib >> $VIRTUAL_ENV/bin/activate
echo export LHAPDF=\${GENIE}/v5_8_8/stage >> $VIRTUAL_ENV/bin/activate
echo export PATH=\$PATH:\${LHAPDF}/bin:\${GENIE}/bin >> $VIRTUAL_ENV/bin/activate
echo export PYTHONPATH=\$PYTHONPATH:\${LHAPDF}/lib/python2.6/site-packages/ >> $VIRTUAL_ENV/bin/activate
echo export LHAPATH=\`lhapdf-config --pdfsets-path\` >> $VIRTUAL_ENV/bin/activate
echo export LLP=LD_LIBRARY_PATH >> $VIRTUAL_ENV/bin/activate
echo eval \${LLP}=\${!LLP}:\${LHAPDF}/lib:\${GENIE}/lib:\${PYTHIA6} >> $VIRTUAL_ENV/bin/activate

source $VIRTUAL_ENV/bin/activate

./src/scripts/build/ext/ 5.8.8 --refetch

source $VIRTUAL_ENV/bin/activate

./configure --with-lhapdf-lib=$LHAPDF/lib --with-lhapdf-inc=$LHAPDF/include

make  # make install prepends 'local', so we don't use it

At this point you should find the command gevgen in your bin folder. If you do not, look for errors in the previous command’s output. You may need to run make twice.

Step 7: gnomon

Now you are ready to get gnomon. One can currently work only from the developer’s version. To get the code, run:

hg clone
cd gnomon

There is no installation for the actual gnomon code since it’s written in an interpreted language (i.e. python). In order to tell Python where to look for gnomon, you must append $VIRTUAL_ENV/bin/activate with the following:

echo export PYTHONPATH=\$VIRTUAL_ENV/src/gnomon/gnomon:\$PYTHONPATH >> $VIRTUAL_ENV/bin/activate

Then you are ready to move to the tutorial (or examples in the gnomon-analysis branch).