Getting started with GlueX Software
This is derived from the original web document "Getting started with HDGeant"
D. Lawrence 11/11/04
D. Lawrence 4/6/06 Updated
D. Lawrence 12/5/06 Converted to Wiki
D. Lawrence 1/18/07 Finished Converting to Wiki
Contents
Overview
This document gives the bare minimum to get you up and going with running the GlueX GEANT-based simulation program hdgeant and looking at the output. More details are given in other HOWTOs (to be written).
The basic steps to running and analyzing a GlueX simulation are:
- Getting and compiling the source code
- Configuring and running the hdgeant program
- Creating a JANA-based program for reconstruction and histogramming
- Running said JANA program and analyzing the results
Getting and compiling the source code
The Hall-D specific source code is currently being kept in a Subversion repository on the JLab CUE. You must have a CUE account and you must belong to the "halld" unix group. (Contact the JLab computer center for help with both of these.)
The source relies on several software packages that were not written for Hall-D and are not kept in its repository. These must be downloaded and installed prior to compiling the Hall-D source. For convenience, some versions known to have compiled/linked are here.
JANA
Make sure you set your JANA_HOME environment variable.
CERNLIB
Make sure you set your CERN and CERN_LEVEL environment variables and that the cernlib script is in your path as it will be used by the makefiles.
ROOT
Make sure your ROOTSYS environment variable is set and that the root-config script is in your path. Also, make sure the ROOT shared libraries directory (usually $ROOTSYS/lib) is in your LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on OS X) environment variable.
Note: You only need the XERCES packages if you're going to be modifying the geometry or the data model.
XERCES
(note that binaries exist on the JLab CUE for certain platforms:)
XERCES Perl module
Download and install the needed packages from the above locations.
We'll assume you are working on a machine outside of JLab.
(All of these instructions will work onsite as well.)
First, you will need to create a directory where your files will be kept. (I use a directory called HallD in my home directory.) Set your HALLD_HOME environment variable to point to this directory.
You should also set your OSNAME environment variable to indicate the OS and architecture on which you are working.
As a summary, here are the environment variables you should have set. Strictly speaking, not all of these are required, but this is a set that is known to be sufficient
setenv OS `/bin/uname -s`
setenv ARCH `/bin/uname -p`
setenv OSNAME ${OS}-${ARCH}
setenv JANA_HOME /group/12gev_phys/builds/LATEST
setenv HALLD_HOME ${HOME}/HallD
setenv JANA_PLUGIN_PATH ${HALLD_HOME}/lib/${OSNAME}
setenv JAVAROOT /apps
setenv HALLD_EXTERNALPACKAGES /group/halld/Software/ExternalPackages
setenv XERCESCROOT ${HALLD_EXTERNALPACKAGES}/xerces-c-src_2_7_0.${OSNAME}
setenv XERCES_INCLUDE ${HALLD_EXTERNALPACKAGES}/include
setenv XERCES_LIB ${HALLD_EXTERNALPACKAGES}/lib/${OSNAME}
setenv PERL5LIB ${HALLD_EXTERNALPACKAGES}/perl_mods/lib/site_perl/5.8.2/i686-linux
in addition, your PATH and (DY)LD_LIBRARY_PATH environment variables should be set to include some of these directories:
setenv PATH ${PATH}:${JANA_HOME}/bin/${OSNAME}:${HALLD_HOME}/bin:${HALLD_HOME}/bin/${OSNAME}:${HALLD_EXTERNALPACKAGES}/bin:${HALLD_EXTERNALPACKAGES}/bin/${OSNAME}:${ROOTSYS}/bin:${CERN}/${CERN_LEVEL}/bin
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${ROOTSYS}/lib:${XERCES_LIB}
NOTES: - You MUST set your JAVAROOT environment variable or else the
schema-hddm script will fail with a very misleading error message. This should point to the directory containing bin/java. For example, if your java executable is /usr/bin/java (i.e. this is what "which java" returns) then you should set JAVAROOT to /usr.
- The HALLD_EXTERNALPACKAGES environment variable is not required. It is
just convienient for defining the other environment variables since things like xerces must be install in a non-standard place on the CUE.
CHECKING OUT THE CODE
1. Check that subversion is installed on your system. Many Linux distributions now install subversion with the development tools so it may already be there (check for an executable named "svn").
2. Check out the needed files with:
svn co https://halldsvn.jlab.org/repos/trunk/src
If your svn binary doesn't support the https access method, you can use the following. Note however that THIS IS NOT RECCOMMENED since the automated e-mail notification system does not work properly with this method.
svn co svn+ssh://svn.jlab.org/group/halld/Repositories/svnroot/trunk/src
COMPILING THE CODE
If you do not need to modify the geometry, then you can skip item 1.) below and go straight to item 2.).
Modifying the Geometry
1. cd into "src/programs/Simulation/hdds". Here you will find a number of XML files that define the geometry of the GlueX detector in the simulation. Modify the appropriate XML file(s) and then do a "make hddsGeant3.F". This will build the hdds-geant executable and run it on the main_HDDS.xml to produce hddsGeant3.F. The hddsGeant3.F file is FORTRAN source which contains all of the geometry definitions for the entire GlueX detector. After generating the hddsGeant3.F file, you will need to copy it into ../HDGeant.
Note that if you make changes to the geometry that you feel should be propagated back into the repository, you should contact Richard Jones (richard.t.jones@uconn.edu) who is the acting gatekeeper for the geometry and simulation just to make sure he's aware of the changes and that they are implemented in a consistent way.
Building HDGeant
2. Now cd into the src/programs/Simulation/HDGeant directory and just type "make". Don't worry if it seems to take a long time to compile hddsGeant3.F. This is a HUGE file so just be patient. When it is all done, you should end up with a few executables including hdgeant. They will, by default, be installed in the $HALLD_HOME/bin/$OSNAME directory. (for example ~/HallD/bin/Linux-i686).
RUNNING HDGEANT
There are two versions of HDGeant. One is just called "hdgeant" and is a batch-mode version. The other is "gxint" and is the interactive version. The README file in the HDGeant directory gives some instructions on running the interactive version.
I'll just give a couple of hints here (note that even though I use "hdgeant", these should be valid for the gxint executable as well):
1. When running hdgeant, make sure the control.in and dsolenoid.table
files exist in the current working directory.
2. To test hdgeant without an input file of generated events,
just comment out the "INFILE" and "BEAM" lines in control.in
placing a "C" as the first character in each line.
3. The simulation produces several output files. The one with the
detector responses that you want is called hdgeant.hddm.
Reading in Simulated Data
- - - - - - - - - - - There are a few ways to look at the output data from hdgeant. The first is to checkout and build the hddm package : cvs -d davidl@cvs.jlab.org:/group/halld/Repositories/cvsroot co hddm There is a tool called hddm-xml provided by this package that will display the contents in XML form.
The second option is to build "hd_dump" which is based on the DANA framework. The source code for this program already exists in the src directory: 1. cd into src/library and do a "make" 2. cd into src/programs/Analysis/hd_dump and do "make" Running hd_dump with no arguments will print a usage message.
The third (and probably most useful) option is to build a custom executable that can be used to define and fill your own histograms. To do this, take a look at the example program:
src/programs/Analysis/hd_ana
Try building and using it as-is first to make sure it all works. It will produce a couple of sample histograms. The only files you'll need to modify are the MyProcessor.cc and MyProcessor.h (All of the work is done in MyProcessor.cc).
