Difference between revisions of "Getting started with GlueX Software"

From GlueXWiki
Jump to: navigation, search
(Replaced svn+ssh method with file method)
(Getting and compiling the source code)
Line 64: Line 64:
  
 
'''XERCES'''
 
'''XERCES'''
 +
* [http://mirror.switch.ch/mirror/apache/dist/xerces/c/sources/xerces-c-src_2_8_0.tar.gz xerces-c-src_2_8_0.tar.gz]
 
* [http://www.jlab.org/Hall-D/software/xerces-c-src_2_7_0.tar.gz xerces-c-src_2_7_0.tar.gz]
 
* [http://www.jlab.org/Hall-D/software/xerces-c-src_2_7_0.tar.gz xerces-c-src_2_7_0.tar.gz]
 
* [http://www.jlab.org/Hall-D/software/xerces-c-src_2_5_0.tar.gz xerces-c-src_2_5_0.tar.gz]
 
* [http://www.jlab.org/Hall-D/software/xerces-c-src_2_5_0.tar.gz xerces-c-src_2_5_0.tar.gz]

Revision as of 09:33, 26 March 2008

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

D. Lawrence 2/4/08 Tweaked for calibDB among others

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

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.

You will also need to set your JANA_CALIB_URL environment variable as is described below.

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.

Check here for possible issues with CERNLIB installation.

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


XALAN-Java


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 in a pinch by accessing the repository directly from your CUE account. Note this means if you want to work on the files on a remote system, you'll have to copy them there and them copy them back to the CUE in order to commit any changes.

First, log into a CUE computer like jlabl1.jlab.org. Then ...

svn co file:///group/halld/Repositories/svnroot/trunk/src

COMPILING THE CODE

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.

RUNNING HDGEANT

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
    file exists in the current working directory. This can be found in the
    src/programs/Simulation/HDGeant directory.
  2. Make sure you JANA_CALIB_URL environment variable is set
    and points to the location of the calibration files. At this point,
    the calibration files are text files stored in the repository
    and can be checked out via:
    svn co https://halldsvn.jlab.org/repos/trunk/calib
    Example:
    The root of your calibration files tree is /home/jdoe/HallD/calib
    setenv JANA_CALIB_URL file:///home/jdoe/HallD/calib


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 any of the following programs:

  • genr8 (src/programs/Simulation/genr8) generator for specific reaction via isobar model
  • bggen (src/programs/Simulation/bggen) generator for full hadronic photoproduction spectrum
  • genphoton (src/programs/Simulation/genphoton) external particle gun for single photons
  • genpi (src/programs/Simulation/genpi) external particle gun for single pions

The program genr8_2_hddm (src/programs/Simulation/genr8_2_hddm) can be used to convert the output of genr8 into HDDM format.

The input files still contain some "pristine" hits. Some smearing of these is still required to accurately model detector responses. In general, the calorimeter values are smeared inside of the reconstruction program while drift chamber hits are are smeared using an intermediate program called mcsmear.

The simulation produces several output files. The default name of the one with the detector responses that you want is called hdgeant.hddm.

Reading in Simulated Data

Simulated data can be accessed from a DANA-based program. 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.

Some programs already exist that can be used verify the hits are there and look at single events. For any kind of sophisticated analysis however, you will likely need to write a custom C++ program.

hd_dump

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

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:

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