Difference between revisions of "Getting started with GlueX Software"

Revision as of 15:55, 5 December 2006

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

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:

1. Getting and compiling the source code
2. Configuring and running the hdgeant program
3. Creating a JANA-based program for reconstruction and histogramming
4. Running said JANA program and analyzing the results

===================================================

1. 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, versions known to have compiled/linked are here:

XERCES

• xerces-c-src_2_7_0.tar.gz
• xerces-c-src_2_5_0.tar.gz

XERCES Perl module

• XML-Xerces-2.7.0-0.tar.gz
• XML-Xerces-2.7.0-0.tar.gz

I'm going to 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.

(In order to build the supporting tools which are required for modifying the geometry) you'll need to have XERCES installed and the xerces perl module. You can download these for free from the web from []. After both of these packages are installed, make sure your environment has the appropriate variables set. Here is a list of the variables I have set for my CUE account:

setenv HALLD_HOME /group/halld/Software/builds/latest setenv JAVAROOT /apps setenv HALLD_EXTERNALPACKAGES /group/halld/Software/ExternalPackages setenv XERCESCROOT ${HALLD_EXTERNALPACKAGES}/xerces-c-src_2_5_0 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 setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${XERCES_LIB} setenv PATH ${HALLD_EXTERNALPACKAGES}/bin:${HALLD_EXTERNALPACKAGES}/bin/${OSNAME}:${PATH}

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. 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 - - - - - - - - - - Since we're only interested in HDGeant here, we just need to build the hddsGeant3.F file from the XML source.

1. cd into "src/programs/Simulation/hdds" and 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. The make file also copies it into ../HDGeant where is will be compiled and used.

It's worth noting here that this is where you would make changes to the geomtery. The .xml files kept in the hdds directory can be modified and the the hddsGeant3.F regenerated by re-running "make hddsGeant3.F".

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 2 different executables gxint and hdgeant. They will be placed in the the $HALLD_HOME/bin/$OSNAME directory. (for example ~/HallD/bin/Linux).

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.

Looking at the output - - - - - - - - - - - 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).