J4HistoryKeeper: A Handy Tool for History Keeping in Geant4 Tracking

Welcome to J4HistoryKeeper sample code page. J4HistoryKeeper is a tool for history keeping in Geant4, which comes in handy for so-called Cheated Particle Flow Analysis (CPFA). This page provides links to sample code using J4HistoryKeeper, which is described in papers by S.Yamamoto, K.Fujii, and A.Miyamoto (YFM2007, 2008).

ACFA Sim-J Group

 What's new?

• September 23, 2008 : This page is opened to public.

 Features

The following is the abstract cited from the YFM paper (YFM2008):

The Particle Flow Analysis (PFA) is currently under intense studies as the most promising way to achieve precision jet energy measurements required at the future linear collider. In order to optimize detector configurations and to tune up the PFA it is crucial to identify factors that limit the PFA performance and clarify the fundamental limits on the jet energy resolution that remain even with the perfect PFA and an infinitely granular calorimeter. This necessitates a tool to connect each calorimeter hit in particle showers to its parent charged track, if any, and eventually all the way back to its corresponding primary particle, while identifying possible interactions and decays along the way. In order to realize this with a realistic memory space, we have developed a set of C++ classes that facilitates history keeping of particle tracks within the framework of Geant4. This software tool, hereafter called J4HistoryKeeper, comes in handy in particular when one needs to stop this history keeping for memory space economy at multiple geometrical boundaries beyond which a particle shower is expected to start.

 Availability

The Jupiter and Satellites system can be downloaded from the CVS repository as described in SimTools Page. The latest full featured versions are always available from the CVS server (JLCCV) as modules named Jupiter and Satellites. Notice that the instructions in the SimTools page might be slightly out-of-date but the CVS version is always up-to-date.

The following is a demo version:

• CPFA-0.1.tar.gz: a snapshot as of Sep.23, 2008,

which is extracted from the full version and made into a single package just to demonstrate key features of the tool.

 Caution

The demo version is most probably over-simplified. It is just to show the functionalities of J4HistoryKeeper in its application to so-called Cheated Particle Flow Analysis (CPFA); many important funcitionalities of Jupiter/Satellites have been omitted; it uses a toy detector model with a calorimeter but with no particle traker, no solenoidal magnet, no beam pipe, no support structure; charged particle trackes are created by just copying "BreakPoint" information.

Since many important features have been eliminated from the demo version to make it slim and to avoid dependencies on some other packages, we do not recommend to use it for any serious PFA sutdies.

 Directory Structure of The Demo Version

The source code of the Jupiter-Lite part is found under the "source" subdirectory, which contains

kern	:  core part of Jupiter including J4HistoryKeeper, etc.
lcexp	:  general classes for linear collider applications
cal	:  calorimeter implementation with tower geometry. Look at S4CALSD and S4CALHit for sample usage of J4HistoryKeeper.
main	:  Jupiter main program.

The source code of the Satellites-Lite part is found under the "examples/MiniSat" subdirectory which contains

src/leda	:  a miniature subset of Leda (generic classes for data analysis).
src/jsf	:  a very limited subset of the JSF core.
src/io/mctruth/kern	:  a very limited subset of the core part of IO.
src/io/mctruth/hist	:  Satellite's J4HistoryKeeper dual.
src/io/mctruth/cal	:  an MC truth unpacker for calorimeter hits.
src/metis/hybt	:  a toy hybrid track maker which just copies break point information.
src/metis/cal	:  a toy calorimeter cluster maker with cheated clustering using J4HistoryKeeper infomation.
src/metis/cpfo	:  a Cheated PFO Maker using the history information.

 How to Build the Demo Version

• First install Geant4, CLHEP, and ROOT. The package has successfully been built on MacOSX 10.5 with geant4.9.1.p02, clhep-2.0.3.3, and root_v5.20.00, using gcc4.3.0.
• Edit "setup.sh" in the top directory to adjust environmental variables such as ROOTSYS and G4INSTALL. The "setup.sh" assumes that env.sh is in $G4INSTALL for geant4-related environmental variables. If it is elsewhere on your system, adjust it too.
• Then type in the following excluding the shell prompt, "$ ":

$ source setup.sh
$ make

This will create directories bin, lib, include, tmp, etc. containing binary files. The Jupiter executable will be in bin/$G4SYSTEM/ in particular.

 How to Run the Demo Version

• Type the following

$ bin/$G4SYSTEM/Jupiter -f data/gld_snowmass.dat

then you will be in a Jupiter interacteive session with a command line prompt such as:

JUPITER(Idle)[/][100]:

• In the Jupiter command line, type, for instance,

JUPITER(Idle)[/][100]: /run/beamOn 10

to simulate 10 events reading a PYTHIA data file "data/pythia_event.data" (which stores 1000 events of e+e- -> ZH followed by Z -> nu nubar at 350 GeV). You will get an ascii file "hit.dat" containing BreakPoint, PreHit, and CALHit information.

• To run Satellites, type in the following

  $ pushd examples/MiniSat/test
  $ root -l cpfa.C

  then you will get an event display canvas with colored cheated Particle Flow Objects (PFOs). Follow the instruction on the terminal window for the next action. You can go to the next event if any, or quit, or get into the edit mode in which you can rotate and zoom up the displayed event.

 References

1. YFM2007: "A Handy Tool for History Keeping of Geant4 Tracks and its Application to Studies of Fundamental Limits on PFA Performance" by Sumie Yamamoto, Keisuke Fujii, and Akiya Miyamoto (http://arxiv.org/abs/0709.3147).
   
2. YFM2008: "A Handy Tool for History Keeping of Geant4 Tracks �| J4HistoryKeeper �|" by Sumie Yamamoto, Keisuke Fujii, and Akiya Miyamoto (http://arxiv.org/abs/0809.4111), which will appear in Computer Physics Communications.

 Note Added

The J4HistoryKeeper package has been built and tested on MacOSX 10.5 with ROOT5.20.00 and gcc4.3.0 compiler, and on Scientific Linux 4.2 with ROOT5.18.00 and the gcc3.4.4 compiler.