Difference between revisions of "Getting started with GlueX Software"

From GlueXWiki
Jump to: navigation, search
(Added instructions on compiling libraries prior to hdgeant)
(add section linking to example build script)
Line 174: Line 174:
$HALLD_HOME/bin/$OSNAME directory.
$HALLD_HOME/bin/$OSNAME directory.
(for example ~/HallD/bin/Linux-i686).
(for example ~/HallD/bin/Linux-i686).
==Example Script==
Assuming that you have the supporting software (i. e., non-GlueX-related) built on your machine, there is an [[example build script|example script]] that summarizes the steps necessary to build JANA and the entire Hall D source tree.

Revision as of 17:34, 3 October 2007

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


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

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.


Make sure you set your JANA_HOME environment variable.


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.

Check here for possible issues with CERNLIB installation.


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.


(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 JAVAROOT /apps
setenv HALLD_EXTERNALPACKAGES /group/halld/Software/ExternalPackages
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:



- 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.


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 Libraries

1. Make sure your HALLD_HOME and JANA_HOME environment variables are set and cd into src/libraries and type "make". This should build all of the Hall-D libraries and place them in $HALLD_HOME/lib/$OSNAME.

If you do not need to modify the geometry, then you can skip item 2. below and go straight to item 3..

Modifying the Geometry

2. 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

3. 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).

Example Script

Assuming that you have the supporting software (i. e., non-GlueX-related) built on your machine, there is an example script that summarizes the steps necessary to build JANA and the entire Hall D source tree.


I've really only used the batch version of HDGeant called hdgeant so that is what these instructions focus on.

I'll just give a couple of hints here:

1. When running hdgeant, make sure the control.in and solenoid.map files exist in the current working directory. These can be found in the src/programs/Simulation/HDGeant directory.

The control.in file should be edited to suit your specific simulation. Most importantly, you need to define the source of events. There are 3 main options which are documented in the example control.in file. They are:

  • coherent bremstrahlung photon generator(built-in)
  • single particle gun(built-in)
  • read events from an external file in HDDM (Hall-D Data Model) format.

An HDDM file can be generated using the genr8 program (src/programs/Simulation/genr8) to first generate the events and put them in a file in ASCII format. The program genr8_2_hddm (src/programs/Simulation/genr8_2_hddm) can then be used to convert this into HDDM format.

2. 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 build the hddm package (src/packages/Analysis/hddm) Note that yoou will need XERCES installed. There is a tool called hddm-xml provided by this package that will display the contents of an HDDM file in XML form. This is useful to at least see that you are getting hits.

The second and preferred method is via DANA. DANA is the Hall-D implementation of the JANA reconstruction framework. The DANA framework can read in an HDDM file using the libHDDM.a library (src/programs/libraries/HDDM) and create C++ objects from it that can then be used to access the event data.


A simple utility program is available called "hd_dump" which is based on the DANA framework. The source code for this program already exists in the src directory tree. To build it:

  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. Essentially through, you just give it the name of the hdgeant.hddm file when you run it. It will list the objects available event by event (pausing for user input after each event). If you give it any "'-Dobjectname" options on the command line, it will attempt to print the contents of all objects of type objectname as well.

Making ROOT histograms in DANA

For Hall-D we use the JANA framework for reconstruction of event-based data. The Hall-D implementation of JANA is called DANA just to distinguish between the two. Documentation on JANA can be found on the JANA website.

The main idea behind JANA is that it passes around C++ objects that contain the data of interest. In order to access the data you want, you must first figure out what object(s) contain it. You can browse or search for the objects you need in the doxygen generated on-line documentation.

Several programs exist that can be used to make ROOT histograms and Trees using HDDM files as inputs. There is no such thing, however, as a generic HDDM to ROOT converter program. The data model is large enough that most jobs will only ever need a fraction of the information so writing out everything would use up resources uneccessarily. The programs that are available can be found in the src/program/analysis directory.

Using plugins

All DANA executables can have plugins attached at run time to extend the functionality of the program. For those who are unfamiliar with the term, a plugin is just a dynamically linked object that contains routines that can be accessed by a running executable.

Several plugins have been written that can add histograms/trees to a ROOT file. For example, the "mcthrown_hists plugin will create histograms and fill them with the "thrown" values from Monte Carlo data. There is also a cdc_hists plugin that will produce histograms related specifically to the CDC. In general, these plugins will create a separate directory in the ROOT file to place their histograms/trees. This allows mulitple plugins to be attached to the same executable without risk of conflict between histogram names. Source code for the plugins resides in the src/programs/Analysis/plugins directory.

Although a plugin can be attached to any DANA program, a generic program hd_root exists that serves as a shell specifically written for this task. For example, to create a root file with the thrown values histograms and the histograms used to study the acceptance of the GlueX detector, type this:

>hd_root --plugin=mcthrown_hists --plugin=acceptance_hists hdgeant.hddm

This will create a ROOT file called hd_tree.root. Inside the file would be two directories called "THROWN" and "ACCEPTANCE" containing the histograms produced by the respective plugins.

You can create your own plugin using one of the existing plugins as a template.

Building a custom executable

The last option is to just build your own custom executable that can be used to define and fill your histograms. To do this, take a look at the example program:


Try building and using it as-is first to make sure it all works. It will produce a couple of sample histograms. To customize hd_ana, the only files you'll need to modify are the MyProcessor.cc and MyProcessor.h (All of the work is done in MyProcessor.cc).